README.md

In ButtR: Download and Extract Data from the 'OzButterflies' Database

🦋 ButtR 🦋

Overview

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

The OzButterflies database can be downloaded manually from Dryad, however it is simpler to use ButtR to do so. The database is quite large, so if the entire database is not required, ButtR provides an efficient mechanism to download and install only the desired parts of the database. It is also much simpler to install the entire database using ButtR than to download and extract all of the zip files.

If you use the OzButterflies database, please cite the paper:

📌 [Citation to be added]

Why Use ButtR?

✅ Easy Download – Quickly access butterfly data with a single command .\ ✅ Selective Filtering – Download only specific species, families, or locations, saving disk space and processing time.

🛠 Functions

The ButtR package provides the following core functions:

| Function | Description | |---------------------------------|---------------------------------------| | get_Oz_butterflies() | Download and install the database, optionally filtered by species, family, or location |

📥 Installation

You can install the stable version from CRAN:

#install the package 
install.packages("ButtR")

#load the package 
library("ButtR") 

Or install the latest development version from GitHub. In this case, you need to have the devtools package installed:

# Install devtools if not already installed 
install.packages("devtools") 
library("devtools")

# Install ButtR from GitHub 
devtools::install_github("DiogoJackson/ButtR") 
library("ButtR")

🚀 Examples of use

After installation and activation, you can use the get_Oz_butterflies() function from ButtR to download the entire database or filter specific subsets.

Download the entire database:

# Download the full OzButterflies Database
get_Oz_butterflies()

Download data for a specific species:

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

Download data for a specific genus:

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

Download data for a specific family:

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

Download data by site:

# Get all butterfly species from Cairns Botanic Gardens ("BG")
get_Oz_butterflies(site = "BG")

Download data for male Delias aganippe and Delias mysis from all sites with standardised collections in Brisbane:

# Get data with multiple filters 
get_Oz_butterflies(sex = "male", 
    species = c("Delias aganippe", "Delias mysis"), 
    site = c("BBG", "CC", "OC", "LSP"))

📑 Summary of database content

Folder structure

The OzButterflies Database has five folders for butterfly families (Papilionidae, Nymphalidae, Lycaenidae, Hesperiidae, Pieridae). Each family folder contains subfolders for each butterfly species. Each species subfolder contains subfolders for each butterfly specimen. Each specimen subfolder contains data and image files for that specimen, as shown in the schema below:

• 📁 Pieridae
  • 📁 Eurema_hecabe
    • 📁 1
      • 📄 1-v-RGB.dng (Ventral wing surfaces photographed in visible light)
      • 📄 1-d-RGB.dng (Dorsal wing surfaces photographed in visible light)
      • 📄 1-v-UV.dng (Ventral wing surfaces photographed in ultraviolet light)
      • 📄 1-d-UV.dng (Dorsal wing surfaces photographed in ultraviolet light)
      • 📄 1-RGB.dng (Dorsal and ventral wing surfaces photographed in visible light - non-pinned)
      • 📄 1-UV.dng (Dorsal and ventral wing surfaces photographed in ultraviolet light - non-pinned)
      • 📄 1-f.ab1 (CO1 gene sequenced forward - DNA)
      • 📄 1-d.jpeg (Reference image for speced patch numbers - dorsal)
      • 📄 1-v.jpeg (Reference image for speced patch numbers - ventral)
      • 📄 1-d-1-s.procspec (Spectra measured at 45 degrees - dorsal, patch 1)
      • 📄 1-d-1-a.procspec (Spectra measured at 60 degrees - dorsal, patch 1)
      • 📄 1-v-2-s.procspec (Spectra measured at 45 degrees - ventral, patch 2)
      • 📄 1.csv (CSV file containing all procspec measures)
      • 📄 1.png (Graph of the spectra measured at 45 degrees)
    • 📁 2
    • 📁 3
  • 📁 Lampides_boeticus
    • 📁 4
    • 📁 5

💡 Citation

If you use this database in a publication, please cite it as follows:

📌 [Citation to be added]

🤝 Helping us to improve

We welcome contributions! If you’d like to improve ButtR, feel free to open an issue for bug reports or feature requests.

ButtR documentation built on April 22, 2026, 1:07 a.m.