How anamul-hoque-emtiaj/crismer works
Project type & purpose (from README + tree)
This is a Python-based ML research/tooling project for genome-wide CRISPR-Cas9 off-target prediction and optimization, centered on a transformer model (“transformer-based interpretable deep learning approach”). It looks like a CLI/scriptable library + notebooks project rather than a web service.
The repository contains:
• A core package-like folder: crismer-opti/ with Python modules, models, utils, and scripts
• Pretrained artifacts: crismer-opti/models/*.pth, *.pkl and top-level models/IDT.pth
• Datasets for training/benchmarking: datasets/*.csv
• Notebooks for parameter exploration and test scenarios: *.ipynb
• A shell script referencing an external off-target search tool: crismer-opti/script/casoffinder_genome.sh
• Example inputs: crismer-opti/example/*
• A test genome FASTA: crismer-opti/data/test_genome.fa
So your “system” is primarily a local ML pipeline: input sequences → candidate generation / enumeration (possibly via Cas-OFFinder) → feature/encoding → transformer inference → postprocessing/interpretability → optimization/ranking outputs.
File structure → infer architectural components
Key files/folders and what they likely represent architecturally:
Core application / orchestration
• crismer-opti/CRISMER.py
• Likely the main entrypoint: runs prediction/optimization pipeline end-to-end (read sgRNAs, generate candidates, call model, produce outputs).
Domain logic / modules
• crismer-opti/crismer_modules.py
• Likely contains model wrappers, training/inference helpers, sequence encoding, scoring, interpretability components.
• crismer-opti/utils.py
• Likely general utilities: IO, preprocessing, metrics, helpers.
ML model artifacts
• crismer-opti/models/
• change_site_circleseq_model.pth (transformer or similar)
• bin_weights.pkl, minmax_scaler.pkl (calibration, scaling, binning)
• Top-level models/IDT.pth
• Another model/checkpoint (maybe a baseline or alternative architecture).
External tool integration
• crismer-opti/script/casoffinder_genome.sh
• Implies a dependency on Cas-OFFinder (or similar) for genome-wide enumeration of potential off-target sites.
Data assets
• datasets/*.csv
• Benchmark/training datasets (GUIDE-seq, CIRCLE-seq, SITE-seq, etc.)
• crismer-opti/data/test_genome.fa
• Small genome for testing local runs.
Outputs
• Level 1 (high-level): major blocks and data flow
• Level 2 (drill-down): expand the “CRISMER pipeline” block into submodules and artifacts
This yields maximum accuracy and detail without pretending this is a deployed service.
Entrypoints / execution modes (left side)
Two entry paths:
Notebook workflow
• test-scenario-1.ipynb, test-scenario-2.ipynb, crismer-opti-params.ipynb
Script/CLI workflow
• crismer-opti/CRISMER.py (primary)
Both feed into the same underlying library modules.
Inputs (explicit, because this is a scientific pipeline)
• sgRNA inputs
• crismer-opti/example/example_sgRNAs.txt
• crismer-opti/example/example.csv
• Reference genome
• crismer-opti/data/test_genome.fa (and “user-provided genome FASTA” as a generalized node)
Candidate off-target enumeration (external integration)
A distinct block:
• Cas-OFFinder (external binary/tool) invoked via:
• crismer-opti/script/casoffinder_genome.sh
Data flow:
• Genome + sgRNA → Cas-OFFinder → list of candidate sites (potential off-targets)
Preprocessing / feature engineering
“sequence encoding + feature scaling” as a stage implemented by:
• crismer_modules.py
• utils.py
Artifacts it loads:
• crismer-opti/models/minmax_scaler.pkl
• Possibly bin_weights.pkl
Data flow:
• Candidate sites → encoded tensors/features → normalized/scaled features → model-ready inputs
ML inference core (transformer model)
A core block:
• Transformer Off-target Prediction Model
• Loads: crismer-opti/models/change_site_circleseq_model.pth
• Possibly alternative model: models/IDT.pth (show as “optional/alternate checkpoint”)
Outputs:
• Prediction scores / probabilities / risk ranking per candidate site
Interpretability + optimization / ranking
Because the README emphasizes “interpretable” and “optimization”, make this its own block (even if implementation is in crismer_modules.py):
• Postprocessing: thresholds, bins, calibration (ties to bin_weights.pkl)
• Interpretability outputs (attribution, attention summaries, motif importance, etc.—label generically if not sure)
• Optimization: suggest improved guides / rank guides by off-target risk
Outputs (right side)
• Ranked off-target list (CSV/TSV)
• Ranked sgRNA recommendations
• Plots/reports (especially in notebooks)
That notebooks might output figures inline.
Datasets (training/benchmark, not necessarily runtime)
datasets/*.csv in a “Data Sources (offline)” section:
• guideseq.csv, circleseq_all.csv, etc.
Them to:
• “Model development/training” (even if training scripts aren’t visible here, it’s still architecturally true that these datasets relate to model creation)
And connect “Model development” to the generated artifacts:
• .pth, .pkl
Architectural patterns / principles to highlight
• Pipeline architecture (sequential stages)
• Separation of concerns
• Orchestration (CRISMER.py)
• Domain logic (crismer_modules.py)
• Utilities (utils.py)
• External enumeration tool (casoffinder_genome.sh)
• Model artifacts (models/*.pth, *.pkl)
• Two-phase lifecycle
• Offline: dataset → training → saved checkpoints/scalers
• Online/local runtime: inputs → enumeration → preprocessing → inference → ranking
“Don’t overthink it” detail maximization checklist (specific to this repo)
• CRISMER.py (main orchestrator)
• crismer_modules.py (core logic)
• utils.py (helpers)
• script/casoffinder_genome.sh (integration layer)
• models/change_site_circleseq_model.pth
• models/minmax_scaler.pkl
• models/bin_weights.pkl
• top-level models/IDT.pth (alternate model)
• datasets/*.csv (offline data)
• example/* and data/test_genome.fa (sample inputs)
• *.ipynb notebooks (interactive entrypoints)