Gene-set files

Gene-set files#

read_gmt() reads a GMT file, one gene set per line, as MSigDB, Reactome, WikiPathways and the GMT exports of the Gene Ontology write them, into a GeneSets: a mapping of set name to gene ids that every gene-set function of CytePool takes as its gene_sets, with each set’s description and the source, version and licence of the collection, which you state when you read it, and the name and SHA-256 digest of the file. CytePool bundles no collection. write_gmt() writes a collection back.

Collections of gene sets, read from and written to GMT files.

A GeneSets maps the name of each gene set to its genes, named by gene id, and keeps the description of each set and where the collection comes from: its source, version and licence, as the user states them from what the provider of the collection documents, and, for a collection read from a file, the name of the file and its SHA-256 digest. CytePool bundles no collection: MSigDB (Liberzon et al. 2011), Reactome, WikiPathways and the Gene Ontology distribute their sets under their own terms, and read_gmt() reads the files that users download from them.

A GeneSets is a mapping of set name to genes, so every gene-set function of CytePool takes it as it is: as gene_sets of camera(), fry(), mroast(), romer() and over_representation(), and one of its sets, as gene_sets[name], as gene_set of roast(). The tests of a linear model match the ids to their gene_ids.

Genes and sets:

A set’s genes are a tuple of gene ids (non-empty strings, compared exactly, case included), each once, in the order given: a gene listed twice keeps its first place, and the genes of a Python set are taken in sorted order, so that every run lists them alike. Set names are non-empty strings. A description of "na", which GSEA writes for a set without one, or an empty description, is None.

Matching and filtering:

GeneSets.restrict_to() keeps the genes of each set that an analysis measured and drops the sets left without genes, as limma’s ids2indices does by default, and refuses ids that match no gene at all, as when the sets name genes by symbol and the analysis by Ensembl id. GeneSets.filter_by_size() keeps the sets of a range of sizes; restricted first, the sizes are those within the analysis, as GSEA counts them before it leaves out sets of fewer than 15 or more than 500 genes, its defaults (GSEA team 2026). GeneSets.select() takes sets by name. Each returns a new GeneSets with the descriptions and the record of the source.

GMT files:

The GMT (gene matrix transposed) format of GSEA (Subramanian et al. 2005; GSEA team 2026) holds one gene set per line, in fields separated by tabs: the set’s name, a description, and the set’s genes. read_gmt() reads:

  • fields separated by tabs only, so that names with spaces, such as Reactome’s pathway names, are read whole;

  • lines that end in a line feed, a carriage return and line feed, or a carriage return; blank lines are skipped;

  • empty fields among the genes, such as a tab at the end of a line, which are skipped, and spaces at either end of a field, which are removed;

  • a set without genes (a name and a description only), kept with no genes;

  • UTF-8 text, with or without a byte-order mark, compressed by gzip or not (recognised by the first bytes of the file, whatever its name).

A line with one field, a set without a name, or a name used for two sets is refused, with the number of the line. write_gmt() writes the same format, with "na" for a set without a description, so that read_gmt() reads back the same sets and descriptions. A GMT file holds no source, version or licence; they are given again when the file is read.

References

Subramanian A, Tamayo P, Mootha VK, Mukherjee S, Ebert BL, Gillette MA, Paulovich A, Pomeroy SL, Golub TR, Lander ES, Mesirov JP (2005). Gene set enrichment analysis: a knowledge-based approach for interpreting genome-wide expression profiles. Proceedings of the National Academy of Sciences 102, 15545-15550. doi:10.1073/pnas.0506580102

Liberzon A, Subramanian A, Pinchback R, Thorvaldsdottir H, Tamayo P, Mesirov JP (2011). Molecular signatures database (MSigDB) 3.0. Bioinformatics 27, 1739-1740. doi:10.1093/bioinformatics/btr260

GSEA team (2026). GSEA-MSigDB documentation: the GSEA User Guide and Data Formats. UC San Diego and Broad Institute, https://docs.gsea-msigdb.org/

class cytepool.gene_sets.GeneSets(sets, *, descriptions=None, source=None, version=None, licence=None, file=None, sha256=None)#

Named gene sets, with their descriptions and the source of the collection.

A read-only mapping of set name to the set’s genes, a tuple of gene ids, so that the gene-set functions of CytePool take it as their gene_sets. The module docstring says how ids, names and descriptions are read. read_gmt builds one from a GMT file. Immutable.

Parameters:

  • sets – Mapping of set name to the set’s genes, as gene ids (strings): a list, tuple, set or 1-D array of them. A gene listed twice counts once.

  • descriptions – Mapping of set name to the set’s description (a string), for some or all of the sets; the others have None.

  • source – Where the sets come from, such as "MSigDB hallmark gene sets".

  • version – The version or release of the collection, such as "2024.1.Hs".

  • licence – The terms under which the provider distributes the sets, such as "CC BY 4.0", as its documentation states them.

  • file – The name of the file the sets were read from.

  • sha256 – The SHA-256 digest of that file, 64 hexadecimal digits in lower case.

