Package 'glyanno'

Description

build_glyanno_cache() is the magic that makes glyanno fast. It precalculates database views and annotation indexes from the installed glydb. You will only need to call this function once on your computer. When glydb is updated, you'll also need to call this function to update the cache. But don't worry. We'll remind you then.

• build_glyanno_cache() reuses a valid cache unless force = TRUE.

• glyanno_cache_info() inspects it without building it, and

• clear_glyanno_cache() removes it and clears the session cache.

Usage

build_glyanno_cache(force = FALSE)

glyanno_cache_info()

clear_glyanno_cache()

Arguments

Details

The cache lives in tools::R_user_dir("glyanno", "cache"). Set the glyanno.cache_dir option to use another directory. Only an explicit call to build_glyanno_cache() writes persistent data. Without a disk cache, annotation builds the required views in memory for the current session.

On interactive attachment, a startup message reminds you to build a missing, outdated, or unreadable cache. No computation or questions block attachment. The cache is invalidated by a changed glydb version, glyrepr or igraph version, R major/minor version, collation locale, or internal cache schema. Restart R after updating dependencies. Development data changes without a version bump require force = TRUE.

Cached data include concrete/generic compositions, intact/topological structures, confidence ranks, exact and compatible composition indexes, residue counts, species/type membership, floating-structure flags, masses for all built-in dictionaries, and local GlyTouCan accession keys. Structure vectors retain their parsed graphs. Arbitrary structure matching still uses glymotif at query time. Custom databases are never persisted.

A complete replacement is written before the previous cache is replaced; failed builds preserve the previous file. Only one completed cache is kept. Metadata inspection reads a small file header and checks the file size. The compressed annotation payload is loaded and validated on first use. Use force = TRUE to repair a damaged payload whose header is still valid.

Value

build_glyanno_cache() invisibly returns the cache file path. glyanno_cache_info() returns a list with path, status (one of "missing", "outdated", "unreadable", or "ready"), size_bytes, expected, and stored version metadata. clear_glyanno_cache() invisibly returns NULL.

Examples

glyanno_cache_info()

Description

This function calculates m/z values from glycans. Different adducts, mass types, and derivatives are supported. Custom mass dictionaries are also supported.

Usage

calculate_mz(glycans, charge = 1, adduct = "H+", mass_dict = NULL, safe = TRUE)

Arguments

Value

A numeric vector of m/z values.

See Also

glyanno_mass_dict()

Examples

library(glyrepr)

# Different input types
calculate_mz(glycan_composition(c(Gal = 1, GalNAc = 1)), charge = 0)
calculate_mz("Gal(1)GalNAc(1)", charge = 0)
calculate_mz(as_glycan_structure("Gal(b1-3)GalNAc(a1-"), charge = 0)
calculate_mz("Gal(b1-3)GalNAc(a1-", charge = 0)

# For common situation in MALDI-TOF MS
calculate_mz("Man(5)GlcNAc(2)", charge = 1,adduct = "Na+")

# For common situation in ESI MS
calculate_mz("Man(5)GlcNAc(2)", charge = 1, adduct = "H+")

# Calculate permethylated m/z values
calculate_mz("Man(5)GlcNAc(2)", charge = 0, mass_dict = glyanno_mass_dict(deriv = "permethyl"))

# Calculate average mass
calculate_mz("Man(5)GlcNAc(2)", charge = 0, mass_dict = glyanno_mass_dict(mass_type = "average"))

# Vectorization
calculate_mz(c("Man(5)GlcNAc(2)", "Gal(1)GalNAc(1)"), charge = 1, adduct = "Na+")

Description

Given glycan compositions, this function matches them to all compatible glycan structures in the glydb database. Generic, concrete, and mixed residue identities are matched residue by residue.

Usage

comp_to_struc(
  comps,
  db = lifecycle::deprecated(),
  return_best = FALSE,
  glycan_type = NULL,
  species = NULL,
  structure_level = "intact",
  mono_type = "concrete",
  mono_range = NULL
)

Arguments

Details

Filter the built-in database with glycan_type, species, structure_level, mono_type, and mono_range.

Value

If return_best=TRUE: A glyrepr::glycan_structure() vector with the same length as comps. Unmatched compositions are returned as NA. If return_best=FALSE: A tibble with the following columns:

• composition: The glycan compositions, as glyrepr::glycan_composition() vector.

• structure: The possible glycan structures, as glyrepr::glycan_structure() vector.

• confidence: The database confidence score for each structure, or NA when no score is available. Note that one glycan composition can have multiple rows in the result, corresponding to different possible glycan structures.

See Also

glyparse::auto_parse()

Examples

comp_to_struc("H5N2")

Description

Given a generic or mixed glycan composition (e.g. Hex(5)HexNAc(2)), this function gives all possible compatible concrete glycan compositions (e.g. Man(5)GlcNAc(2)).

Usage

enhance_comp(
  comps,
  db = lifecycle::deprecated(),
  return_best = FALSE,
  glycan_type = NULL,
  species = NULL,
  mono_type = "concrete",
  mono_range = NULL
)

Arguments

Details

Filter the built-in database with glycan_type, species, mono_type, and mono_range.

Value

If return_best=TRUE: A glyrepr::glycan_composition() vector with the same length as comps. Unmatched compositions are returned as NA. If return_best=FALSE: A tibble with the following columns:

• raw: The original compositions.

• enhanced: The enhanced compositions.

