9 GSON: the knowledge representation and exchange layer

A functional enrichment workflow has two different jobs:

the analysis engine tests whether gene sets are enriched; and
the knowledge layer defines which terms, pathways, diseases, or other biological concepts belong to which genes.

These jobs should not be confused. enricher() and GSEA() provide enrichment interfaces, whereas a gene-set resource provides the biological knowledge that those interfaces test. The gson package supplies a standard way to represent that knowledge and to move it between data sources, analysis functions, and machines.

9.1 Chapter overview

Aspect	GSON knowledge layer
Questions	How can gene-set knowledge be represented, versioned, shared, subset, validated, combined, and passed to enrichment interfaces?
Input	Term-to-gene mappings plus metadata: gene set names, species, gene identifier type, gene set ID domain, source, release, and access date.
Methods	Knowledge packaging, inspection, subsetting, serialization to `.gson` and GMT, merging or paralleling several resources, and integration with ORA/GSEA. GSON is not a statistical test.
Main functions	`gson()`, `gson_GO()`, `gson_KEGG()`, `gson_WP()`, `read.gmt()`, `read.gmt.wp()`, `write.gson()`, `read.gson()`, `write.gmt()`, `x[i]`, `gsonList()`, `gson_union()`, `validate_gson()`, `gson_url()`, `browseGS()`.
Output	A `GSON` object, a `.gson` or GMT file, a `GSONList` of parallel resources, or one enrichment result per source.
Main limitations	GSON stores and moves knowledge. It does not convert identifiers, does not compute ontology structure, and cannot resolve two sources that use the same gene set ID for different gene sets.

9.2 What GSON represents

GSON means Gene Set Object Notation. The gson package defines the GSON class for storing gene-set information together with the metadata needed to interpret and reuse it. A GSON object is therefore more than a two-column TERM2GENE table: it is a portable knowledge resource that can retain information about the source, species, identifiers, and the version or release from which the gene sets were obtained.

This separation is useful in practice. The same enrichment engine can be used with GO, KEGG, WikiPathways, a disease collection, a cell-marker catalogue, or a project-specific annotation table. Only the knowledge object changes; the statistical question and the downstream result workflow can remain the same.

GSON is a knowledge representation and exchange layer, not a new statistical enrichment test. ORA, GSEA, network-aware enrichment, and other methods still determine how evidence is evaluated. GSON determines the knowledge that is evaluated.

An object of the class holds three mapping tables and nine metadata slots. The tables are the knowledge; the slots say what the tables mean.

Component	Columns	What it records
`gsid2gene`	`gsid`, `gene`	Gene set membership. The only required table.
`gsid2name`	`gsid`, `name`	Human-readable name of each gene set.
`gene2name`	`gene`, `name`	Symbol or display name of each gene.

Slot	Records
`gsname`	Name of the collection, for example `GO`, `KEGG`, `WikiPathways`.
`species`	Organism the genes belong to.
`keytype`	Identifier domain of the genes, for example `ENTREZID`, `SYMBOL`.
`gsidtype`	Identifier domain of the gene set IDs, for example `GO`, `KEGG`, `REAC`, `WP`.
`version`	Release of the resource.
`accessed_date`	Date the resource was obtained.
`urlpattern`	Template that turns a gene set ID into the web address of that gene set.
`schema_version`	Version of the `.gson` file format, as declared by the producer.
`info`	Free-text note for the producer’s own use.

keytype and gsidtype describe two different namespaces. A collection of KEGG pathways whose members are Entrez gene IDs has gsidtype = "KEGG" and keytype = "ENTREZID". Keeping them apart means a consumer does not have to infer which namespace the gene set IDs come from.

9.3 Obtaining a GSON object

clusterProfiler and related packages expose helper functions whose names start with gson_. The helpers do not share one argument convention, so a script that passes arguments by name needs the right ones. gson_GO() reads a local organism package; the other two download their source, so their result should be frozen once, as described under Writing and reading a collection.

