Merge pull request #11 from earmingol/new_version

New version - v0.5.11

README.md

@@ -86,7 +86,7 @@ associated with Memory. This may happen when the tensor is big enough to make th
        *bioRxiv*, (2020). **DOI: 10.1101/2020.11.22.392217**
 
 
-- **Tensor-cell2cell** should be cited using this pre-print in bioRxiv:
+- **Tensor-cell2cell** should be cited using this research article:
     - Armingol E., Baghdassarian H., Martino C., Perez-Lopez A., Aamodt C., Knight R., Lewis N.E.
-     [Context-aware deconvolution of cell-cell communication with Tensor-cell2cell](https://doi.org/10.1101/2021.09.20.461129)
-     *bioRxiv*, (2021). **DOI: 10.1101/2021.09.20.461129**
+     [Context-aware deconvolution of cell-cell communication with Tensor-cell2cell](https://doi.org/10.1038/s41467-022-31369-2)
+     *Nat. Commun.* **13**, 3665 (2022). **DOI: 10.1038/s41467-022-31369-2**

cell2cell/__init__.py

@@ -14,4 +14,4 @@
 from cell2cell import tensor
 from cell2cell import utils
 
-__version__ = "0.5.10"
+__version__ = "0.5.11"

cell2cell/analysis/pipelines.py

@@ -87,6 +87,13 @@ class BulkInteractions:
         For example, '&' is the complex_sep for a list of ligand-receptor pairs
         where a protein partner could be "CD74&CD44".
 
+    complex_agg_method : str, default='min'
+        Method to aggregate the expression value of multiple genes in a
+        complex.
+
+        - 'min' : Minimum expression value among all genes.
+        - 'mean' : Average expression value among all genes.
+
     verbose : boolean, default=False
         Whether printing or not steps of the analysis.
 
@@ -115,6 +122,14 @@ class BulkInteractions:
         For example, '&' is the complex_sep for a list of ligand-receptor pairs
         where a protein partner could be "CD74&CD44".
 
+
+    complex_agg_method : str
+        Method to aggregate the expression value of multiple genes in a
+        complex.
+
+        - 'min' : Minimum expression value among all genes.
+        - 'mean' : Average expression value among all genes.
+
     ref_ppi : pandas.DataFrame
         Reference list of protein-protein interactions (or ligand-receptor pairs) used
         for inferring the cell-cell interactions and communication. It could be the
@@ -193,7 +208,8 @@ class BulkInteractions:
     '''
     def __init__(self, rnaseq_data, ppi_data, metadata=None, interaction_columns=('A', 'B'),
                  communication_score='expression_thresholding', cci_score='bray_curtis', cci_type='undirected',
-                 sample_col='sampleID', group_col='tissue', expression_threshold=10, complex_sep=None, verbose=False):
+                 sample_col='sampleID', group_col='tissue', expression_threshold=10, complex_sep=None,
+                 complex_agg_method='min', verbose=False):
         # Placeholders
         self.rnaseq_data = rnaseq_data
         self.metadata = metadata
@@ -202,6 +218,7 @@ def __init__(self, rnaseq_data, ppi_data, metadata=None, interaction_columns=('A
         self.analysis_setup = dict()
         self.cutoff_setup = dict()
         self.complex_sep = complex_sep
+        self.complex_agg_method = complex_agg_method
         self.interaction_columns = interaction_columns
 
         # Analysis setup
@@ -238,6 +255,7 @@ def __init__(self, rnaseq_data, ppi_data, metadata=None, interaction_columns=('A
                                                               cutoff_setup=self.cutoff_setup,
                                                               analysis_setup=self.analysis_setup,
                                                               complex_sep=complex_sep,
+                                                              complex_agg_method=complex_agg_method,
                                                               interaction_columns=self.interaction_columns,
                                                               verbose=verbose)
 
@@ -442,6 +460,13 @@ class SingleCellInteractions:
         For example, '&' is the complex_sep for a list of ligand-receptor pairs
         where a protein partner could be "CD74&CD44".
 
+    complex_agg_method : str, default='min'
+        Method to aggregate the expression value of multiple genes in a
+        complex.
+
+        - 'min' : Minimum expression value among all genes.
+        - 'mean' : Average expression value among all genes.
+
     verbose : boolean, default=False
         Whether printing or not steps of the analysis.
 
@@ -472,6 +497,13 @@ class SingleCellInteractions:
         For example, '&' is the complex_sep for a list of ligand-receptor pairs
         where a protein partner could be "CD74&CD44".
 
+    complex_agg_method : str
+        Method to aggregate the expression value of multiple genes in a
+        complex.
+
+        - 'min' : Minimum expression value among all genes.
+        - 'mean' : Average expression value among all genes.
+
     ref_ppi : pandas.DataFrame
         Reference list of protein-protein interactions (or ligand-receptor pairs) used
         for inferring the cell-cell interactions and communication. It could be the
@@ -578,7 +610,7 @@ class SingleCellInteractions:
     def __init__(self, rnaseq_data, ppi_data, metadata, interaction_columns=('A', 'B'),
                  communication_score='expression_thresholding', cci_score='bray_curtis', cci_type='undirected',
                  expression_threshold=0.20, aggregation_method='nn_cell_fraction', barcode_col='barcodes',
-                 celltype_col='cell_types', complex_sep=None, verbose=False):
+                 celltype_col='cell_types', complex_sep=None, complex_agg_method='min', verbose=False):
         # Placeholders
         self.rnaseq_data = rnaseq_data
         self.metadata = metadata
@@ -588,6 +620,7 @@ def __init__(self, rnaseq_data, ppi_data, metadata, interaction_columns=('A', 'B
         self.analysis_setup = dict()
         self.cutoff_setup = dict()
         self.complex_sep = complex_sep
+        self.complex_agg_method = complex_agg_method
         self.interaction_columns = interaction_columns
         self.ccc_permutation_pvalues = None
         self.cci_permutation_pvalues = None
@@ -641,6 +674,7 @@ def __init__(self, rnaseq_data, ppi_data, metadata, interaction_columns=('A', 'B
                                                               cutoff_setup=self.cutoff_setup,
                                                               analysis_setup=self.analysis_setup,
                                                               complex_sep=self.complex_sep,
+                                                              complex_agg_method=self.complex_agg_method,
                                                               interaction_columns=self.interaction_columns,
                                                               verbose=verbose)
 
@@ -710,6 +744,7 @@ def permute_cell_labels(self, permutations=100, evaluation='communication', fdr_
                                                              cutoff_setup=self.cutoff_setup,
                                                              analysis_setup=self.analysis_setup,
                                                              complex_sep=self.complex_sep,
+                                                             complex_agg_method=self.complex_agg_method,
                                                              interaction_columns=self.interaction_columns,
                                                              verbose=False)
 
@@ -757,7 +792,8 @@ def __init__(self, rnaseq_data, ppi_data, gene_cutoffs, spatial_dict, score_type
 
 
 def initialize_interaction_space(rnaseq_data, ppi_data, cutoff_setup, analysis_setup, excluded_cells=None,
-                                 complex_sep=None, interaction_columns=('A', 'B'), verbose=True):
+                                 complex_sep=None, complex_agg_method='min', interaction_columns=('A', 'B'),
+                                 verbose=True):
     '''Initializes a InteractionSpace object to perform the analyses
 
     Parameters
@@ -838,6 +874,13 @@ def initialize_interaction_space(rnaseq_data, ppi_data, cutoff_setup, analysis_s
         For example, '&' is the complex_sep for a list of ligand-receptor pairs
         where a protein partner could be "CD74&CD44".
 
+    complex_agg_method : str, default='min'
+        Method to aggregate the expression value of multiple genes in a
+        complex.
+
+        - 'min' : Minimum expression value among all genes.
+        - 'mean' : Average expression value among all genes.
+
     interaction_columns : tuple, default=('A', 'B')
         Contains the names of the columns where to find the partners in a
         dataframe of protein-protein interactions. If the list is for
@@ -866,6 +909,7 @@ def initialize_interaction_space(rnaseq_data, ppi_data, cutoff_setup, analysis_s
                                                 cci_score=analysis_setup['cci_score'],
                                                 cci_type=analysis_setup['cci_type'],
                                                 complex_sep=complex_sep,
+                                                complex_agg_method=complex_agg_method,
                                                 interaction_columns=interaction_columns,
                                                 verbose=verbose)
     return interaction_space

cell2cell/core/interaction_space.py

@@ -69,7 +69,8 @@ def generate_pairs(cells, cci_type, self_interaction=True, remove_duplicates=Tru
 
 
 def generate_interaction_elements(modified_rnaseq, ppi_data, cci_type='undirected', cci_matrix_template=None,
-                                  complex_sep=None, interaction_columns=('A', 'B'), verbose=True):
+                                  complex_sep=None, complex_agg_method='min', interaction_columns=('A', 'B'),
+                                  verbose=True):
     '''Create all elements needed to perform the analyses of pairwise
     cell-cell interactions/communication. Corresponds to the interaction
     elements used by the class InteractionSpace.
@@ -103,6 +104,13 @@ def generate_interaction_elements(modified_rnaseq, ppi_data, cci_type='undirecte
         For example, '&' is the complex_sep for a list of ligand-receptor pairs
         where a protein partner could be "CD74&CD44".
 
+    complex_agg_method : str, default='min'
+        Method to aggregate the expression value of multiple genes in a
+        complex.
+
+        - 'min' : Minimum expression value among all genes.
+        - 'mean' : Average expression value among all genes.
+
     interaction_columns : tuple, default=('A', 'B')
         Contains the names of the columns where to find the partners in a
         dataframe of protein-protein interactions. If the list is for
@@ -134,7 +142,10 @@ def generate_interaction_elements(modified_rnaseq, ppi_data, cci_type='undirecte
                                                                                              complex_sep=complex_sep,
                                                                                              interaction_columns=interaction_columns
                                                                                              )
-        modified_rnaseq = add_complexes_to_expression(modified_rnaseq, complexes)
+        modified_rnaseq = add_complexes_to_expression(rnaseq_data=modified_rnaseq,
+                                                      complexes=complexes,
+                                                      agg_method=complex_agg_method
+                                                      )
 
     # Cells
     cell_instances = list(modified_rnaseq.columns)  # @Erick, check if position 0 of columns contain index header.
@@ -255,6 +266,13 @@ class InteractionSpace():
         For example, '&' is the complex_sep for a list of ligand-receptor pairs
         where a protein partner could be "CD74&CD44".
 
+    complex_agg_method : str, default='min'
+        Method to aggregate the expression value of multiple genes in a
+        complex.
+
+        - 'min' : Minimum expression value among all genes.
+        - 'mean' : Average expression value among all genes.
+
     interaction_columns : tuple, default=('A', 'B')
         Contains the names of the columns where to find the partners in a
         dataframe of protein-protein interactions. If the list is for
@@ -324,7 +342,7 @@ class InteractionSpace():
 
     def __init__(self, rnaseq_data, ppi_data, gene_cutoffs, communication_score='expression_thresholding',
                  cci_score='bray_curtis', cci_type='undirected', cci_matrix_template=None, complex_sep=None,
-                 interaction_columns=('A', 'B'), verbose=True):
+                 complex_agg_method='min', interaction_columns=('A', 'B'), verbose=True):
 
         self.communication_score = communication_score
         self.cci_score = cci_score
@@ -361,6 +379,7 @@ def __init__(self, rnaseq_data, ppi_data, gene_cutoffs, communication_score='exp
                                                                   cci_matrix_template=cci_matrix_template,
                                                                   cci_type=self.cci_type,
                                                                   complex_sep=complex_sep,
+                                                                  complex_agg_method=complex_agg_method,
                                                                   verbose=verbose)
 
         self.interaction_elements['ppi_score'] = self.ppi_data['score'].values

cell2cell/plotting/__init__.py

@@ -3,7 +3,7 @@
 from cell2cell.plotting.aesthetics import get_colors_from_labels, map_colors_to_metadata, generate_legend
 from cell2cell.plotting.ccc_plot import clustermap_ccc
 from cell2cell.plotting.cci_plot import clustermap_cci
-from cell2cell.plotting.circos_plot import circos_plot
+from cell2cell.plotting.circular_plot import circos_plot
 from cell2cell.plotting.pval_plot import dot_plot
 from cell2cell.plotting.factor_plot import context_boxplot, loading_clustermap, ccc_networks_plot
 from cell2cell.plotting.pcoa_plot import pcoa_3dplot

cell2cell/plotting/factor_plot.py

@@ -218,7 +218,7 @@ def context_boxplot(context_loadings, metadict, included_factors=None, group_ord
 
 def loading_clustermap(loadings, loading_threshold=0., use_zscore=True, metric='euclidean', method='ward',
                        optimal_leaf=True, figsize=(15, 8), heatmap_lw=0.2, cbar_fontsize=12, tick_fontsize=10, cmap=None,
-                       filename=None, **kwargs):
+                       cbar_label=None, filename=None, **kwargs):
     '''
     Plots a clustermap of the tensor-factorization loadings from one tensor dimension or
     the joint loadings from multiple tensor dimensions.
@@ -285,6 +285,10 @@ def loading_clustermap(loadings, loading_threshold=0., use_zscore=True, metric='
         Name of the color palette for coloring the heatmap. If None,
         cmap='Blues' would be used when use_zscore=False; and cmap='vlag' when use_zscore=True.
 
+    cbar_label : str, default=None
+        Label for the color bar. If None, default labels will be 'Z-scores \n across factors'
+        or 'Loadings', depending on `use_zcore` is True or False, respectively.
+
     filename : str, default=None
         Path to save the figure of the elbow analysis. If None, the figure is not
         saved.
@@ -305,13 +309,14 @@ def loading_clustermap(loadings, loading_threshold=0., use_zscore=True, metric='
             cmap = 'vlag'
         val = np.ceil(max([abs(df.min().min()), abs(df.max().max())]))
         vmin, vmax = -1. * val, val
-        cbar_label = 'Z-scores \n across factors'
+        if cbar_label is None:
+            cbar_label = 'Z-scores \n across factors'
     else:
         if cmap is None:
             cmap='Blues'
         vmin, vmax = 0., df.max().max()
-        cbar_label = 'Loadings'
-
+        if cbar_label is None:
+            cbar_label = 'Loadings'
     # Clustering
     dm_rows = compute_distance(df, axis=0, metric=metric)
     row_linkage = compute_linkage(dm_rows, method=method, optimal_ordering=optimal_leaf)

cell2cell/preprocessing/rnaseq.py

@@ -141,7 +141,7 @@ def divide_expression_by_mean(rnaseq_data, axis=1):
     return new_data
 
 
-def add_complexes_to_expression(rnaseq_data, complexes):
+def add_complexes_to_expression(rnaseq_data, complexes, agg_method='min'):
     '''
     Adds multimeric complexes into the gene expression matrix.
     Their gene expressions are the minimum expression value
@@ -157,6 +157,13 @@ def add_complexes_to_expression(rnaseq_data, complexes):
         Dictionary where keys are the complex names in the list of PPIs, while
         values are list of subunits for the respective complex names.
 
+    agg_method : str, default='min'
+        Method to aggregate the expression value of multiple genes in a
+        complex.
+
+        - 'min' : Minimum expression value among all genes.
+        - 'mean' : Average expression value among all genes.
+
     Returns
     -------
     tmp_rna : pandas.DataFrame
@@ -169,7 +176,14 @@ def add_complexes_to_expression(rnaseq_data, complexes):
     for k, v in complexes.items():
         if all(g in tmp_rna.index for g in v):
             df = tmp_rna.loc[v, :]
-            tmp_rna.loc[k] = df.min().values.tolist()
+            if agg_method == 'min':
+                tmp_rna.loc[k] = df.min().values.tolist()
+            elif agg_method == 'mean':
+                tmp_rna.loc[k] = df.mean().values.tolist()
+            # elif agg_method == 'gmean':
+            #    tmp_rna.loc[k] = df.gmean().values.tolist() # Not implemented
+            else:
+                ValueError("{} is not a valid agg_method".format(agg_method))
         else:
             tmp_rna.loc[k] = [0] * tmp_rna.shape[1]
     return tmp_rna

cell2cell/tensor/__init__.py

@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+from cell2cell.tensor.external_scores import (dataframes_to_tensor)
 from cell2cell.tensor.factor_manipulation import (normalize_factors)
 from cell2cell.tensor.metrics import (correlation_index)
 from cell2cell.tensor.tensor import (InteractionTensor, PreBuiltTensor, build_context_ccc_tensor, generate_tensor_metadata,