Gene set collections

Gene set collections organize related groups of genes. Each gene set has a name, a description, and a list of gene symbols. For example, the Gene Ontology (GO) collection contains gene sets associated with biological processes, molecular functions, and cellular components. GAIn provides the GeneSetCollection Python class for accessing these resources. Individual gene sets are represented by GeneSet objects.

Accessing a gene set collection

A GeneSetCollection object can be built from a resource ID and a repository using build_gene_set_collection_from_resource_id():

import gain.grr as grr

repo = grr.build_genomic_resource_repository()
collection = grr.build_gene_set_collection_from_resource_id(
    "gene_properties/gene_sets/GO_2025-07-22_release", repo
)

If you already have a GenomicResource object, use build_gene_set_collection_from_resource() instead:

resource = repo.get_resource(
    "gene_properties/gene_sets/GO_2025-07-22_release"
)
collection = grr.build_gene_set_collection_from_resource(resource)

Both builder functions are available through gain.grr.

Loading a gene set collection

A newly built collection must be loaded before its gene sets can be accessed. Call load() to read the gene sets from the resource into memory:

collection.load()

The load() method returns the collection itself, so it can also be chained to a builder function. GAIn reuses the same GeneSetCollection object when the same resource is requested again, and that object may already be loaded. Calling load() on an already-loaded collection has no effect. Use is_loaded() to check its state. The collection does not maintain an open file handle and has no close() method.

Retrieving gene sets

get_all_gene_sets() returns a list of all gene sets in the collection. get_gene_set() retrieves one gene set by name and returns None if the name is not found.

A GeneSet object has four attributes: name, desc (description), syms (gene symbols), and count (number of gene symbols).

For example, the following code retrieves the number of gene sets in the GO collection and examines one of them:

gene_sets = collection.get_all_gene_sets()
print("Number of gene sets:", len(gene_sets))

selected = collection.get_gene_set(
    "GO:0000009-alpha-1,6-mannosyltransferase_activity"
)
print(selected.name, selected.count)
print(selected.syms)

Number of gene sets: 21608
GO:0000009-alpha-1,6-mannosyltransferase_activity 3
['ALG12', 'ALG2', 'PIGV']

The collection also has a collection_id, taken from the resource’s id: setting. Its web_label and web_format_str attributes provide formatting information used when displaying gene sets in a web interface.

Resource formats

The format: setting in the resource definition determines how gene sets are stored. GAIn supports three formats:

directory stores each gene set in a separate file within a directory.
gmt stores the gene sets in a GMT file.
map stores mappings from genes to gene sets.

All three formats are loaded into the same GeneSetCollection and GeneSet Python objects. The resource configuration options are described in Genomic resources and repositories.

Gene set statistics

A statistics build stores two histograms for a gene set collection. One describes the number of genes in each gene set. The other describes the number of gene sets containing each gene.

The methods get_genes_per_gene_set_hist() and get_gene_sets_per_gene_hist() retrieve these histograms:

genes_per_set = collection.get_genes_per_gene_set_hist()
sets_per_gene = collection.get_gene_sets_per_gene_hist()

Each method returns None if the corresponding histogram is not stored in the resource. Histogram objects and their contents are explained in Histograms.

API

The classes below are defined in the module gain.gene_sets.gene_set. GeneSetCollection is also exported by gain.grr, as grr.GeneSetCollection. The builders build_gene_set_collection_from_resource_id and build_gene_set_collection_from_resource are defined in the same module. They are also exported by gain.grr, as grr.build_gene_set_collection_from_resource_id and grr.build_gene_set_collection_from_resource.

`build_gene_set_collection_from_resource`(resource)	Build the gene set collection of a genomic resource.
`build_gene_set_collection_from_resource_id`(...)	Build the gene set collection of the resource with a given id.
`GeneSetCollection`(resource)	The gene sets of a `gene_set_collection` resource.
`GeneSetCollection.files`	Return the names of the resource files that hold the gene sets.
`GeneSetCollection.get_all_gene_sets`()	Return all the gene sets of the collection.
`GeneSetCollection.get_gene_collection_count_statistics`()	Read the stored counts of the collection.
`GeneSetCollection.get_gene_set`(gene_set_id)	Return one gene set by its name.
`GeneSetCollection.get_gene_sets_list_statistics`()	Read the stored list of gene sets with their sizes.
`GeneSetCollection.get_gene_sets_per_gene_hist`()	Read the stored histogram of the gene sets that contain a gene.
`GeneSetCollection.get_genes_per_gene_set_hist`()	Read the stored histogram of the number of genes in a gene set.
`GeneSetCollection.is_loaded`()	Return whether the collection holds any loaded gene set.
`GeneSetCollection.load`()	Read the gene sets from the resource.
`GeneSet`(name, desc, syms)	A named set of genes.

