Type: Package
Title: Download and Extract Data from the 'OzButterflies' Database
Version: 1.1.1
Description: Provides tools to download and extract data from the 'OzButterflies' Database <doi:10.5281/zenodo.19019034>, which contains reflectance spectra, calibrated photographs, and cytochrome c oxidase subunit I (COI) sequences of Australian butterflies. The main function get_Oz_butterflies() downloads the database and extracts selected files to a specified directory using user-defined filters.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.3
Imports: httr, jsonlite
Suggests: testthat (≥ 3.0.0), withr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-04-17 17:50:21 UTC; User
Author: Diogo Silva ORCID iD [aut, cre], Jim McLean ORCID iD [aut]
Maintainer: Diogo Silva <diogojackson@hotmail.com>
Repository: CRAN
Date/Publication: 2026-04-21 19:22:20 UTC

ButtR: Downloading the OzButterflies Database

Description

ButtR is an R package designed to simplify the download and extraction of the OzButterflies Database, a comprehensive dataset containing reflectance spectra, calibrated photographs, and CO1 sequences of Australian butterflies (Reference).

Details

The package includes the function get_Oz_butterflies, which allows users to download specific subsets of the database by applying multiple filters (parameters), providing tailored access to the data based on user-defined criteria.

Author(s)

Maintainer: Diogo Silva diogojackson@hotmail.com (ORCID)

Authors:

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.

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)