Skip to content

CLAUDE.md

Latest commit

 

History

History
197 lines (152 loc) · 7.62 KB

CLAUDE.md

File metadata and controls

197 lines (152 loc) · 7.62 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

pLannotate is a command-line tool and web server for annotating engineered plasmid sequences. The tool performs multi-method searches using BLAST, DIAMOND, and Infernal to identify features in DNA sequences and generate interactive visualizations.

Core Architecture

The main application is organized into focused modules:

  • plannotate/main.py - CLI entry point using Typer with commands:
    • plannotate batch - Main annotation command
    • plannotate setupdb - Database setup
    • plannotate makedb - Build a custom BLAST/DIAMOND database (plus descriptions and a ready-to-run YAML) from a FASTA and optional CSV
    • plannotate yaml - Configuration export
    • plannotate databases - Print the installed database manifest
    • plannotate streamlit - Launch the optional web app (requires the server extra)
  • plannotate/annotate.py - Candidate collection and final annotation pipeline
  • plannotate/models.py - Construct, Feature, conversions, and output methods
  • plannotate/_tools/ - BLAST, DIAMOND, and Infernal integrations
  • plannotate/_concurrency.py - Core allocation and ordered thread-pool execution
  • plannotate/_curation.py - Curated selection-marker, origin copy-number, global feature-suppression, and composite-reference-region lookups (data/data/selection_markers.csv, data/data/ori_copy_number.csv, data/data/feature_suppressions.csv, data/data/composite_reference_regions.csv, data/data/fragment_suppression_regions.csv). Tables are keyed on source accessions, so they are pinned to one database bundle; run python tools/curation_pins.py check after setupdb to surface drift. Exact SnapGene composite-region validation also requires blastdbcmd
  • plannotate/_nested.py - Conservative nested-feature policy shared by runtime annotation and the audit/viewer. Pair overrides live in data/data/nested_feature_overrides.csv; source-level embedded-component intervals live in data/data/composite_reference_regions.csv, and manually adjudicated low-specificity fragment intervals live in data/data/fragment_suppression_regions.csv
  • plannotate/_package_data.py - Packaged assets and database configuration
  • plannotate/_database_builder.py - Build custom BLAST/DIAMOND databases from a FASTA (behind plannotate makedb)
  • plannotate/bokeh_plot.py - Plot preparation, geometry, and Bokeh rendering
  • plannotate/streamlit_app.py - Optional Streamlit web front end, built on Construct

Database Architecture

The tool uses multiple annotation databases configured via YAML:

  • SnapGene - Curated plasmid features (BLAST nucleotide search)
  • Swiss-Prot - Protein sequences (DIAMOND protein search)
  • FPbase - Fluorescent proteins (DIAMOND protein search)
  • Rfam - RNA families (Infernal covariance model search)

Database locations and search parameters are defined in plannotate/data/data/databases.yml.

Key Data Flow

  1. validation.validate_file() reads one FASTA or GenBank record.
  2. Construct calls annotate.annotate().
  3. annotate.annotate() runs configured sources and finalizes their candidates.
  4. _filter.filter_and_clean_hits() scores hits and resolves overlaps.
  5. Construct exports GenBank, CSV, or optional Bokeh HTML.

Development Commands

Environment Setup

# Create conda environment from file
conda env create -f environment.yml
conda activate plannotate

# Install the package and development dependencies
pip install -e '.[test,lint]'

# Download required databases
plannotate setupdb

Testing

# Fast suite
pytest

# Include external tools and downloaded databases
pytest --run-integration

# GitHub skips the integration job when PLANNOTATE_DATABASE_URL is unavailable;
# run it locally before merging any annotation-output change.

# Static checks
python -m mypy
ruff check .
ruff format --check .

Code Quality

# Format code
ruff format .

# Lint code  
ruff check .

Python comments

Python comments should be clear and concise, following the project's style guidelines. Use docstrings for module, class, and function documentation. Inline comments should explain complex logic or decisions; explain they "why" rather than the "what" of the code. Start inline comments with a lowercase letter and keep them brief. Use # TODO for tasks that need to be addressed later, and # NOTE for particularly thorny or important points that may not be immediately obvious.

Example Usage

# Basic annotation
plannotate batch -i input/plasmid.fa -o output/ --html

# Annotation with custom database
plannotate batch -i input/plasmid.fa -o output/ --yaml-file custom_db.yaml

# Linear DNA annotation
plannotate batch -i input/linear.fa --linear --csv

Database Builds

Runtime annotation uses only the Python standard library for scheduling. Snakemake is an optional database-build dependency: pip install -e '.[databases]'. The build workflow lives under plannotate/gather_databases/; it is not part of the runtime annotation path.

The supported Python entry point for rebuilding the bundle is plannotate.build_databases(output_directory, cores=...).

Python API

The tool can be imported and used programmatically:

from plannotate.annotate import annotate
from plannotate import Construct

# Direct annotation
hits_df = annotate(sequence_string, linear=False)

# Full pipeline with outputs
construct = Construct(seq=sequence, linear=False)
gbk_content = construct.to_genbank()
html_content = construct.to_html()
csv_df = construct.to_csv()

Important Implementation Notes

Database Dependencies

  • Databases must be downloaded via plannotate setupdb before first use
  • Custom databases can be configured by modifying the YAML configuration
  • External tools required: BLAST+, DIAMOND, and Infernal

File Format Support

  • Input: FASTA (.fa, .fasta, .fas, .fna), GenBank (.gbk, .gb, .gbf, .gbff)
  • Output: GenBank, HTML (interactive Bokeh plots), CSV

Performance Considerations

  • Annotation permits nested features of different types and applies the curated nested-feature policy introduced in #83
  • Large sequences may require significant processing time
  • DIAMOND searches are faster than BLAST for protein sequences

Logging

  • Library modules use standard logging.getLogger(__name__) loggers.
  • The CLI configures the plannotate logger; --verbose enables debug output.

Bash Command Formatting Style

When writing shell commands in Snakemake rules, follow these strict guidelines:

Required Format

# Correct format - call Python scripts, never inline code
python3 example.py \
    --input {input.seq} \
    --output {output.hits} \
    --database {params.db_name} \
>& {log}

Formatting Rules

  • NEVER use python3 -c with inline code in shell directives
  • All Python code must be in separate scripts in scripts/ directory
  • Use backslashes (\) for line continuation
  • Align parameters vertically with proper indentation
  • Place each parameter on its own line for long commands
  • Use >& {log} for log redirection (combines stdout and stderr)
  • Keep commands readable and well-structured

Script Requirements

  • All scripts in scripts/ should use proper argparse for command-line arguments
  • Scripts should have clear error handling and logging
  • Each script should have a single, focused purpose
  • Use docstrings and follow the project's Python style guidelines

This architecture emphasizes modularity, with each component having a single focused responsibility and clear interfaces between modules.