build_gene_set_collection_from_resource(resource: GenomicResource) → GeneSetCollection[source]

Build the gene set collection of a genomic resource.

The returned collection may not be loaded. Calls with the same resource return the same object, so an earlier caller may have loaded it.

Parameters:: resource (GenomicResource) – A resource of type gene_set_collection.
Returns:: The collection of the resource. Check is_loaded() or call load() before any read.
Return type:: GeneSetCollection
Raises:: ValueError – If the resource is not of type gene_set_collection.

build_gene_set_collection_from_resource_id(resource_id: str, grr: GenomicResourceRepo | None = None) → GeneSetCollection[source]

Build the gene set collection of the resource with a given id.

The returned collection may not be loaded. Calls that find the same resource return the same object, so an earlier caller may have loaded it.

Parameters:

resource_id (str) – The id of a resource of type gene_set_collection in the repository.
grr (GenomicResourceRepo | None) – The repository that resolves resource_id. When it is None, the function builds the default repository with build_genomic_resource_repository().

Returns:

The collection of the resource. Check is_loaded() or call load() before any read.

Return type:

GeneSetCollection

Raises:

FileNotFoundError – If a protocol-backed repository has no resource with this id.
ValueError – If a group repository has no resource with this id, or if the resource is not of type gene_set_collection.

class GeneSetCollection(resource: GenomicResource)[source]

The gene sets of a gene_set_collection resource.

Build a collection with build_gene_set_collection_from_resource_id or build_gene_set_collection_from_resource. The built collection may not be loaded: call load() before the first read.

Variables:

resource (GenomicResource) – The resource that holds the gene sets.
config (GeneSetResourceSchema) – The validated config of the resource.
collection_id (str) – The id: key of the resource config.
web_label (str) – The label that a web interface shows for the collection. Empty when the config sets no web_label.
web_format_str (str) – The format string that a web interface uses to show a gene set. Empty when the config sets no web_format_str.
gene_sets (dict[str, GeneSet]) – The loaded gene sets by name. The dictionary is empty until load() runs.

property files: set[str]: Return the names of the resource files that hold the gene sets.

get_all_gene_sets() → list[GeneSet][source]

Return all the gene sets of the collection.

Returns:: The gene sets in the order of the resource. The list is empty when the collection is not loaded.
Return type:: list[GeneSet]

get_gene_collection_count_statistics() → dict | None[source]

Read the stored counts of the collection.

Returns:: A dictionary with the keys number_of_gene_sets and number_of_unique_genes. None when the resource has no stored counts because no statistics build ran.
Return type:: dict | None

get_gene_set(gene_set_id: str) → GeneSet | None[source]

Return one gene set by its name.

Parameters:: gene_set_id (str) – The name of the gene set.
Returns:: The gene set, or None when the collection has no set with this name. The collection logs a warning in that case. An unloaded collection has no sets, so it always returns None.
Return type:: GeneSet | None

get_gene_sets_list_statistics() → list[dict] | None[source]

Read the stored list of gene sets with their sizes.

Returns:: One dictionary for each gene set, with the keys name, count and desc, ordered by falling count. None when the resource has no stored list because no statistics build ran.
Return type:: list[dict] | None

get_gene_sets_per_gene_hist() → NullHistogram | CategoricalHistogram | NumberHistogram | None[source]

Read the stored histogram of the gene sets that contain a gene.

Returns:: The histogram, or None when the resource has no stored histogram because no statistics build ran.
Return type:: Histogram | None

get_genes_per_gene_set_hist() → NullHistogram | CategoricalHistogram | NumberHistogram | None[source]

Read the stored histogram of the number of genes in a gene set.

Returns:: The histogram, or None when the resource has no stored histogram because no statistics build ran.
Return type:: Histogram | None

is_loaded() → bool[source]

Return whether the collection holds any loaded gene set.

Returns:: True after load() read at least one gene set. A resource with no gene sets always reports False.
Return type:: bool

load() → GeneSetCollection[source]

Read the gene sets from the resource.

A call on a loaded collection does nothing.

Returns:: This collection, so the call chains.
Return type:: GeneSetCollection
Raises:: ValueError – If the format: key of the resource is not directory, gmt or map.

class GeneSet(name: str, desc: str, syms: list[str])[source]

A named set of genes.

Variables:

name (str) – The name of the gene set, unique in its collection.
desc (str) – The description of the gene set. It can be empty.
count (int) – The number of gene symbols in syms.
syms (list[str]) – The gene symbols of the set.