First release as traits.use, a generic package for loading and wrangling any traits.build database. The code and history come from the austraits package (version 3.1.1 and earlier, listed below), which becomes a thin AusTraits-specific layer over traits.use (austraits#188).
What is specific to AusTraits stays in the austraits package: load_austraits(), get_versions() and get_version_latest() (load AusTraits with load_database() and its doi instead), the AusTraits Getting Started vignette, and the map of Australia used by plot_locations().
Requires R 4.1.0 or later, as the code uses the native pipe |>.
New dataset austraits_lite: 24 datasets from AusTraits 7.0.0 (CC BY 4.0), a small traits.build database to try the package on without downloading anything. The examples now use it and run; those of load_database(), which download, run only in interactive sessions.
Fix bug in as_wide_table(), which failed on a database without contexts or without known location properties (8 of the 23 AusTraits 5.0.0 datasets we tried, each on its own). Such databases now give the same columns, empty where there is nothing to fill. The location columns now always come in the order latitude (deg), longitude (deg), location.
as_wide_table() now puts its most-used columns first, as it was meant to (#25). Its reordering had never been applied, so the columns came in the order of the joins. No column is dropped: source_id, repeat_measurements_id and the other columns of the traits, methods and taxa tables follow the most-used ones, so trait_pivot_wider() works on the result.
Fix bug in separate_trait_values(), which lost values: rows whose method_context_id or repeat_measurements_id was NA were merged before being separated (AusTraits 5.0.0’s ABRS_1981 went from 36,603 rows to 28,138 when bound and 19,675 when separated again; it now returns to 36,603). It also returned NULL when there was nothing to separate, and left missing values as the text "NA" in basis_of_value. Its definitions argument is no longer needed.
extract_*() return the tables in the order of a release and bind_databases(), with identifiers before contributors.
join_identifiers() works on a database without an identifiers table (built before traits.build added it), adding an empty identifier_types column as for an empty table, rather than failing.
New plotting functions from austraits.portal (#15, #7): plot_trait_distribution_jitter() plots a numeric trait by group, about 3 to 10 times faster than the beeswarm plot on AusTraits 5.0.0 traits; plot_categorical_trait_distribution() plots the proportion of each family’s taxa with each value of a categorical trait; plot_trait_distribution() picks between them from the trait’s type. They return a ggplot object, match the trait name exactly, leave out bins and ranges, and keep negative values within the x-axis limits. They also carry the changes traits.build’s dataset report had made to its copies, so the report can use these (#21): the categorical plot sizes points by the number of taxa with a record of each value, where the portal’s version used a fractional total that under-counts taxa whose records disagree, while its legend said “species count”; the jitter plot draws highlighted groups in pink, which stands out from the alternating blue and orange, and names them in pink in the bottom-right corner (in static plots; plotly::ggplotly() drops the label). Beyond what the report had, the jitter plot also gives raw values their own shape, an open circle, rather than filing them under “Unknown”, and its legend lists only the value types present, rather than every type with blank keys for those missing.
plot_trait_distribution_beeswarm() is removed: use plot_trait_distribution_jitter(), which draws the same distribution many times faster, or plot_trait_distribution(), which picks the plot from the trait’s type. ggbeeswarm and gridExtra are no longer needed.
The plotting functions say which suggested packages they need (ggplot2 and others) when one is not installed, rather than failing partway.
plot_locations() draws without a map by default. Its basemap argument takes a data frame of map cells (columns x and y) to draw the locations over; basemap = "australia" now gives an error pointing to the austraits package.
In the extract_*() functions, a value that is itself in the column, such as a taxon name with brackets, is matched as plain text (#10). Before, the 3,918 taxon names in AusTraits 5.0.0 with brackets, such as "Abrotanella sp. [White_2020]", were read as regular expressions: they could not find themselves, and 836 of them matched other taxa instead ([...] is a character class). They now find themselves and the names containing them. A value that is not a valid regular expression is matched as plain text, with a message, rather than giving an error.
extract_data() on the contexts table now honours partial_matches_allowed: matching is case-insensitive by default, exact with FALSE (so brackets are read literally), and several values are combined. partial_matches_allowed is now documented in all extract_*() functions.
Support databases built with traits.build 2.3, where every observation names the reference it was taken from in source_id (the dataset_id unless it came from another study) and the methods table’s reference columns are dataset_id_type, dataset_id_citation, secondary_id and secondary_citation (traitecoevo/traits.build#296). Older databases still work.
New function join_sources() adds each observation’s references to the traits table: dataset_id_citation, source_id_citation (formatted from sources[[source_id]]), secondary_id and secondary_citation.
New function get_references() lists the references a database, or an extract_*() result, cites, as a tibble of key, formatted citation and type (dataset, source or secondary); with file, it also writes them to a BibTeX file (#8). These are the references extract_data() keeps in sources. A cited key with no reference in sources is listed with an NA citation and a warning, rather than dropped.
Fix bug in the citations join_sources(), flatten_database() and as_wide_table() format from sources: outside Australian time zones, they gave the year before for every reference (e.g. Falster_2003 as 2002). The references’ dates are stored as midnight in Sydney, the previous day in UTC; they are now read from each reference’s own fields.
flatten_database() takes its references from join_sources(), so the flattened table has those columns in place of the methods table’s source_* columns.
as_wide_table() has dataset_id_citation, source_id_citation and secondary_citation in place of source_primary_citation and source_secondary_citation.
extract_data() keeps every reference the extracted observations cite, including the studies observations were taken from, which it used to drop; it no longer fails on a database without source_secondary_key.
bind_databases() orders sources and definitions in the C locale, as dplyr::arrange() does, so a database built on any machine comes out in the same order (#6). Before, the order followed the session’s collation, e.g. bark_B_per_dry_mass before or after bark_ash_per_dry_mass. summarise_database() sorts the same way.
bind_databases() warns when one citation key names different references in different datasets (titles or years differ), since sources keeps only one entry per key and the other is lost.
sources can now be looked up by key with $ (austraits#185): database$sources$Falster_2005 returns the reference, as database$sources[["Falster_2005"]] does. Before, $ on a BibEntry only did field access, so a key returned a list of NULLs. bind_databases(), load_database() and extract_data() give sources the class traits_build_sources (see ?traits_build_sources), also for older releases; field access such as sources$title, printing and RefManageR::WriteBib() output are unchanged.
Added new function load_database which loads any traits.build database from its doi (Zenodo, Figshare or a doi resolving directly to an .rds file). By default it keeps downloads in a per-user cache folder (tools::R_user_dir(), or the traits.use.cache_dir option), so each release is downloaded once per computer and shared by every project (#22); give path to keep a copy with a project instead. Nothing is written to the working directory unasked.
load_database(flattened = TRUE) loads the flattened version of a database, one table with the others joined to the traits table, which releases of AusTraits include from 7.0.0 (#9). It is cached like the relational database, so list_cached_databases() and clear_database_cache() now include a release’s flattened .rds (also one downloaded by hand into a folder given as path).
New functions database_cache_dir(), list_cached_databases() and clear_database_cache() show where the cache is, what it holds, how big it is and when each database was last used, and delete releases you no longer need (clear_database_cache(older_than = 180) deletes those not used for six months). They only touch files load_database() wrote, also in a folder given as path.
load_database() loads a saved database when the repository cannot be reached (e.g. offline), using its saved record, rather than failing.
Fix bug in load_database downloads: when the temporary folder was on a different drive to path, the file was saved under its temporary name and could not be loaded. The user’s timeout option is now also restored after a download.
Fix bug in plot_locations that silently left out locations east of 153°E (Brisbane, the Gold Coast, Byron Bay) and north of 9.5°S (Torres Strait), about 2% of AusTraits 5.0.0 records with coordinates. Locations beyond the map are now reported in a message. ... is now passed on to geom_pointdensity(), and feature = NA works.