pyCoReGraph 0.0.1a2__tar.gz → 0.0.1a4__tar.gz

{pycoregraph-0.0.1a2 → pycoregraph-0.0.1a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyCoReGraph
-Version: 0.0.1a2
+Version: 0.0.1a4
 Summary: CoReGraph : Correlation-based dynamic gene Regulatory Graphs
 Author-email: Joseph Léger <josephleger@outlook.fr>
 License: MIT

{pycoregraph-0.0.1a2 → pycoregraph-0.0.1a4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyCoReGraph"
-version = "0.0.1a2"
+version = "0.0.1a4"
 description = "CoReGraph : Correlation-based dynamic gene Regulatory Graphs"
 readme = "README.md"
 requires-python = ">=3.10"

{pycoregraph-0.0.1a2 → pycoregraph-0.0.1a4}/src/coregraph/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.0.1a2"
+__version__ = "0.0.1a4"
 
 # Models
 from coregraph.models import (
@@ -32,7 +32,7 @@ from coregraph.graphics.network import (
     animate_network,
 )
 
-from coregraph.analysis.subset import (
+from coregraph.analysis.reductions import (
     starry,
     subset_coregraph,
 )

{pycoregraph-0.0.1a2 → pycoregraph-0.0.1a4}/src/coregraph/analysis/bins.py

@@ -3,9 +3,14 @@
 import numpy as np
 
 
-def _calculate_bins(data, pseudotime, n_bins):
-    '''Discretize pseudotime expression in bins'''
-    
+def _calculate_bins(
+    data,
+    pseudotime, 
+    n_bins
+    ):
+    '''
+    Discretize pseudotime expression in bins.
+    '''
     bin_range = (pseudotime.max() - pseudotime.min())/n_bins
     bin_seq   = pseudotime.min() + np.arange(1,n_bins)*bin_range
     bins      = (np.digitize(pseudotime, bin_seq)*bin_range)+(bin_range/2)

{pycoregraph-0.0.1a2 → pycoregraph-0.0.1a4}/src/coregraph/analysis/correlations.py

@@ -3,8 +3,24 @@
 import numpy as np
 
 
-def _calculate_all_cors(data, window, i, tensor, reflag, MAC, LAG_id, LAG, LAG_means, dim3_start, step=1, num_format=np.array([1,15]), dtype=np.float64):
-    '''Calculate all lagged correlations for a unique given reference i'''
+def _calculate_all_cors(
+    data, 
+    window, 
+    i, 
+    tensor, 
+    reflag, 
+    MAC, 
+    LAG_id, 
+    LAG, 
+    LAG_means, 
+    dim3_start, 
+    step = 1, 
+    num_format = np.array([1,15]), 
+    dtype = np.float64
+    ):
+    '''
+    Calculate all lagged correlations for a unique given reference i.
+    '''
     dim3 = dim3_start
     n_genes, n_cells = data.shape
 
@@ -43,8 +59,17 @@ def _calculate_all_cors(data, window, i, tensor, reflag, MAC, LAG_id, LAG, LAG_m
 
     return dim3, MAC, LAG_id, LAG, LAG_means
 
-def _calculate_LEAP_cors(data, window, i=0, step=1, num_format=np.array([1,15]), dtype=np.float64):
-    '''Calculate all lagged correlations for a unique given reference i using LEAP traditional algorithm'''
+def _calculate_LEAP_cors(
+    data, 
+    window, 
+    i = 0, 
+    step = 1, 
+    num_format = np.array([1,15]), 
+    dtype = np.float64
+    ):
+    '''
+    Calculate all lagged correlations for a unique given reference i using LEAP traditional algorithm.
+    '''
     n_genes, n_cells = data.shape
     MAC              = np.zeros((n_genes, n_genes))
     LAG              = np.zeros((n_genes, n_genes))
@@ -76,9 +101,19 @@ def _calculate_LEAP_cors(data, window, i=0, step=1, num_format=np.array([1,15]),
     return MAC, LAG
 
 
-def _calculate_star_cors(data, target_row, MAC, window, i, step=1, num_format=np.array([1,15]), dtype=np.float64):
-    '''Calculate all lagged correlations for a unique given reference i using a single reference row against all rows.'''
-
+def _calculate_star_cors(
+    data, 
+    target_row, 
+    MAC, 
+    window, 
+    i, 
+    step = 1, 
+    num_format = np.array([1,15]), 
+    dtype = np.float64
+    ):
+    '''
+    Calculate all lagged correlations for a unique given reference i using a single reference row against all rows.
+    '''
     n_genes, n_cells = data.shape
 
     # Take reference row only

{pycoregraph-0.0.1a2 → pycoregraph-0.0.1a4}/src/coregraph/analysis/fdr.py

@@ -5,9 +5,19 @@ import numpy as np
 from coregraph.analysis.correlations import (_calculate_LEAP_cors, _calculate_star_cors)
 
 
-def _calculate_FDR(data, MAC, window, n_perms = 100, FDR_cutoffs = 101, step=1, num_format=np.array([1,15]), dtype=np.float64):
-    '''Calculate False Discovery Rate by permutations'''
-
+def _calculate_FDR(
+    data, 
+    MAC, 
+    window, 
+    n_perms = 100, 
+    FDR_cutoffs = 101, 
+    step = 1, 
+    num_format = np.array([1,15]), 
+    dtype = np.float64
+    ):
+    '''
+    Calculate False Discovery Rate by permutations.
+    '''
     MAC_true  = np.absolute(MAC.copy())
     samp_size = np.minimum(100, data.shape[0])
     MACs_perm = np.zeros((n_perms, samp_size, samp_size))
@@ -51,9 +61,20 @@ def _calculate_FDR(data, MAC, window, n_perms = 100, FDR_cutoffs = 101, step=1,
        
     return results[::-1]
 
-def _calculate_star_FDR(data, target_row, MAC, window, n_perms = 100, FDR_cutoffs = 101, step=1, num_format=np.array([1,15]), dtype=np.float64):
-    '''Calculate False Discovery Rate by permutations for a single reference row against all rows.'''
-
+def _calculate_star_FDR(
+    data, 
+    target_row, 
+    MAC, 
+    window, 
+    n_perms = 100, 
+    FDR_cutoffs = 101, 
+    step = 1, 
+    num_format = np.array([1,15]), 
+    dtype = np.float64
+    ):
+    '''
+    Calculate False Discovery Rate by permutations for a single reference row against all rows.
+    '''
     MAC_true  = np.absolute(MAC.copy())
     samp_size = np.minimum(100, data.shape[0])
     MACs_perm = np.zeros((n_perms, samp_size))

pycoregraph-0.0.1a4/src/coregraph/analysis/queries.py

@@ -0,0 +1,206 @@
+## QUERIES ##
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from coregraph.utils.decorators import (requires_cors, requires_FDR)
+
+
+@requires_cors
+def get_correlation(
+    C: CoReGraph, 
+    regulator: str, 
+    target: str, 
+    ref_lag: tuple[int, int]
+    ) -> float :
+    '''
+    Get correlation value between two genes at a specific (reference, lag) window pair.
+
+    Parameters
+    ----------
+    C : CoReGraph 
+        CoReGraph object with calculated correlations
+    regulator : str
+        Gene to consider as regulator for the relationship
+    target : str
+        Gene to consider as regulated for the relationship
+    ref_lag : tuple[int, int]
+        Tuple containing reference and lagged window for regulator and target genes respectively
+    '''  
+    ref, lag = ref_lag
+
+    if (ref % C.cors.step != 0) or (lag % C.cors.step != 0):
+        raise ValueError(f"ref_lag must be multiples of step={C.cors.step}")
+
+    reg_idx = C.gene_to_idx[regulator]
+    tar_idx = C.gene_to_idx[target]
+
+    if ref <= lag:
+        tensor_i = reg_idx
+        tensor_j = tar_idx
+        search_ref = ref
+        search_lag = lag
+    else:
+        tensor_i = tar_idx
+        tensor_j = reg_idx
+        search_ref = lag
+        search_lag = ref
+
+    dim3 = np.argwhere((C.cors.reflag[:, 0] == search_ref) & (C.cors.reflag[:, 1] == search_lag))[0][0]
+
+    value = (C.cors.tensor[tensor_i, tensor_j, dim3] / C.cors.num_format[0])
+
+    return float(value)
+
+
+@requires_cors
+def get_all_correlations(
+    C: CoReGraph, 
+    regulator: str, 
+    target: str, 
+    ref: int
+    ) -> np.ndarray :
+    '''
+    Get all lagged correlations between two genes for a fixed reference window.
+    
+    Parameters
+    ----------
+    C : CoReGraph 
+        CoReGraph object with calculated correlations
+    regulator : str
+        Gene to consider as regulator for the relationship
+    target : str
+        Gene to consider as regulated for the relationship
+    ref : int
+        Reference window to consider
+    '''  
+    if (ref % C.cors.step != 0) :
+        raise ValueError(f"ref must be a multiple of step={C.cors.step}")
+
+    correlations = np.empty(C.cors.n_steps, dtype=C.cors.dtype)
+
+    for i in range(C.cors.n_steps):
+        lag = i * C.cors.step
+        correlations[i] = get_correlation(C,regulator,target,(ref, lag))
+
+    return correlations
+
+
+@requires_cors
+def get_mac(
+    C: CoReGraph, 
+    regulator: str, 
+    target: str
+    ) -> dict :
+    '''
+    Get maximal absolute correlation (MAC) and corresponding reference/lag pair for two genes.
+
+    Parameters
+    ----------
+    C : CoReGraph 
+        CoReGraph object with calculated correlations
+    regulator : str
+        Gene to consider as regulator for the relationship
+    target : str
+        Gene to consider as regulated for the relationship
+    '''
+    reg_idx = C.gene_to_idx[regulator]
+    tar_idx = C.gene_to_idx[target]
+
+    return {
+        "ref": int(C.cors.LAG_id[0, reg_idx, tar_idx]), 
+        "lag": int(C.cors.LAG_id[1, reg_idx, tar_idx]),
+        "cor": float(C.cors.MAC[reg_idx, tar_idx] / C.cors.num_format[0])
+        }
+
+
+@requires_cors
+def get_mac_results(C: CoReGraph) -> tuple[pd.DataFrame, pd.DataFrame] :
+    '''
+    Get MAC and LAG matrices.
+
+    Parameters
+    ----------
+    C : CoReGraph 
+        CoReGraph object with calculated correlations
+    '''
+    mac_df = pd.DataFrame(C.cors.MAC / C.cors.num_format[0], index=C.gene_id, columns=C.gene_id)
+    lag_df = pd.DataFrame(C.cors.LAG, index=C.gene_id, columns=C.gene_id)
+
+    return mac_df, lag_df
+
+
+@requires_cors
+@requires_FDR
+def get_regulated_genes(
+    C: CoReGraph, 
+    regulator: str, 
+    cor_threshold: float = 0.0
+    ) -> pd.DataFrame :
+    '''
+    Get genes regulated by a regulator gene.
+
+    Parameters
+    ----------
+    C : CoReGraph 
+        CoReGraph object with calculated correlations and FDR
+    regulator : str
+        Gene to consider as regulator for the relationship
+    cor_threshold : float
+        Correlation threshold required for genes to be considered as targets
+    '''
+    reg_idx = C.gene_to_idx[regulator]
+
+    values = (C.cors.MAC[reg_idx, :] / C.cors.num_format[0])
+
+    df = pd.DataFrame({
+        "gene": C.gene_id,
+        "correlation": values,
+        "lag": C.cors.LAG[reg_idx, :]
+        })
+
+    df = df[np.abs(df["correlation"]) > cor_threshold]
+
+    df = df.sort_values(by="correlation", key=np.abs, ascending=False)
+
+    return df.set_index("gene")
+
+
+@requires_cors
+@requires_FDR
+def get_regulator_genes(
+    C: CoReGraph, 
+    target: str, 
+    cor_threshold: float = 0.0
+    ) -> pd.DataFrame :
+    '''
+    Get genes regulating a target gene.
+    
+    Parameters
+    ----------
+    C : CoReGraph 
+        CoReGraph object with calculated correlations and FDR
+    target : str
+        Gene to consider as target for the relationship
+    cor_threshold : float
+        Correlation threshold required for genes to be considered as regulators
+    '''
+    tar_idx = C.gene_to_idx[target]
+
+    values = (C.cors.MAC[:, tar_idx] / C.cors.num_format[0])
+
+    df = pd.DataFrame({
+        "gene": C.gene_id,
+        "correlation": values,
+        "lag": C.cors.LAG[:, tar_idx]
+        })
+
+    df = df[np.abs(df["correlation"]) > cor_threshold]
+
+    df = df.sort_values(by="correlation", key=np.abs, ascending=False)
+
+    return df.set_index("gene")
+
+

pycoregraph-0.0.1a4/src/coregraph/analysis/reductions.py

@@ -0,0 +1,113 @@
+## REDUCTIONS ##
+
+import numpy as np
+import pandas as pd
+
+from tqdm import tqdm
+
+from coregraph.models.coregraph import CoReGraph
+from coregraph.models.stargraph import StarGraph
+
+from coregraph.analysis.correlations import _calculate_star_cors
+from coregraph.analysis.fdr import _calculate_star_FDR
+from coregraph.utils.validation import _solve_step
+
+
+def starry(
+    C : CoReGraph, 
+    central_gene : str, 
+    window: int | None = None, 
+    FDR_thr : float = 0.05, 
+    n_perms : int = 100, 
+    FDR_cutoffs : int = 501, 
+    step: int | None = None, 
+    n_steps: int | None = None, 
+    verbose : bool = False
+    ) -> StarGraph : 
+    '''
+    Estimate starry gene regulatory network centered on a given gene
+
+    Parameters
+    ----------
+    C : CoReGraph 
+        CoReGraph object to turn into a stargraph object
+    central_gene : str
+        Central gene of the newly created stargraph
+    window : int | None
+        Number of cells in the window for applying lags (default : n_cells*2/3)
+    FDR_thr : float
+        Maximal FDR for genes to be selected as in relationship with the central gene
+    n_perms : int
+        Number of repetition of matrix permutation to establish FDR    
+    FDR_cutoffs : int
+        Number of levels between 0 and 1 calculated to determine the FDR
+    step : int | None
+        Step to apply while shifting window
+    n_steps : int | None
+        Total number of steps to consider while shifting window
+    verbose : bool
+        Wether show progression bar (slightly slow down the process)
+    '''
+    if window is None:
+        window = round(C.n_cells*(2/3))
+
+    n_genes, n_cells = C.data.shape
+    target_row       = C.gene_id.index(central_gene) 
+    step, n_steps    = _solve_step(step, n_steps, window, n_cells)
+
+    ## Calculate MAC ##
+    MAC      = np.zeros((n_genes), dtype=np.float64)
+
+    np.seterr(divide='ignore', invalid='ignore')
+    iterator = tqdm(range(0, n_cells-window+1, step), desc="Calculating Correlations", disable=not verbose)
+    for i in iterator:
+        MAC = _calculate_star_cors(C.data, target_row, MAC, window, i, step)
+
+    ## Calculate FDR ##
+    FDR = _calculate_star_FDR(C.data, target_row, MAC, window, n_perms, FDR_cutoffs, step)
+    FDR = pd.DataFrame(FDR)
+    FDR.columns            = ["cors", "MACs_observed", "MACs_ave_perm", "FDR"]
+    FDR[["MACs_observed"]] = FDR[["MACs_observed"]].astype(int)
+
+    cor_thr   = min(FDR['cors'][FDR['FDR'] < FDR_thr])
+    MAC       = pd.DataFrame(MAC, index=C.gene_id, columns=['MAC'])
+    MAC       = MAC.sort_values(by='MAC', key=abs, ascending=False)
+
+    ## Create a new object and fill in it ##
+    star = StarGraph()
+    star.central_gene = central_gene
+    star.window       = window
+    star.step         = step
+    star.n_steps      = n_steps
+    star.MAC          = MAC
+    star.FDR          = FDR
+    star.set_FDR_threshold(FDR_thr)
+    
+    return star
+
+
+def subset_coregraph(
+    C: CoReGraph, 
+    gene_list : list[str], 
+    ) -> CoReGraph :
+    '''
+    Reduct a CoReGraph object based on a gene list.
+
+    Parameters
+    ----------
+    C : CoReGraph 
+        CoReGraph object to turn into a stargraph object
+    gene_list : str
+        List of genes to keep in subsetted object
+    '''
+    id_dict = {}
+    for i, b in enumerate(C.gene_id):
+        id_dict[b] = i
+
+    shared_id = [id_dict[g] for g in gene_list]
+    shared_id.sort()
+    subdata   = C.data[shared_id,:]
+    subid     = [C.gene_id[g] for g in shared_id]
+
+    subobject = CoReGraph(subdata, C.pseudotime, subid, C.cell_id)
+    return subobject

pycoregraph-0.0.1a4/src/coregraph/graphics/animations.py

@@ -0,0 +1,100 @@
+## ANIMATIONS ##
+
+from __future__ import annotations
+
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.patches as patches
+
+from matplotlib.animation import FuncAnimation
+
+from coregraph.graphics.colors import ColorBlind
+from coregraph.analysis.queries import (get_all_correlations)
+from coregraph.utils.decorators import (requires_cors, requires_bins)
+
+
+@requires_bins
+@requires_cors
+def animate_correlations(
+    C: CoReGraph, 
+    regulator: str, 
+    target: str, 
+    ref: int, 
+    scaled: bool = False, 
+    decimals: int = 15, 
+    color: tuple = (ColorBlind[0], ColorBlind[3]), 
+    linewidth: float = 1 , 
+    figsize: tuple = (8,4)
+    ):
+    '''
+    Animate lagged correlations.
+    
+    Parameters
+    ----------
+    C : CoReGraph 
+        CoReGraph object with calculated correlations
+    regulator : str
+        Gene to consider as regulator for the relationship
+    target : str
+        Gene to consider as regulated for the relationship
+    ref : int
+        Reference window to consider
+    scaled : bool
+        Whether displayed expressions has to be scaled from 0 to 1
+    decimals : int
+        Number of decimals to display for correlation values
+    color : tuple
+        Colors for each considered gene
+    linewidth : float
+        Width of expression curves
+    figsize : tuple
+        Figure width and height
+    '''
+    if C.graphics.n_bins is None:
+        raise ValueError("Bins have not been calculated.")
+    
+    values        = (C.graphics.scaled if scaled else C.graphics.mean)
+    reg_idx       = C.gene_to_idx[regulator]
+    tar_idx       = C.gene_to_idx[target]
+    y_max         = np.max([values[reg_idx, :], values[tar_idx, :]]) * 1.1
+    all_cors      = get_all_correlations(C, regulator, target, ref)
+    all_cors_norm = (all_cors / np.max(np.abs(all_cors)))
+    
+    vmin = min(all_cors_norm)
+    vmax = max(all_cors_norm)
+
+    fig, ax = plt.subplots(1, 2, figsize=figsize, width_ratios=[25, 1],)
+    x       = np.unique(C.graphics.bin_id)
+
+    # Regulator and target lines
+    ax[0].plot(x, values[reg_idx, :], color=color[0], linewidth=linewidth)
+    ax[0].plot(x, values[tar_idx, :], color=color[1], linewidth=linewidth)
+    ax[1].set(xlim=[0,1], ylim=[-1 if vmin <= 0 else 0, 1 if vmax >= 0 else 0])
+    ax[1].yaxis.tick_right()
+    ax[1].set_xticks([])
+    #ax[1].axis('off')
+
+    fixed_rect  = ax[0].add_patch(patches.Rectangle((ref, 0), C.cors.window, y_max, facecolor=color[0], alpha=0.1,))
+    moving_rect = ax[0].add_patch(patches.Rectangle((0, 0), C.cors.window, y_max, facecolor=color[1], alpha=0.1,))
+    moving_bar  = ax[1].add_patch(patches.Rectangle((0, 0), 0, 0, facecolor=(1,1,1), edgecolor = None, fill=True, alpha=1))
+
+    def update(frame):
+        lag = frame * C.cors.step
+        moving_rect.set_x(lag)
+        moving_bar.set_bounds(0, 0, 1, all_cors_norm[frame])
+        if all_cors_norm[frame] >= 0:
+            moving_bar.set(facecolor=(1,(1-all_cors_norm[frame])/2,(1-all_cors_norm[frame])/2))
+        else:
+            moving_bar.set(facecolor=((1+all_cors_norm[frame])/2,(1+all_cors_norm[frame])/2,1))
+
+        cor = all_cors[frame]
+        ax[0].set_title(f"lag = {lag}\ncor = {np.round(cor, decimals)}")
+        ax[1].set_title(f"{np.absolute(round(all_cors_norm[frame]*100,1))}% of MAC\n ")
+
+        return (moving_rect, moving_bar)
+
+    ani = FuncAnimation(fig, update, frames=C.cors.n_steps, blit=True)
+    #HTML(ani.to_jshtml())
+    return ani
+
+

{pycoregraph-0.0.1a2 → pycoregraph-0.0.1a4}/src/coregraph/graphics/network.py

@@ -14,7 +14,11 @@ from coregraph.analysis.queries import (get_all_correlations, get_mac)
 from coregraph.utils.decorators import (requires_cors, requires_FDR)
 
 
-def _build_correlation_tensor(C, genes, correlation_threshold):
+def _build_correlation_tensor(
+    C, 
+    genes, 
+    correlation_threshold
+    ):
     '''
     Build tensor (n_genes, n_genes, n_steps) containing all dynamic correlations.
     '''
@@ -48,7 +52,11 @@ def _build_adjacency_tensor(cor_tensor):
     return filtered
 
 
-def _compute_node_sizes(C, genes, node_ratio=1):
+def _compute_node_sizes(
+    C, 
+    genes, 
+    node_ratio = 1
+    ):
     '''
     Compute node size evolution through time.
     '''
@@ -116,15 +124,15 @@ def _draw_network_frame(ax, G, pos, genes, adjacency_matrix, node_sizes, cmap, n
 def animate_network(
     C: CoReGraph,
     genes: list[str],
-    fdr_threshold: float=0.01,
+    fdr_threshold: float = 0.01,
     correlation_threshold: float | None = None,
-    edge_ratio: float=1,
-    node_ratio: float=1,
-    min_target_margin: float=15,
-    min_source_margin: float=15,
-    font_size: int=8,
-    figsize: tuple=(6, 6)
-):
+    edge_ratio: float = 1,
+    node_ratio: float = 1,
+    min_target_margin: float = 15,
+    min_source_margin: float = 15,
+    font_size: int = 8,
+    figsize: tuple = (6, 6)
+    ):
     '''
     Animate dynamic gene regulatory network.
 
@@ -132,25 +140,25 @@ def animate_network(
     ----------
     C : CoreGraph
         CoreGraph object.
-
     genes : list[str]
         Genes to include in network.
-
     fdr_threshold : float
         FDR threshold used to infer minimum correlation threshold.
-
     correlation_threshold : float | None
         Correlation threshold.
-
     edge_ratio : float
         Edge width scaling factor.
-
     node_ratio : float
         Node size scaling factor.
-
+    min_target_margin : float
+        The minimum margin (gap) at the end of the edge at the target.   
+    min_source_margin : float
+        The minimum margin (gap) at the beginning of the edge at the source.
+    font_size : int
+        Text size 
     figsize : tuple
         Figure size.
-   '''
+    '''
     # Validate threshold
     if correlation_threshold is None:
         correlation_threshold = np.min(C.cors.FDR.loc[C.cors.FDR["FDR"] < fdr_threshold, "cors"])
@@ -167,13 +175,9 @@ def animate_network(
     # Figure
     fig, ax = plt.subplots(figsize=figsize)
     cmap    = cm.bwr
-    vmin    = cor_tensor.min()
-    vmax    = cor_tensor.max()
-
-    if vmin == vmax:
-        vmax += 1e-10
-
-    norm = mcolors.TwoSlopeNorm(vmin=vmin, vcenter=0.0, vmax=vmax)
+    vmax    = np.max(np.abs(cor_tensor))
+   
+    norm = mcolors.TwoSlopeNorm(vmin=-vmax, vcenter=0, vmax=vmax)
 
     # Edge normalization
     if C.cors.dtype == np.int64:
@@ -181,7 +185,6 @@ def animate_network(
     else:
         edge_ratio *= 10
 
-
     # Update function
     def update(frame):
         adjacency_matrix = cor_tensor[:, :, frame]