# News for Package <span class="pkg">finbif</span>

# finbif 0.10.0

## MINOR IMPROVEMENTS

   - New variable `materialEntityType` added.

## BREAKING CHANGES

   - The default value of `finbif_use_dwc` is now `TRUE`. meaning that
     `finbif_collections()` expects and returns DwC style variable names unless
     otherwise specified by the user.

# finbif 0.9.14

## MINOR IMPROVEMENTS

   - DwC style field names can be set with a global option `finbif_use_dwc`.
   - `finbif_taxa` gains a `locale` argument.
      
## DEPRECATION

   - The default value of `finbif_use_dwc` is `FALSE`. This is deprecated and
     will be set to `TRUE` in v0.10.0.

# finbif 0.9.13

## MINOR IMPROVEMENTS

   - Package now uses version 1 of upstream API.
   - A collection ID QName is used if there is no collection code.

## BUG FIXES

   - Fixed an error in the formatting of iso8061 dates.
   - Fixed an error triggered if collection code is requested without
     institution code.

# finbif 0.9.12

## MINOR IMPROVEMENTS

   - Added a new function to renew access tokens.

## BUG FIXES

   - Fixed issue with fetching collection metadata due to upstream API changes.

# finbif 0.9.11

## MINOR IMPROVEMENTS

   - Added capacity to import new DarwinCore archive formatted FinBIF
     download files.
   - Added new variables and filters from upstream API (undocumented).

# finbif 0.9.10

## MINOR IMPROVEMENTS

   - Improvements have been made to the way errors in parsing json are handled.

# finbif 0.9.9

## DEFUNCT

  - Importing `.ods` and `.xlsx` occurrence data files is now defunct. Users
    should use `.tsv` download files only.

## MINOR IMPROVEMENTS

  - Occurrence download progress indicator has been simplified.
  - Location data parsing (country, region, municipality and local area) has
    been improved.

# finbif 0.9.8

## DEPRECATION

  - Importing `.ods` and `.xlsx` occurrence data files has been deprecated and
    will be defunct in a future release.

## MINOR IMPROVEMENTS

  - Caching behaviour has been made more consistent.

# finbif 0.9.7

## NEW FEATURES

  - Record pagination has been simplified and improved so that it should not be
    possible to have duplicate records when using `finbif_occurrence`.

## MINOR IMPROVEMENTS

  - `finbif_last_mod` can be used without a `filter` argument value.
  - Error handling for API requests has been improved.

## BUG FIXES

  - Fixed an issue triggered when multi-filter set requests returned
    zero results.
  - Fixed bug triggered when dropping columns of all NA data.
  - Fixed an issue with file-based caches timing out correctly.
  - Fixed an issue triggered when selecting certain variables and zero records
    were returned.

# finbif 0.9.6

## MINOR IMPROVEMENTS

  - New undocumented variable and filter `local` added from upstream API.

## BUG FIXES

  - Fixed an issue that caused more records than requested to be returned for
    certain values of `n`.

# finbif 0.9.5

## MINOR IMPROVEMENTS

  - A more informative error message is given when requesting an access token
    for an email address that has already been assigned one.

## BUG FIXES

  - Fixed an issue with reading facts for FinBIF record download files.
  - Fixed an issue with reading column names using `data.table` package to
    ingest FinBIF record download files.

# finbif 0.9.4

## NEW FEATURES

  - New undocumented variable "source" can be selected with `finbif_occurrence`.

## MINOR IMPROVEMENTS

  - Record pagination should now often require less queries of FinBIF server and
    should be faster.
  - FinBIF collections field names have been sanitised.
  - When filtering records by "collection\_id" a full URL ID can be used or a
    QName.

## BUG FIXES

  - Reading zero observation data downloads will now produce a zero row
    `data.frame` instead of triggering an error.

# finbif 0.9.3

## BUG FIXES

  - Fix a bug resulting in the incorrect region being assigned to occurrence
    records.

## MINOR IMPROVEMENTS

  - New undocumented variables `institution_code` and `collection_code` can be
    selected when using functions `finbif_collections` and `finbif_occurrence`.

# finbif 0.9.2

## BUG FIXES

  - Fixed a bug triggered when localising some variables and multiple pages of
    data had been requested.

# finbif 0.9.1

## NEW FEATURES

  - New option `finbif_use_cache_metadata` to set caching for metadata only. Is
    ignored if `finbif_use_cache` is `TRUE`.

## BUG FIXES

  - Fixed a bug triggered when trying to compute a variable from an identifier
    and data returned contained zero records.

# finbif 0.9.0

