NEWS

---

finbif 0.10.0.9000

• This is the current development version.

finbif 0.10.0 (2026-07-02)

MINOR IMPROVEMENTS

• New variable materialEntityType added.

BREAKING CHANGES

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

finbif 0.9.14 (2026-04-17)

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 (2026-03-04)

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 (2026-01-27)

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 (2025-08-22)

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 (2025-04-15)

MINOR IMPROVEMENTS

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

finbif 0.9.9 (2024-11-05)

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 (2024-08-19)

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 (2024-07-23)

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 (2024-04-25)

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 (2024-03-15)

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 (2024-01-12)

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 (2023-09-28)

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 (2023-08-28)

BUG FIXES

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

finbif 0.9.1 (2023-06-29)

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 (2023-05-23)

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 (2023-03-29)

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 (2023-02-06)

MINOR IMPROVEMENTS

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

finbif 0.7.1 (2022-11-24)

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 (2022-09-13)

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 (2022-08-08)

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 (2022-05-20)

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 (2022-03-10)

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 (2022-01-03)

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 (2021-09-03)

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 (2021-07-26)

BUG FIXES

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

finbif 0.6.0 (2021-07-22)

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 (2021-03-27)

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 (2021-01-27)

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 (2020-12-17)

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 (2020-11-24)

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 (2020-04-23)

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 (2020-01-16)

NEW FEATURES

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

MINOR IMPROVEMENTS

• Add more content to vignettes.

finbif 0.1.0 (2019-11-19)

• Initial release.