• confidence: The database confidence score for each enhanced composition, or NA when no score is available. Note that one raw composition can have different enhanced compositions as multiple rows in the result.

Examples

enhance_comp("Hex(5)HexNAc(2)")

Description

Given a glycan structure vector of any resolution level (see glyrepr::get_structure_level() for details), this function gives compatible structures with more specific residue identities or linkage information.

Usage

enhance_struc(
  strucs,
  db = lifecycle::deprecated(),
  return_best = FALSE,
  glycan_type = NULL,
  species = NULL,
  structure_level = "intact",
  mono_type = "concrete",
  mono_range = NULL
)

Arguments

Details

Input and database vectors may mix generic, concrete, and mixed residues, as well as topological, partial, and intact structures. Each database candidate is matched against each input independently.

Value

If return_best=TRUE: An unnamed glyrepr::glycan_structure() vector with the same length as strucs. Unmatched structures are returned as NA. If return_best=FALSE: A tibble with the following columns:

• raw: The original glycan structures.

• enhanced: The enhanced glycan structures.

• confidence: The database confidence score for each enhanced structure, or NA when no score is available. Note that one raw glycan structure can have different enhanced structures as multiple rows in the result.

Examples

enhance_struc("Gal(??-?)GalNAc(??-", glycan_type = "O-GalNAc",
  species = "Homo sapiens")

Description

Reconstructs generic topological N-glycans from their core and branches. Every non-missing input must have only generic residues and no linkage information. Inputs that cannot be reconstructed de novo are matched against a fallback database at "topological" level.

Topological de-novo enhancement preserves optional core fucose and bisecting GlcNAc residues. Complex N-glycan branches are matched against the internal branch data. For hybrid N-glycans, the all-Hex arm is assigned as mannose and the HexNAc-bearing arm uses branch matching. High-mannose candidates are constrained to core-aligned subtrees of the Glc3Man9 precursor.

Usage

enhance_struc_denovo(strucs, fallback_db = NULL)

Arguments

Value

An unnamed glyrepr::glycan_structure() vector with the same length as strucs. Unmatched structures are returned as NA.

Examples

n_generic <- glyrepr::n_glycan_core(linkage = FALSE, mono_type = "generic")
enhance_struc_denovo(n_generic)

Description

A named numeric vector of the mass of each monosaccharide residue. Used by default as the mass_dict argument in calculate_mz().

The names includes:

• Monosaccharides: Hex, HexNAc, dHex, dHexNAc, ddHex, Pen, HexA, HexN, NeuAc, NeuGc, Kdn, Neu

• Ions: H+, H, H2O, K+, Na+, NH4+, H-, Cl-, HCO3-

• Substituents: S, P

• Reducing end: red_end, which is the additional mass of the reducing end of the glycan.

Usage

glyanno_mass_dict(deriv = "none", mass_type = "mono")

Arguments

Value

A named numeric vector.

Examples

glyanno_mass_dict(deriv = "none", mass_type = "mono")
glyanno_mass_dict(deriv = "permethyl", mass_type = "mono")
glyanno_mass_dict(deriv = "none", mass_type = "average")

Description

Given m/z values, this function matches them to all possible glycan compositions in the glydb database.

Usage

mz_to_comp(
  mz,
  tol = ppm(10),
  db = lifecycle::deprecated(),
  return_best = FALSE,
  charge = 1,
  adduct = "H+",
  mass_dict = NULL,
  glycan_type = NULL,
  species = NULL,
  mono_type = "concrete",
  mono_range = NULL
)

Arguments

Value

If return_best=TRUE: An unnamed glyrepr::glycan_composition() vector with the same length as mz. Unmatched m/z values are returned as NA. If return_best=FALSE: A tibble with the following columns:

• mz: The molecule m/z values, same as the input mz.

• composition: The possible glycan compositions, as glyrepr::glycan_composition() vector.

• confidence: The database confidence score for each composition, or NA when no score is available. Note that one m/z value can have multiple rows in the result, corresponding to different possible glycan compositions.

Filter the built-in database

Use glycan_type, species, mono_type, and mono_range to select compositions from glydb::glydb_compositions(). For example,

mz_to_comp(mz, species = "Homo sapiens", glycan_type = "N")

See Also

ppm(), glyanno_mass_dict()

Examples

mz_to_comp(933.3175, charge = 1, adduct = "Na+")

Description

This helper function should be used in mz_to_comp() as the tol argument. It makes the function using PPM as dynamic tolerance.

Usage

ppm(x)

Arguments

Value

A function that takes a numeric vector of m/z values and returns a numeric vector of tolerances.

Examples

ppm(10)(2368.84)
ppm(10)(c(2368.84, 2368.85))

Description

This function takes a vector of glycan structures and returns the corresponding GlyTouCan accessions. It first looks up structures from glydb::glydb_data, then uses the GlycanFormatConverter API maintained by the Glycosmos project for structures not found locally.

Usage

struc_to_glytoucan(strucs)

Arguments

Details

For "topological" structures (e.g., "Gal(??-?)GalNAc(??-"), this function will first call glyrepr::fill_anomer_pos() to fill in the missing anomeric positions before looking up accessions. This is necessary because all glycan structures in GlyTouCan must have defined anomeric positions.

Value

A character vector of GlyTouCan accessions corresponding to the input glycan structures. If a structure cannot be converted to a GlyTouCan accession, the corresponding entry will be NA.