Global

Methods

adjustFdr(pvalues, optionsopt) → {Float64Array}

Description:

  • Adjust p-values to control the false discovery rate using the Benjamini-Hochberg method. This is primarily intended for use with p-values from testEnrichment, typically using the total number of sets from numberOfSets as totalTests.

Source:
Parameters:
Name Type Attributes Default Description
pvalues Float64Array

Array of p-values.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
totalTests number <optional>
<nullable>
 null

Total number of tests. If null, defaults to the length of pvalues. If greater than pvalues, all tests not in pvalues are assumed to have p-values of 1.
Returns:

Array of length equal to pvalues, containing the BH-adjusted p-values.

Type
Float64Array

computeEnrichmentCurve(ranking, setMembers, optionsopt) → {object}

Description:

  • Compute an enrichment curve from a gene ranking. At each position in the ranking, the value of the curve is defined as the proportion of genes with the same or higher rank that are present in the gene set. This can be used to visualize the change in enrichment as the ranking changes, typically with respect to some kind of decreasing importance.

Source:
Parameters:
Name Type Attributes Default Description
ranking Array | TypedArray

Ranking of genes, where earlier entries are considered to be more highly ranked. Each entry may either be an integer representing a gene (typically a gesel gene ID), or an array of such integers, e.g., as produced by searchGenes.
setMembers Set | Array | TypedArray

Array of integers specifying the genes (typically gesel gene IDs) belonging to the gene set. A preconstructed Set may also be supplied.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
pseudoCount number <optional>
 5

Count to add to the total number of genes when computing the proportion. This avoids large fluctuations at the start of the curve at the cost of biasing the reported proportions.
Returns:

Object containing the following properties:

  • proportions: a Float64Array of length equal to ranking. Each entry contains the proportion of genes with equal or higher ranks that belong to the set.
  • found: a Uint32Array containing the indices of ranking corresponding to the genes that were found in the set.
Type
object

countSetOverlaps(setsForSomeGenes) → {Array}

Description:

  • This is a utility function that is called internally by findOverlappingSets. However, it can be used directly to obtain overlap counts if the gene-to-set mappings are manually obtained.

Source:
Parameters:
Name Type Description
setsForSomeGenes Array

Array where each entry corresponds to a gene and contains an array of the set IDs containing that gene. Each inner array is typically the result of calling fetchSetsForGene.
Returns:

An array of objects, where each object corresponds to a set that is present in at least one entry of setsForSomeGenes. Each object contains:

  • id: the ID of the set in fetchAllSets.
  • count: the number of genes in the set that overlap with genes in genes.
Type
Array

effectiveNumberOfGenes(species) → {number}

Source:
Parameters:
Name Type Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
Returns:

Number of genes that belong to at least one set for species. This can be used as a more appropriate universe size in testEnrichment.

Type
number

(async) fetchAllCollections(species, optionsopt) → (nullable) {Array}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
download boolean <optional>
 true

Whether to download the collection details if they are not already available. If false, null is returned if the collection details have not already been loaded into memory.
Returns:

Array of objects where each entry corresponds to a set collection and contains details about that collection. Each object can be expected to contain:

  • title, the title for the collection.
  • description, the description for the collection.
  • species, the species for all gene identifiers in the collection. This should contain the full scientific name, e.g., "Homo sapiens", "Mus musculus".
  • maintainer, the maintainer of this collection.
  • source, the source of this set, usually a link to some external resource.
  • start, the index for the first set in the collection in the output of sets. All sets from the same collection are stored contiguously.
  • size, the number of sets in the collection.

In a gesel context, the identifier for a collection (i.e., the "collection ID") is defined as the index of the collection in this array.

If the collection details have not already been loaded and download = false, null is returned.

Type
Array

(async) fetchAllGenes(species, optionsopt) → {Map}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
types Array <optional>
<nullable>
 null

