ScreenPro2 0.5.0__py3-none-any.whl

screenpro/dashboard/__init__.py

@@ -0,0 +1,293 @@
+## Copyright (c) 2022-2025 ScreenPro2 Development Team.
+## All rights reserved.
+## Gilbart Lab, UCSF / Arc Institute.
+## Multi-Omics Tech Center, Arc Insititue.
+
+
+import numpy as np
+import pandas as pd
+import bokeh
+import bokeh.plotting
+
+
+class DataDashboard:
+
+    def __init__(self):
+        pass
+
+    def _new_plot(self,title,tooltips,width,height,toolbar_location):
+        
+        TOOLS = "box_select,box_zoom,lasso_select,reset,save,wheel_zoom,pan,copy,undo,redo,reset,examine,fullscreen"
+
+        # create a new plot with a specific size
+        p = bokeh.plotting.figure(
+            sizing_mode="stretch_width",
+            tools=TOOLS,
+            tooltips=tooltips,
+            toolbar_location=toolbar_location,
+            title=title,
+            max_width=width, height=height, 
+        )
+        p.toolbar.autohide = True
+        return p
+    
+    def _get_html(self, p):
+        html = bokeh.embed.file_html(p, bokeh.resources.CDN, "")
+        return html
+
+
+class DrugScreenDashboard(DataDashboard):
+    
+    def __init__(
+            self, screen, treated, untreated, 
+            t0='T0', threshold=3, ctrl_label='negative_control', 
+            run_name='auto', 
+            score_col='score', pvalue_col='pvalue'
+            ):
+        self.screen = screen
+        self.threshold = threshold
+        self.ctrl_label = ctrl_label
+        self.run_name = run_name
+        self.gamma_score_name = f'gamma:{untreated}_vs_{t0}'
+        self.rho_score_name = f'rho:{treated}_vs_{untreated}'
+        self.df = self._prep_data(screen, score_col=score_col, pvalue_col=pvalue_col)
+        self.plots = {}
+        super().__init__()
+
+    def _prep_data(self,screen, score_col='score', pvalue_col='pvalue'):
+
+        gamma = screen.getPhenotypeScores(
+            phenotype_name=self.gamma_score_name,
+            run_name=self.run_name,
+            threshold=self.threshold,
+            ctrl_label=self.ctrl_label,
+            score_col=score_col,
+            pvalue_col=pvalue_col
+        )
+
+        rho = screen.getPhenotypeScores(
+            phenotype_name=self.rho_score_name,
+            run_name=self.run_name,
+            threshold=self.threshold,
+            ctrl_label=self.ctrl_label,
+            score_col=score_col,
+            pvalue_col=pvalue_col
+        )
+
+        df = pd.DataFrame({
+            'target': rho['target'],
+            'rho_score': rho['score'],
+            'rho_pvalue': rho[pvalue_col],
+            'rho_label': rho['label'],
+            '-log10(rho_pvalue)': np.log10(rho[pvalue_col]) * -1,
+            'gamma_score': gamma.loc[rho.index,'score'],
+            'gamma_pvalue': gamma.loc[rho.index,pvalue_col],
+            'gamma_label': gamma.loc[rho.index,'label'],
+            '-log10(gamma_pvalue)': np.log10(gamma.loc[rho.index,pvalue_col]) * -1,
+        })
+
+        return df
+
+    def _plot_scatter(
+            self,
+            x_source,y_source,
+            xaxis_label,yaxis_label,
+            up_hit, down_hit,
+            hit_label_col,
+            x_min, x_max, y_min, y_max,
+            title='',
+            dot_size=1,
+            width=500, height=400,
+            toolbar_location='below',
+            legend_loc="top_left",
+        ):
+        df = self.df.copy()
+        if y_max == 'auto': y_max = df[y_source].max() * 1.2
+        if x_max == 'auto': x_max = df[x_source].max() * 1.2
+        if y_min == 'auto': y_min = df[y_source].min() * 1.2
+        if x_min == 'auto': x_min = df[x_source].min() * 1.2
+
+        TOOLTIPS = [
+            ("name", "@target"),
+            ("rho score", "@rho_score"),
+            ("rho p-value", "@rho_pvalue"),
+            ("rho label", "@rho_label"),
+            ("gamma score", "@gamma_score"),
+            ("gamma p-value", "@gamma_pvalue"),
+            ("gamma label", "@gamma_label"),        
+        ]
+
+        p = self._new_plot(
+            title=title,
+            tooltips=TOOLTIPS,
+            width=width,
+            height=height,
+            toolbar_location=toolbar_location
+        )
+
+        source = bokeh.models.ColumnDataSource(
+            df.loc[df[hit_label_col] == 'target_non_hit',:]
+        )
+        p.scatter(
+            x=x_source, y=y_source,
+            source=source,
+            alpha=0.2,
+            size=dot_size * 1.2, 
+            color='gray', 
+            legend_label='target_non_hit',
+            name='circles'
+        )
+
+        # size_mapper=bokeh.models.LinearInterpolator(
+        #     x=[df['1/gamma_score'].min(),df['1/gamma_score'].max()],
+        #     y=[1,100]
+        # )
+
+        source = bokeh.models.ColumnDataSource(
+            df.loc[df[hit_label_col] == up_hit,:]
+        )
+        p.scatter(
+            x=x_source, y=y_source,
+            source=source,
+            alpha=0.8,
+            size=dot_size * 1.2, 
+            # size={'field':'1/gamma_score','transform':size_mapper},
+            color='#fcae91',
+            legend_label=up_hit,
+            name='circles'
+        )
+        
+        source = bokeh.models.ColumnDataSource(
+            df.loc[df[hit_label_col] == down_hit,:]
+        )
+        p.scatter(
+            x=x_source, y=y_source,
+            source=source,
+            alpha=0.8,
+            # size={'field':'1/gamma_score','transform':size_mapper},
+            size=dot_size * 1.2, 
+            color='#bdd7e7',
+            legend_label=down_hit,
+            name='circles'
+        )
+        
+        source = bokeh.models.ColumnDataSource(
+            df.loc[df[hit_label_col] == self.ctrl_label,:]
+        )
+        p.scatter(
+            x=x_source, y=y_source,
+            source=source,
+            alpha=0.2,
+            size=dot_size*0.8, 
+            color='silver',
+            legend_label=self.ctrl_label,
+            name='circles'
+        )
+        
+        # Set x-axis and y-axis labels
+        p.xaxis.axis_label = xaxis_label
+        p.xaxis.axis_label_text_font_style = 'normal'
+        p.yaxis.axis_label = yaxis_label
+        p.yaxis.axis_label_text_font_style = 'normal'
+
+        # Set x-axis limits
+        p.x_range.start = x_min
+        p.x_range.end = x_max
+
+        # Set y-axis limits
+        p.y_range.start = y_min
+        p.y_range.end = y_max
+
+        # Add legend
+        if legend_loc == False or legend_loc == None:
+            p.legend.visible = False
+        else:
+            p.legend.location = legend_loc
+
+        p.title.text = title
+        p.title.align = 'center'
+        p.title.text_font_size = '12pt'
+        p.title.text_font_style = 'bold'
+
+        return p
+    
+    def RhoVolcanoPlot(
+        self,
+        x_source='rho_score', y_source='-log10(rho_pvalue)',
+        xaxis_label='phenotype score',
+        yaxis_label='-log10(p-value)',
+        up_hit='resistance_hit', down_hit='sensitivity_hit',
+        hit_label_col='rho_label',
+        x_min=-2.5, x_max=2.5, y_min=0, y_max='auto',
+        return_html=True,
+        **kwargs
+        ):
+        p = self._plot_scatter(
+            x_source, y_source,
+            xaxis_label, yaxis_label,
+            up_hit, down_hit,
+            hit_label_col,
+            x_min, x_max, y_min, y_max,
+            **kwargs
+        )
+
+        if return_html:
+            return self._get_html(p)
+                    
+        self.plots.update(
+            {'RhoVolcanoPlot': p}
+        )
+
+    def GammaVolcanoPlot(
+        self,
+        x_source='gamma_score', y_source='-log10(gamma_pvalue)',
+        xaxis_label='phenotype score',
+        yaxis_label='-log10(p-value)',
+        up_hit='up_hit', down_hit='essential_hit',
+        hit_label_col='gamma_label',
+        x_min=-2.5, x_max=2.5, y_min=0, y_max='auto',
+        return_html=True,
+        **kwargs
+        ):
+        p = self._plot_scatter(
+            x_source, y_source,
+            xaxis_label, yaxis_label,
+            up_hit, down_hit,
+            hit_label_col,
+            x_min, x_max, y_min, y_max,
+            **kwargs
+        )
+
+        if return_html:
+            return self._get_html(p)
+        
+        self.plots.update(
+            {'GammaVolcanoPlot': p}
+        )
+    
+    def RhoGammaScatter(
+        self,
+        x_source='rho_score', y_source='gamma_score',
+        xaxis_label='rho score',
+        yaxis_label='gamma score',
+        up_hit='resistance_hit', down_hit='sensitivity_hit',
+        hit_label_col='rho_label',
+        x_min=-2.5, x_max=2.5, y_min=-2.5, y_max=2.5,
+        return_html=True,
+        **kwargs
+        ):
+        p = self._plot_scatter(
+            x_source, y_source,
+            xaxis_label, yaxis_label,
+            up_hit, down_hit,
+            hit_label_col,
+            x_min, x_max, y_min, y_max,
+            **kwargs
+        )
+
+        if return_html:
+            return self._get_html(p)
+        
+        self.plots.update(
+            {'GammaRhoScatter': p}
+        )

