Organism ID with Genome Stats

A Python command-line tool to identify organisms from images using the BioCLIP model and fetch genome statistics from NCBI. If a species lacks a sequenced genome, it falls back to the nearest sequenced relative. Built on mlfoundations/open_clip.

• Python 3.10+
• UV for package management
• Git
• Optional: NVIDIA GPU for faster inference (CPU works but is slower)

1. Clone the repository:

   git clone https://github.com/yourusername/organism-id-genome-stats.git
   cd organism-id-genome-stats

2. Install UV:

   pip install uv

3. Create and activate virtual environment:

   uv venv
   source .venv/bin/activate  # Unix/Mac
   .venv\Scripts\activate     # Windows

4. Install dependencies:

   uv sync

5. Configure .env:

   • Copy the example file:

     cp .env.example .env

   • Edit .env with your details:

     NCBI_API_KEY=your_ncbi_api_key_here  # Optional: Get from https://account.ncbi.nlm.nih.gov/
     ENTREZ_EMAIL=your.email@example.com  # Required for NCBI queries
     TAXA_LIST_PATH=taxa_list.txt         # Path to custom taxa list (edit taxa_list.txt)
     

   • Get an NCBI API key (optional) for faster queries (>3/sec) at https://account.ncbi.nlm.nih.gov/.

6. Optional: Customize taxa list:

   • Edit taxa_list.txt to add species names (one per line, e.g., Homo sapiens).
   • For broader coverage, download a taxa list from TreeOfLife-10M and update TAXA_LIST_PATH in .env.

Run the tool with an image file:

python organism_id.py path/to/image.jpg --genome

• Input: A JPG/PNG image of an organism (e.g., plant, animal).
• Output: Identified taxon (e.g., species name) and, with --genome, genome stats like size and gene count.
• Example output:

  Identified: Homo sapiens
  Genome stats for taxid 9606 (Homo sapiens):
    Total Length: 3099922541 bp
    Gene Count: 20000
  

1. Place a sample image (e.g., flower.jpg) in the repo.
2. Run:

   python organism_id.py flower.jpg --genome

• Add dependencies: uv add package-name (updates pyproject.toml).
• Test images: Use JPG/PNG files of organisms (e.g., from iNaturalist).
• Extend: Add Ensembl API support or expand taxa coverage.
• Troubleshooting:
  • Ensure .env has a valid ENTREZ_EMAIL.
  • Check internet for NCBI queries.
  • GPU issues? Ensure torch detects CUDA (python -c "import torch; print(torch.cuda.is_available())").

MIT (inherited from open_clip). BioCLIP model under Apache-2.0.