exprmat 0.1.48__tar.gz → 0.1.50__tar.gz

{exprmat-0.1.48 → exprmat-0.1.50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: exprmat
-Version: 0.1.48
+Version: 0.1.50
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
@@ -101,7 +101,7 @@ Provides-Extra: cuda12
 License-File: license
 Summary: exprmat: Routines for expression matrices
 Author-email: Zheng Yang <xornent@outlook.com>
-Requires-Python: >=3.9, <3.13
+Requires-Python: >=3.10, <3.13
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Repository, https://github.com/yang-z-03/exprmat
 
@@ -150,18 +150,18 @@ options:
   --version VERSION    The version to fetch from remote.
 ```
 
-Suppose you are installing the database version `0.1.25` to `~/database`.
+Suppose you are installing the database version `0.1.50` to `~/database`.
 
 ```bash
 # enter the intended path of installation
 cd ~/database
 
-# download the version 0.1.25 of database distribution
+# download the version 0.1.50 of database distribution
 # you must download the same version of the database with the package. the database
 # and package content are published strictly synchronically.
 bsync-fetch --id <your-id> --secret <your-api-secret> \
             --bucket exprmat-data --endpoint oss-cn-wuhan-lr.aliyuncs.com \
-            --version 0.1.25
+            --version 0.1.50
 ```
 
 The authentication tokens passed to `--id` and `--secret` is provided by the

{exprmat-0.1.48 → exprmat-0.1.50}/exprmat/__init__.py

@@ -82,7 +82,7 @@ due to the extensive size of the reference data. You need to setup the database
 and configure it properly with configuration file `.exprmatrc` under your
 user root or current working directory
 
-For more guide on how to setup the database folder, and more information about
+For more guide on how to install the database, and more information about
 what the database includes, see <https://github.com/yang-z-03/exprmat>
 """
 
@@ -192,6 +192,22 @@ def memory():
     info(f'virtual memory: {format_file_size(virtual)}')
 
 
+def license():
+    print(f'''
+exprmat {ver_string} - Routines to manipulate expression matrices
+Copyright (C) 2025 - 2026 Zheng Yang (杨政) <xornent@outlook.com>
+
+exprmat is free software and comes with ABSOLUTELY NO WARRANTY.
+You are welcome to redistribute it under certain conditions. 
+You should have received a copy of the GNU General Public License
+version 3 along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+The GNU General Public License does not permit incorporating 
+your program into proprietary programs.
+''')
+
+
+
 setwd = os.chdir
 getwd = os.getcwd
 
@@ -200,6 +216,17 @@ import tqdm
 tqdm.tqdm(disable = True, total = 0)
 
 
+# show version info after any install or update of the database.
+# this always synchronizes with the package update.
+
+try:
+    fd = os.open(os.path.join(basepath, '.license'), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+    with os.fdopen(fd, "w") as f: f.write("shown")
+    license()
+
+except FileExistsError: pass
+
+
 __all__ = [
     # exposed external namespace
     'np', 'mu', 'ad', 'sc', 'pd',
@@ -219,6 +246,7 @@ __all__ = [
     'version_db'
     'cuda',
     'memory',
+    'license',
     'setwd',
     'getwd',
     'pprog',

{exprmat-0.1.48 → exprmat-0.1.50}/exprmat/clustering/gating.py

@@ -62,3 +62,4 @@ def polygon_gate(
     df.index = df['id'].tolist()
     adata.obs[key_added] = False
     adata.obs.loc[df.index, key_added] = df['gate']
+    adata.obs[key_added] = adata.obs[key_added].astype('str').astype('category')

exprmat-0.1.50/exprmat/data/icnet.py

@@ -0,0 +1,74 @@
+
+from exprmat import basepath
+import pandas as pd
+import os
+
+
+def get_gene_regulatory_network(taxa):
+    return pd.read_feather(os.path.join(basepath, taxa, 'icnet', 'gene-regulatory.feather'))
+
+def get_lr_network(taxa):
+    return pd.read_feather(os.path.join(basepath, taxa, 'icnet', 'ligand-receptors.feather'))
+
+def get_signaling_network(taxa):
+    return pd.read_feather(os.path.join(basepath, taxa, 'icnet', 'signaling.feather'))
+
+def get_gene_regulatory_weights(taxa, version = 'v2'):
+    return pd.read_feather(os.path.join(basepath, taxa, 'icnet', version, 'gene-regulatory.feather'))
+
+def get_lr_weights(taxa, version = 'v2'):
+    return pd.read_feather(os.path.join(basepath, taxa, 'icnet', version, 'lr-significance.feather'))
+
+def get_ligand_target_matrix(taxa, version = 'v2'):
+    return pd.read_feather(os.path.join(basepath, taxa, 'icnet', version, 'ligand-target.feather'))
+
+def get_ligand_tf_matrix(taxa, version = 'v2'):
+    return pd.read_feather(os.path.join(basepath, taxa, 'icnet', version, 'ligand-tf.feather'))
+
+
+def get_weighted_ligand_target_links(ligand, geneset, ligand_target_matrix, n = 250):
+    import numpy as np
+    ltm_series = ligand_target_matrix[ligand]
+    data = np.array(ltm_series.values)
+    flat = data.flatten('C')
+    indices = np.argsort(flat)[-n:]
+
+    # retrieve indices
+    # rows are targets and columns are ligands.
+    ligs = []
+    targs = []
+    weights = []
+    for i in indices:
+        row = i // len(ligand)
+        col = i % len(ligand)
+        target = ligand_target_matrix.index[row]
+        if target in geneset:
+            ligs.append(ligand[col])
+            targs.append(ligand_target_matrix.index[row])
+            weights.append(flat[i])
+
+    return pd.DataFrame({
+        'ligand': ligs,
+        'target': targs,
+        'weight': weights
+    })
+
+
+def get_weighted_ligand_receptor_links(
+    best_upstream_ligands, expressed_receptors, 
+    lr_network, weighted_networks_lr_sig
+):
+    lr_network = lr_network.drop_duplicates(subset = ['from', 'to'])
+    weighted_networks_lr = pd.merge(weighted_networks_lr_sig, lr_network, on = ['from', 'to'])
+
+    lr_network_top = lr_network[
+        (lr_network['from'].isin(best_upstream_ligands)) & 
+        (lr_network['to'].isin(expressed_receptors))
+    ].drop_duplicates(subset = ['from','to'])
+    best_upstream_receptors = lr_network_top['to'].unique()
+
+    lr_network_top_df_long = weighted_networks_lr[
+        (weighted_networks_lr['from'].isin(best_upstream_ligands)) & 
+        (weighted_networks_lr['to'].isin(best_upstream_receptors))]
+    
+    return lr_network_top_df_long

exprmat-0.1.50/exprmat/lr/icnet/__init__.py

@@ -0,0 +1,100 @@
+
+from exprmat.data.icnet import (
+    get_gene_regulatory_network,
+    get_gene_regulatory_weights,
+    get_ligand_target_matrix,
+    get_ligand_tf_matrix,
+    get_lr_network,
+    get_lr_weights,
+    get_signaling_network,
+    get_weighted_ligand_receptor_links,
+    get_weighted_ligand_target_links
+)
+
+from exprmat.lr.icnet.importance import predict_ligand_activities
+from exprmat import info, error
+import numpy as np
+
+
+def nichenet(
+    adata,
+    taxa,
+    receiver, # you must specify the receiver cells
+    sender = None,
+    identity = 'cell.type',
+    foreground = None,
+    background = None,
+    expression_threshold = 0.001,
+    ncpus = 1,
+    key_added = 'nichenet'
+):
+    ltm = get_ligand_target_matrix(taxa)
+
+    if background:
+        background = list(set(background))
+        info(f'using user-specified background gene set of size {len(background)}')
+    
+    else: background = adata.var['gene'].tolist()
+    background = list(set(background).intersection(set(ltm.index.tolist())))
+    info(f'background gene set constructed with size {len(background)}')
+    
+    if foreground:
+        foreground = list(set(foreground))
+        info(f'using user-specified foreground gene set of size {len(foreground)}')
+    else: error('foreground gene set must be specified')
+    
+    expressed_genes = adata.var['gene'].loc[
+        np.array((adata.X.sum(0) / adata.X.shape[0]) > expression_threshold)[0]].tolist()
+    rec = adata[[x in receiver for x in adata.obs[identity]], :]
+    target_expressed_genes = rec.var['gene'].loc[np.array(
+        (rec.X.sum(0) / rec.X.shape[0]) > expression_threshold)[0]].tolist()
+    
+    lr_network = get_lr_network(taxa)
+    all_receptors = lr_network['to'].unique().tolist()
+    expressed_receptors = list(set(all_receptors).intersection(set(target_expressed_genes)))
+    potential_ligands = [x for x, y in zip(lr_network['from'], lr_network['to']) if y in expressed_genes]
+
+    if sender:
+        send = adata[[x in sender for x in adata.obs[identity]], :]
+        sender_expressed_genes = send.var['gene'].loc[np.array(
+            (send.X.sum(0) / send.X.shape[0]) > expression_threshold)[0]].tolist()
+        potential_ligands = list(set(potential_ligands).intersection(set(sender_expressed_genes)))
+        info(f'{len(potential_ligands)} potential ligands filtered by sender cells expression')
+    else: 
+        potential_ligands = list(set(potential_ligands))
+        info(f'using {len(potential_ligands)}(all) potential ligands')
+
+    info(f'using {len(expressed_receptors)} expressed receptors in receivers')
+    
+    ligact = predict_ligand_activities(
+        geneset = foreground,
+        background_expressed_genes = background,
+        ligand_target_matrix = ltm.values,
+        ligand_names = ltm.columns.tolist(),
+        target_names = ltm.index.tolist(),
+        potential_ligands = potential_ligands,
+        ncpus = ncpus
+    )
+
+    adata.uns[key_added] = {
+        'foreground': foreground,
+        'background': background,
+        'taxa': taxa,
+        'activities': ligact.sort_values(['aupr.adj'], ascending = False)
+    }
+
+    pass
+
+
+def nichenet_infer_targets(adata, key_nichenet, ligands = 10, n_targets = 250):
+
+    nnet = adata.uns[key_nichenet]
+    ltm = get_ligand_target_matrix(nnet['taxa'])
+    ltl = get_weighted_ligand_target_links(
+        ligand = ligands if isinstance(ligands, list) else nnet['activities'].head(ligands)['ligand'].tolist(),
+        geneset = nnet['foreground'],
+        ligand_target_matrix = ltm,
+        n = n_targets
+    )
+
+    adata.uns[key_nichenet]['ligand_targets'] = ltl

exprmat-0.1.50/exprmat/lr/icnet/construction.py

@@ -0,0 +1,270 @@
+"""
+Network construction functions: weighted networks and hub corrections
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, List, Tuple, Optional
+
+
+def construct_weighted_networks(
+    lr_network: pd.DataFrame,
+    sig_network: pd.DataFrame,
+    gr_network: pd.DataFrame,
+    source_weights_df: pd.DataFrame,
+    n_output_networks: int = 2
+) -> Dict[str, pd.DataFrame]:
+    """
+    Construct layer-specific weighted integrated networks from input source networks
+    via weighted aggregation.
+    
+    Parameters:
+    -----------
+    lr_network : pd.DataFrame
+        Ligand-receptor interactions (required columns: from, to, source)
+    sig_network : pd.DataFrame
+        Signaling interactions (required columns: from, to, source)
+    gr_network : pd.DataFrame
+        Gene regulatory interactions (required columns: from, to, source)
+    source_weights_df : pd.DataFrame
+        Weights associated to each data source (required columns: source, weight)
+    n_output_networks : int
+        Number of output networks: 2 (ligand-signaling and gene regulatory; default)
+        or 3 (ligand-receptor, signaling and gene regulatory)
+    
+    Returns:
+    --------
+    dict
+        Dictionary containing:
+        - If n_output_networks=2: {'lr_sig': DataFrame, 'gr': DataFrame}
+        - If n_output_networks=3: {'lr': DataFrame, 'sig': DataFrame, 'gr': DataFrame}
+        Each DataFrame has columns: from, to, weight
+    """
+    # Input validation
+    if not isinstance(lr_network, pd.DataFrame):
+        raise TypeError("lr_network must be a pandas DataFrame")
+    if not isinstance(sig_network, pd.DataFrame):
+        raise TypeError("sig_network must be a pandas DataFrame")
+    if not isinstance(gr_network, pd.DataFrame):
+        raise TypeError("gr_network must be a pandas DataFrame")
+    if not isinstance(source_weights_df, pd.DataFrame):
+        raise TypeError("source_weights_df must be a pandas DataFrame")
+    
+    required_cols_lr = ['from', 'to', 'source']
+    required_cols_weights = ['source', 'weight']
+    
+    for col in required_cols_lr:
+        if col not in lr_network.columns:
+            raise ValueError(f"lr_network must have column '{col}'")
+        if col not in sig_network.columns:
+            raise ValueError(f"sig_network must have column '{col}'")
+        if col not in gr_network.columns:
+            raise ValueError(f"gr_network must have column '{col}'")
+    
+    for col in required_cols_weights:
+        if col not in source_weights_df.columns:
+            raise ValueError(f"source_weights_df must have column '{col}'")
+    
+    if (source_weights_df['weight'] > 1).any():
+        raise ValueError("No data source weight may be higher than 1")
+    
+    if n_output_networks not in [2, 3]:
+        raise ValueError("n_output_networks must be 2 or 3")
+    
+    # Remove data sources for which weight equals 0
+    source_weights_df = source_weights_df[source_weights_df['weight'] > 0].copy()
+    
+    # Perform weighted network aggregation for gene regulatory network
+    gr_network_w = (
+        gr_network
+        .merge(source_weights_df, on='source', how='inner')
+        .groupby(['from', 'to'], as_index=False)
+        .agg({'weight': 'sum'})
+    )
+    
+    if n_output_networks == 2:
+        # Combine ligand-receptor and signaling networks
+        ligand_signaling_w = (
+            pd.concat([lr_network, sig_network], ignore_index=True)
+            .merge(source_weights_df, on='source', how='inner')
+            .groupby(['from', 'to'], as_index=False)
+            .agg({'weight': 'sum'})
+        )
+        return {
+            'lr_sig': ligand_signaling_w,
+            'gr': gr_network_w
+        }
+    else:  # n_output_networks == 3
+        lr_network_w = (
+            lr_network
+            .merge(source_weights_df, on='source', how='inner')
+            .groupby(['from', 'to'], as_index=False)
+            .agg({'weight': 'sum'})
+        )
+        sig_network_w = (
+            sig_network
+            .merge(source_weights_df, on='source', how='inner')
+            .groupby(['from', 'to'], as_index=False)
+            .agg({'weight': 'sum'})
+        )
+        return {
+            'lr': lr_network_w,
+            'sig': sig_network_w,
+            'gr': gr_network_w
+        }
+
+
+def apply_hub_corrections(
+    weighted_networks: Dict[str, pd.DataFrame],
+    lr_sig_hub: float,
+    gr_hub: float
+) -> Dict[str, pd.DataFrame]:
+    """
+    Apply hub corrections to the weighted integrated ligand-signaling and gene
+    regulatory network. Downweighs the importance of nodes with a lot of incoming links.
+    
+    Hub correction method: W_cor = W * D^(-h)
+    where D is the indegree matrix and h is the correction factor.
+    
+    Parameters:
+    -----------
+    weighted_networks : dict
+        Dictionary with keys 'lr_sig' and 'gr', each containing a DataFrame
+        with columns: from, to, weight
+    lr_sig_hub : float
+        Hub correction factor for ligand-signaling network (0-1).
+        0: no correction, 1: maximal correction
+    gr_hub : float
+        Hub correction factor for gene regulatory network (0-1).
+        0: no correction, 1: maximal correction
+    
+    Returns:
+    --------
+    dict
+        Dictionary with hub-corrected networks: {'lr_sig': DataFrame, 'gr': DataFrame}
+    """
+    # Input validation
+    if not isinstance(weighted_networks, dict):
+        raise TypeError("weighted_networks must be a dictionary")
+    if 'lr_sig' not in weighted_networks:
+        raise ValueError("weighted_networks must contain 'lr_sig' key")
+    if 'gr' not in weighted_networks:
+        raise ValueError("weighted_networks must contain 'gr' key")
+    
+    if not isinstance(weighted_networks['lr_sig'], pd.DataFrame):
+        raise TypeError("weighted_networks['lr_sig'] must be a pandas DataFrame")
+    if not isinstance(weighted_networks['gr'], pd.DataFrame):
+        raise TypeError("weighted_networks['gr'] must be a pandas DataFrame")
+    
+    if 'weight' not in weighted_networks['lr_sig'].columns:
+        raise ValueError("lr_sig must contain a column named 'weight'")
+    if 'weight' not in weighted_networks['gr'].columns:
+        raise ValueError("gr must contain a column named 'weight'")
+    
+    if not (0 <= lr_sig_hub <= 1):
+        raise ValueError("lr_sig_hub must be between 0 and 1 (inclusive)")
+    if not (0 <= gr_hub <= 1):
+        raise ValueError("gr_hub must be between 0 and 1 (inclusive)")
+    
+    ligand_signaling_network = weighted_networks['lr_sig'].copy()
+    regulatory_network = weighted_networks['gr'].copy()
+    
+    # Apply hub correction to ligand-signaling network
+    if lr_sig_hub > 0:
+        # Count incoming edges (indegree) for each node
+        indegree = ligand_signaling_network.groupby('to', as_index=False).size()
+        indegree.columns = ['to', 'n']
+        
+        # Merge indegree counts and apply correction
+        ligand_signaling_network = (
+            ligand_signaling_network
+            .merge(indegree, on='to', how='left')
+            .assign(weight=lambda x: x['weight'] / (x['n'] ** lr_sig_hub))
+            .drop(columns=['n'])
+        )
+    
+    # Apply hub correction to gene regulatory network
+    if gr_hub > 0:
+        # Count incoming edges (indegree) for each node
+        indegree = regulatory_network.groupby('to', as_index=False).size()
+        indegree.columns = ['to', 'n']
+        
+        # Merge indegree counts and apply correction
+        regulatory_network = (
+            regulatory_network
+            .merge(indegree, on='to', how='left')
+            .assign(weight=lambda x: x['weight'] / (x['n'] ** gr_hub))
+            .drop(columns=['n'])
+        )
+    
+    return {
+        'lr_sig': ligand_signaling_network,
+        'gr': regulatory_network
+    }
+
+
+def add_new_datasource(
+    new_source: pd.DataFrame,
+    network: Optional[pd.DataFrame],
+    new_weight: float,
+    source_weights_df: pd.DataFrame
+) -> Tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Add a new data source to one of the ligand-receptor, signaling or gene
+    regulatory data sources.
+    
+    Parameters:
+    -----------
+    new_source : pd.DataFrame
+        Novel interactions (required columns: from, to, source)
+    network : pd.DataFrame or None
+        Base network to which to add the new data source (required columns: from, to, source)
+        If None, creates a new network
+    new_weight : float
+        Weight value between 0 and 1 to assign to the new data source
+    source_weights_df : pd.DataFrame
+        Weights associated to each already included data source (required columns: source, weight)
+    
+    Returns:
+    --------
+    tuple
+        (updated_network, updated_source_weights_df)
+    """
+    # Input validation
+    if not isinstance(new_source, pd.DataFrame):
+        raise TypeError("new_source must be a pandas DataFrame")
+    if network is not None and not isinstance(network, pd.DataFrame):
+        raise TypeError("network must be a pandas DataFrame or None")
+    if not isinstance(source_weights_df, pd.DataFrame):
+        raise TypeError("source_weights_df must be a pandas DataFrame")
+    
+    if not (0 <= new_weight <= 1):
+        raise ValueError("new_weight must be between 0 and 1")
+    
+    if (source_weights_df['weight'] > 1).any() or new_weight > 1:
+        raise ValueError("No data source weight may be higher than 1")
+    
+    # Get unique source name(s) from new_source
+    new_source_names = new_source['source'].unique()
+    
+    if network is None:
+        # Create new network
+        updated_network = new_source.copy()
+        updated_source_weights_df = pd.DataFrame({
+            'source': new_source_names,
+            'weight': [new_weight] * len(new_source_names)
+        })
+    else:
+        # Add to existing network
+        updated_network = pd.concat([network, new_source], ignore_index=True)
+        new_weights = pd.DataFrame({
+            'source': new_source_names,
+            'weight': [new_weight] * len(new_source_names)
+        })
+        updated_source_weights_df = pd.concat(
+            [source_weights_df, new_weights],
+            ignore_index=True
+        )
+    
+    return updated_network, updated_source_weights_df
+