Helper	Example call	Argument conventions
`gson_GO()`	`gson_GO(OrgDb = "org.Hs.eg.db", keytype = "ENTREZID", ont = "BP")`	`OrgDb` is an object or the name of an organism package; `keytype` and `ont` default to `"ENTREZID"` and `"BP"`
`gson_KEGG()`	`gson_KEGG(species = "hsa")`	The gene argument is `keyType`, with a capital `T`; `KEGG_Type = "KEGG"` selects pathway membership
`gson_WP()`	`gson_WP(organism = "Homo sapiens")`	The argument is `organism`, not `species`, and takes the Latin name

library(gson)
library(clusterProfiler)

kk_gson <- gson_KEGG(species = "hsa")
wp_gson <- gson_WP(organism = "Homo sapiens")
go_gson <- gson_GO(OrgDb = "org.Hs.eg.db", keytype = "ENTREZID", ont = "BP")

A collection that is already on disk is the offline route, and the gson installation ships one so that this chapter can run without a network. The WikiPathways GMT parser read.gmt.wp() returns a GSON when asked for one.

wpfile <- system.file(
  "extdata",
  "wikipathways-20220310-gmt-Homo_sapiens.gmt",
  package = "gson"
)
wp <- read.gmt.wp(wpfile, output = "GSON")
wp

>> Gene Set: WikiPathways
>> 7781 genes annotated by 724 gene sets.
>> Species: Homo sapiens
>> Version: WikiPathways_20220310
>> Gene set ID type: WP

The parser filled in what the file stated and what the format declares: the source, the organism, the release, the gene set ID domain WP, and a urlpattern that resolves a WP identifier to its WikiPathways page.

The same file parsed by the generic reader is the long term/gene table that enricher() accepts as TERM2GENE, which is the difference between the two representations: a data frame carries the membership and nothing else.

head(read.gmt(wpfile))

                                                                                             term
1 NIPBL role in DNA damage - Cornelia de Lange syndrome%WikiPathways_20220310%WP5119%Homo sapiens
2 NIPBL role in DNA damage - Cornelia de Lange syndrome%WikiPathways_20220310%WP5119%Homo sapiens
3 NIPBL role in DNA damage - Cornelia de Lange syndrome%WikiPathways_20220310%WP5119%Homo sapiens
4 NIPBL role in DNA damage - Cornelia de Lange syndrome%WikiPathways_20220310%WP5119%Homo sapiens
5 NIPBL role in DNA damage - Cornelia de Lange syndrome%WikiPathways_20220310%WP5119%Homo sapiens
6 NIPBL role in DNA damage - Cornelia de Lange syndrome%WikiPathways_20220310%WP5119%Homo sapiens
   gene
1  9025
2 25836
3  9656
4   545
5  3014
6 11335

9.4 Constructing a collection from your own tables

gson() builds an object from user-supplied data frames. The arguments are the three tables named above, not TERM2GENE and TERM2NAME. Each table is read by position: the first two columns become gsid and gene, gsid and name, or gene and name, so the names you use in your own data frame do not matter and any further columns are dropped.

gsid2gene <- data.frame(
  term = c("GS1", "GS1", "GS1", "GS2", "GS2"),
  gene = c("10196", "7157", "3689", "7157", "5728")
)
gsid2name <- data.frame(
  term = c("GS1", "GS2"),
  name = c("apoptosis signalling", "ribosomal proteins")
)
gene2name <- data.frame(
  gene = c("10196", "7157", "3689", "5728"),
  symbol = c("BAX", "TP53", "MDM2", "NPM1")
)

custom <- gson(
  gsid2gene = gsid2gene,
  gsid2name = gsid2name,
  gene2name = gene2name,
  species = "Homo sapiens",
  gsname = "Project-curated",
  version = "2026-10",
  accessed_date = "2026-10-08",
  keytype = "ENTREZID",
  gsidtype = "GS"
)
custom

