Networks#

A Network maps each source, a transcription factor or a pathway, to its target genes with signed weights, and records its name, version, licence, citation and the file it was read from. collectri() returns CollecTRI’s regulons of human transcription factors, at the licence level you choose, and progeny() the pathway signatures of PROGENy for human or mouse; both download their files on first use, check them against pinned SHA-256 digests and keep them in a cache. The activity functions of cytepool.activity take a network, or a table with the columns source, target and weight.

Networks of regulators and pathways and the genes they act on, with signed weights: CollecTRI’s transcription factors and PROGENy’s pathways, downloaded from their releases, and networks given as tables.

A Network maps each source, a transcription factor or a pathway, to its targets, the genes it regulates or that respond to it, each with a weight whose sign says whether the source raises the gene (positive) or lowers it (negative). The activity functions of cytepool.activity take one, as decoupler takes its networks (Badia-i-Mompel et al. 2022): a table with the columns source, target and weight. A network records its name, version, where it comes from, its licence and its citation, and, for a network read from a file, the name of the file and its SHA-256 digest.

CollecTRI (collectri()):

The signed regulons of 1,186 human transcription factors, 43,175 interactions, that Mueller-Dott et al. (2023) assembled from twelve resources of literature curation and text mining: version 2.0 of the file CollecTRI_regulons.csv of Zenodo record 8192729 (doi:10.5281/zenodo.8192729), which decoupler 2.2.0 reads too, under the Creative Commons Attribution 4.0 licence. Each interaction has a weight of 1 (activation) or -1 (repression), the resources that list it, the PubMed ids of its references and how its sign was decided. The complexes AP1 and NFKB are sources of their own, as in the file.

Licence levels. Each resource keeps its own terms, which OmniPath records (Tuerei et al. 2021). licence="commercial", the default, keeps the interactions that at least one resource listed for commercial use supports: every resource but GEREDB, which OmniPath lists for academic use (under the Academic Free License 3.0), so that the 3,279 interactions that GEREDB alone supports are left out, 39,896 remain. licence="academic" keeps every interaction. The terms of the other resources, as OmniPath lists them: CC BY 4.0 (ExTRI, NTNU Curated, TFactS, SIGNOR, IntAct, CytReg, GOA and Pavlidis2021), CC BY-SA 4.0 (TRRUST), LGPL 3.0 (HTRIdb) and an informal licence (DoRothEA’s level A). Use under any level is subject to these terms, such as attribution.

PROGENy (progeny()):

The weights of the genes that respond to 14 signalling pathways, from the perturbation experiments of Schubert et al. (2018), for human, and their transfer to mouse (Holland, Szalai and Saez-Rodriguez 2020): the data frames model_human_full (22,479 genes) and model_mouse_full (17,426 genes) of the R package progeny 1.28.0, from its Bioconductor 3.20 release, under the Apache License 2.0, with a weight (a z-score) and a p-value for every gene and pathway. By default the genes with a p-value below 0.05 are kept, as decoupler’s op.progeny keeps them; top keeps the genes of each pathway with the smallest p-values, those tied with the last one included, as progeny’s getModel does (100 genes by default there).

Downloads and the cache:

Each network is downloaded on first use from the address it was published at, pinned by its size and SHA-256 digest, into the cache directory: cache_dir, else cytepool/networks under XDG_CACHE_HOME or ~/.cache. A file whose size or digest differs from the pinned ones is refused, whether downloaded or found in the cache, so that a network is always the release its version names. With the file in the cache, as when copied there from another machine, no connection is made.

R’s data files:

progeny keeps its weights in R’s data files (.rda), which this module reads with a reader of R’s serialization format (version 2 or 3, XDR; R Core Team 2025) limited to what data frames of numbers, text and factors use: vectors, pairlists of attributes, symbols and references to them, and R’s compact sequences of numbers, compressed by xz, bzip2 or gzip.

References

Mueller-Dott S, Tsirvouli E, Vazquez M, Ramirez Flores RO, Badia-i-Mompel P, Fallegger R, Tuerei D, Laegreid A, Saez-Rodriguez J (2023). Expanding the coverage of regulons from high-confidence prior knowledge for accurate estimation of transcription factor activities. Nucleic Acids Research 51, 10934-10949. doi:10.1093/nar/gkad841

Schubert M, Klinger B, Kluenemann M, Sieber A, Uhlitz F, Sauer S, Garnett MJ, Bluethgen N, Saez-Rodriguez J (2018). Perturbation-response genes reveal signaling footprints in cancer gene expression. Nature Communications 9, 20. doi:10.1038/s41467-017-02391-6

Holland CH, Szalai B, Saez-Rodriguez J (2020). Transfer of regulatory knowledge from human to mouse for functional genomics analysis. Biochimica et Biophysica Acta (BBA) - Gene Regulatory Mechanisms 1863, 194431. doi:10.1016/j.bbagrm.2019.194431

Tuerei D, Valdeolivas A, Gul L, Palacio-Escat N, Klein M, Ivanova O, Oelbei M, Gabor A, Theis F, Modos D, Korcsmaros T, Saez-Rodriguez J (2021). Integrated intra- and intercellular signaling knowledge for multicellular omics analysis. Molecular Systems Biology 17, e9923. doi:10.15252/msb.20209923

Badia-i-Mompel P, Velez Santiago J, Braunger J, Geiss C, Dimitrov D, Mueller-Dott S, Taus P, Dugourd A, Holland CH, Ramirez Flores RO, Saez-Rodriguez J (2022). decoupleR: ensemble of computational methods to infer biological activities from omics data. Bioinformatics Advances 2, vbac016. doi:10.1093/bioadv/vbac016

