idtdna/hdr-model repository overview

⁠HDR_Predictive_Model

A containerized toolkit for turning SelfTarget/FORECasT CRISPR/Cas9 repair predictions into a compact feature vector and scoring it with a trained homology‑directed‑repair (HDR) model.

The tool does two things:

1. Feature annotation — parses FORECasT *_predictedindelsummary.txt and *_predictedreads.txt files into a single‑row feature CSV (deletion/insertion frequencies, entropy, templated‑insertion %, MMEJ %, etc.).
2. Model scoring — loads a statically‑baked, calibrated scikit‑learn pipeline (HDR_Model.joblib) and predicts an HDR class + probability from those features.

Both steps run inside a single Docker image via one entry point (run_hdr.py).

⁠What the features mean

Feature annotation emits a single row per gRNA with these columns (0–100 scale unless noted):

⁠Quick start (Docker)

To start you will need to ensure you have run the FORECasT tool and generated the following two files for the gRNA(s) of interest:

1. results_predictedindelsummary.txt
2. results_predictedreads.txt

For simplicity of the docker command we will assume both of these are in the active working directory. To end-to-end annotate features and do predictions for the gRNA using these indel profiles, run the following:

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -v "$PWD:/data" \
  hdr-model:latest pipeline \
  -s /data/results_predictedindelsummary.txt \
  -r /data/results_predictedreads.txt \
  -n NAME \
  -o /data/NAME_scored.csv

The primary output NAME_scored.csv can be named using the -n parameter and contains the following information:

Name,prediction,probability
NAME,1,0.87

---

## Command reference

The entrypoint `run_hdr.py` exposes three subcommands.

### `features` — annotation only

```bash
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/data" \
  hdr-model:latest features \
  -s /data/results_forecastpredictedindelsummary.txt \
  -r /data/results_forecastpredictedreads.txt \
  -n NAME \
  -o /data/NAME_features.csv

⁠predict — score an existing feature CSV with the baked‑in model

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/data" \
  hdr-model:latest predict \
  -i /data/NAME_features.csv \
  -o /data/NAME_scored.csv \
  --id-column Name \
  --threshold 0.5

⁠pipeline — features → predict in one call

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/data" \
  hdr-model:latest pipeline \
  -s /data/results_forecastpredictedindelsummary.txt \
  -r /data/results_forecastpredictedreads.txt \
  -n NAME \
  -o /data/NAME_scored.csv \
  --features-out /data/NAME_features.csv   # optional: keep intermediate CSV

⁠How prediction is derived

prediction = 1  if  probability >= threshold   (default threshold = 0.5)
prediction = 0  otherwise

The probability is produced by a calibrated classifier, so it is intended to be read as a genuine likelihood rather than an uncalibrated score. A value near 0.5 means the model is uncertain; values near 0 or 1 indicate confident calls.

⁠What the positive class represents

The positive class corresponds to the target column the model was trained on — which in this case was the class of being in the top 60% of HDR gRNA. This corresponds to how the model was used in the original manuscript.

⁠Choosing a threshold

--threshold trades precision vs. recall and does not require retraining — it only re‑bins the same probabilities produced by the model:

Because probability is written to every row, you can re‑threshold downstream in a spreadsheet or pandas without re‑running the container as well if desired.

⁠License & Usage

© Integrated DNA Technologies, Inc. (IDT). All rights reserved.

This tool is provided free of charge for academic, non‑commercial research use only. Commercial use of any kind requires explicit prior written consent from IDT.

To request commercial‑use permission, please contact the author: 📧 [email protected]⁠