Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,275 @@
----
-license: mit
----
+---
+license: mit
+language:
+- en
+library_name: ultralytics
+tags:
+- biology
+- CV
+- images
+- animals
+- object-detection
+- YOLO
+- fine-tuned
+datasets:
+- custom_animal_dataset
+metrics:
+- precision
+- recall
+- mAP50
+- mAP50-95
+---
+
+# Model Card for Fine-Tuned YOLOv11m Animal Detection Model
+
+This model is a fine-tuned version of YOLOv11m optimized for detection and classification of wildlife from low-altitude drone imagery. It has been trained to identify zebras (Plains and Grevy's), giraffes, Persian onagers, and African Painted dogs with high accuracy across diverse environmental conditions.
+
+## Model Details
+
+### Model Description
+
+- **Developed by:** Jenna Kline
+- **Model type:** Object Detection and Classification
+- **Language(s) (NLP):** Not applicable (Computer Vision model)
+- **License:** CC0-1.0
+- **Fine-tuned from model:** YOLOv11m (ultralytics/yolo11m.pt)
+
+### Model Sources
+
+- **Repository:** https://github.com/Imageomics-ABC-edu/final-project-kenyan-ungulates-with-wilddroneeu
+- **Paper:** [MMLA](https://arxiv.org/abs/2504.07744)
+- **Demo:** TO DO
+
+## Uses
+
+### Direct Use
+
+This model is designed for direct use in wildlife monitoring applications, ecological research, and biodiversity studies. It can:
+
+- Detect and classify zebras, giraffes, onagers, and dogs in camera trap images
+- Monitor wildlife populations in their natural habitats
+- Assist researchers in automated processing of large image datasets
+- Support biodiversity assessments by identifying species present in field surveys
+
+The model can be used by researchers, conservationists, wildlife managers, and citizen scientists to automate and scale up wildlife monitoring efforts, particularly in African ecosystems.
+
+### Downstream Use
+
+This model can be integrated into larger ecological monitoring systems including:
+- Automated camera trap processing pipelines
+- Wildlife conservation monitoring platforms
+- Ecological research workflows
+- Citizen science applications for species identification
+- Environmental impact assessment tools
+
+### Out-of-Scope Use
+
+This model is not suitable for:
+- Medical diagnosis or human-related detection tasks
+- Security or surveillance applications targeting humans
+- Applications where errors in detection could lead to harmful conservation decisions without human verification
+- Real-time detection systems requiring extremely low latency (model prioritizes accuracy over speed)
+- Detection of species not included in the training set (only trained on zebras, giraffes, onagers, and dogs)
+
+## Bias, Risks, and Limitations
+
+- **Species representation bias:** The model may perform better on species that were well-represented in the training data.
+- **Environmental bias:** Performance may degrade in environmental conditions not represented in the training data (e.g., extreme weather, unusual lighting).
+- **Morphological bias:** Similar-looking species may be confused with one another (particularly among equids like zebras and onagers).
+- **Geospatial bias:** The model may perform better in biomes similar to those present in the training data, particularly African savanna environments.
+- **Seasonal bias:** Detection accuracy may vary based on seasonal appearance changes in animals or environments.
+- **Technical limitations:** Performance depends on image quality, with reduced accuracy in low-resolution, blurry, or poorly exposed images.
+
+### Recommendations
+
+Users (both direct and downstream) should be made aware of the risks, biases, and limitations of the model:
+- Always verify critical detections with human review, especially for rare species or conservation decision-making
+- Consider confidence scores when evaluating detections
+- Be cautious when applying the model to new geographic regions or habitats not represented in training data
+- Periodically validate model performance on new data to ensure continued reliability
+- Consider fine-tuning the model on domain-specific data when applying to new regions or species
+
+## How to Get Started with the Model
+
+Use the code below to get started with the model:
+
+```python
+from ultralytics import YOLO
+
+# Load the model
+model = YOLO('path/to/your/model.pt')
+
+# Run inference on an image
+results = model('path/to/image.jpg')
+
+# Process results
+for result in results:
+    boxes = result.boxes  # Boxes object for bounding boxes outputs
+    for box in boxes:
+        x1, y1, x2, y2 = box.xyxy[0]  # get box coordinates
+        conf = box.conf[0]  # confidence score
+        cls = int(box.cls[0])  # class id
+        class_name = model.names[cls]  # class name (Zebra, Giraffe, Onager, or Dog)
+        print(f"Detected {class_name} with confidence {conf:.2f} at position {x1:.1f}, {y1:.1f}, {x2:.1f}, {y2:.1f}")
+        
+# Visualize results
+results[0].plot()
+```
+
+## Training Details
+
+### Training Data
+
+Dataset is available at [Hugging Face](https://huggingface.co/collections/imageomics/wildwing-67f572d3ba17fca922c80182). See /data/dataset.yaml for details on train/val/test splits.
+
+### Training Procedure 
+
+#### Preprocessing
+
+- Images were resized to 640x640 pixels (as specified in the training script)
+- Standard YOLOv11 augmentation pipeline was applied
+
+#### Training Hyperparameters
+
+The model was trained with the following hyperparameters as specified in the training script:
+- **Base model:** YOLOv11m (yolo11m.pt)
+- **Epochs:** 100
+- **Image size:** 640
+- **Dataset configuration:** Custom YAML file defining 4 classes (Zebra, Giraffe, Onager, Dog)
+- **Training regime:** Default YOLOv11 training parameters
+
+```python
+# Training script
+from ultralytics import YOLO
+
+model = YOLO("yolo11m.pt")
+results = model.train(
+    data="/data/dataset.yaml",
+    epochs=100,
+    imgsz=640,
+)
+```
+
+#### Speeds, Sizes, Times 
+
+- **Training hardware:** [Your GPU/CPU specifications]
+- **Training time:** [Duration]
+- **Model size:** [Size in MB]
+- **Inference speed:** [FPS on specific hardware]
+
+## Evaluation
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+The model was evaluated on a held-out test set located at `/fs/ess/PAS2136/Kenya-2023/yolo_benchmark/HerdYOLO/data/images/test` containing:
+- [Number] test images with instances of Zebra, Giraffe, Onager, and Dog
+- [Any other relevant testing data details]
+
+#### Factors
+
+The evaluation disaggregated performance by:
+- Species (Zebra, Giraffe, Onager, Dog)
+- [Other evaluation factors if applicable]
+
+#### Metrics
+
+The model was evaluated using standard object detection metrics:
+- **Precision:** Ratio of true positives to all predicted positives
+- **Recall:** Ratio of true positives to all actual positives (ground truth)
+- **mAP50:** Mean Average Precision at IoU threshold of 0.5
+- **mAP50-95:** Mean Average Precision averaged over IoU thresholds from 0.5 to 0.95
+
+### Results
+
+#### Summary
+
+- **Overall mAP50:** [Value]
+- **Overall mAP50-95:** [Value]
+- **Per-class performance:**
+  - Zebra: mAP50 = [Value], Precision = [Value], Recall = [Value]
+  - Giraffe: mAP50 = [Value], Precision = [Value], Recall = [Value]
+  - Onager: mAP50 = [Value], Precision = [Value], Recall = [Value]
+  - Dog: mAP50 = [Value], Precision = [Value], Recall = [Value]
+
+## Model Examination
+
+- **Confusion analysis:** [Any notable confusion between classes, such as between Zebra and Onager]
+- **Failure cases:** [Specific conditions where the model performs less reliably]
+- **Interpretability findings:** [Any insights from model interpretation techniques]
+
+## Environmental Impact
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://doi.org/10.48550/arXiv.1910.09700).
+
+- **Hardware Type:** [GPU model]
+- **Hours used:** [Number]
+- **Cloud Provider:** [Provider name or local]
+- **Compute Region:** [Region]
+- **Carbon Emitted:** [Amount] kg CO₂eq
+
+## Technical Specifications
+
+### Model Architecture and Objective
+
+- Base architecture: YOLOv11m
+- Detection heads: Standard YOLOv11 architecture
+- Classes: 4 (Zebra, Giraffe, Onager, Dog)
+
+### Compute Infrastructure
+
+#### Hardware
+
+- **Training:** [GPU/CPU details]
+- **Inference:** Tested on [range of devices]
+- **Minimum requirements:** [Specifications]
+
+#### Software
+
+- Python 3.8+
+- PyTorch 2.0+
+- Ultralytics YOLOv11 framework
+- CUDA 11.7+ (for GPU acceleration)
+
+## Citation
+
+**BibTeX:**
+
+```
+@software{your_name_yolo11m_2025,
+  author = {Your Name},
+  title = {Fine-Tuned YOLOv11m Animal Detection Model},
+  version = {1.0.0},
+  year = {2025},
+  url = {https://huggingface.co/your-username/your-model-name}
+}
+```
+
+## Acknowledgements
+
+This work was supported by both the [Imageomics Institute](https://imageomics.org) and the [AI and Biodiversity Change (ABC) Global Center](http://abcresearchcenter.org). The Imageomics Institute is funded by the US National Science Foundation's Harnessing the Data Revolution (HDR) program under [Award #2118240](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2118240) (Imageomics: A New Frontier of Biological Information Powered by Knowledge-Guided Machine Learning). The ABC Global Center is funded by the US National Science Foundation under [Award No. 2330423](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2330423&HistoricalAwards=false) and Natural Sciences and Engineering Research Council of Canada under [Award No. 585136](https://www.nserc-crsng.gc.ca/ase-oro/Details-Detailles_eng.asp?id=782440). This model draws on research supported by the Social Sciences and Humanities Research Council.
+
+Additional support was provided by the National Ecological Observatory Network (NEON), a program sponsored by the National Science Foundation and operated under cooperative agreement by Battelle Memorial Institute. This material is based in part upon work supported by the National Science Foundation through the NEON Program.
+
+Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation, Natural Sciences and Engineering Research Council of Canada, or Social Sciences and Humanities Research Council.
+
+## Glossary
+
+- **YOLO:** You Only Look Once, a family of real-time object detection models
+- **mAP:** mean Average Precision, a standard metric for evaluating object detection models
+- **IoU:** Intersection over Union, a measure of overlap between predicted and ground truth bounding boxes
+- **Onager:** Also known as the Asian wild ass, a species of equid native to Asia
+- **YOLOv11m:** The medium-sized variant of the YOLOv11 architecture
+
+## More Information
+
+[Any additional information you'd like to include]
+
+## Model Card Authors
+
+Jenna Kline, The Ohio State University
+
+## Model Card Contact
+
+kline.377 at osu dot edu