News for Package finbif

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.