Array of strings specifying the identifier types to be retrieved. The exact choice of strings depends on how the references were constructed. If null, it defaults to an array containing "symbol", "entrez" and "ensembl".
Returns:

Object where each key is named after an identifier type in types. Each value is an array where each element corresponds to a gene and is itself an array of strings containing all identifiers of the current type for that gene.

The arrays for different identifier types are all of the same length, and corresponding elements across these arrays describe the same gene. gesel's identifier for each gene (i.e., the "gene ID") is defined as the index of that gene in any of these arrays.

Type
Map

(async) fetchAllSets(species, optionsopt) → {Array}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
download boolean <optional>
 true

Whether to download the set details if they are not already available. If false, null is returned if the set details have not already been loaded into memory.
Returns:

Array of objects where each entry corresponds to a set and contains the details about that set. Each object can be expected to contain:

  • name, the name of the set.
  • description, the description of the set.
  • size, the number of genes in the set.
  • collection, the index of the collection containing the set.
  • number, the number of the set within the collection.

In a gesel context, the identifier for a set (i.e., the "set ID") is defined as the index of the set in this array.

If the set details have not already been loaded and download = false, null is returned.

Type
Array

(async) fetchCollectionSizes(species) → {Array}

Source:
Parameters:
Name Type Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
Returns:

Number of sets in each collection. Each value corresponds to a collection in fetchAllCollections.

Type
Array

(async) fetchEmbeddings(species, optionsopt) → (nullable) {Object}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
download boolean <optional>
 true

Whether to download the embeddings if they are not already available. If false, null is returned if the embeddings have not already been loaded into memory.
Returns:

Object with the x and y-coordinates for the t-SNE embedding.

Each value is a Float64Array of length equal to the total number of sets for this species. Each entry of the Float64Array corresponds to a gene set in fetchAllSets and that set's x/y-coordinates on the embedding.

If the embedding mappings have not already been loaded and download = false, null is returned.

Type
Object

(async) fetchGenesForAllSets(species, optionsopt) → (nullable) {Array}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
download boolean <optional>
 true

Whether to download the set-to-gene mappings if they are not already available. If false, null is returned if the set-to-gene mappings have not already been loaded into memory.
Returns:

Array of length equal to the total number of sets for this species. Each element corresponds to an entry in fetchAllSets and is an array of integers containing the IDs for all genes belonging to that set. Gene IDs refer to indices in fetchAllGenes.

If the set-to-gene mappings have not already been loaded and download = false, null is returned.

Type
Array

(async) fetchGenesForSet(species, setnullable, optionsopt) → {Uint32Array}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
set number <nullable>

Set ID, see fetchAllSets for details.

If null, no request is performed, but various internal caches are initialized for subsequent calls to this function. This is useful for guaranteeing that caches are available in concurrent calls.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceRequest boolean <optional>
 false

Whether to force a range request to the server. By default, the return value is extracted from the full set-to-gene mappings if fetchGenesForAllSets was called before this function. Setting this to true is only useful for testing.
forceDownload boolean <optional>
 false

Whether to forcibly download all set-to-gene information up-front to avoid range requests. This is done by calling fetchGenesForAllSets. Ignored if forceRequest = true.
Returns:

Array of integers containing the IDs for all genes belonging to the set. Gene IDs refer to indices in fetchAllGenes.

If set = null, no return value is provided.

Type
Uint32Array

(async) fetchSetsForAllGenes(species, optionsopt) → (nullable) {Array}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
download boolean <optional>
 true

Whether to download the gene-to-set mappings if they are not already available. If false, null is returned if the gene-to-set mappings have not already been loaded into memory.
Returns:

Array of length equal to the total number of genes for this species. Each element corresponds to an entry in fetchAllGenes and is an array of integers containing the IDs for all sets containing that gene. Set IDs refer to indices in fetchAllSets.

If the gene-to-set mappings have not already been loaded and download = false, null is returned.

Type
Array

(async) fetchSetsForGene(species, genenullable, optionsopt) → {Uint32Array}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
gene number <nullable>

