Metadata-Version: 2.4
Name: screenviz
Version: 0.2.6
Summary: A tool to visualize the results of 1D CRISPR screens
Author: noam teyssier
License: MIT License
        
        Copyright (c) 2023 Noam Teyssier
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dash>=2.18.1
Requires-Dist: idea-bio>=0.2.5
Requires-Dist: numpy>=1.26.4
Requires-Dist: pandas>=2.2.3
Requires-Dist: plotly>=5.24.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: scipy>=1.14.1
Requires-Dist: dash-daq>=0.5.0
Dynamic: license-file

# screenviz

A CRISPR screen visualization toolkit.

## Installation

The easiest way to get started with `screenviz` is to use [`uv`](https://docs.astral.sh/uv/)

```bash
uv tool install screenviz
screenviz --help
```

Or if you prefer using just pip

```bash
pip install screenviz
```

## Usage

This program is meant to be run from the commandline and will generate interactive visualizations for your CRISPR screen results.

### Quality Control

This is used to check the quality of your screen mapping.
It generates visualizations to inspect various quality control metrics of your screen.
The input of this subcommand is a `tsv` file with the following table structure: [sgrna, gene, sample1, sample2, ...].
This is the output of [`sgcount`](https://github.com/noamteyssier/sgcount) used to generate the mapping.

It will create a webserver that is tied to your terminal and will output a link to the visualizations which you can open in your browser.

```bash
screenviz qc -i mapping.tsv
```

### Results

This is used to generate a single interactive integrated visualization suite of your screen results. It will generate visualizations for the sgRNA and gene level results.

The input of this subcommand are two `tsv` files which are output of `crispr_screen`: `*.sgrna_results.tsv` and `*.gene_results.tsv`.

It will create a webserver that is tied to your terminal and will output a link to the visualizations which you can open in your browser.

```bash
screenviz results -s results.sgrna_results.tsv -g results.gene_results.tsv
```

### Gene Enrichment

To explore the gene-level enrichment of your analysis - specifically the classic volcano plot (log-fold-change on the x-axis and negative log p-value on the y-axis) -
you can use the `screenviz gene` subcommand:

```bash
screenviz gene -i results.gene_results.tsv
```

If your screen result is an output of `crispr_screen`, the defaults of the program will immediately generate a visualization which will be written to an `*.html` file
on your computer. You can open this file in your favorite browser and explore the results interactively there.

For a better visualization, pass in the `.yaml` configuration file produced from your `crispr_screen` run.
This will automatically determine if `RRA` or `INC` was used and show appropriate thresholds.

```bash
screenviz gene -i results.gene_results.tsv -c results.screenviz.yaml
```

If your screen result is an output of a different program, you will need to tell `screenviz` what the names of the columns in your data represent.

If your result is from `MAGeCK` you can do the following:

```bash
# Left side of the volcano
screenviz gene \
    -i sample1.gene_summary.txt \
    -g "id" \
    -f "neg|lfc" \
    -p "neg|fdr" \
    -t "neg|fdr"

# Right side of the volcano
screenviz gene \
    -i sample1.gene_summary.txt \
    -g "id" \
    -f "pos|lfc" \
    -p "pos|fdr" \
    -t "pos|fdr"
```

Check out what the arguments are with the help command:

```bash
screenviz gene --help
```

### sgRNA Enrichment

To explore the sgrna-level enrichment of your analysis - specifically the classic volcano plot (log-fold-change on the x-axis and negative log p-value on the y-axis) -
you can use the `screenviz sgrna` subcommand:

```bash
screenviz sgrna -i results.sgrna_results.tsv
```

If your screen result is an output of `crispr_screen`, the defaults of the program will immediately generate a visualization which will be written to an `*.html` file
on your computer. You can open this file in your favorite browser and explore the results interactively there.

If your screen result is an output of a different program, you will need to tell `screenviz` what the names of the columns in your data represent.

If your result is from `MAGeCK` you can do the following:

```bash
screenviz sgrna \
    -i sample1.sgrna_summary.txt \
    -g "Gene" \
    -f "LFC" \
    -p "FDR" \
    -t "FDR"
```

### Comparison

To compare the results of two different analysis methods you can use the `screenviz compare` subcommand

```bash
screenviz compare \
    -i results_a.gene_results.tab \
    -I results_b.gene_results.tab
```

This will generate a scatter plot to compare the calculated FDR values of two different results.

To compare between `crispr_screen` and `MAGeCK` one can do:

```bash

# compare depleted genes
screenviz compare \
    -i results.gene_results.tsv \
    -I sample1.gene_summary.txt \
    -x fdr_low \
    -X "neg|fdr" \
    -m gene \
    -M id \
    -t fdr_low \
    -T "neg|fdr"

# compare enriched genes
screenviz compare \
    -i results.gene_results.tsv \
    -I sample1.gene_summary.txt \
    -x fdr_high \
    -X "pos|fdr" \
    -m gene \
    -M id \
    -t fdr_high \
    -T "pos|fdr"
```