>> Gene Set: Project-curated
>> 4 genes annotated by 2 gene sets.
>> Species: Homo sapiens
>> Version: 2026-10
>> Gene set ID type: GS

Identifiers are stored as character. A producer that passes a factor gets character columns in the result, which matters because a factor carries the levels it no longer uses: a grouping step over such a column yields one empty gene set per unused level, and the phantom sets then show up in length(), names(), and every file the object is written to. A double column is stored by its digits, formatted without scientific notation, so one million is "1000000" rather than "1e+06".

Use a plain annotation table for a one-off exploratory test; promote it to a versioned GSON object when it will be shared, reused, combined with other resources, or cited in a report.

9.5 Inspecting and subsetting a collection

A GSON behaves like a container of gene sets. length() counts gene sets, names() lists their IDs in the order the collection holds them, x[[i]] returns the genes of one gene set, and as.data.frame() gives the full membership table with the names joined in.

length(wp)

[1] 724

head(names(wp))

[1] "WP5119" "WP2840" "WP4685" "WP5043" "WP2889" "WP289"

wp[["WP4685"]][1:5]

[1] "4893" "2353" "1385" "1021" "1019"

head(as.data.frame(custom))

  gsid                 name  gene gene_name
1  GS1 apoptosis signalling 10196       BAX
2  GS1 apoptosis signalling  7157      TP53
3  GS2   ribosomal proteins  7157      TP53
4  GS1 apoptosis signalling  3689      MDM2
5  GS2   ribosomal proteins  5728      NPM1

x[i] returns a smaller GSON. Taking a subset used to mean filtering gsid2gene by hand and keeping gsid2name and gene2name in step with it, which is easy to get wrong in exactly the direction a validator reports: a gene2name row for a gene that is no longer a member of any kept gene set. The subset method prunes all three tables together and carries the metadata over.

by_name <- wp[c("WP4685", "WP5043", "WP179")]
by_position <- wp[1:3]
by_logical <- wp[names(wp) %in% c("WP4685", "WP2840")]
length(by_name)

[1] 3

names(by_position)

[1] "WP5119" "WP2840" "WP4685"

length(by_logical)

[1] 2

by_name@urlpattern

[1] "https://www.wikipathways.org/pathways/{gsid}.html"

Gene set IDs, positions, and logical vectors all select, and x[] returns x. An ID the object does not hold, or an index out of bounds, is an error that names what is missing. x[, j] is also an error, since a GSON has no second dimension.

9.6 Checking an object

Two checks answer two different questions.

The class enforces its structural contract when an object is created, so a table that is not a data frame, lacks the documented columns, or holds identifiers that are not character is refused rather than stored.

tryCatch(
  methods::new("GSON", gsid2gene = data.frame(gsid = 1, gene = 2)),
  error = conditionMessage
)

[1] "invalid class \"GSON\" object: gsid2gene should hold gsid and gene columns of type character"

validate_gson() then asks about the content, and reports instead of refusing, because an object that breaks a content rule still has to be constructible so that it can be inspected. Duplicated identifiers, missing cross-references among the three tables, empty tables, a keytype or gsidtype left at a placeholder such as UNKNOWN, a gsidtype that the object’s own gene set IDs contradict, and a schema_version this package cannot read are all reported.

defective <- gson(
  gsid2gene = data.frame(
    gsid = c("GO:1", "GO:1", "GO:2"),
    gene = c("1", "2", NA)
  ),
  gsid2name = data.frame(gsid = "GO:1", name = "one"),
  gene2name = data.frame(gene = "99", name = "dangling"),
  keytype = "UNKNOWN",
  gsidtype = "KEGG"
)
validate_gson(defective, error = FALSE)

[1] "gsid2gene$gene should not contain missing or empty values"                            
[2] "gene2name contains gene values not found in gsid2gene"                                
[3] "keytype 'UNKNOWN' names no identifier type; leave it NULL when the type is not known" 
[4] "gsidtype 'KEGG' is not the prefix of the gene set IDs, which begin GO -- as in 'GO:1'"

