exprmat 0.1.49__tar.gz → 0.1.51__tar.gz

{exprmat-0.1.49 → exprmat-0.1.51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: exprmat
-Version: 0.1.49
+Version: 0.1.51
 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,20 +150,123 @@ 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
 Alibaba Cloud service (See the [Documentation](https://help.aliyun.com/zh/ram/user-guide/create-an-accesskey-pair)
 for details)
+
+### Licensing
+
+The original part of the source code is licensed under GNU GPLv3.
+
+```
+exprmat - 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.
+```
+
+I acknowledge the following author(s) for modifying and integrating their work
+in the form of source code to this package.
+
+```
+parts of the source code under /preprocessing comes from the scanpy project.
+
+  BSD 3-Clause License. For full text of the license, see 
+  <https://opensource.org/license/BSD-3-clause>
+  Copyright (c) 2025 scverse®
+  Copyright (c) 2017 F. Alexander Wolf, P. Angerer, Theis Lab
+
+function embedding_atlas (file /reduction/plot.py) comes from the omicverse project.
+
+  GNU GPLv3. (same as this project)
+  Copyright (c) 2024 112 Lab
+
+most of the code from /snapatac2 and /snapatac2-core comes from the SnapATAC
+project, including the rust build system and the compiled binaries.
+
+  The MIT license. For full text of the license, see
+  <https://opensource.org/license/MIT>
+  Copyright (c) 2022-2024 Kai Zhang
+
+file /clustering/sc3.py comes from the sc3s project.
+
+  GNU GPLv3. (same as this project)
+  Copyright (c) Quah, F.X. and Hemberg, M. and contributors.
+
+file /clustering/nmf.py comes from cNMF project.
+
+  The MIT license
+  Copyright (c) 2019 Dylan Kotliar
+
+directory /cnv comes from infercnvpy project.
+  
+  BSD 3-Clause License
+  Copyright (c) 2022, Gregor Sturm
+
+directory /deconv comes from the TAPE project.
+
+  GNU GPLv3. (same as this project)
+  Copyright (c) The contributors.
+
+directory /metacell comes from the MetaQ project.
+  
+  MIT License
+  Copyright (c) 2024 XLearning Group
+
+directory /grn comes from the scenicplus project.
+
+  Academic Non-commercial Software License Agreement.
+  For full text of the license, see <https://github.com/aertslab/scenicplus>
+  Copyright (c) The contributors.
+
+directory /lr (but not /lr/icnet) comes from the lianapy project
+
+  BSD 3-Clause License
+  Copyright (c) 2025, Daniel Dimitrov
+
+directory /peaks/idr.py comes from the idr project
+
+  GNU GPLv2. For copyright details, see <https://github.com/nboley/idr>
+  Copyright (c) The contributors
+
+function diffmap comes from the pydiffmap project
+
+  MIT License
+  Copyright (c) 2018 Ralf Banisch, Erik Henning Thiede, Zofia Trstanova
+
+principle tree fitting and trajectory analysis comes from the scFates project
+
+  BSD 3-Clause License
+  Copyright (c) 2020, Louis Faure
+
+file /trajectory/cytotrace.py comes from the CytoTRACE2 project
+
+  Stanford Non-commercial Software License Agreement
+  Copyright (c) The contributors.
+
+rna velocity fitting comes from the scvelo project
+
+  BSD 3-Clause License
+  Copyright (c) 2018, Theis Lab
+```
+

{exprmat-0.1.49 → exprmat-0.1.51}/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>
 """
 
@@ -112,7 +112,7 @@ basepath = config['data']
 
 # core method exports
 from exprmat.utils import setup_styles, savefig
-from exprmat.ansi import pprog, pproga, info, error, warning
+from exprmat.ansi import pprog, pproga, info, error, warning, default_logger, logger
 from exprmat.reader.experiment import experiment, load_experiment
 from exprmat.reader.metadata import metadata, load_metadata
 import exprmat.reader.static as st
@@ -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.49 → exprmat-0.1.51}/exprmat/ansi.py

@@ -7,7 +7,48 @@ from functools import partial
 from tqdm import tqdm
 from tqdm.auto import tqdm as tqdma
 
-SILENT = False
+
+class logger:
+
+    silent = False
+
+    def __init__(self, silent: bool = False) -> None:
+        self.silent = silent
+    
+    def error(self, text: str, error = None) -> None:
+
+        if self.silent: 
+            if error: raise Exception(text) from error
+            else: raise Exception(text)
+
+        fore_red()
+        print('[error]', end = ' ')
+        ansi_reset()
+        print(text)
+
+        if error is None: raise Exception(text)
+        else: raise Exception(text) from error
+
+
+    def warning(self, text: str) -> None:
+        if self.silent: return
+        fore_yellow()
+        print('[!]', end = ' ')
+        ansi_reset()
+        print(text)
+        ansi_reset()
+
+
+    def info(self, text: str) -> None:
+        if self.silent: return
+        fore_cyan()
+        print('[i]', end = ' ')
+        ansi_reset()
+        print(text)
+        ansi_reset()
+
+
+default_logger = logger()
 
 
 def fore_black() -> None:
@@ -114,32 +155,15 @@ def format_file_size(size):
 
 
 def error(text: str, error = None) -> None:
-    if SILENT: raise Exception(text) from error
-    fore_red()
-    print('[error]', end = ' ')
-    ansi_reset()
-    print(text)
-
-    if error is None: raise Exception(text)
-    else: raise Exception(text) from error
+    default_logger.error(text, error)
 
 
 def warning(text: str) -> None:
-    if SILENT: return
-    fore_yellow()
-    print('[!]', end = ' ')
-    ansi_reset()
-    print(text)
-    ansi_reset()
+    default_logger.warning(text)
 
 
 def info(text: str) -> None:
-    if SILENT: return
-    fore_cyan()
-    print('[i]', end = ' ')
-    ansi_reset()
-    print(text)
-    ansi_reset()
+    default_logger.info(text)
 
 
 def clear():

exprmat-0.1.51/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.51/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