8 Data Object
The data object serves a couple of functions. First, it provides a central method and common approach for data retrieval from the FinCatch system. It stores the filters used for retrieval and provides a standard diction for calling the data retrieval functions in the FinCatchAccess package. Second, it provides a caching mechanism so that during an analysis chain or report, data will only be downloaded/retrieved from the database once. Additionally, any commonly used calculations (i.e. length-frequency extrapolations) can be defined and cached as well.
If the filter objects used in creating the data object change, the data object should be destroyed and re-created to ensure the cached data and filters remain synchronized!
8.1 Creating FinCatch Data Objects
8.2 Data Caching And Retrieval
Data is cached in the “data_…” and “codes_…” properties of the object. Data and codes are retrieved from the data object using the “get_data_…” and “get_codes_…” functions. These “get_” functions first check for cached data in the “data_” objects and returns it; otherwise they will retrieve it from the database, cache it in the “data_” objects, and return it. The names of “get_” functions match their counterparts in the “data_” objects. The “data_” objects are exposed to users (rather than hiding them as private objects) so that advanced users can utilize the FinCatchAnalysis package and the data object by directly saving data to the cache.
Data should always be retrieved using “get_” functions, so that caching works. Trying to retrieve data directly from the “data_” and “code_” cache objects opens up logic errors where lack of data and yet-to-be retrieved data are confused and confounded.
While data column names may be renamed and table structures combined and split during caching operations, data should not be modified in any way that introduce assumptions or potential bias. These type of operations should use “get_calc_” and “calc_” names as described below!
8.3 Calculated Data
Commonly used calculations are defined in the the data object so that they do not need to be repeated in the same analysis chain or report. One example would be length-frequency extrapolations when part of a fish sample are sub-sampled for length and then extrapolated by fish counts. These calculations are defined and retrieved in “get_calc_…” functions with their results cached in “data_…” objects similar to the “data_” and “code_” objects.
8.4 Warnings and Errors
Warning and error properties exist in the data object. These accumulate potential issues encountered when retrieving data/codes from the database or when performing calculations (such as extrapolated length-freqencies from a small subsample). These errors are printed to the console when the FinCatchAnalysis package is used interactively.
When the FinCatchAnalysis package is used in a non-interactive environment like markdown, quarto, or shiny, it is important that these warnings and errors are explicitly and intentionally shown to the end user as part of the output!