validate_gson(wp)

[1] TRUE

There is deliberately no dictionary of accepted keytype or gsidtype values. MicrobiomeProfiler, for example, writes kegg_orthology, eggNOG_OG, taxid, and hmdb_id as keytype, none of which is a keytypes() value of any Bioconductor annotation package, so a list held by gson would reject the collections the ecosystem itself produces. What the package can verify is an object against itself, so only a prefix the identifiers actually carry is compared. Nothing is rewritten: a value the object declares is reported as it stands, because the reader that knows what a file says is not the one that decides what the producer meant.

9.7 Writing and reading a collection

write.gson() stores a collection as JSON and read.gson() reads it back. The round trip is exact, so a frozen file can be treated as the object it was written from. The JSON keys the memberships by gene set ID and carries the names and the metadata beside them; it is plain JSON, so a collection can also be read by tools outside R.

f <- tempfile(fileext = ".gson")
write.gson(custom, file = f)
identical(read.gson(f), custom)

[1] TRUE

writeLines(readLines(f))

{
  "gsid2gene": {
    "GS1": ["10196", "7157", "3689"],
    "GS2": ["7157", "5728"]
  },
  "gsid2name": {
    "gsid": ["GS1", "GS2"],
    "name": ["apoptosis signalling", "ribosomal proteins"]
  },
  "gene2name": {
    "gene": ["10196", "7157", "3689", "5728"],
    "name": ["BAX", "TP53", "MDM2", "NPM1"]
  },
  "schema_version": ["1.0"],
  "species": ["Homo sapiens"],
  "gsname": ["Project-curated"],
  "version": ["2026-10"],
  "accessed_date": ["2026-10-08"],
  "keytype": ["ENTREZID"],
  "gsidtype": ["GS"],
  "urlpattern": null,
  "info": null
}

GMT is the interoperable format: read.gmt() parses it and write.gmt() produces it from a collection. The GMT form keeps the membership and the gene set name and drops the rest of the metadata, so a .gmt file is for exchange and a .gson file is for the versioned copy. write.gmt() also sorts the gene sets alphabetically, so the three selected below are written in a different order from the one the collection held them in; a ranked or curated order survives only in the .gson file.

gmt_file <- tempfile(fileext = ".gmt")
write.gmt(by_name, file = gmt_file)
writeLines(substr(readLines(gmt_file), 1, 60))

WP179   Cell cycle  4172    4173    7043    4174    4175    4176    8379    29945   20
WP4685  Melanoma    4893    2353    1385    1021    1019    595 80243   673 4763    
WP5043  Pentose phosphate pathway in senescent cells    6120    221

dim(read.gmt(gmt_file))

[1] 199   2

Memberships that carry no gene set ID or no gene are skipped when a collection is written, with a warning that says how many were omitted, and write.gmt() falls back to the gene set ID when gsid2name holds no usable name for a set. A NA that reached a file would come back as a gene genuinely named NA and be handed on to the enrichment routines.

A .gson file is written by other programs as often as by this one, so read.gson() names the file and the shape it found instead of passing on what the JSON parser happened to notice. A file whose memberships are not keyed by gene set ID, whose tables hold a string where an array belongs, or that cannot be parsed at all is an error that says which file and which member; a local path that does not exist is caught before the parser is asked.

9.8 Locating the source database

urlpattern is a claim that each gene set ID resolves to a web page. gson_url() builds those URLs and browseGS() opens one in a browser, which is the step that turns a row of an enrichment table back into evidence to read.

gson_url(wp)[1:2]

                                             WP5119 
"https://www.wikipathways.org/pathways/WP5119.html" 
                                             WP2840 
"https://www.wikipathways.org/pathways/WP2840.html"

gson_url(wp, c("WP100", "WP106"))

                                             WP100 
"https://www.wikipathways.org/pathways/WP100.html" 
                                             WP106 
"https://www.wikipathways.org/pathways/WP106.html"

browseGS(wp, "WP4685")

