GRAPE

GRAPE: Genetic interaction Regression Analysis of Pairwise Effects is a tool for analyzing genetic interaction scores from dual-gene CRISPR multiplex screens using regression modeling.

Dependencies

To run this software, Python>=3.10.1 is required.

Software dependencies:

• numpy==1.26.2
• pandas==2.1.4
• scipy==1.11.4
• statsmodels==0.14.1
• scikit-learn==1.3.2

Installation

1. Clone the repository into a directory on your computer and cd into the root directory of the GRAPE package.

git clone https://github.com/hart-lab/GRAPE.git
cd GRAPE

2. Optional but recommended, create and start a virtual environment for the tool with:

python3 -m venv grenv
source grenv/bin/activate

3. Install using the setup.py file with:

pip3 install .

4. Verify installation:

grape -h

      You should see the following:

usage: grape [-h] [--version] -i INPUT_FILEPATH -o OUTPUT_DIRECTORY -c CONTROL_COLUMNS [CONTROL_COLUMNS ...] -t TARGET_GENE_FILE [-p OUTPUT_PREFIX] [--min-reads MIN_READS] [--pseudocount PSEUDOCOUNT] [--target-columns TARGET_COLUMNS [TARGET_COLUMNS ...]][--no-mean-replicates] [--no-groupby-targets] [--nonessential-gene-file NONESSENTIAL_GENE_FILE] [--genepair-del GENEPAIR_DEL] [--fit-intercept] [--half-window-size HALF_WINDOW_SIZE] [--monotone-filter]

Run GRAPE

options:
  -h, --help            show this help message and exit
  --version             print version and exit

Usage Example

grape \
  -i path/to/read_count_file.csv \
  -o output_directory/ \
  -c T0_R1 T0_R2 \
  -t path/to/target_gene_list.txt \
  --target-columns T18_R1 T18_R2 \
  -p T18

Input File Formats

1. Read Count file

The read count file is a tab-delimited text file containing raw counts for each gRNA across all replicates.

• gRNA: unique gRNA identifier (often GENE1_guideindex, GENE2_guideindex, GENE1_GENE2_guideindex).
• GENE: target genes and gene pairs for the gRNA. Dual-gene constructs are joined using the delimiter specified by --genepair-del (default is _).
• Sample columns: read counts for control and experimental replicates (column names must match arguments passed with -c and --target-columns).

Example:

gRNA	GENE	T0_R1	T0_R2	T18_R1	T18_R2
MAPK1_1	MAPK1	251	364	20	19
MAPK3_1	MAPK3	445	724	85	31
MAPK1_MAPK3_1	MAPK1_MAPK3	218	112	27	11
...

2. Target Gene file

A plain text file with one gene per line, listing the target genes to include in the regression analysis (exclude controls).

Example:

   MAPK1
   MAPK3
   ATM
   BLM
   ...

Required Arguments

Argument	Description
-i, --input-filepath	Input read count file
-o, --output-directory	Output directory path
-c, --control-columns	Space-separated list of control columns (e.g., T0 replicates)
-t, --target-gene-file	Path to target gene list file (excluding control genes), with one unique gene per line. For asymmetric library designs, combine your query and target gene lists into this single file, removing any duplicate genes.

Optional Arguments

Argument	Description	Default
-p, --output-prefix	Prefix for output files	None
--min-reads	Minimum read count threshold	0
--pseudocount	Pseudocount to avoid division by zero	1
--target-columns	Space-separated list of target columns to average	None
--no-mean-replicates	Disable averaging across replicates	False
--no-groupby-targets	Disable grouping by target gene	False
--nonessential-gene-file	Path to nonessential/reference gene list for mode-centering. If not provided, mode-centering is performed using the full fold-change distribution.	None
--genepair-del	Delimiter for gene pairs	"_"
--fit-intercept	Fit intercept in regression	False
--half-window-size	Half-window size for local variance estimation. If set to 0, a global variance is calculated instead of a local one. As a practical guideline, set this to ~1–2% of the total number of gene pairs in the library. Must NOT exceed the total number of pairwise constructs. See note below.	500
--monotone-filter	Apply monotonic filter to local std deviations	False

Choosing --half-window-size: Genetic interaction variance is not constant across the range of expected fold changes, so GRAPE estimates local variance using a sliding window of gene pairs (ordered by expected FC). Smaller windows better capture local variance but are noisier; larger windows are more stable but may smooth over real local structure. For more detail, see the Empirical Bayes Z-score normalization subsection of the Methods (under GRAPE) in the accompanying paper.

Output Files

After a successful run, GRAPE produces the following files in the specified output directory (with the user-defined prefix -p if provided):

1. grape_pairs_<prefix>.txt

Contains regression results and genetic interaction (GI) Z-scores for gene pairs.

• GENE_PAIR: gene pair names.
• fc_obs: observed mode-centered fold change for the gene pair.
• fc_exp: expected fold change predicted by the regression model for the gene pair (sum of single-gene coefficients for gene1 and gene2).
• GI_raw: unnormalized GI score, computed as fc_obs – fc_exp.
• g1_fc: single-gene fold change for the first gene in the pair.
• g2_fc: single-gene fold change for the second gene in the pair.
• dLFC: observed pairwise fold change – (observed fold change of gene1 + gene2).
• local_std: local standard deviation estimated from a sliding window.
• GI_Zscore: normalized genetic interaction score; negative values indicate synthetic genetic interactions, positive values indicate suppressing interactions.
• Pval_synth: p-value for detecting synthetic (negative) interactions.
• Padj_synth: Benjamini–Hochberg adjusted p-value for synthetic interactions.
• Pval_supp: p-value for detecting suppressor (positive) interactions.
• Padj_supp: Benjamini–Hochberg adjusted p-value for suppressor interactions.

2. grape_singles_<prefix>.txt

Contains regression outputs for single-gene effects.

• index: single gene names.
• fc_obs: observed mode-centered fold change for the gene.
• fc_exp: expected fold change predicted by the regression model for the gene. (single-gene coefficient beta)

3. modecenter_meanfc_<prefix>.txt

Contains the mode-centered mean fold-change values used as input for regression analysis.

• GENE: all genes and gene pairs.
• meanFC: gene-level fold-change, averaged across all replicates. This value is mode-centered based on the method specified by the user. By default, the mode is calculated from the full FC distribution. If a --nonessential-gene-file is provided, the mode is calculated from the fold-change distribution of non-essential genes.