format_bdvis: Prepare data frame for flagging functions

Description

format_bdvis renames certain fields in the data frame to make sure the other package functions knows how to use them. This step is highly recommended for the proper working of the functions.

Usage

format_bdvis(
  indf,
  source = NULL,
  config = NULL,
  quiet = FALSE,
  gettaxo = FALSE,
  ...
)

Value

The provided data frame, with field names changed to suite the functioning of further visualization functions.

Arguments

indf: Required. The data.frame on which to operate.
source: Optional. Indicates the package that was used to retrieve the data. Currently accepted values are "rvertnet", "rgbif", "bdsns" or "rinat". Either source, config or individual parameters must be present (see details).
config: Optional. Configuration object indicating mapping of field names from the data.frame to the DarwinCore standard. Useful when importing data multiple times from a source not available via the source argument. Either source, config or individual parameters must be present (see details).
quiet: Optional. Don't show any logging message at all. Defaults to FALSE.
gettaxo: optional. Call function gettaxo to build higher level taxanony. Defaults to FALSE.
...: Optional. If none of the previous is present, the four key arguments (Latitude, Longitude, Date_collected, Scientific_name) can be put here. See examples.

Details

When invoked, there are three ways of indicating the function how to transform the data.frame: using the source parameter, providing a config object with field mapping, or passing individual values to the mapping function. This is the order in which the function will parse arguments; source overrides config, which overrides other mapping arguments.

source refers to the package that was used to retrieve the data. Currently, three values are supported for this argument: "rgbif", "rvertnet", "besns" and "rinat", but many more are on their way. A caution with "besns" data is he scientific name has to be in the field "searchText".

config asks for a configuration object holding the mapping of the field names. This option is basically a shortcut for those users with custom-formatted data.frames who will use the same mapping many times, to avoid having to type them each time. In practice, this object is a named list with the following four fields: Latitude, Longitude, Date_collected and Scientific_name. Each element must have a string indicating the name of the column in the data.frame holding the values #' for that element. If the data.frame doesn't have one or more of these fields, #' put NA in that element; otherwise, the function will throw an error. See the examples section.

If none of the two is provided, the function expects the user to provide the mapping by passing the individual column names associated with the right term. See the examples section.

Examples

Run this code

if (FALSE) {
# Using the rgbif package and the source argument
if (requireNamespace("rinat", quietly=TRUE)) {
 d <- get_inat_obs_project("reptileindia") 
 d <- format_bdvis(d, source="rinat")

 # Using a configuration object, matches 'rinat' schema
 conf <- list(Latitude <- "latitude",
              Longitude <- "longitude",
              Date_collected <- "Observed.on",
              Scientific_name <- "Scientific.name")
 d <- format_bdvis(d, config=conf)

 # Passing individual parameters, all optional
 d <- format_bdvis(d,
                Latitude <- "lat",
                Longitude <- "lng",
                Date_collected <- "ObservedOn",
                Scientific_name <- "sciname")
}
}