The URL comes only from what the object declares. gson ships no table of other databases’ websites, so a producer that wants its gene sets browsable has to name the pattern; ReactomePA::gson_Reactome() currently passes urlpattern = NULL. An object that declares none gets a vector of NA from gson_url() and an error from browseGS().

gson_url(custom)[1]

Warning: this GSON carries no 'urlpattern', so its gene sets have no URL

GS1 
 NA

This is also where gsidtype earns its place. A consumer that knows the domain of the identifiers can choose the right resource and the right pattern, whereas one that does not has to infer the domain from the shape of the IDs, which is a guess about someone else’s data.

9.9 Combining collections

Two operations answer two different questions, and choosing between them is a design decision rather than a stylistic one.

gsonList() keeps the resources separate and names them, so one input is tested against each knowledge base and the sources stay distinguishable in the result.

gsons <- gsonList(wikipathways = wp, project = custom)
names(gsons)

[1] "WikiPathways"    "Project-curated"

class(gsons[1])

[1] "GSONList" "list"

The component names come from the gsname slot of each object, not from the argument labels of the call, so gsonList(wikipathways = wp) is still "WikiPathways". Set gsname when the identity of a resource must survive into the result table. Subsetting keeps the GSONList class, so gsons[1] still prints as a list of collections.

gson_union() merges several collections into one membership table, which is what an analysis needs when a single test should see all the annotations at once, for example GO, KEGG, and REAC as one enricher() input.

half <- gson_union(wp[1:50], wp[51:100])
length(half)

[1] 100

half@gsname

[1] "WikiPathways"

Two objects that name the same source are the same collection, so a gene set that both of them carry is joined into one set holding every gene either gives it. Two files of one download therefore merge rather than collide.

A gene set ID that two different sources both use is refused, because the merged table would say that one ID names two sets of genes, and every result read from it would be quietly wrong.

left <- gson(
  gsid2gene = data.frame(gsid = c("X1", "X2"), gene = c("1", "2")),
  gsid2name = data.frame(gsid = c("X1", "X2"), name = c("set one", "set two")),
  gsname = "SourceA",
  gsidtype = "X"
)
right <- gson(
  gsid2gene = data.frame(gsid = c("X1", "X3"), gene = c("7", "8")),
  gsid2name = data.frame(gsid = c("X1", "X3"), name = c("other one", "set three")),
  gsname = "SourceB",
  gsidtype = "X"
)
tryCatch(gson_union(left, right), error = conditionMessage)

[1] "gene set ID(s) used by more than one source: X1 -- merge with .conflict = \"prefix\" to qualify every ID with its source, or .conflict = \"rename\" to qualify only these"

.conflict decides how a collision is resolved. "prefix" qualifies every ID with the source it comes from, "rename" qualifies only the colliding ones and leaves IDs that already begin with their source alone, and the gsid2name rows follow the IDs they describe.

merged <- gson_union(left, right, .conflict = "prefix")
names(merged)

[1] "SourceA:X1" "SourceA:X2" "SourceB:X1" "SourceB:X3"

merged@gsname

[1] "SourceA + SourceB"

The metadata merges by what the merged object can still honestly say. species, keytype, and schema_version have to agree, because one membership table cannot mean two organisms, two identifier types, or two file schemas. gsname, gsidtype, version, accessed_date, and info are joined with " + " when the sources name themselves differently. urlpattern is kept only when every object declares the same one and no ID moved, since a pattern that resolves part of the collection to the wrong page is worse than no pattern.

9.10 Passing a collection to the engines

The enrichment layer consumes a GSON through the gson argument of enricher() and GSEA(), which takes the place of TERM2GENE. Over representation analysis tests a thresholded gene vector against the collections.

gene <- unique(c(wp[["WP4685"]][1:25], wp[["WP5043"]]))
ora <- enricher(
  gene = gene,
  gson = wp,
  minGSSize = 5,
  maxGSSize = 500,
  pvalueCutoff = 0.05
)
head(as.data.frame(ora)[, c("ID", "Description", "Count", "pvalue")])

           ID                                  Description Count       pvalue