Gene ID, see fetchAllGenes for details.

If null, no request is performed, but various internal caches are initialized for subsequent calls to this function. This is useful for guaranteeing that caches are available in concurrent calls.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceRequest boolean <optional>
 false

Whether to force a range request to the server. By default, the return value is extracted from the full gene-to-set mappings if fetchSetsForAllGenes was called before this function. Setting this to true is only useful for testing.
forceDownload boolean <optional>
 false

Whether to forcibly download all gene-to-set mappings up-front to avoid range requests. This is done by calling fetchSetsForAllGenes Ignored if forceRequest = true.
Returns:

Array of integers containing the IDs of all sets containing the gene. IDs are treated as indices into the return value of fetchAllSets or as input to fetchSingleSet.

If gene = null, no return value is provided.

Type
Uint32Array

(async) fetchSetSizes(species) → {Array}

Source:
Parameters:
Name Type Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
Returns:

Number of genes in each set. Each value corresponds to a set in fetchAllSets.

Type
Array

(async) fetchSingleCollection(species, collectionnullable, optionsopt) → {object}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
collection number <nullable>

Collection ID, see fetchAllCollections for details.

If null, no request is performed, but various internal caches are initialized for subsequent calls to this function. This is useful for guaranteeing that caches are available in concurrent calls.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceRequest boolean <optional>
 false

Whether to force a request to the server. By default, the return value is extracted from the full collection details if fetchAllCollections was called before this function. Setting this to true is only useful for testing.
forceDownload boolean <optional>
 false

Whether to forcibly download all collection details up-front to avoid range requests. This is done by calling fetchAllCollections. Ignored if forceRequest = true.
Returns:

Object containing the details of the collection. This should be identical to the corresponding entry of the array returned by fetchAllCollections.

If collection = null, no return value is provided.

Type
object

(async) fetchSingleSet(species, setnullable, optionsopt) → {object}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
set number <nullable>

Set ID, see fetchAllSets for details.

If null, no request is performed, but various internal caches are initialized for subsequent calls to this function. This is useful for guaranteeing that caches are available in concurrent calls.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
forceRequest boolean <optional>
 false

Whether to force a request to the server. By default, the return value is extracted from the full set details if fetchAllSets was called before this function. Setting this to true is only useful for testing.
forceDownload boolean <optional>
 false

Whether to forcibly download all set details up-front to avoid range requests. This is done by calling fetchAllSets. Ignored if forceRequest = true.
Returns:

Object containing the details of the set. This should be identical to the corresponding entry of the array returned by fetchAllSets.

If set = null, no return value is provided.

Type
object

(async) findOverlappingSets(species, genes, optionsopt) → {Array}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
genes Array

Array of unique integers containing user-supplied gene IDs, see fetchAllGenes for details.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
includeSize boolean <optional>
 true

Whether to include the size of each set in the output.
testEnrichment boolean <optional>
 true

Whether to compute the enrichment p-value for each set with testEnrichment. The list and universe sizes will only count genes that are involved in at least one set, by checking fetchSetsForGene and effectiveNumberOfGenes respectively.
forceDownload boolean <optional>
 false

See fetchSetsForGene.
Returns:

An array of objects, where each object corresponds to a set that has non-zero overlaps with genes. Each object contains:

  • id: the ID of the set in fetchAllSets.
  • count: the number of genes in the set that overlap with genes in genes.
  • size: the size of each set. Only included if includeSize = true.
  • pvalue: the enrichment p-value. Only included if testEnrichment = true.
Type
Array

geneBaseUrl(urlopt) → {string}

Description:

  • Get or set the base URL for the gene information. By default, it uses the genes-* release files from the feedstock repository. Setters should call this function before calling any other gesel functions that might fetch resources.

Source:
Parameters:
Name Type Attributes Description
url string <optional>

Base URL to use for the gene informatin.
Returns:

