criscross 0.1.8

CPU-friendly sequence-only CRISCross off-target prediction (scikit-learn-style API). Ships compressed weights in-wheel; optional genome scanning via criscross.offinder needs a system OpenCL runtime (see README).

criscross

CPU-friendly sequence-only CRISCross off-target prediction with a scikit-learn-style API. The pretrained model weights ship inside the wheel (fp16 + zstd-compressed) so no extra downloads are required.

Install

pip install criscross

Optional marker extra (PEP 621 optional-dependencies): use pip install criscross[offinder] when you intend to use genome scanning. The extra carries no additional Python packages; OpenCL drivers are installed separately on the system. This pattern keeps the install line and documentation aligned. See the Python Packaging User Guide on optional dependencies.

CPU-only install (no CUDA libraries pulled in):

pip install criscross --extra-index-url https://download.pytorch.org/whl/cpu

If you plan to use criscross.offinder (important)

pip install criscross is enough for model inference (sequence_model.predict(...)).

If you also want genome scanning via criscross.offinder.prepare(...), you must install an OpenCL runtime on the machine. Cas-OFFinder requires OpenCL even in CPU mode. This follows the usual pattern for Python packages that wrap native tools: document system dependencies, expose optional extras for discoverability, and fail with a clear error when the feature is used without the runtime.

Check your environment before a long scan:

from criscross.offinder import check_opencl, opencl_setup_instructions

status = check_opencl()
print(status)
if not status["ok"]:
    print(opencl_setup_instructions())

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install pocl-opencl-icd

Conda (cross-platform option):

conda install -c conda-forge pocl ocl-icd-system

If OpenCL is missing, offinder.prepare(...) will fail with an error like clGetPlatformIDs Failed: -1001.

Quickstart

from criscross import sequence_model, sample_input_path
import pandas as pd

# Single datapoint (dict)
prob = sequence_model.predict({
    "Guide_sequence":   "GCTCGGGGACACAGGATCCCTGG",     # 23 nt
    "off_target_512nt": "GCAG...TGCC",                 # 512 nt, RC for - strand
    "strand_id":        1,                             # 1 for +, 0 for -
})
print(prob)   # float in [0, 1]

# Dataset (DataFrame or path to CSV)
df = pd.read_csv(sample_input_path())
probs = sequence_model.predict(df)           # -> np.ndarray, shape [N]
probs = sequence_model.predict(sample_input_path())  # same

Preparing inputs from a genome scan (Cas-OFFinder)

If you have guide RNA(s) and a reference genome FASTA, you can generate the Guide_sequence/off_target_512nt/strand_id table with Cas-OFFinder and feed it directly into sequence_model.predict(...).

from criscross import offinder, sequence_model

X = offinder.prepare(
    guide_rnas=["GCTCGGGGACACAGGATCCCTGG"],
    fasta="reference.fasta",  # path to your reference FASTA (file or directory)
    pam="NGG",            # default
    max_mismatches=6,     # default
)

# X is a DataFrame you can pass straight to criscross
probs = sequence_model.predict_proba(X)

Requirements:

• Cas-OFFinder needs an OpenCL runtime even for CPU mode. On Linux, the simplest CPU runtime is PoCL, e.g. conda install -c conda-forge pocl ocl-icd-system (or sudo apt install pocl-opencl-icd).
• Cas-OFFinder 2.4.1 is bundled inside the criscross wheel. To use a different binary, set the CAS_OFFINDER environment variable to its path (or pass cas_offinder_path=).

Accepted inputs to predict(X)

X	Returned
dict / pandas.Series with the 3 required keys	float
(guide, off_target_512nt, strand_id) 3-tuple	float
pandas.DataFrame with the 3 required columns	np.ndarray shape [N]
list of dicts	np.ndarray shape [N]
str / pathlib.Path pointing to a CSV with the 3 columns	np.ndarray shape [N]

Required columns/keys:

key	dtype	meaning
Guide_sequence	23nt string	sgRNA guide sequence
off_target_512nt	512nt string	candidate off-target window, already reverse-complemented for - strand
strand_id	int 0/1	1 for + strand, 0 for -

CLI

criscross predict --demo --out preds.csv
# or, with your own file:
criscross predict --csv path/to/your_input.csv --out preds.csv

If the input CSV also has a label column (0/1), AUPRC is printed to stderr.

Loading a custom checkpoint

from criscross import sequence_model
sequence_model.load("path/to/my_model.pt")           # fp32 raw .pt
sequence_model.load("path/to/my_model.pt.zst")       # zstd-compressed fp16

Inspecting the model

sequence_model.config()    # hyperparameters used to build CRISCross(**config)
sequence_model.metadata()  # versions, training-time test_auprc, input/output signature, seed

Citation

If you use this package in research, please cite the upstream CRISCross work. This package is a CPU-only, sequence-only repackaging of that model.