WP4685 WP4685                                     Melanoma    26 2.182072e-49
WP5043 WP5043 Pentose phosphate pathway in senescent cells     9 1.828985e-22
WP2261 WP2261              Glioblastoma signaling pathways    15 1.102757e-21
WP4255 WP4255                   Non-small cell lung cancer    14 1.069648e-20
WP2828 WP2828                               Bladder cancer    11 5.290695e-18
WP4155 WP4155                           Endometrial cancer    12 1.255424e-17

For the ranked-list case the separation is the same: the ranking is the statistical input and the GSON object supplies the gene sets it is tested against.

data(geneList, package = "DOSE")
gsea <- GSEA(
  geneList = geneList,
  gson = wp,
  minGSSize = 10,
  maxGSSize = 500,
  eps = 0,
  pvalueCutoff = 0.05,
  seed = 123
)
head(as.data.frame(gsea)[, c("ID", "Description", "setSize", "NES", "pvalue")])

           ID                             Description setSize      NES
WP2446 WP2446           Retinoblastoma gene in cancer      84 2.887672
WP466   WP466                         DNA replication      42 2.750442
WP179   WP179                              Cell cycle     111 2.720093
WP2361 WP2361                Gastric cancer network 1      23 2.529323
WP45     WP45              G1 to S cell cycle control      62 2.436411
WP4290 WP4290 Metabolic reprogramming in colon cancer      41 2.403659
             pvalue
WP2446 2.782455e-18
WP466  4.006163e-13
WP179  4.735758e-17
WP2361 8.622333e-09
WP45   6.555802e-10
WP4290 2.751761e-08

Passed a gsonList, enricher() returns one result per source, keyed by the names of the list, and the table or figure can be faceted by knowledge base. The KEGG-specific wrappers take the same objects through organism.

kk <- enrichKEGG(gene = gene, organism = kk_gson)
kk2 <- gseKEGG(geneList = geneList, organism = kk_gson)
res_multi <- enricher(gene = gene, gson = gsons)

The engine layer reads the same container directly: enrichit provides ora_gson(), gsea_gson(), nsea_gson(), and mnsea_gson(). GOSemSim accepts a GSON of GO annotations as the annoDb of godata() from version 2.39.3, so a frozen collection can enter the semantic-similarity layer as well as the enrichment layer.

The wrapper form and the generalized form serve the same reproducibility goal: the analysis uses a local, explicit knowledge resource instead of silently retrieving a changing online database during every run.

9.11 Versioning, metadata, and reproducibility

Knowledge bases change independently of the code used to analyze them. A reproducible enrichment result therefore requires more than the R script and p-value cutoff. At minimum, preserve:

the GSON file or an immutable copy of the source tables;
the resource name (gsname) and the release (version) or download date;
the species;
keytype for the genes and gsidtype for the gene set IDs;
the source URL or the package that produced the resource, and urlpattern when the gene sets should be browsable;
schema_version as the producer wrote it;
any filtering, ID conversion, or deduplication applied to the annotation;
the clusterProfiler, gson, and related package versions;
the analysis method, background universe, thresholds, and random seeds where applicable; and
the names of a gsonList when several resources were tested in parallel, or the merge policy when gson_union() joined them.

The object carries most of this itself, which is the point of the format: a .gson file that states its source, organism, release, and identifier domains does not depend on the notebook that produced it to explain what it is. Run validate_gson() on a resource received from elsewhere before analyzing it, and keep the report with the analysis record.

The simplest local-freezing workflow is to write the GSON object once and read it during analysis:

kk_gson <- gson_KEGG(species = "hsa")
write.gson(kk_gson, file = "knowledge/kegg_hsa.gson")

kk_gson <- read.gson("knowledge/kegg_hsa.gson")

