Merge pull request #74 from ArcInstitute/dev

refactor modules and add new analysis features

docs/source/assays.rst → docs/source/assays.md

@@ -1,7 +1,8 @@
-CRISPR Screen Assays
-======================
+# CRISPR Screen Assays
 
+```{eval-rst}  
 .. automodule:: screenpro.assays
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:
+```

docs/source/history.rst

@@ -2,11 +2,17 @@
 History
 =======
 
-0.4.0 (coming soon)
+1.0.0
+~~~~~
+* coming soon!
+
+0.4.0 - after (June 2024 - July 2024)
 ~~~~~~~~~~~~~~~~~~~
-* add command line interface
+* add command line interface, i.e. `screenpro --help`
+* rename `Counter` class to `GuideCounter` for code clarity
+* major bug fixes and improvements in code formatting
 
-0.2.11 - 0.3.0 (Apr 2024 - May 2024)
+0.2.11 - 0.3.5 (Apr 2024 - June 2024)
 ~~~~~~~~~~~~~~~~~
 * introduce `Counter` class as wrapper for `ngs` module
 * improve core functionalities for CLI

docs/source/index.rst

@@ -15,7 +15,7 @@ Welcome to ScreenPro2's documentation!
    assays
    ngs
    phenotype
-   plotting
+   visulize
    load
 
 .. toctree::

docs/source/load.md

@@ -0,0 +1,14 @@
+# Data loading module
+
+Set of python functions to read, write, and integrate CRISPR screening
+resources (e.g. guide RNA libraries) and datasets from different platforms 
+and analysis tools.
+
+___
+
+```{eval-rst}  
+.. automodule:: screenpro.load
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/source/ngs.md

@@ -0,0 +1,30 @@
+# NGS screen processing module
+
+`GuideCounter` class is a wrapper to run the functions for a
+CRISPR screen experiment.
+
+This module contains a set of python functions to process and analyze
+NGS files from CRISPR screens. Based on the type of CRISPR-Cas system
+used for the screen, the functions are divided into two classes:
+`Cas9` and `Cas12`.
+
+------------------------------------------------------------------------
+```{eval-rst}  
+.. automodule:: screenpro.ngs
+   :members:
+   :show-inheritance:
+```
+
+### Cas9 CRISPR-Cas system (single or dual sgRNA libraries)
+```{eval-rst}  
+.. automodule:: screenpro.cas9
+   :members:
+   :show-inheritance:
+```
+
+### Cas12 CRISPR-Cas system (multiplexed crRNA libraries)
+```{eval-rst}  
+.. automodule:: screenpro.cas12
+   :members:
+   :show-inheritance:
+```

docs/source/phenotype.md

@@ -0,0 +1,63 @@
+# Phenotype calculation modules
+
+Log ratio of $y$ vs $x$:
+
+$$\Delta=\log(\frac{\begin{bmatrix}{N_{y}}\end{bmatrix}_{(a,b)} + 1}{\begin{bmatrix}{N_{x}}\end{bmatrix}_{(a,b)} + 1})$$
+
+-   $y \rightarrow$ condition $x$ (e.g. treated samples)
+-   $x \rightarrow$ condition $y$ (e.g. $t_{0}$ samples)
+-   $a \rightarrow$ number of library elements with sgRNAs targeting $T$
+-   $b \rightarrow$ number of biological replicates, $R$ (e.g. 2 or 3)
+-   $N_{x}$ \| $N_{y} \rightarrow$ read counts normalized for sequencing
+    depth in condition $x$ or $y$
+
+Here is a formula for V3 library with single library element per gene
+(i.e. dual sgRNAs in one construct targeting same gene).
+
+Phenotype score for each $T$ comparing $y$ vs $x$:
+
+$$\text{PhenoScore}(T,x,y) =
+\left(
+\frac{
+\overline{\Delta_{(x,y)}}
+}{
+\text{median}( {\overline{\Delta_{(x_{ctrl},y_{ctrl})}}} )
+}
+\right)
+\times \frac{ 1 }{d_{growth}}$$
+
+-   $\overline{\Delta(x,y)} \rightarrow$ log ratio averaged across
+    replicates
+-   $T \rightarrow$ library elements with sgRNAs targeting $T$
+-   $d_{growth} \rightarrow$ growth factor to normalize the phenotype
+    score.
+
+Statistical test comparing $y$ vs $x$ per each target, $T$:
+
+$$\text{p-value}(T,x,y) = \text{t-test} \left(
+\begin{bmatrix}{N_{x}}\end{bmatrix}_{(a,b)},
+\begin{bmatrix}{N_{y}}\end{bmatrix}_{(a,b)}
+\right)$$
+
+(see this wikipedia page: [Dependent t-test for paired
+samples](https://en.wikipedia.org/wiki/Student%27s_t-test#Dependent_t-test_for_paired_samples))
+
+(see the link to the implemented tool: [ttest_rel, a scipy
+module](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.ttest_rel.html))
+
+> This is a test for the null hypothesis that two related or repeated
+> samples have identical average (expected) values.
+
+___
+
+```{eval-rst}  
+.. automodule:: screenpro.phenoscore
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: screenpro.phenostats
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/source/references.md

