Getting started
wiutils has several utilities for exploring and manipulating (filtering, plotting and summarizing) information from Wildlife Insights (WI) projects. These functions are useful to compute basic statistics, prepare the information for further analysis (e.g. occupancy models) and translate it into other standards (i.e. Darwin Core) that facilitate its publication on biodiversity information centers (e.g. GBIF).
Installation
Currently, wiutils works with Python versions 3.6 through 3.10.
Stable
You can install the latest stable version of wiutils using either pip or conda (recommended). In either case, we recommend creating a virtual environment for the installation.
pip install wiutils
conda install -c conda-forge wiutils
Note
If you are using conda, the installation is only available through the conda-forge channel.
From source
If you prefer to install wiutils from source, you'll need to install it from the GitHub repository. This can be done with pip or a combination of pip and git.
pip install --upgrade https://github.com/PEM-Humboldt/wiutils/tarball/master
pip install git+https://github.com/PEM-Humboldt/wiutils.git#egg=wiutils
Overview
wiutils has a wide range of functions to explore and manipulate information from WI projects. To get started and use most of these functions, you'll need to download your projects to your machine. Data from WI has a specific standard and depending on the type of project (i.e. images or sequences), every download will be divided into four of the following five files: projects.csv, cameras.csv, deployments.csv, images.csv, sequences.csv.
Warning
Except for functions that take only deployment information as an input, wiutils does not support sequence projects yet.
Functions in wiutils can be grouped in seven different categories:
- Reading: functions to read information from WI projects into DataFrames.
- Extraction: functions for extracting information based on different WI image's columns.
- Filtering: functions to filter WI images based on different conditions.
- Summarizing: functions to summarize (i.e. create new tables) WI data.
- Plotting: functions to plot information from the images and deployments tables.
- Darwin Core: functions to translate WI data to the Darwin Core standard.
- Preprocessing: functions to preprocess videos and images before uploading them to WI.
Note
Preprocessing functions are the only functions that do not need WI data as an input; rather they work on images and videos to preprocess data before uploading it to Wildlife Insights.
Reading
| Function | Description |
|---|---|
load_demo |
Loads the cameras, deployments, images and projects tables from a demo dataset. |
read_bundle |
Reads the cameras, deployments, images and projects tables from a specific Wildlife Insights project bundle. |
read_cameras |
Reads the cameras' table from a specific Wildlife Insights project bundle. |
read_deployments |
Reads the deployments' table from a specific Wildlife Insights project bundle. |
read_images |
Reads the images' table from a specific Wildlife Insights project bundle. |
read_projects |
Reads the projects' table from a specific Wildlife Insights project bundle. |
Extraction
| Function | Description |
|---|---|
get_date_ranges |
Gets deployment date ranges using information from either images, deployments or both. |
get_lowest_taxon |
Gets the lowest identified taxa and ranks. |
get_scientific_name |
Gets the scientific name of each image by concatenating their respective genus and specific epithet. |
Filtering
| Function | Description |
|---|---|
remove_domestic |
Removes images where the identification corresponds to a domestic species. |
remove_duplicates |
Removes duplicate records (images) from the same taxon in the same deployment given a time interval. |
remove_inconsistent_dates |
Removes images where the timestamp is outside the date range of the corresponding deployment. |
remove unidentified |
Removes unidentified (up to a specific taxonomic rank) images. |
Summarizing
| Function | Description |
|---|---|
compute_count_summary |
Computes a summary of images, records and taxa count by deployment. |
compute_detection |
Computes the detection (in terms of abundance or presence)of each taxon by deployment. |
compute_detection_history |
Computes the detection history (in terms of abundance or presence) by taxon and deployment, grouping observations into specific days-long intervals. |
compute_general_count |
Computes the general abundance and number of deployments for each taxon. |
compute_hill_numbers |
Computes the Hill numbers of order q (also called effective number of species) by site for some given values of q. |
Plotting
| Function | Description |
|---|---|
plot_activity_hours |
Plots the activity hours of one or multiple taxa by grouping all observations into a 24-hour range. |
plot_date_ranges |
Plots deployment date ranges. |
plot_detection_history |
Plots detection history matrix for a given species. |
Darwin Core
| Function | Description |
|---|---|
create_dwc_archive |
Creates a Darwin Core Archive consisting of four different cores and extensions: Event, Occurrence, Measurement or Facts and Simple Multimedia. |
create_dwc_event |
Creates a Darwin Core Event dataframe from deployments and projects information. |
create_dwc_measurement |
Creates a Darwin Core Measurement or Facts dataframe from cameras and deployments information. |
create_dwc_multimedia |
Creates a Darwin Core Simple Multimedia dataframe from images and deployments information. |
create_dwc_occurrence |
Creates a Darwin Core Occurrence dataframe from images, deployments and projects information |
Preprocessing
| Function | Changes an image's associated timestamp metadata for a new timestamp. |
|---|---|
change_image_timestamp |
Plots the activity hours of one or multiple taxa by grouping all observations into a 24-hour range. |
convert_video_to_images |
Converts a video to images with an associated timestamp. |
reduce_image_size |
Reduces image file size by resampling using a given factor. |
User guide
Head to the user guide to see usage examples and explanations for the different functions.
Reference
Head to the reference to see all available functions.
Wildlife Insights
Wildlife Insights is a cloud-based platform that uses machine learning to identify animals in camera trap images. Apart from helping with image classification, Wildlife Insights allows to store and manage camera trap data and metadata. It also offers the possibility to download this data in a convenient format for further analysis and sharing. To learn more about Wildlife Insights go to https://www.wildlifeinsights.org/get-started.