For larger projects, keep the GSON files under version control or in an archival storage system alongside a small manifest. The manifest should state which file was used for which analysis and should not rely only on a mutable database URL. If the project uses gsonList, save every component and the list of names, not only the final enrichment table.

One thing the format does not preserve is the row order of gsid2gene when a collection is not already grouped by gene set ID, because a .gson file keys the memberships by gsid and reading one regroups the table. The gene sets, and the order of the genes within each set, survive; the interleaving of the rows does not. Files written before gsidtype existed read it back as NULL, and a file that carries it still opens in older releases of the package, which ignore the unknown key.

9.12 Where GSON fits in the toolchain

GSON makes the boundaries between the layers explicit:

   custom table, GMT file, or remote knowledge source
                          |
        gson() / read.gmt() / read.gmt.wp() / gson_*() helpers
                          |
                GSON object  ---  validate_gson()
                          |
            +-------------+-------------+
            |                           |
   gsonList (parallel)         gson_union (merged)
            |                           |
   enricher() / GSEA() /  ora_gson() / gsea_gson() / godata()
            |                           |
   enrichment results           gson_url() / browseGS()
            |                           |
   plots and interpretation      manual evidence check

This architecture has three practical consequences:

The analysis engine can be reused. The same ORA or GSEA logic can work across multiple knowledge resources.
The knowledge resource can be frozen. A saved GSON file separates a publication or pipeline run from future changes in an online database, and reads back as the object it was written from.
The resource can be shared. A custom annotation can be distributed as a named, documented object rather than as an unexplained pair of data frames.

GSON is therefore the bridge between biological knowledge and the rest of the biomedical knowledge-mining toolkit. It allows GO, KEGG, WikiPathways, project-specific annotations, and other compatible resources to enter a common workflow without pretending that they are the same biological evidence.

9.13 Summary

gson defines the GSON class for portable gene-set knowledge and metadata. Three mapping tables hold the knowledge; the metadata slots say what the identifiers, organism, release, and source mean.
gson_KEGG(species = ), gson_WP(organism = ), and gson_GO(OrgDb = , keytype = , ont = ) create resource-specific objects, and read.gmt.wp(file, output = "GSON") creates one from a file already on disk.
gson() builds an object from gsid2gene, gsid2name, and gene2name, taking each table by position and storing every identifier as character.
length(), names(), as.data.frame(), x[[i]], and x[i] inspect and subset a collection; subsetting prunes the three tables together and keeps the metadata.
validate_gson() reports what an object holds or claims without carrying it, while the class itself refuses a structurally invalid object at creation.
write.gson() and read.gson() round-trip exactly; write.gmt() and read.gmt() exchange memberships and names without the metadata.
gson_url() and browseGS() resolve gene sets to the pages of their source database, but only when the object declares a urlpattern.
gsonList() tests one input against several separate resources; gson_union() merges several resources into one membership table and refuses an ambiguous gene set ID.
enricher() and GSEA() take these objects through gson, the KEGG wrappers through organism, and enrichit and GOSemSim consume the same container.
Resource identity, version, metadata, and the saved GSON files are part of a reproducible analysis record.

The next steps are to inspect the enrichment result, compare or reduce redundant terms, and choose a visualization appropriate to the question. See the chapters on result objects, semantic similarity, and enrichplot for those operations.

9.14 Next steps

To analyze custom or unsupported annotations, see universal enrichment.
For knowledge-source examples, see GO or KEGG.
To score the terms a collection holds, see GO semantic similarity, where godata() also accepts a GSON of GO annotations.
For result visualization, continue to the visualization map.

9.1 Chapter overview

9.2 What GSON represents

9.3 Obtaining a GSON object

9.4 Constructing a collection from your own tables

9.5 Inspecting and subsetting a collection

9.6 Checking an object

9.7 Writing and reading a collection

9.8 Locating the source database

9.9 Combining collections

9.10 Passing a collection to the engines

9.11 Versioning, metadata, and reproducibility

9.12 Where GSON fits in the toolchain

9.13 Summary

9.14 Next steps

References