screenpro/load.py

@@ -0,0 +1,239 @@
+## Copyright (c) 2022-2024 ScreenPro2 Development Team.
+## All rights reserved.
+## Gilbart Lab, UCSF / Arc Institute.
+## Multi-Omics Tech Center, Arc Insititue.
+
+"""Load module
+
+Functions to load screen datasets and sgRNA library tables.
+"""
+
+import pickle
+import pandas as pd
+
+
+def load_cas9_sgRNA_library(library_path, library_type, sep='\t', index_col=0, protospacer_length=19, verbose=True, **args):
+    '''Load Cas9 sgRNA library table for single or dual guide design.
+    '''
+    library = pd.read_csv(
+        library_path,
+        sep=sep,
+        index_col=index_col,
+        **args
+    )
+
+    ## Evaluate library table and reformat columns for downstream analysis
+    # I would like to name the target column 'target' if it is named 'gene'!
+    #TODO: Add option to keep sublibrary column!
+
+    if library_type == "single_guide_design":
+        eval_columns = ['target', 'sgID', 'protospacer', 'sequence']
+
+        # reformating columns as needed
+        if 'gene' in library.columns:
+            # rename gene column to target
+            library = library.rename(columns={'gene': 'target'})
+        if 'sequence' in library.columns and 'protospacer' not in library.columns:
+            library.rename(columns={'sequence': 'protospacer'}, inplace=True)
+        if 'sgId' in library.columns:
+            library.rename(columns={'sgId': 'sgID'}, inplace=True)
+
+        # Upper case protospacer sequences
+        library['protospacer'] = library['protospacer'].str.upper()
+
+        protospacer_col = 'protospacer'
+        in_length = _check_protospacer_length(library, 'protospacer')
+        if in_length == protospacer_length:
+            pass
+        elif in_length > protospacer_length:
+            if verbose: print(f"Trimming protospacer sequences in '{protospacer_col}' column.")
+            library = _trim_protospacer(
+                library, protospacer_col, 
+                '5prime', 
+                in_length - protospacer_length
+            )
+
+        elif in_length < protospacer_length:
+            raise ValueError(
+                f"Input protospacer length for '{protospacer_col}' is less than {protospacer_length}"
+            )
+        
+        # write `sequence` column as `protospacer` (after trimming)
+        library['sequence'] = library['protospacer']
+
+        for col in eval_columns:
+            if col not in library.columns:
+                raise ValueError(f"Column '{col}' not found in library table.")
+        
+        library = library[eval_columns]
+
+    elif library_type == "dual_guide_design":
+        eval_columns = [
+            'target', 'sgID_AB',
+            'sgID_A', 'protospacer_A', 
+            'sgID_B', 'protospacer_B', 
+            'sequence'
+        ]
+        
+        # reformating columns as needed
+        if 'gene' in library.columns:
+            # rename gene column to target
+            library = library.rename(columns={'gene': 'target'})
+
+        # Upper case protospacer sequences
+        library['protospacer_A'] = library['protospacer_A'].str.upper()
+        library['protospacer_B'] = library['protospacer_B'].str.upper()
+
+        # # TODO: Enable trimming of protospacer sequences through command line arguments.
+        for protospacer_col in ['protospacer_A', 'protospacer_B']:
+            in_length = _check_protospacer_length(library, protospacer_col) 
+            if in_length == protospacer_length:
+                pass
+            elif in_length > protospacer_length:
+                if verbose: print(f"Trimming protospacer sequences in '{protospacer_col}' column.")
+                library = _trim_protospacer(
+                    library, protospacer_col, 
+                    '5prime', 
+                    in_length - protospacer_length
+                )
+
+            elif in_length < protospacer_length:
+                raise ValueError(
+                    f"Input protospacer length for '{protospacer_col}' is less than {protospacer_length}"
+                )
+    
+        # write `sequence` column as `protospacer_A;protospacer_B` (after trimming)
+        library['sequence'] = library['protospacer_A'] + ';' + library['protospacer_B']
+
+        for col in eval_columns:
+            if col not in library.columns:
+                raise ValueError(f"Column '{col}' not found in library table.")
+
+        library = library[eval_columns]
+
+    else:
+        raise ValueError(f"Invalid library type: {library_type}. Please choose 'single_guide_design' or 'dual_guide_design'.")
+    
+    if verbose: print("Library table successfully loaded.")
+
+    return library
+
+
+def loadScreenProcessingData(experimentName, collapsedToTranscripts=True, premergedCounts=False):
+    """
+    Load ScreenProcessing outputs
+    (see original code `here <https://github.com/mhorlbeck/ScreenProcessing/blob/master/screen_analysis.py#L70>`__)
+    Input files:
+        * `*_librarytable.txt` => library table
+        * `*_mergedcountstable.txt` => merged counts table
+        * `*_phenotypetable.txt` => phenotype table
+
+    Parameters:        
+        experimentName (str): name of the experiment
+        collapsedToTranscripts (bool): whether the gene scores are collapsed to transcripts
+        premergedCounts (bool): whether the counts are premerged
+    
+    Returns:
+        dict: dictionary of dataframes
+    """
+    # dict of dataframes
+    dataDict = {
+        'library': pd.read_csv(
+            experimentName + '_librarytable.txt', 
+            sep='\t', 
+            header=0, 
+            index_col=0
+        ),
+        'counts': pd.read_csv(
+            experimentName + '_mergedcountstable.txt', 
+            sep='\t', 
+            header=list(range(2)),
+            index_col=list(range(1))
+        ),
+        'phenotypes': pd.read_csv(
+            experimentName + '_phenotypetable.txt', 
+            sep='\t', 
+            header=list(range(2)),
+            index_col=list(range(1))
+        )
+    }
+
+    if premergedCounts:
+        # add premerged counts
+        dataDict['premerged counts'] = pd.read_csv(
+            experimentName + '_rawcountstable.txt', 
+            sep='\t',
+            header=list(range(3)), 
+            index_col=list(range(1))
+        )
+
+    if collapsedToTranscripts:
+        # add transcript scores
+        dataDict['transcript scores'] = pd.read_csv(
+            experimentName + '_genetable.txt', 
+            sep='\t', 
+            header=list(range(3)),
+            index_col=list(range(2))
+        )
+        dataDict['gene scores'] = pd.read_csv(
+            experimentName + '_genetable_collapsed.txt', 
+            sep='\t',
+            header=list(range(3)), 
+            index_col=list(range(1))
+        )
+    else:
+        # add gene scores
+        dataDict['gene scores'] = pd.read_csv(
+            experimentName + '_genetable.txt', 
+            sep='\t', 
+            header=list(range(3)),
+            index_col=list(range(1))
+        )
+
+    return dataDict
+
+
+def _check_protospacer_length(library, protospacer_col):
+    lengths = list(set(library[protospacer_col].str.len()))
+    if len(lengths) > 1:
+        raise ValueError(f"Protospacer lengths are not uniform: {lengths}")
+    else:
+        length = lengths[0]
+        return length
+
+
+def _trim_protospacer(library, protospacer_col, trim_side, trim_len):
+    if trim_side == '5prime':
+        library[protospacer_col] = library[protospacer_col].str[trim_len:].str.upper()
+    
+    elif trim_side == '3prime':
+        library[protospacer_col] = library[protospacer_col].str[:-trim_len].str.upper()
+    
+    return library
+
+
+def _write_screen_pkl(screen, name):
+    """
+    Write AnnData object to a pickle file
+    
+    Parameters:
+        screen (object): ScreenPro object to save
+        name (str): name of the output file (.pkl extension will be added)
+    """
+    file_name = f'{name}.pkl'
+    with open(file_name, 'wb') as file:
+        pickle.dump(screen, file)
+        print(f'Object successfully saved to "{file_name}"')
+
+
+def _read_screen_pkl(name):
+    """
+    Read ScreenPro object from a pickle file
+    
+    Parameters:
+        name (str): name of the input file (.pkl extension will be added)
+    """
+    file_name = f'{name}.pkl'
+    with open(file_name, 'rb') as f:
+        screen = pickle.load(f)
+    return screen