Animl comprises a variety of machine learning tools for analyzing ecological data. The package includes a set of functions to classify subjects within camera trap field data and can handle both images and videos.

1. Tips for Use
2. Models
3. Installation
4. Release Notes

Below are the steps required for automatic identification of animals within camera trap images or videos.

First, build the file manifest of a given directory.

library(animl)
imagedir <- "examples/TestData"
#create save-file placeholders and working directories
WorkingDirectory(imagedir, globalenv())
# Read exif data for all images within base directory
files <- build_file_manifest(imagedir, out_file=filemanifest, exif=TRUE)
# Process videos, extract frames for ID
allframes <- extract_frames(files, out_dir = vidfdir, out_file=imageframes,
                            frames=3, parallel=T, num_workers=parallel::detectCores())

This produces a dataframe of images, including frames taken from any videos to be fed into the classifier. The authors recommend a two-step approach using the 'MegaDector' object detector to first identify potential animals and then using a second classification model trained on the species of interest.

More info on
MegaDetector v5/v1000
MegaDetector v6

#Load the Megadetector model
md_py <- load_detector("/Models/md_v5a.0.0.pt", model_type = 'mdv5', device='cuda:0')
# Obtain crop information for each image
mdraw <- detect(md_py, allframes, resize_width=1280, resize_height=960, batch_size=4, device='cuda:0')
# Add crop information to dataframe
mdresults <- parse_detections(mdraw, manifest = allframes, out_file = detections)

Then feed the crops into the classifier. We recommend only classifying crops identified by MD as animals.

# Pull out animal crops
animals <- get_animals(mdresults)
# Set of crops with MD human, vehicle and empty MD predictions. 
empty <- get_empty(mdresults)
# load class list
classes <- load_class_list("/Models/Southwest/v3/southwest_v3_classes.csv")
class_list <- classes$class
# load the model
model_file <- "/Models/Southwest/v3/southwest_v3.pt"
southwest <- load_classifier(model_file, len(class_list))
# obtain species predictions likelihoods
pred_raw <- classify(southwest, animals, resize_width=480, resize_height=480, out_file=predictions, batch_size=16, num_workers=8)
# apply class_list labels and combine with empty set
manifest <- single_classification(animals, empty, pred_raw, class_list)

If your data includes videos or sequences, we recommend using the sequence_classification algorithm. This requires the raw output of the prediction algorithm.

# Sequence Classification
manifest <- sequence_classification(animals, empty=empty, pred_raw, classes=class_list, station_col="station", empty_class="empty")

The Conservation Technology Lab has several models available for use.

Detectors: MegaDetector v5/v1000
MegaDetector v6

• R >= 4.0
• Reticulate
• Python >= 3.9
• Animl-Py >= 3.0.0

We recommend running animl on a computer with a dedicated GPU.

animl depends on python and will install python package dependencies if they are not available if installed via CRAN.
However, we recommend setting up a conda environment using the provided config file.

Instructions to install conda

The R version of animl depends on the python version to handle the machine learning: animl-py

Next, install animl-py in your preferred python environment (such as conda) using pip:

pip install animl

Animl-r can be installed through CRAN:

install.packages('animl')

Animl-r can also be installed by downloading this repo, opening the animl.Rproj file in RStudio and selecting Build -> Install Package.

• compatible with animl-py v3.0.0
• remove package dependencies
• on load, also load animl-py
• change function name "predict_species" to "classify"
• add "load_detector" function that can handle MDv5, v6, v1000 and other YOLO models
• change "sort" to "export"
• add function to install animl-py and create conda env if does not exist
• add distance calculation functions for re-id
• fix bug in sequence_classification that mishandled overlap in classifier classes with megadetector classes
• changed function naming conventions to follow animl-py
• correct examples and documentation to reflect above changes

Kyra Swanson
Mathias Tobler
Edgar Navarro
Josh Kessler
Jon Kohler