Count How Many Times Glycans have the Given Motif(s)

These functions are closely related to have_motif(). However, instead of returning logical values, they return the number of times the glycans have the motif(s).

count_motif() counts a single motif in multiple glycans
count_motifs() counts multiple motifs in multiple glycans

Usage

count_motif(glycans, motif, alignment = NULL, ignore_linkages = FALSE)

count_motifs(glycans, motifs, alignments = NULL, ignore_linkages = FALSE)

Arguments

glycans: A 'glyrepr_structure' object, or an IUPAC-condensed structure string vector.
motif: A 'glyrepr_structure' object, an IUPAC-condensed structure string, or a known motif name (use available_motifs() to see all available motifs).
alignment: A character string. Possible values are "substructure", "core", "terminal" and "whole". If not provided, the value will be decided based on the motif argument. If motif is a motif name, the alignment in the database will be used. Otherwise, "substructure" will be used.
ignore_linkages: A logical value. If TRUE, linkages will be ignored in the comparison.
motifs: A character vector of motif names, IUPAC-condensed structure strings, or a 'glyrepr_structure' object.
alignments: A character vector specifying alignment types for each motif. Can be a single value (applied to all motifs) or a vector of the same length as motifs.

Value

count_motif(): An integer vector indicating how many times each glycan has the motif.
count_motifs(): An integer matrix where rows correspond to glycans and columns correspond to motifs. Row names contain glycan identifiers and column names contain motif identifiers.

Details

This function actually perform v2f algorithm to get all possible matches between glycans and motif. However, the result is not necessarily the number of matches.

Think about the following example:

glycan: Gal(b1-?)[Gal(b1-?)]GlcNAc(b1-4)GlcNAc
motif: Gal(b1-?)[Gal(b1-?)]GlcNAc(b1-

To draw the glycan out:

Gal 1
   \ b1-? b1-4
    GlcNAc -- GlcNAc
   / b1-?
Gal 2

To draw the motif out:

Gal 1
   \ b1-?
    GlcNAc b1-
   / b1-?
Gal 2

To differentiate the galactoses, we number them as "Gal 1" and "Gal 2" in both the glycan and the motif. The v2f subisomorphic algorithm will return two matches:

Gal 1 in the glycan matches Gal 1 in the motif, and Gal 2 matches Gal 2.
Gal 1 in the glycan matches Gal 2 in the motif, and Gal 2 matches Gal 1.

However, from a biological perspective, the two matches are the same. This function will take care of this, and return the "unique" number of matches.

For other details about the handling of monosaccharide, linkages, alignment, substituents, and implementation, see have_motif().

Examples

library(glyparse)

count_motif("Gal(b1-3)Gal(b1-3)GalNAc", "Gal(b1-")
#> [1] 2
count_motif(
  "Man(b1-?)[Man(b1-?)]GalNAc(b1-4)GlcNAc",
  "Man(b1-?)[Man(b1-?)]GalNAc"
)
#> [1] 1
count_motif("Gal(b1-3)Gal", "Man")
#> [1] 0

# Vectorized usage with single motif
count_motif(c("Gal(b1-3)Gal(b1-3)GalNAc", "Gal(b1-3)GalNAc"), "Gal(b1-")
#> [1] 2 1

# Multiple motifs with count_motifs()
glycan1 <- parse_iupac_condensed("Gal(b1-3)Gal(b1-3)GalNAc")
glycan2 <- parse_iupac_condensed("Man(b1-?)[Man(b1-?)]GalNAc(b1-4)GlcNAc")
glycans <- c(glycan1, glycan2)

motifs <- c("Gal(b1-3)GalNAc", "Gal(b1-", "Man(b1-")
result <- count_motifs(glycans, motifs)
print(result)
#>                                            Gal(b1-3)GalNAc Gal(b1- Man(b1-
#> Gal(b1-3)Gal(b1-3)GalNAc(?1-                             1       2       0
#> Man(b1-?)[Man(b1-?)]GalNAc(b1-4)GlcNAc(?1-               0       0       2

# Monosaccharide type matching examples
# Concrete glycan vs generic motif: matches (glycan converted to generic)
count_motif("Man", "Hex")  # Returns 1
#> [1] 1

# Generic glycan vs concrete motif: doesn't match
count_motif("Hex", "Man")  # Returns 0
#> [1] 0

# Matrix example showing type matching rules
count_motifs(glycans = c("Hex", "Man"), motifs = c("Hex", "Man"))
#>     Hex Man
#> Hex   1   0
#> Man   1   1