## NEW FEATURES

  - New function `finbif_update_cache` can be used to update all the cached
    objects that have reached their expiration and are no longer valid.
  - A restricted data API token can be explicitly declared via the
    `restricted_api` argument to `finbif_occurrence`.
  - Cached data can use a database as a backend by passing a `DBI` database
    connection object to the package option `finbif_cache_path`.
  - Cached data can be assigned a timeout by using a number (hours) instead of a
    logical value for the `cache` argument to `finbif_` functions or the package
    option `finbif_use_cache`.
  - Record aggregations with `finbif_occurrence` can now be combined with
    multi-filter requests. Removing duplicate records or aggregate record
    combinations can be controlled with the `duplicates` argument and adding a
    column indicating the filter sets can be added with the `filter_col`
    argument.

##### BUG FIXES

  - Fixed a bug causing an infinite recursion when determining page size
    during record download pagination.
  - Fix bug triggered when using aggregation with some selected variables.

## DEFUNCT

  - Mapping utilities `finland_map`, `breaks_xy`, `hist_xy` and the plot method
    for `finbif_occ` objects are now defunct.
  - User access to `finbif_records` and its classes and methods is now defunct.

# finbif 0.8.0

## DEPRECATION

  - Mapping utilities `finland_map`, `breaks_xy`, `hist_xy` and the plot method
    for `finbif_occ` objects have been deprecated as they are out-of-scope.
  - User access to `finbif_records` and its classes and methods isdeprecated in
    favour of `finbif_occurrence`.

## NEW FEATURES

  - Record aggregations with `finbif_occurrence` can now include "individual"
    and "pair" sums.

# finbif 0.7.2

## MINOR IMPROVEMENTS

  - Updated deprecated use of `tidy::pivot_wider`.
  - Added new filters and variables from upstream API.

# finbif 0.7.1

## NEW FEATURES

  - New function `finbif_mod_date` to get last modified date for FinBIF
    occurrence data.
  - Region is now a selectable variable for `finbif_occurrence` and can also be
    used to filter records.

## MINOR IMPROVEMENTS

  - For the sake of clarity "province" is now referred to as "bio-province".
  - Many variables, including `sex`, `life_stage` and `record_quality` are now
    localised.
  - The variable `restriction_reasons` is now referred to in the singular as
    `restriction_reason`.
  - For consistency, `lang` argument to `finbif_collections` has been changed to
    `locale`.

## BUG FIXES

  - Fixed bug that caused locale to be set incorrectly for multipage requests.

# finbif 0.7.0

## NEW FEATURES

  - New function `taxon_id` that returns FinBIF taxon identifiers given a
    scientific name, vernacular name or other taxon identifier.
  - New filters `complete_list_taxon_id` and `complete_list_type` now available.
  - New global option `finbif_hide_progress` to suppress progress bars when
    downloading, importing or processing FinBIF records.
  - For the sake of clarity and consistency the term "administrative status"
    is now referred to as "regulatory status" throughout.
  - Regulatory status, informal taxonomic group and habitat data are now
    localised.
  - Option `unlist` added to `finbif_occurrence` that casts list columns to
    strings. If a cell has multiple values the values are cast to a string
    separated by semi-colons.
  - New argument `facts` added to `finbif_occurrence` that can be used to
    automatically extract facts when downloading occurrence records.

## BUG FIXES

  - Fixed bug triggered by incorrect data type applied to `taxonomic_order`.
  - Fixed bug preventing locale switching of vernacular name data.

# finbif 0.6.6

## NEW FEATURES

  - New option to exclude all records with any NA values for any of the
    selected variables added to `finbif_occurrence`.

## MINOR IMPROVEMENTS

  - The warning/error message returned when an invalid taxon is requested with
    `finbif_occurrence` has been made more detailed, warning the user they may
    be using synonyms or other invalid taxon names.

## BUG FIXES

  - Fix applied for a print method error triggered by clashing class names.
  - Fixed issue with ordering by some variables.

# finbif 0.6.5

## NEW FEATURES

  - New variables and filters (currently undocumented) have been added for the
    forthcoming Finnish atlas of breeding birds.
  - Skip rows argument added to `finbif_occurrence_load` so files can be read in
    chunks.

## MINOR IMPROVEMENTS

  - For clarity, KKJ coordinate reference system is now referred to as YKJ.
  - When selecting all available variables for download file imports using
    `finbif_occurrence_load` "extra" variables will no longer be automatically
    added.

# finbif 0.6.4

## MINOR IMPROVEMENTS

  - New administrative statuses added.
  - The number of (and interval between) api request retries can be configured
    (currently undocumented).
  - For some museum collections scientific names have been added for non-Finnish
    species.
  - New fields have been added to citable download imports.
  - New argument `aggregate_counts` (defaulting to `TRUE`) added to
    `finbif_occurrence` to toggle the inclusion of aggregation count fields on
    and off.
  - New bird association area, occurrence types and location tag metadata added.
  - New filters and variables (currently undocumented) added from upstream API.

## BUG FIXES

  - Fix bug triggered when printing occurrence records where all records have no
    coordinate uncertainty.

