Proto is not affiliated with Broad Institute, The Jackson Laboratory, and Yale University. This toolkit is open source and builds on the implementations produced by these organizations. Product names, logos, and trademarks are the property of their respective owners.

```bibtex theme={null} @article{gosai2024machine, title={Machine-guided design of cell-type-targeting cis-regulatory elements}, author={Gosai, Sager J. and Castro, Rodrigo I. and Fuentes, Natalia and Butts, John C. and Mouri, Kousuke and Alasoadura, Michael and Kales, Susan and Nguyen, Thanh Thanh L. and Noche, Ramil R. and Rao, Arya S. and Joy, Mary T. and Sabeti, Pardis C. and Reilly, Steven K. and Tewhey, Ryan}, journal={Nature}, volume={634}, pages={1211--1220}, year={2024}, doi={10.1038/s41586-024-08070-z}, url={https://doi.org/10.1038/s41586-024-08070-z} } @misc{gosai2024machine_zenodo, title={Machine-guided design of cell-type-targeting cis-regulatory elements}, author={Gosai, Sager and Castro, Rodrigo and Fuentes, Natalia and Butts, John and Mouri, Kousuke and Alasoadura, Michael and Kales, Susan and Nguyen, Thanh Thanh and Noche, Ramil and Rao, Arya and Joy, Mary Teena and Sabeti, Pardis and Reilly, Steven and Tewhey, Ryan}, year={2024}, publisher={Zenodo}, version={1.0}, doi={10.5281/zenodo.10698014}, url={https://doi.org/10.5281/zenodo.10698014}, note={Supplemental data and resources for the Nature article, including the Malinois model artifact} } ```

Copy citation

### Malinois Score (`malinois-score`) Scores one or more 200 bp DNA inserts and returns raw Malinois predictions keyed by requested cell type. #### API Reference

Source DNA insert sequence(s) to score. A single string is normalized to a one-item list. Sequences must contain only A, C, G, and T; the configured `seq_length` is checked at run time.

Source Cell-type outputs to return. Expected insert length before MPRA flank padding. Optional local override path to the Malinois model artifact tarball. Leave empty to download `artifact_url` into the managed weights cache. HTTPS URL used to provision the Malinois artifact. Optional MD5 checksum for the downloaded artifact. Optional local override directory containing unpacked artifact metadata. Leave empty to use the cache extraction directory. Number of sequences to process in each GPU batch. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device used for inference. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source Per-sequence Malinois predictions. DNA sequence that was scored. Length of the scored DNA sequence. Malinois predictions keyed by requested cell type name. Cell types included in each result's `scores`. Expected insert length used for MPRA flank padding. **Metrics** (one set per `results` item) | Metric | Type | Range | Availability | | ------- | ----- | --------- | -------------- | | `K562` | float | unbounded | when requested | | `HepG2` | float | unbounded | when requested | | `SKNSH` | float | unbounded | when requested |

#### Applications Use this tool to rank regulatory DNA designs by predicted activity in K562, HepG2, or SK-N-SH cells, screen MPRA insert candidates, or compare candidate designs before selecting sequences for downstream validation. #### Usage Tips * **Sequence length is fixed by default.** Inputs must match `seq_length`, which defaults to 200 bp. * **Cell type keys are canonical.** Request outputs as `K562`, `HepG2`, and `SKNSH`; `SKNSH` maps to the SK-N-SH model output. * **Batch size affects throughput.** Increase `batch_size` for many same-length inserts when GPU memory allows.

### Malinois Gradient (`malinois-gradient`) Computes a weighted differentiable activity objective and, by default, returns the gradient with respect to batched relaxed DNA logits. #### API Reference

Source Batched relaxed DNA sequence logits with shape `(B, L, 4)` in `A,C,G,T` order. Use `B=1` for a single design candidate. Softmax temperature used to relax logits.

Source Per-cell objective terms summed into one scalar loss. Malinois output to optimize. Available options: `K562`, `HepG2`, `SKNSH` `"max"` minimizes `1 - sigmoid((raw - center) / scale)`; `"min"` minimizes `sigmoid((raw - center) / scale)`. Available options: `max`, `min` Non-negative scalar applied before terms are summed. Raw Malinois score where the sigmoid is 0.5. Positive scale for the raw score transform. Expected insert length before Malinois flank padding. Optional local artifact tarball path. URL used to provision the Malinois artifact. Expected checksum for the downloaded artifact. Optional extracted Malinois artifact directory. Blend hard argmax one-hot (0) to softmax probabilities (1). Straight-through hard-forward coefficient. Run backward pass and return gradient. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device used for inference and backpropagation. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source Per-sample metric containers with scalar loss and raw cell-type scores. Per-objective-term metadata, including direction, weight, sigmoid transform, and weighted score. Name of the metric that best summarizes the result overall (e.g. `"avg_plddt"` for AlphaFold2). Used by downstream UI and reporting to pick a headline value. Concrete Metrics subclass tag; enables typed reconstruction after a serialization round-trip. Gradient tensor matching input DNA logits, or `None` when `compute_gradient=False`. Sum of per-sample weighted scalar objective values. Per-sample values are available in `sample_metrics`. Auxiliary metadata bundle from the standalone worker, including raw scores, objective-term metadata, and runtime relaxation parameters. DNA column ordering for logits and gradient. **Metrics** | Metric | Type | Range | Availability | | ------- | ----- | --------- | -------------- | | `loss` | float | ≥ 0.0 | always | | `K562` | float | unbounded | when requested | | `HepG2` | float | unbounded | when requested | | `SKNSH` | float | unbounded | when requested |

#### Applications Use this tool inside gradient-based DNA design loops to maximize activity in an on-target cell type while minimizing activity in off-target cell types. It is designed for optimizer calls rather than final biological validation. #### Usage Tips * **Logits are batched.** Pass logits with shape `B x L x 4` in `A,C,G,T` order; use `B=1` for a single candidate. * **Directions are per term.** `direction="max"` minimizes `1 - sigmoid(raw)` and `direction="min"` minimizes `sigmoid(raw)` after centering and scaling. * **Soft/hard mixing controls relaxation.** `soft=1.0, hard=0.0` is fully soft; increasing `hard` uses a straight-through hard-forward estimator.