If url is not supplied, the current base URL is returned.

If url is supplied, it is set as the base URL, and the previous base URL is returned.

Type
string

geneDownload(funopt) → {function}

Description:

  • Set the global download function to fetch gene information. By default, it uses the global fetch in browsers and later versions of Node.js. Applications may specify a different function, e.g., to handle authentication or caching; this should be done before calling any other gesel functions that might fetch resources.

Source:
Parameters:
Name Type Attributes Description
fun function <optional>

Function that performs a GET request to an index file, returning a Response object containing the file contents. This should accept the base name of the pre-built index file of interest (e.g., "9606_symbol.tsv.gz").
Returns:

If fun is not supplied, the current global downloader is returned.

If fun is supplied, it is used to set the global downloader, and the previous global value of the function is returned.

Type
function

intersect(arrays) → {Array}

Source:
Parameters:
Name Type Description
arrays Array

Array of arrays over which to compute the intersection.
Returns:

Intersection of all arrays in arrays.

Type
Array

(async) mapGenesByIdentifier(species, type, optionsopt) → {Map}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
type string

Type of the identifier to use as the key of the map, e.g., "ensembl".
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
lowerCase boolean <optional>
 false

Whether to use lower-case keys in the map.
Returns:

Map where each key is a string containing a (possibly lower-cased) identifier of the specified type and each value is an array. Each array contains the gesel gene IDs associated with the type identifier, see fetchAllGenes for ore details.

Type
Map

(async) numberOfCollections(species) → {number}

Source:
Parameters:
Name Type Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
Returns:

Total number of collections for this species.

Type
number

(async) numberOfSets(species) → {number}

Source:
Parameters:
Name Type Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
Returns:

Total number of sets for this species.

Type
number

preloadSearchSetText(species)

Source:
Parameters:
Name Type Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
Returns:

Preloads the search indices for use in searchSetText. This performs a one-off download of the indices such that further calls to searchSetText do not need to perform HTTP range requests.

referenceBaseUrl(urlopt) → {string}

Description:

  • Get or set the base URL for the pre-built references. By default, it uses the indices-* release files from the feedstock repository. Setters should call this function before calling any gesel functions that might fetch resources.

Source:
Parameters:
Name Type Attributes Description
url string <optional>

Base URL to use for the prebuilt references.
Returns:

If url is not supplied, the current base URL is returned.

If url is supplied, it is set as the base URL, and the previous base URL is returned.

Type
string

referenceDownload(funopt) → {function}

Description:

  • Get or set the global download function to fetch pre-built references. By default, it uses the global fetch in browsers and later versions of Node.js. Applications may specify a different function, e.g., to handle authentication or caching; this should be done before calling any other gesel functions that might fetch resources.

Source:
Parameters:
Name Type Attributes Description
fun function <optional>

Function that performs a GET request to an index file, returning a Response object containing the file contents. This accepts three arguments:

  • The base name of the pre-built index file of interest (e.g., "10090_collections.tsv.gz").
  • The starting byte of the request.
  • The ending byte of the request.

If all three arguments are specified, the function should perform a HTTP range request to obtain the specified range of bytes. If only the first argument is supplied, the function should download the entire file.
Returns:

If fun is not supplied, the current global downloader is returned.

If fun is supplied, it is used to set the global downloader, and the previous global value of the function is returned.

Type
function

reindexGenesForAllSets(geneMapping, genesForSets) → {Array}

Description:

  • Reindex the gene sets for a user-defined gene universe. This is helpful for applications that know their own gene universe and want to convert the gesel gene IDs to indices within that universe.

Source:
Parameters:
Name Type Description
geneMapping Array

Array of length equal to the number of genes in a user-defined gene universe. Each entry corresponds to one gene in the user's universe and should be an array containing the corresponding gesel gene ID(s) (see fetchAllGenes for details).
genesForSets Array