# finbif 0.6.3

## MINOR IMPROVEMENTS

  - Argument `drop_na_facts` has been changed to `drop_facts_na` for function
    `finbif_occurrence_load` to avoid problems due to partial matching of
    argument `drop_na`.
  - Data quality description has been appended to description field in
    `data.frame` returned by `finbif_collections()`.
  - Occurrence record filtering can now be done using open-ended date ranges.
  - New administrative statuses added.

## BUG FIXES

  - Fix bug in importing of file downloads triggered by string quotation errors.

# finbif 0.6.2

## NEW FEATURES

  - New package option, `finbif_allow_query`, with default value, `TRUE`. If set
    to `FALSE` then remote API queries will trigger an error meaning only cached
    requests will run if a cache is found.
  - Records can now be aggregated by document.

## MINOR IMPROVEMENTS

  - A client-side error will be triggered if an attempt is made to filter by
    taxon and aggregate data by event with `finbif_occurrence`.

## BUG FIXES

  - Fix bug preventing loading of FinBIF archives that is triggered when all
    variables are selected with `select = "all"`.
  - Fix bug preventing `finbif_occ` objects from printing when one or more
    columns contain missing data only.

# finbif 0.6.1

## BUG FIXES

  - Fixed a regression in the last release that prevented collection names being
    converted from their URIs.

# finbif 0.6.0

## NEW FEATURES

  - New variables `lat_euref` and `lon_euref` available for occurrence record
    downloads. These new variables represent the central point of a bounding box
    encompassing a record's geographic coverage in the EUREF
    (ETRS89/ETRS-TM35FIN) coordinate system.
  - Option now available to retain the TSV data file when loading FinBIF
    occurrence data with `finbif_occurrence_load` from ZIP archive or online
    reference.
  - Option now available to extract "facts" when using `finbif_occurrence_load`
    to import records from a ZIP archive. The user must supply a named list,
    where the names refer to one or more fact types: "record", "event" and/or
    "document", and the list elements are character vectors indicating which
    "facts" to extract.
  - "Lite" download files (occurrence record datasets of less than 10,000
    records downloaded directly from laji.fi) can now be imported using
    `finbif_occurrence_load`.
  - New filters (currently undocumented) `ely_center_id` and `region_id` are
    available for `finbif_occurrence`.
  - New function, `from_schema`, to convert variable names from FinBIF schema to
    other styles.
  - New computed variable `date_time_ISO8601` (currently undocumented) can be
    selected when creating `finbif_occ` objects.
  - New computed variable `epsg` (currently undocumented). If selected, the
    column will have the EPSG code of the first column that contains geographic
    data.

## MINOR IMPROVEMENTS

  - Can now select all available variables when importing a FinBIF download
    request file using `finbif_occurrence_load` with `select = "all"`.
  - New option, `drop_na`, to drop columns that only contain missing data added
    to `finbif_occurrence` and `finbif_occurrence_load`.
  - User can now select columns multiple times and rename them on the fly by
    using a named character vector as the value of the 'select' argument.
  - The variable `taxon_rank` is now converted to a string on the fly via
    `taxon_rank_id`.
  - Variables that are computed from their identifiers are now localised when
    multiple languages are available.

## BUG FIXES

  - Fixed bug that prevented occurrence record counting when caching was not in
    use.
  - Fixed bug that triggered an error when selected a variable that had to be
    computed from its ID when using DwC style variable names.

# finbif 0.5.0

## NEW FEATURES

  - Getting records from FinBIF can now be speed up (\~1.5x) with asynchronous
    processing. If the `future` package is available and an asynchronous
    strategy (e.g., `plan(multisession, workers = 2)`) is selected then
    downloading records and processing them will occur simultaneously in
    separate threads, often leading to a significant speed up over sequential
    processing.
  - Occurrence records can now be requested using multiple sets of filters at
    the same time. If a list of filters (with unnamed elements) is supplied then
    a record request will be made for each set of filters and the results of all
    requests combined and all duplicate records removed.
  - Occurrence records can now be read directly from FinBIF download request
    files. The function `finbif_occurrence_load` can load data from a local file
    or remotely using a persistent identifier URI (e.g.,
    `http://tun.fi/HBF.49381`).
  - Aggregation of records can now be performed at the recording "event" level
    as well as the "record" level.

# finbif 0.4.1

## NEW FEATURES

  - New functions `scientific_name` and `common_name` are now available to get
    scientific and common names for taxa (given a taxon name or FinBIF ID code)
    or extract names from a `finbif_taxa`- class object.
  - Add ability to extract complex record variables such as those associated
    with record media (currently undocumented).

## MINOR IMPROVEMENTS

  - Collection name can be selected as a variable for occurrence records.
    Previously it had to be manually translated from collection ID.
  - Variables `restriction_reasons_conservation`,
    `restriction_reason_embargo` and `restriction_reason_custom` are no longer
    in use upstream and can no longer be selected.