@@ -0,0 +1,20 @@
+# References
+
+-   @Herken2023 *bioRxiv* - Gilbert Lab
+-   @Hsiung2023 *bioRxiv* - Gilbert Lab
+-   @Han2020 *Nature* - Bassik Lab
+-   @Han2017 *Nature Biotechnology* - Bassik Lab
+-   @Tian2019 *Neuron* - Kampmann Lab
+-   @Horlbeck2016 *eLife* - Weissman Lab
+-   @Gilbert2014 *Cell* - Weissman Lab
+-   @Kampmann2014 *Nature Protocols* - Weissman Lab
+-   @Kampmann2013 *PNAS* - Weissman Lab
+-   @Bassik2013 *Cell* - Weissman Lab
+
+___
+
+```{eval-rst}  
+.. bibliography::
+    :all:
+
+```

docs/source/visualize.md

@@ -0,0 +1,12 @@
+# Visualize module
+
+Set of python classes and functions to enable visualizing CRISPR screening datasets.
+
+___
+
+```{eval-rst}  
+.. automodule:: screenpro.visualize
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

screenpro/__init__.py

@@ -1,14 +1,33 @@
-from . import plotting as pl
+## Copyright (c) 2022-2024 ScreenPro2 Development Team.
+## All rights reserved.
+## Gilbart Lab, UCSF / Arc Institute.
+## Multi-Omics Tech Center, Arc Insititue.
+
+'''ScreenPro2: A Python package for pooled CRISPR screens analysis
+
+This package contains several modules, including:
+
+**Main modules:**
+- ngs: tools for generating counts from NGS data
+- phenoscore: tools for calculating phenoscores
+- assays: wrappers for analyzing CRISPR screens data from standard assays
+
+**Additional modules:**
+- load: tools for loading and saving data
+- visualize: tools for visualizing data
+- datasets: API for accessing pre-processed datasets
+'''
+
 from . import phenoscore as ps
 
-from . import utils
 from . import ngs
+from . import assays
 from . import load
-from . import dashboard
+from . import visualize as viz
 
 from .ngs import GuideCounter
 from .assays import PooledScreens, GImaps
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 __author__ = "Abe Arab"
 __email__ = '[email protected]' # "[email protected]"

screenpro/__main__.py

@@ -1,3 +1,8 @@
+## Copyright (c) 2022-2024 ScreenPro2 Development Team.
+## All rights reserved.
+## Gilbart Lab, UCSF / Arc Institute.
+## Multi-Omics Tech Center, Arc Insititue.
+
 from .main import main
 
 main()