Array of length equal to the number of reference gene sets. Each entry corresponds to a set and is an array containing gesel gene IDs for all genes in that set. This is typically obtained from fetchGenesForAllSets.
Returns:

Array of length equal to genesForSets. Each entry corresponds to a reference gene set and is a Uint32Array where the elements are indices into geneMapping, specifying the genes in the user's universe that belong to that set. If a gene in geneMapping maps to multiple gesel IDs, it is considered to belong to all sets containing any of its mapped gesel gene IDs.

Type
Array

reindexSetsForAllGenes(geneMapping, setsForGenes) → {Array}

Description:

  • Reindex the gene-to-set mappings for a user-defined gene universe. This is helpful for applications that know their own gene universe and want to create a mapping of all sets containing each of their own genes.

Source:
Parameters:
Name Type Description
geneMapping Array

Array of length equal to the number of genes in a user-defined gene universe. Each entry corresponds to one gene in the user's universe and should be an array containing the corresponding gesel gene ID(s) (see fetchAllGenes for details).
setsForGenes Array

Array of length equal to the number of gesel gene IDs. Each entry corresponds to a gesel gene ID and is an array containing the set IDs for all sets containing that gene. This is typically obtained from fetchSetsForAllGenes.
Returns:

Array of length equal to geneMapping. Each entry corresponds to a gene in the user-supplied universe and is a Uint32Array where the elements are the gesel set IDs containing that gene. If a gene in geneMapping maps to multiple gesel IDs, we report all sets containing any of its mapped gesel gene IDs.

Type
Array

(async) searchGenes(species, queries, optionsopt) → {Array}

Source:
Parameters:
Name Type Attributes Default Description
species string

Taxonomy ID of the species of interest, e.g., "9606" for human.
queries Array

Array of strings containing gene identifiers of some kind (e.g., Ensembl, symbol, Entrez).
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
types Array <optional>
<nullable>
 null

Array of strings specifying the identifier types to use for searching. The exact choice of strings depends on how the references were constructed. If null, it defaults to an array containing "entrez", "ensembl" and "symbol".
ignoreCase boolean <optional>
 true

Whether to perform case-insensitive matching.
Returns:

An array of length equal to queries. Each element of the array is an array containing the gesel gene IDs with any identifiers that match the corresponding search string. See fetchAllGenes for more details on the interpretation of these IDs.

Type
Array

(async) searchSetText(species, query, optionsopt) → {Array}

Source:
Parameters:
Name Type Attributes Default Description
species string

The taxonomy ID of the species of interest, e.g., "9606" for human.
query string

Query string containing multiple words to search in the names and/or descriptions of each set.

Each stretch of alphanumeric characters and dashes is treated as a single word. All other characters are treated as punctuation between words, except for the following wildcards:

  • *: match zero or more alphanumeric or dash characters.
  • ?: match exactly one alphanumeric or dash character.

A set's name and/or description must contain all words in query to be considered a match.
options object <optional>
 {}

Optional parameters.

Properties
Name Type Attributes Default Description
inName boolean <optional>
 true

Whether to search the name of the set for matching words.
inDescription boolean <optional>
 true

Whether to search the description of the set for matching words.
Returns:

Array of indices of the sets with names and/or descriptions that match query.

Type
Array

testEnrichment(overlap, listSize, setSize, universe) → {number}

Description:

  • Hypergeometric test for gene set enrichment, based on the overlap between a user-supplied list and the gene set.

Source:
Parameters:
Name Type Description
overlap number

Number of overlapping genes between the user's list and the gene set, typically obtained from findOverlappingSets.
listSize number

Size of the user's list.
setSize number

Size of the gene set, see the size property from fetchSingleSet.
universe number

Size of the gene universe (i.e., the total number of genes for this species). This can either be obtained from the arrays in fetchAllGenes or using effectiveNumberOfGenes.
Returns:

P-value for the enrichment of the user's list in the gene set. This may be NaN if the inputs are inconsistent, e.g., overlap is greater than listSize or setSize.

Type
number