crispr-analysis-utils

Python utilities and command-line tools for analysing CRISPR perturbation screens.

Documentation: https://engreitzlab.github.io/crispr-analysis-utils/

Install

The package is not on PyPI yet. Install it from GitHub; pip brings numpy, pandas and pysam along:

pip install "crispr-analysis-utils @ git+https://github.com/EngreitzLab/crispr-analysis-utils"

Aligning guides also needs the GEM3 aligner, which pip cannot install. To get it, or to work on the package, clone the repository and use pixi: one environment holds the package, pysam and GEM3, on Linux (x86-64) and macOS. bioconda builds GEM3 for x86-64 only, so on Apple silicon pixi installs that environment as an Intel macOS (osx-64) one, which runs under Rosetta 2 (softwareupdate --install-rosetta installs it):

git clone https://github.com/EngreitzLab/crispr-analysis-utils.git
cd crispr-analysis-utils
pixi install         # the package, pysam and GEM3
pixi install -e dev  # the same, plus the development tools

Use

import pandas as pd

import crispr_analysis_utils as cau

counts = pd.DataFrame(
    {"sample_a": [100, 300], "sample_b": [50, 50]},
    index=["guide_1", "guide_2"],
)
cpm = cau.counts_per_million(counts)

Module	What it does
cau.accession	Accession ids for SpCas9 guides, encoded from the guide's own sequence
cau.counts_per_million	Counts-per-million normalization of count matrices
cau.guide_alignment	Where a guide library maps: each guide's exact sites, class, coordinates and target site (also the cau guide-alignment command)
cau.guide_annotation	What those sites hit: genic or intergenic, exon or intron, every promoter they sit in, the gene and transcript, and the distances to the nearest TSS and the gene's 5' end (also the cau guide-annotation command)
cau.element_mapping	Which element of a screen each guide tests, and which guides are controls (also the cau element-mapping command)
cau.igvf_export	The guide design in the IGVF per-guide metadata format, ready to submit or to feed the CRISPR pipeline (also the cau igvf-export command)
cau.mudata_builder	A sequenced channel's gene and guide counts as one MuData, annotated and laid out like the IGVF pipeline's object (also the cau mudata-builder command)

The cau command line tool comes with the package:

cau --help

Claude Code skills and agents

Every analysis module comes with a Claude Code skill that teaches Claude to use it: what to ask you before running anything, the real defaults, and how to read the outputs. Modules whose use is a long multi-step job can also get an agent. Install them one of two ways, not both (with both, every skill is listed twice):

• With the package, so the skills match the version you have installed:

  cau install-skills                   # into ~/.claude (or $CLAUDE_CONFIG_DIR)
  cau install-skills --target .claude  # into the current project only
  cau install-skills --list            # what is bundled

  After upgrading the package, run it again with --force.

• As a Claude Code plugin, which follows the main branch:

  /plugin marketplace add EngreitzLab/crispr-analysis-utils
  /plugin install crispr-analysis-utils@crispr-analysis-utils
  

  Update it with /plugin marketplace update crispr-analysis-utils, or add the marketplace as EngreitzLab/crispr-analysis-utils#<tag> to follow a tag instead of main.

Development

pixi run -e dev install-hooks  # once per clone: the commit and push hooks
pixi run -e dev test
pixi run -e dev lint           # every hook on every tracked file
pixi run -e docs docs          # the documentation site, served locally

pixi is the default environment for development: it is the only one with GEM3.

main changes only through pull requests whose CI checks pass. The conventions (4-space indentation, ruff check, no file over 512 KB, UPPERCASE commit verbs) are in the contributing guide and in CLAUDE.md.

License

MIT. See LICENSE.