# finbif 0.4.0

## NEW FEATURES

  - Occurrence record requests can now be made with aggregation,
    `aggregate = c("records", "species", "taxa")`. This returns the number of
    records, and/or species or taxa for each combination of the selected
    variables instead of the occurrence records themselves.

## MINOR IMPROVEMENTS

  - Error is triggered when attempting to request less than one record.
  - New content on requesting aggregated occurrence records added to vignette: 
    2. Occurrence records from FinBIF.

## BUG FIXES

  - Fixed two bugs in print method for FinBIF occurrence records that were
    triggered when attempting to print only one row of data.
  - Fixed bug triggering error when attempting to print occurrence record
    objects with zero rows.
  - Fixed bug triggered when trying to print occurrence record data with NA
    values.
  - Fixed bug causing incorrect subsetting of occurrence records when using
    logical vectors to subset rows.
  - Fixed bug that printed occurrence records with multi-element data
    incorrectly when there was a single element.
  - Fixed bug triggered by some system locales (\#1).

# finbif 0.3.1

## NEW FEATURES

  - Occurrence records can be ordered by the total number of records or total
    number of Finnish records of the taxon (variables: `n_total_records` &
    `n_total_finnish_records`, currently undocumented).
  - New Finnish occurrence status, `records_only`, added.
  - New administrative statuses added to filters.

## MINOR IMPROVEMENTS

  - Filtering vignette updated to reflect changes to data quality filters.

# finbif 0.3.0

## NEW FEATURES

  - All user facing functions with a `finbif_` prefix can now also be used with
    the alternative shorter prefix `fb_`.
  - Crop Wild Relative, CWR, added to admin statuses.
  - There are two new utility functions, `to_dwc` and `to_native` for converting
    variable names to and from Darwin Core style.
  - Users can select and order by variables in Darwin Core style when using
    `finbif_occurrence`.
  - Some changes in variables and filters have flowed from upstream changes to
    "api.laji.fi". The variables `is_unidentifiable`, `record_reliable`,
    `collection_reliability`, `taxon_reliability`, `taxon_reliability_message`
    and `taxon_reliability_source` have been deprecated and replaced with
    `requires_verification`, `requires_identification`, `record_reliability` and
    `record_quality`. The filters `collection_reliability` and
    `taxon_reliability` have been deprecated and replaced with
    `requires_verification`, `collection_quality`, `record_reliability`,
    `record_quality`, and `expert_verified`.
  - Vernacular names are now localised. Users can select a language to use for
    taxon vernacular names. Missing names will fallback gracefully to other
    languages. A package-wide locale can be set and is by default set to the
    system locale (if not set or can't be determined it will default to English).
  - New vignettes on getting occurrence records, selecting and ordering
    variables, metadata and plotting have been added.

## MINOR IMPROVEMENTS

  - Caching defaults to in memory caching instead of relying on the temporary
    directory.
  - Front matter of vignettes is now visible when using the R help browser.
  - Retired "quiet" option for `on_check_fail` argument in function
    `finbif_occurrence()`.
  - Improved error messages when taxa fail checking in `finbif_occurrence()`.
  - Global option to set timezone, `finbif_tz`, as default value for "tzone"
    argument to `finbif_occurrence()`. Avoids having to set system environment
    variable TZ or specify "tzone" every time `finbif_occurrence()` is run.
  - Now when a record has no time information the start time is assumed to be
    midday. Previous behaviour was to assume start time was midnight, making
    errors potentially biased.
  - Package options are now documented in the package level man page.
  - News file is now accessible via R internal help system.
  - The number of default variables selected when accessing occurrence records
    has been reduced to speed up downloads and improve the display of
    `finbif_occ` objects.
  - The print method for occurrence record objects has been updated. It is now
    aware of console width and when truncating variable values is more
    considerate of the context.
  - Variables can now be "deselected" when using the `select` argument to
    `finbif_occurrence` by prepending the variable name with a "`-`".
  - After some failures, API requests are now automatically retried up to three
    times.

## BUG FIXES

  - Ordering by descending variables did not work when ordering by both
    ascending and descending variables.
  - Fixed bug in handling of duplicates that could result in an infinite
    recursion.
  - Fixed bug that (when `on_check_fail = "warn"`) all taxa failed checks
    `finbif_occurrence()` would proceed as if no taxa had been selected.
  - Fixed bug in print method for `finbif_occ` objects that caused error when
    trying to display a single column objects with a list-col only.

# finbif 0.2.0

## NEW FEATURES

  - Add capacity to request a random sample of FinBIF records.

## MINOR IMPROVEMENTS

  - Add more content to vignettes.

# finbif 0.1.0

  - Initial release.
