Package {gson}

Title: Base Class and Methods for 'gson' Format
Version: 0.2.0
Description: Provides a lightweight container and exchange format for gene set collections. It stores gene set membership, names, gene identifiers, species, versions, and source metadata, with utilities for reading, writing, validating, and converting gene set data for enrichment analysis and related workflows.
Imports: jsonlite, methods, rlang, stats, tidyr, utils, yulab.utils (≥ 0.0.7)
Suggests: digest, fs, testthat (≥ 3.0.0)
ByteCompile: true
License: Artistic-2.0
Encoding: UTF-8
Config/testthat/edition: 3
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-07-01 00:58:24 UTC; HUAWEI
Author: Guangchuang Yu ORCID iD [aut, cre, cph]
Maintainer: Guangchuang Yu <guangchuangyu@gmail.com>
Repository: CRAN
Date/Publication: 2026-07-01 22:50:09 UTC

gson: Base Class and Methods for 'gson' Format

Description

Provides a lightweight container and exchange format for gene set collections. It stores gene set membership, names, gene identifiers, species, versions, and source metadata, with utilities for reading, writing, validating, and converting gene set data for enrichment analysis and related workflows.

Author(s)

Maintainer: Guangchuang Yu guangchuangyu@gmail.com (ORCID) [copyright holder]

Authors:

Class "GSON" This class represents gene set information.

Description

Class "GSON" This class represents gene set information.

Slots

gsid2gene

data.frame with two columns of 'gsid' and 'gene'

gsid2name

data.frame with two columns of 'gsid' and 'name'

gene2name

data.frame with two columns of 'gene' and 'name'

schema_version

version of the GSON file schema

species

species of the annotation

gsname

gene set name, e.g., GO, KEGG

version

version of the gene set

accessed_date

time to obtain the gene set data

keytype

keytype of genes

urlpattern

URL pattern to browse gene set online

info

extra information

Author(s)

Guangchuang Yu https://yulab-smu.top

Extract genes from a GSON object

Description

Extract genes from a GSON object

Usage

## S3 method for class 'GSON'
x[[i, ...]]

Arguments

x

A GSON object.

i

A gene set ID or numeric index.

...

Unused.

Value

A character vector of genes.

Coerce GSON to a data frame

Description

Coerce GSON to a data frame

Usage

## S3 method for class 'GSON'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

x

A GSON object.

row.names

Unused.

optional

Unused.

...

Unused.

Value

A data frame with gene set-gene memberships and optional names.

construct a 'GSON' object

Description

construct a 'GSON' object

Usage

gson(
  gsid2gene,
  gsid2name = NULL,
  gene2name = NULL,
  schema_version = "1.0",
  species = NULL,
  gsname = NULL,
  version = NULL,
  accessed_date = NULL,
  keytype = NULL,
  urlpattern = NULL,
  info = NULL
)

Arguments

gsid2gene

A data frame with first column of gene set IDs and second column of genes

gsid2name

A data frame with first column of gene set IDs and second column of gene set names

gene2name

A data frame with first column of genes and second column of gene symbols

schema_version

GSON file schema version

species

Which species of the genes belongs to

gsname

Name of the gene set (e.g., GO, KEGG, etc.)

version

version of the gene set

accessed_date

date to obtain the gene set data

keytype

keytype of genes

urlpattern

URL pattern

info

extra information

Value

A 'GSON' instance

Examples

wpfile <- system.file('extdata', "wikipathways-20220310-gmt-Homo_sapiens.gmt", package='gson')
x <- read.gmt.wp(wpfile)
gsid2gene <- data.frame(gsid=x$wpid, gene=x$gene)
gsid2name <- unique(data.frame(gsid=x$wpid, name=x$name))
species <- unique(x$species)
version <- unique(x$version)
gson(gsid2gene=gsid2gene, gsid2name=gsid2name, species=species, version=version)

construct a 'GSONList' object

Description

construct a 'GSONList' object

Usage

gsonList(...)

Arguments

...

input GSON objects

Value

A 'GSONList' instance

read.gmt

Description

parse gmt file to a data.frame

write a GSON object to GMT format

Usage

read.gmt(gmtfile)

read.gmt.wp(gmtfile, output = "data.frame")

write.gmt(x, file = "")

Arguments

gmtfile

gmt file

output

one of 'data.frame' or 'GSON'

x

A GSON object

file

output GMT file

Value

data.frame

Author(s)

Guangchuang Yu

read and write gson file

Description

read and write gson file

Usage

read.gson(file)

write.gson(x, file = "")

Arguments

file

A gson file

x

A GSON instance

Value

A GSON instance

Examples

wpfile <- system.file('extdata', "wikipathways-20220310-gmt-Homo_sapiens.gmt", package='gson')
x <- read.gmt.wp(wpfile, output = "GSON")
f = tempfile(fileext = '.gson')
write.gson(x, f)
read.gson(f)

show method

Description

show method for GSON instance

Usage

show(object)

Arguments

object

A GSON object

Value

message

Author(s)

Guangchuang Yu https://yulab-smu.top

Validate a GSON object

Description

validate_gson() checks the core data contract of a GSON gene set collection. It is useful after constructing an object manually or reading one from an external source.

Usage

validate_gson(x, error = TRUE)

Arguments

x

A GSON object.

error

Logical. If TRUE, throw an error when validation fails. If FALSE, return a character vector of validation messages.

Value

TRUE if the object is valid. If error = FALSE, returns a character vector of validation messages when invalid.

Examples

x <- gson(data.frame(gsid = "GS1", gene = "gene1"))
validate_gson(x)