mohammedelabbas/na-butterflies-v3

---
license: mit
tags:
  - image-classification
  - butterflies
  - wildlife
  - timm
  - resnet50
datasets:
  - iNaturalist
metrics:
  - accuracy
---

# NA Butterflies v3 — ResNet50 Classifier

A ResNet50 image classifier for **105 North American butterfly species**,
trained on iNaturalist observations via the GBIF Darwin Core Archive
`northamerica_butterflies_106spp_2081177rec` (2026-02-27).

## Performance (test set — 492,261 images)

| Metric | Value |
|---|---|
| Weighted accuracy (instance-level) | **96.27%** |
| Macro accuracy (per-species average) | **88.86%** |

> **Weighted**: percentage of correctly classified images across the entire test set.
> **Macro**: average per-species accuracy, treating each species equally regardless of image count.

## Model details

- Architecture: `resnet50` via [timm](https://github.com/huggingface/pytorch-image-models)
- Input: 224×224 RGB, ImageNet normalization
- Output: 105-class softmax
- Checkpoint: `resnet50_20260311_020513_checkpoint.pt`
- Training date: 2026-03-11

## Usage

```python
import torch
import timm
import json
from huggingface_hub import hf_hub_download
from PIL import Image

# Load category map
cat_path = hf_hub_download("mohammedelabbas/na-butterflies-v3", "na_butterflies_v3_category_map.json")
with open(cat_path) as f:
    name_to_id = json.load(f)
id_to_name = {v: k for k, v in name_to_id.items()}

# Load model
model = timm.create_model("resnet50", pretrained=False, num_classes=105)
ckpt_path = hf_hub_download("mohammedelabbas/na-butterflies-v3", "resnet50_20260311_020513_checkpoint.pt")
state = torch.load(ckpt_path, map_location="cpu")["model_state_dict"]
model.load_state_dict(state)
model.eval()

# Transform (ImageNet standard)
data_config = timm.data.resolve_model_data_config(model)
transform = timm.data.create_transform(**data_config, is_training=False)

# Predict
image = Image.open("butterfly.jpg").convert("RGB")
tensor = transform(image).unsqueeze(0)
with torch.no_grad():
    probs = torch.softmax(model(tensor), dim=1)[0]
top5 = probs.topk(5)
for score, idx in zip(top5.values, top5.indices):
    print(f"{id_to_name[idx.item()]}: {score.item():.4f}")
```

## Species

<details>
<summary>All 105 species</summary>

- Aglais io

• Aglais milberti

• Amblyscirtes hegon

• Amblyscirtes vialis

• Anatrytone logan

• Ancyloxypha numitor

• Argynnis aphrodite

• Argynnis atlantis

• Argynnis cybele

• Asterocampa celtis

• Asterocampa clyton

• Battus philenor

• Boloria bellona

• Boloria myrina

• Burnsius communis

• Callophrys augustinus

• Callophrys gryneus

• Callophrys henrici

• Callophrys lanoraieensis

• Callophrys niphon

• Calycopis cecrops

• Carterocephalus mandan

• Cecropterus pylades

• Celastrina lucia

• Celastrina neglecta

• Celastrina serotina

• Cercyonis pegala

• Chlosyne harrisii

• Chlosyne nycteis

• Coenonympha california

• Colias eurytheme

• Colias interior

• Colias philodice

• Cupido comyntas

• Danaus plexippus

• Dione vanillae

• Epargyreus clarus

• Erora laeta

• Erynnis baptisiae

• Erynnis icelus

• Erynnis juvenalis

• Euphydryas phaeton

• Euphyes bimacula

• Euphyes conspicua

• Euphyes dion

• Euphyes vestris

• Euptoieta claudia

• Eurema lisa

• Feniseca tarquinius

• Glaucopsyche lygdamus

• Heraclides cresphontes

• Hesperia colorado

• Hesperia leonardus

• Hesperia sassacus

• Hylephila phyleus

• Junonia coenia

• Lethe anthedon

• Lethe appalachia

• Lethe eurydice

• Libytheana carinenta

• Limenitis archippus

• Limenitis arthemis

• Limochores mystic

• Limochores origenes

• Lon hobomok

• Lycaena hypophlaeas

• Megisto cymela

• Nymphalis antiopa

• Nymphalis l-album

• Oeneis jutta

• Papilio canadensis

• Papilio glaucus

• Papilio polyxenes

• Papilio solstitius

• Papilio troilus

• Parrhasius m-album

• Pholisora catullus

• Phyciodes cocyta

• Phyciodes tharos

• Pieris oleracea

• Pieris rapae

• Pieris virginiensis

• Poanes massasoit

• Poanes viator

• Polites egeremet

• Polites peckius

• Polites themistocles

• Polygonia comma

• Polygonia faunus

• Polygonia interrogationis

• Polygonia progne

• Polyommatus icarus

• Satyrium acadica

• Satyrium calanus

• Satyrium caryaevorus

• Satyrium liparops

• Satyrium titus

• Strymon melinus

• Tharsalea epixanthe

• Tharsalea hyllus

• Thymelicus lineola

• Vanessa atalanta

• Vanessa cardui

• Vanessa virginiensis

• Vernia verna