R Core Team (2025). R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing, Vienna. https://www.R-project.org/

class cytepool.networks.Network(edges, *, name=None, version=None, url=None, licence=None, citation=None, file=None, sha256=None)#

Sources, such as transcription factors or pathways, and their target genes, with signed weights.

A read-only mapping of each source to its targets, a mapping of gene id to weight, so that network["STAT1"]["IRF1"] is the weight of the edge from STAT1 to IRF1. The edges keep the order given, and the sources the order in which they first appear. collectri() and progeny() build one from their releases. Immutable.

Parameters:

edges – A Table, a pandas DataFrame or a mapping of column name to values, with the columns source, target and, optionally, weight (1 for every edge without it), one row per edge; other columns, such as a p-value or the resources of an interaction, are kept with the edges. Or a mapping of source to its targets: a mapping of gene id to weight, or a list of gene ids, each of weight 1, so that a GeneSets is a network of unweighted sets.
name – The network’s name, such as "CollecTRI".
version – Its version or release.
url – Where it was obtained.
licence – The terms under which it is distributed, as its provider states them.
citation – The work to cite for it.
file – The name of the file it was read from.
sha256 – The SHA-256 digest of that file, 64 hexadecimal digits in lower case.

Raises:

TypeError – If edges is none of these, a source or target is not a string, a weight is not a real number, a text option is not a string, or an argument is or holds a numpy masked array.
ValueError – If a table lacks the source or target column, a source or target is missing or empty, a weight is not finite, an edge is given twice, there are no edges, or sha256 is not a SHA-256 digest.

Example

>>> network = Network({"STAT1": {"IRF1": 1.0, "SOCS1": 1.0, "MYC": -1.0}})
>>> network["STAT1"]["MYC"]
-1.0

Explained in: Gene-set tests

property edges#: The edges, one row per edge, with the columns source, target and weight and any others given.

property sources#: The sources, in the order in which they first appear.

property name#: The network’s name; None when not stated.

property version#: Its version or release; None when not stated.

property url#: Where it was obtained; None when not stated.

property licence#: The terms under which it is distributed; None when not stated.

property citation#: The work to cite for it; None when not stated.

property file#: The name of the file it was read from; None for a network built in Python.

property sha256#: The SHA-256 digest of that file; None for a network built in Python.

select(sources)#

Return the edges of the given sources, in that order of sources.

Parameters:

sources – A source, or a sequence of them.

Raises:

KeyError – If a name is not a source’s; the message suggests close names.
TypeError – If a name is not a string, or sources is or holds a numpy masked array.
ValueError – If a source is given twice, or none is given.

Explained in: Gene-set tests

cytepool.networks.collectri(*, licence='commercial', cache_dir=None)#

The CollecTRI network of human transcription factors and their target genes.

The signed regulons of Mueller-Dott et al. (2023), version 2.0 of its Zenodo record, at the licence level asked for: the module docstring says what each level holds and the terms of each resource. The file is downloaded on first use, checked against its pinned size and SHA-256 digest, and kept in the cache.

Parameters:

licence – "commercial", the interactions of resources that OmniPath lists for commercial use (39,896), or "academic", every interaction (43,175).
cache_dir – The directory that holds the downloaded file; by default cytepool/networks under XDG_CACHE_HOME or ~/.cache.

Returns:

A network with the columns source, target, weight (1 or -1), resources (the resources that list the interaction, separated by ";"), references (PubMed ids, separated by ";") and sign_decision, in the order of the file.

Raises:

ValueError – If licence is not one of the levels, or the file in the cache, or the one downloaded, is not the file pinned (its size or digest differs).
TypeError – If an argument has the wrong type.
OSError – If the file is not in the cache and cannot be downloaded.

Example

>>> network = collectri()
>>> network["STAT1"]["IRF1"]
1.0

Used in: Gene sets and pathways, Pathway and regulator activity

Explained in: Choosing a method, Gene-set tests

cytepool.networks.progeny(*, organism='human', top=None, max_p_value=_PROGENY_MAX_P_VALUE, cache_dir=None)#

The PROGENy network of 14 signalling pathways and the genes that respond to them.

The weights of the R package progeny 1.28.0 (Schubert et al. 2018; Holland, Szalai and Saez-Rodriguez 2020), under the Apache License 2.0: each pathway’s genes in increasing order of their p-values, those with a p-value below max_p_value, as decoupler’s op.progeny keeps them, and, with top, only the top genes with the smallest p-values, those tied with the last one included, as progeny’s getModel keeps them. The package is downloaded on first use, checked against its pinned size and SHA-256 digest, and kept in the cache.

Parameters:

organism – "human" or "mouse".
top – The most genes of each pathway, at least 1; None for no limit. progeny’s getModel and progeny take 100 by default, decoupler’s tutorials 500.
max_p_value – Keep the genes with a p-value below it, in (0, 1]; None keeps every gene. 0.05 by default, as in decoupler.
cache_dir – The directory that holds the downloaded file; by default cytepool/networks under XDG_CACHE_HOME or ~/.cache.

Returns:

A network with the columns source (the pathway), target (the gene), weight and p_value, the pathways in alphabetical order and the genes of each in increasing order of their p-values.

Raises:

ValueError – If an option is out of range, or the file in the cache, or the one downloaded, is not the file pinned (its size or digest differs).
TypeError – If an argument has the wrong type.
OSError – If the file is not in the cache and cannot be downloaded.

Example

>>> network = progeny(top=100)
>>> len(network)
14

Used in: Pathway and regulator activity

Explained in: Choosing a method, Gene-set tests

Networks

Contents

Networks#