# animl-py
AniML comprises a variety of machine learning tools for analyzing ecological data. This Python package includes a set of functions to classify subjects within camera trap field data and can handle both images and videos.
This package is also available in R: [animl](https://github.com/conservationtechlab/animl)
Table of Contents
1. Installation
2. [Usage](#usage)
3. [Models](#models)
## Installation Instructions
It is recommended that you set up a conda environment for using animl.
See **Dependencies** below for more detail. You will have to activate the conda environment first each
time you want to run AniML from a new terminal.
### From GitHub
```
git clone https://github.com/conservationtechlab/animl-py.git
cd animl-py
pip install -e .
```
### From PyPi
```
pip install animl
```
### Dependencies
We recommend running AniML on GPU-enabled hardware. **If using an NVIDIA GPU, ensure driviers, cuda-toolkit and cudnn are installed.
PyTorch will install these automatically if using a conda environment.
The /models/ and /utils/ modules are from the YOLOv5 repository. https://github.com/ultralytics/yolov5
Python >= 3.9
Python Package Dependencies
* numpy >= 1.26.4
* onnxruntime-gpu == 1.18.0
* pandas >= 2.2.2
* panoptes_client >= 1.6.2
* pillow > 10.3.0
* pyexiftool >= 0.5.6
* opencv-python >= 4.10.0.82
* scikit-learn >= 1.5.0
* timm >= 1.0,
* torch >= 2.2.2
* torchvision >= 0.17.2
* tqdm >= 4.66.4
* wget >= 3.2
Animl also depends on [exiftool](https://exiftool.org/index.html) for accessing file metadata.
### Verify Install
We recommend you download the [examples](https://github.com/conservationtechlab/animl-py/blob/main/examples/Southwest.zip) folder within this repository.
Download and unarchive the zip folder. Then with the conda environment active:
```
python -m animl /path/to/example/folder
```
This should create an Animl-Directory subfolder within
the example folder.
Or, if using your own data/models, animl can be given the paths to those files:
Download and unarchive the zip folder. Then with the conda environment active:
```
python -m animl /example/folder --detector /path/to/megadetector --classifier /path/to/classifier --classlist /path/to/classlist.txt
```
You can use animl in this fashion on any image directory.
Finally you can use the animl.yml config file to specify parameters:
```
python -m animl /path/to/animl.yml
```
## Usage
### Inference
The functionality of animl can be parcelated into its individual functions to suit your data and scripting needs.
The sandbox.ipynb notebook has all of these steps available for further exploration.
1. It is recommended that you use the animl working directory for storing intermediate steps.
```python
from animl import file_management
workingdir = file_management.WorkingDirectory('/path/to/save/data')
```
2. Build the file manifest of your given directory. This will find both images and videos.
```python
files = file_management.build_file_manifest('/path/to/images', out_file=workingdir.filemanifest, exif=True)
```
3. If there are videos, extract individual frames for processing.
Select either the number of frames or fps using the argumments.
The other option can be set to None or removed.
```python
from animl import video_processing
allframes = video_processing.extract_frames(files, out_dir=workingdir.vidfdir, out_file=workingdir.imageframes,
parallel=True, frames=3, fps=None)
```
4. Pass all images into MegaDetector. We recommend [MDv5a](https://github.com/agentmorris/MegaDetector/releases/download/v5.0/md_v5a.0.0.pt).
The function parse_MD will convert the json to a pandas DataFrame and merge detections with the original file manifest, if provided.
```python
from animl import detect, megadetector
detector = megadetector.MegaDetector('/path/to/mdmodel.pt', device='cuda:0')
mdresults = detect.detect_MD_batch(detector, allframes, file_col="Frame", checkpoint_path=working_dir.mdraw, quiet=True)
detections = detect.parse_MD(mdresults, manifest=all_frames, out_file=workingdir.detections)
```
5. For speed and efficiency, extract the empty/human/vehicle detections before classification.
```python
from animl import split
animals = split.get_animals(detections)
empty = split.get_empty(detections)
```
6. Classify using the appropriate species model. Merge the output with the rest of the detections
if desired.
```python
from animl import classifiers, inference
classifier, class_list = classifiers.load_model('/path/to/model', '/path/to/classlist.txt', device='cuda:0')
animals = inference.predict_species(animals, classifier, class_list, file_col="Frame",
batch_size=4, out_file=working_dir.predictions)
manifest = pd.concat([animals if not animals.empty else None, empty if not empty.empty else None]).reset_index(drop=True)
```
7. (OPTIONAL) Save the Pandas DataFrame's required columns to csv and then use it to create json for TimeLapse compatibility
```python
from animl import timelapse, animl_results_to_md_results
csv_loc = timelapse.csv_converter(animals, empty, imagedir, only_animl = True)
animl_results_to_md_results.animl_results_to_md_results(csv_loc, imagedir + "final_result.json")
```
8. (OPTIONAL) Create symlinks within a given directory for file browser access.
```python
manifest = link.sort_species(manifest, working_dir.linkdir)
file_management.save_data(manifest, working_dir.results)
```
---
### Training
Training workflows are still under development. Please submit Issues as you come upon them.
1. Assuming a file manifest of training data with species labels, first split the data into training, validation and test splits.
This function splits each label proportionally by the given percentages, by default 0.7 training, 0.2 validation, 0.1 Test.
```python
from animl import split
train, val, test, stats = split.train_val_test(manifest, out_dir='path/to/save/data/', label_col="species",
percentage=(0.7, 0.2, 0.1), seed=None)
```
2. Set up training configuration file. Specify the paths to the data splits from the previous step. Example .yaml file:
```
seed: 28 # random number generator seed (long integer value)
device: cuda:0 # set to local gpu device
num_workers: 8 # number of cores
# dataset parameters
num_classes: 53 # might need to be adjusted based on the classes file
training_set: "/path/to/save/train_data.csv"
validate_set: "/path/to/save/validate_data.csv"
test_set: "/path/to/save/test_data.csv"
class_file: "/home/usr/machinelearning/Models/Animl-Test/test_classes.txt"
# training hyperparameters
architecture: "efficientnet_v2_m" # or choose "convnext_base"
image_size: [299, 299]
batch_size: 16
num_epochs: 100
checkpoint_frequency: 10
patience: 10 # remove from config file to disable
learning_rate: 0.003
weight_decay: 0.001
# overwrite .pt files
overwrite: False
experiment_folder: '/home/usr/machinelearning/Models/Animl-Test/'
# model to test
active_model: '/home/usr/machinelearning/Models/Animl-Test/best.pt'
```
class_file refers to a flle that contains index,label pairs. For example:<br>
test_class.txt
```
id,class,Species,Common
1,cat, Felis catus, domestic cat
2,dog, Canis familiaris, domestic dog
```
3. (Optional) Update train.py to include MLOPS connection.
4. Using the config file, begin training
```bash
python -m animl.train --config /path/to/config.yaml
```
Every 10 epochs (or define custom 'checkpoint_frequency'), the model will be checkpointed to the 'experiment_folder' parameter in the config file, and will contain performance metrics for selection.
5. Testing of a model checkpoint can be done with the "test.py" module. Add an 'active_model' parameter to the config file that contains the path of the checkpoint to test.
This will produce a confusion matrix of the test dataset as well as a csv containing predicted and ground truth labels for each image.
```bash
python -m animl.test --config /path/to/config.yaml
```
# Models
The Conservation Technology Lab has several models available for use.
* Southwest United States [v3](https://sandiegozoo.box.com/s/0mait8k3san3jvet8251mpz8svqyjnc3)
* [Amazon](https://sandiegozoo.box.com/s/dfc3ozdslku1ekahvz635kjloaaeopfl)
* [Savannah](https://sandiegozoo.box.com/s/ai6yu45jgvc0to41xzd26moqh8amb4vw)
* [Andes](https://sandiegozoo.box.com/s/kvg89qh5xcg1m9hqbbvftw1zd05uwm07)
* [MegaDetector](https://github.com/agentmorris/MegaDetector/releases/download/v5.0/md_v5a.0.0.pt)
Raw data
{
"_id": null,
"home_page": null,
"name": "animl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "camera trap, ecology, conservation, zoo, SDZWA, conservationtechlab",
"author": null,
"author_email": "Kyra Swanson <tswanson@sdzwa.org>",
"download_url": "https://files.pythonhosted.org/packages/2b/51/4afd71175f851bf9a9eef56e4e4e5050bd7d14eb7da9de3f2251ee53de18/animl-1.4.3.tar.gz",
"platform": null,
"description": "# animl-py\r\nAniML comprises a variety of machine learning tools for analyzing ecological data. This Python package includes a set of functions to classify subjects within camera trap field data and can handle both images and videos. \r\nThis package is also available in R: [animl](https://github.com/conservationtechlab/animl)\r\n\r\nTable of Contents\r\n1. Installation\r\n2. [Usage](#usage)\r\n3. [Models](#models)\r\n\r\n## Installation Instructions\r\n\r\nIt is recommended that you set up a conda environment for using animl.\r\nSee **Dependencies** below for more detail. You will have to activate the conda environment first each\r\ntime you want to run AniML from a new terminal.\r\n\r\n### From GitHub\r\n```\r\ngit clone https://github.com/conservationtechlab/animl-py.git\r\ncd animl-py\r\npip install -e .\r\n```\r\n\r\n### From PyPi\r\n```\r\npip install animl\r\n```\r\n\r\n### Dependencies\r\nWe recommend running AniML on GPU-enabled hardware. **If using an NVIDIA GPU, ensure driviers, cuda-toolkit and cudnn are installed.\r\nPyTorch will install these automatically if using a conda environment. \r\nThe /models/ and /utils/ modules are from the YOLOv5 repository. https://github.com/ultralytics/yolov5\r\n\r\nPython >= 3.9\r\n\r\nPython Package Dependencies\r\n* numpy >= 1.26.4\r\n* onnxruntime-gpu == 1.18.0\r\n* pandas >= 2.2.2\r\n* panoptes_client >= 1.6.2\r\n* pillow > 10.3.0\r\n* pyexiftool >= 0.5.6\r\n* opencv-python >= 4.10.0.82\r\n* scikit-learn >= 1.5.0\r\n* timm >= 1.0,\r\n* torch >= 2.2.2\r\n* torchvision >= 0.17.2\r\n* tqdm >= 4.66.4\r\n* wget >= 3.2\r\n\r\nAniml also depends on [exiftool](https://exiftool.org/index.html) for accessing file metadata.\r\n\r\n### Verify Install \r\nWe recommend you download the [examples](https://github.com/conservationtechlab/animl-py/blob/main/examples/Southwest.zip) folder within this repository.\r\nDownload and unarchive the zip folder. Then with the conda environment active:\r\n```\r\npython -m animl /path/to/example/folder\r\n```\r\nThis should create an Animl-Directory subfolder within\r\nthe example folder.\r\n\r\nOr, if using your own data/models, animl can be given the paths to those files:\r\nDownload and unarchive the zip folder. Then with the conda environment active:\r\n```\r\npython -m animl /example/folder --detector /path/to/megadetector --classifier /path/to/classifier --classlist /path/to/classlist.txt\r\n```\r\nYou can use animl in this fashion on any image directory.\r\n\r\nFinally you can use the animl.yml config file to specify parameters:\r\n```\r\npython -m animl /path/to/animl.yml\r\n```\r\n\r\n## Usage\r\n\r\n### Inference\r\nThe functionality of animl can be parcelated into its individual functions to suit your data and scripting needs.\r\nThe sandbox.ipynb notebook has all of these steps available for further exploration.\r\n\r\n1. It is recommended that you use the animl working directory for storing intermediate steps.\r\n```python\r\nfrom animl import file_management\r\nworkingdir = file_management.WorkingDirectory('/path/to/save/data')\r\n```\r\n\r\n2. Build the file manifest of your given directory. This will find both images and videos.\r\n```python\r\nfiles = file_management.build_file_manifest('/path/to/images', out_file=workingdir.filemanifest, exif=True)\r\n```\r\n\r\n3. If there are videos, extract individual frames for processing.\r\n Select either the number of frames or fps using the argumments.\r\n The other option can be set to None or removed.\r\n```python\r\nfrom animl import video_processing\r\nallframes = video_processing.extract_frames(files, out_dir=workingdir.vidfdir, out_file=workingdir.imageframes,\r\n parallel=True, frames=3, fps=None)\r\n```\r\n\r\n4. Pass all images into MegaDetector. We recommend [MDv5a](https://github.com/agentmorris/MegaDetector/releases/download/v5.0/md_v5a.0.0.pt).\r\n The function parse_MD will convert the json to a pandas DataFrame and merge detections with the original file manifest, if provided.\r\n\r\n```python\r\nfrom animl import detect, megadetector\r\ndetector = megadetector.MegaDetector('/path/to/mdmodel.pt', device='cuda:0')\r\nmdresults = detect.detect_MD_batch(detector, allframes, file_col=\"Frame\", checkpoint_path=working_dir.mdraw, quiet=True)\r\ndetections = detect.parse_MD(mdresults, manifest=all_frames, out_file=workingdir.detections)\r\n```\r\n\r\n5. For speed and efficiency, extract the empty/human/vehicle detections before classification.\r\n```python\r\nfrom animl import split\r\nanimals = split.get_animals(detections)\r\nempty = split.get_empty(detections)\r\n```\r\n6. Classify using the appropriate species model. Merge the output with the rest of the detections\r\n if desired.\r\n```python\r\nfrom animl import classifiers, inference\r\nclassifier, class_list = classifiers.load_model('/path/to/model', '/path/to/classlist.txt', device='cuda:0')\r\nanimals = inference.predict_species(animals, classifier, class_list, file_col=\"Frame\",\r\n batch_size=4, out_file=working_dir.predictions)\r\nmanifest = pd.concat([animals if not animals.empty else None, empty if not empty.empty else None]).reset_index(drop=True)\r\n```\r\n\r\n7. (OPTIONAL) Save the Pandas DataFrame's required columns to csv and then use it to create json for TimeLapse compatibility\r\n\r\n```python\r\nfrom animl import timelapse, animl_results_to_md_results\r\ncsv_loc = timelapse.csv_converter(animals, empty, imagedir, only_animl = True)\r\naniml_results_to_md_results.animl_results_to_md_results(csv_loc, imagedir + \"final_result.json\")\r\n```\r\n\r\n8. (OPTIONAL) Create symlinks within a given directory for file browser access.\r\n```python\r\nmanifest = link.sort_species(manifest, working_dir.linkdir)\r\nfile_management.save_data(manifest, working_dir.results)\r\n```\r\n\r\n---\r\n### Training\r\n\r\nTraining workflows are still under development. Please submit Issues as you come upon them.\r\n\r\n1. Assuming a file manifest of training data with species labels, first split the data into training, validation and test splits.\r\n This function splits each label proportionally by the given percentages, by default 0.7 training, 0.2 validation, 0.1 Test.\r\n```python\r\nfrom animl import split\r\ntrain, val, test, stats = split.train_val_test(manifest, out_dir='path/to/save/data/', label_col=\"species\",\r\n percentage=(0.7, 0.2, 0.1), seed=None)\r\n```\r\n\r\n2. Set up training configuration file. Specify the paths to the data splits from the previous step. Example .yaml file:\r\n```\r\nseed: 28 # random number generator seed (long integer value)\r\ndevice: cuda:0 # set to local gpu device \r\nnum_workers: 8 # number of cores\r\n\r\n# dataset parameters\r\nnum_classes: 53 # might need to be adjusted based on the classes file\r\ntraining_set: \"/path/to/save/train_data.csv\"\r\nvalidate_set: \"/path/to/save/validate_data.csv\"\r\ntest_set: \"/path/to/save/test_data.csv\"\r\nclass_file: \"/home/usr/machinelearning/Models/Animl-Test/test_classes.txt\" \r\n\r\n# training hyperparameters\r\narchitecture: \"efficientnet_v2_m\" # or choose \"convnext_base\"\r\nimage_size: [299, 299]\r\nbatch_size: 16\r\nnum_epochs: 100\r\ncheckpoint_frequency: 10\r\npatience: 10 # remove from config file to disable\r\nlearning_rate: 0.003\r\nweight_decay: 0.001\r\n\r\n# overwrite .pt files\r\noverwrite: False\r\nexperiment_folder: '/home/usr/machinelearning/Models/Animl-Test/'\r\n\r\n# model to test\r\nactive_model: '/home/usr/machinelearning/Models/Animl-Test/best.pt' \r\n```\r\n\r\nclass_file refers to a flle that contains index,label pairs. For example:<br>\r\ntest_class.txt\r\n```\r\nid,class,Species,Common\r\n1,cat, Felis catus, domestic cat\r\n2,dog, Canis familiaris, domestic dog\r\n```\r\n\r\n3. (Optional) Update train.py to include MLOPS connection. \r\n\r\n4. Using the config file, begin training\r\n```bash\r\npython -m animl.train --config /path/to/config.yaml\r\n```\r\nEvery 10 epochs (or define custom 'checkpoint_frequency'), the model will be checkpointed to the 'experiment_folder' parameter in the config file, and will contain performance metrics for selection.\r\n\r\n\r\n5. Testing of a model checkpoint can be done with the \"test.py\" module. Add an 'active_model' parameter to the config file that contains the path of the checkpoint to test.\r\n This will produce a confusion matrix of the test dataset as well as a csv containing predicted and ground truth labels for each image.\r\n```bash\r\npython -m animl.test --config /path/to/config.yaml\r\n```\r\n\r\n# Models\r\n\r\nThe Conservation Technology Lab has several models available for use. \r\n\r\n* Southwest United States [v3](https://sandiegozoo.box.com/s/0mait8k3san3jvet8251mpz8svqyjnc3)\r\n* [Amazon](https://sandiegozoo.box.com/s/dfc3ozdslku1ekahvz635kjloaaeopfl)\r\n* [Savannah](https://sandiegozoo.box.com/s/ai6yu45jgvc0to41xzd26moqh8amb4vw)\r\n* [Andes](https://sandiegozoo.box.com/s/kvg89qh5xcg1m9hqbbvftw1zd05uwm07)\r\n* [MegaDetector](https://github.com/agentmorris/MegaDetector/releases/download/v5.0/md_v5a.0.0.pt)\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Tools for classifying camera trap images",
"version": "1.4.3",
"project_urls": {
"Homepage": "https://github.com/conservationtechlab/animl-py"
},
"split_keywords": [
"camera trap",
" ecology",
" conservation",
" zoo",
" sdzwa",
" conservationtechlab"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e0cdebfd60e2cd4322a6c2a7e9dff4451c621584301b659faac088e329b01a24",
"md5": "4b36080c817ded4f0585912d5b1d18bb",
"sha256": "bc276e2c30562ecc9d69aee2303a9fad4136eb719f3f8ec59b60c84e474a15fa"
},
"downloads": -1,
"filename": "animl-1.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4b36080c817ded4f0585912d5b1d18bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 117326,
"upload_time": "2025-01-21T19:46:39",
"upload_time_iso_8601": "2025-01-21T19:46:39.788054Z",
"url": "https://files.pythonhosted.org/packages/e0/cd/ebfd60e2cd4322a6c2a7e9dff4451c621584301b659faac088e329b01a24/animl-1.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2b514afd71175f851bf9a9eef56e4e4e5050bd7d14eb7da9de3f2251ee53de18",
"md5": "6a664b9bcfda5e4933962d6536d7193f",
"sha256": "845a278f474b55af1777cf6ce7f785f2165b3f02b85c569c36195988e3f6dd5d"
},
"downloads": -1,
"filename": "animl-1.4.3.tar.gz",
"has_sig": false,
"md5_digest": "6a664b9bcfda5e4933962d6536d7193f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 107185,
"upload_time": "2025-01-21T19:46:41",
"upload_time_iso_8601": "2025-01-21T19:46:41.804981Z",
"url": "https://files.pythonhosted.org/packages/2b/51/4afd71175f851bf9a9eef56e4e4e5050bd7d14eb7da9de3f2251ee53de18/animl-1.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-21 19:46:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "conservationtechlab",
"github_project": "animl-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "animl"
}
JSON