Raises:

  • TypeError – If sets or descriptions is not a mapping, a name, gene id or text is not a string, a set’s genes are a single string or map genes to weights, or an argument is or holds a numpy masked array.

  • ValueError – If a name or gene id is empty, a description names a set that is not in sets, or sha256 is not a SHA-256 digest.

Example

>>> sets = GeneSets({"interferon": ["ISG15", "IFIT1", "MX1"]}, source="my lab")
>>> sets["interferon"]
('ISG15', 'IFIT1', 'MX1')

Explained in: Gene-set tests

property descriptions#

The description of every set, None where it has none, as a read-only mapping.

property source#

Where the sets come from, as stated; None when not stated.

property version#

The version or release of the collection, as stated; None when not stated.

property licence#

The terms under which the sets are distributed, as stated; None when not stated.

property file#

The name of the file the sets were read from; None for sets not read from a file.

property sha256#

The SHA-256 digest of the bytes of that file, as stored (compressed or not); None for sets not read from a file.

select(names)#

Return the sets with the given names, in that order.

Parameters:

names – A set name, or a sequence of them.

Raises:

  • KeyError – If a name is not a set’s; the message suggests close names.

  • TypeError – If a name is not a string, or names is or holds a numpy masked array.

  • ValueError – If a name is given twice.

Explained in: Gene-set tests

restrict_to(genes, *, keep_empty=False)#

Return the sets with only their genes among genes.

Each set keeps its genes that are among genes, in its own order, as the gene-set tests would match them; sets left without genes are dropped, as limma’s ids2indices drops them by default, unless keep_empty.

Parameters:

  • genes – The ids of the genes of an analysis, such as the feature_id or symbol column of a differential-expression table. Missing ids (None, NaN or empty strings) are ignored.

  • keep_empty – Whether to keep the sets left without genes.

Raises:

  • TypeError – If genes does not hold strings, or is or holds a numpy masked array.

  • ValueError – If no gene of any set is among genes: the sets and the analysis name genes in different ways, for example by symbol and by Ensembl id.

Explained in: Gene-set tests

filter_by_size(min_size, max_size=None)#

Return the sets of at least min_size and at most max_size genes.

Sizes are the numbers of genes the sets hold: to count the genes of an analysis only, as GSEA does, call restrict_to() first.

Parameters:

  • min_size – The fewest genes a set may hold, at least 0.

  • max_size – The most genes a set may hold, at least min_size; None for no limit.

Raises:

  • TypeError – If a size is not an integer.

  • ValueError – If min_size is negative or max_size is smaller than min_size.

Explained in: Gene-set tests

cytepool.gene_sets.read_gmt(path, *, source=None, version=None, licence=None)#

Read gene sets from a GMT file.

One set per line: its name, a description and its genes, separated by tabs, as MSigDB, Reactome, WikiPathways and the GMT exports of the Gene Ontology write them; the module docstring says what is read and how. The collection records the name of the file and the SHA-256 digest of its bytes, and the source, version and licence given here, which the file cannot hold: state them as the provider documents them, so that results can say which sets they used.

Parameters:

  • path – The GMT file, compressed by gzip or not.

  • source – Where the sets come from, such as "MSigDB hallmark gene sets".

  • version – The version or release of the collection, such as "2024.1.Hs".

  • licence – The terms under which the provider distributes the sets, such as "CC BY 4.0".

Returns:

The sets, in the order of the file.

Raises:

  • TypeError – If path is not a str or os.PathLike, or an option is not a string.

  • ValueError – If the file is not UTF-8 text or valid gzip, holds no gene set, or a line holds one field only, a set without a name or the name of an earlier set; the message gives the line.

  • FileNotFoundError – If there is no file at path.

Explained in: Choosing a method, Gene-set tests

cytepool.gene_sets.write_gmt(gene_sets, path, *, overwrite=False)#

Write gene sets to a GMT file.

One line per set, in order: its name, its description ("na" without one) and its genes, separated by tabs, in UTF-8 with line feeds, compressed by gzip when the name of the file ends in .gz. read_gmt() reads back the same sets and descriptions. The source, version and licence of a GeneSets are not written: GMT has no place for them.

Parameters:

  • gene_sets – A GeneSets, or a mapping of set name to gene ids.

  • path – The file to write.

  • overwrite – Whether to replace a file that exists at path.

Raises:

  • TypeError – If gene_sets is not a mapping of names to gene ids, or overwrite is not a bool.

  • ValueError – If a name, description or gene id holds a tab or a line break, or starts or ends with spaces, which a GMT file cannot hold as written.

  • FileExistsError – If a file exists at path and overwrite is False.

Explained in: Gene-set tests