Package 'ButtR'

Download and install the OzButterflies Database

Description

Simplifies downloading the OzButterflies database (Ref) to a local folder. The function allows users to download specific subsets of the database by applying multiple filters, such as species name, genus, site, family, specific IDs, and more.

Usage

get_Oz_butterflies(
  species = NULL,
  genus = NULL,
  family = NULL,
  sex = NULL,
  year = NULL,
  site = NULL,
  spectra = NULL,
  sampleIDs = NULL,
  download_images = c("raw", "jpeg"),
  download_dna = TRUE,
  save_folder = NULL,
  timeout = 10 * 60 * 60,
  quiet = FALSE,
  db_version = NA
)

Arguments

species	Optional vector of binomial names of species of interest. If specified, only species from this list will be included in the local database.
genus	If specified, only specimens from this genus will be installed.
family	If specified, only specimens from this family will be installed.
sex	If specified, only specimens of this sex ("male", "female" or "unknown") will be installed.
year	If specified, only specimens collected during these years will be installed (options are 2022 or 2023).
site	If specified, only specimens collected at these sites will be installed.
spectra	If specified, only specimens with the specified spectra value will be installed ("y" or "n").
sampleIDs	If specified, only specimens with the specified IDs will be installed.
download_images	Specifies whether "raw" and/or "jpeg" images should be downloaded. Only images with the specified type(s) will be downloaded. In versions 1 to 3 of the Oz butterflies database, raw files are in Sony raw format (.ARW) database. From version 4, raw files are in the Adobe Digital negative format (.DNG) (see the db_version parameter).
download_dna	If TRUE (the default), DNA files (.ab1) will be downloaded and installed. If FALSE, DNA files will not be installed.
save_folder	Folder where the downloaded database will be saved. This argument must be provided by the user.
timeout	Maximum time allowed (in seconds) to download each file; default is 10 hours. The time required will depend on the speed of your Internet connection and the parts of the database that you choose to download. If you experience an error message such as "Timeout of 36000 seconds was reached", try increasing the timeout.
quiet	If FALSE, a progress bar is displayed showing the download progress for each file as it is downloaded from the repository, and informational messages are printed to the console. Specify quiet = TRUE to prevent progress bar display.
db_version	Version of the database to download. NA (the default) means download the latest version. An integer version number will download that version of the database. Note that in version 3 and earlier, raw image files were in .ARW format. Starting from version 4, raw images are in .DNG format.

Details

Be aware that downloading very large files can take many hours, depending on the speed of your Internet connection.

get_Oz_butterflies will not remove local existing files, so subsequent calls can be used to add to the installed database.

If you receive an intermittent error such as "⁠status was 'SSL peer certificate or SSH remote key was not OK'⁠", try using a different download method. ButtR downloads files by calling download.file, so the download method can be specified by setting the download.file.method option; for example, options(download.file.method = "curl"). See the download.file help for further details.

Value

The installation folder (save_folder) in canonical form in invisible form (which means it is not automatically printed).

Examples

## Not run: 
# Download the full OzButterflies Database
get_Oz_butterflies(save_folder = "OzButterflies")

# Get data only for Delias aganippe
get_Oz_butterflies(species = "Delias aganippe", save_folder = "Delias_aganippe")

# Get data for all species of the genus Delias
get_Oz_butterflies(genus = "Delias", save_folder = "Delias_database")

# Get all species within the Nymphalidae family
get_Oz_butterflies(family = "Nymphalidae", save_folder = "Nymphalidae_data")

# Get raw files in .ARW format (from version 3 of the database)
get_Oz_butterflies(
  download_images = "raw",
  db_version = 3,
  species = "Delias aganippe",
  save_folder = "Delias_raw_ARW"
)

# Get raw files in .DNG format (from version 4 of the database)
get_Oz_butterflies(
  download_images = "raw",
  db_version = 4,
  species = "Delias aganippe",
  save_folder = "Delias_raw_DNG"
)

## End(Not run)

---

Summarise contents of the locally installed OzButterflies database

Description

Summarise contents of the locally installed OzButterflies database

Usage

Oz_butterflies_summary(
  save_folder = "OzButterflies",
  imgExt = "\\.DNG$|\\.dng$|\\.ARW$|\\.arw$"
)

Arguments

save_folder	Path of folder that contains the OzButterflies database.
imgExt	Regular expression used to identify files to be counted as images. Default is .DNG or .ARW files which are the RGB and UV photos of specimens. DNG is the Adobe open Digital Negative format and used in version 4 (and above) of the database, while ARW is the Sony raw file format, and used in versions 1, 2 and 3.

Value

Data frame with 1 row and columns that summarise the database contents. All summary statistics, apart from the Images count, describe the entire database, regardless of whether the entire database or a subset is installed locally.

---