Package {mechgraph}

Convert a mechgraph object to an igraph object

Description

Convert a mechgraph object (an S3 list with nodes, edges and metadata) to an igraph object, preserving node and edge columns as vertex/edge attributes.

Usage

## S3 method for class 'mechgraph'
as.igraph(x, ...)

Arguments

Value

An igraph object. Node columns become vertex attributes (id, type, taxon_id, ...), the display label is set as the vertex name, and size is set to the degree. Edge columns (type, source, evidence, n_evidence, ...) become edge attributes. Parallel (multi) edges are preserved; call igraph::simplify() to collapse them.

Modify mechgraph nodes and edges

Description

Add or remove nodes and edges while preserving the mechgraph table schema.

Usage

mg_add_nodes(x, nodes)

mg_add_edges(x, edges, add_missing_nodes = FALSE)

mg_drop_nodes(x, nodes)

mg_drop_edges(x, edges)

Arguments

Value

A new mechgraph object with the modified node and/or edge tables; the input graph is left unchanged. mg_add_nodes() and mg_add_edges() row-bind the new records onto the existing tables (with add_missing_nodes = TRUE, mg_add_edges() creates type = "unknown" nodes for endpoints absent from the graph). mg_drop_nodes() removes the given nodes and every edge incident to them; mg_drop_edges() removes the given edges (a data frame of from/to/type rows, numeric row indices, or a logical mask) while keeping all nodes.

Combine mechgraph objects

Description

Combine graphs while preserving duplicate evidence records by default.

Usage

mg_bind(...)

mg_combine(..., merge_nodes = TRUE, merge_edges = FALSE)

Arguments

Value

A new mechgraph object. mg_bind() row-binds the edge tables of the input graphs (duplicate evidence records are preserved), merges the node tables by identifier (duplicated node ids are dropped), and records the input metadata in a list under metadata$inputs. mg_combine() additionally removes duplicate edges sharing the same from, to, and type when merge_edges = TRUE.

Filter mechgraph objects

Description

Filter node and edge tables and return a new mechgraph object.

Usage

mg_filter_nodes(x, type = NULL, ids = NULL, source = NULL)

mg_filter_edges(x, type = NULL, source = NULL, score = NULL, weight = NULL)

mg_induced_subgraph(x, nodes)

Arguments

Value

A new mechgraph object with the filtered node and/or edge tables and the metadata of the input graph. mg_filter_nodes() and mg_induced_subgraph() keep only the selected nodes and the edges whose both endpoints are among them; mg_filter_edges() keeps the selected edges and leaves the node table unchanged.

Build a mechgraph from BioGRID

Description

Download, parse, and convert BioGRID physical interaction tables into a mechgraph object.

Usage

mg_biogrid_versions()

mg_biogrid_file_url(version = "latest", dataset = c("mv_physical", "all"),
  format = c("tab3", "mitab"))

mg_biogrid_download(version = "latest", dataset = c("mv_physical", "all"),
  format = c("tab3", "mitab"), cache = TRUE, destdir = NULL, quiet = TRUE)

mg_biogrid_parse(file, format = c("tab3", "mitab"), taxon_id = NULL,
  collapse = TRUE)

mg_from_biogrid(file = NULL, version = "latest", dataset = "mv_physical",
  format = c("tab3", "mitab"), taxon_id = NULL,
  collapse = TRUE, cache = TRUE)

Arguments

Value

• mg_biogrid_versions() returns a character vector of supported BioGRID version labels ("latest").

• mg_biogrid_file_url() returns the download URL as a character string.

• mg_biogrid_download() returns the path to the downloaded (or cached) file as a character string.

• mg_biogrid_parse() returns a list with components nodes and edges, the two data.frames to be passed to mg_from_edges().

• mg_from_biogrid() returns a mechgraph object with type = "ppi" edges carrying the BioGRID evidence annotation (evidence, evidence_type, pmid) and provenance metadata (source, version, dataset, format, taxon_id, URL, license).

Build a mechgraph from an edge list

Description

Create a mechgraph from a plain edge list. If nodes is missing, nodes are inferred from edge endpoints.

Usage

mg_from_edges(edges, nodes = NULL, metadata = list())

as_mechgraph(x, ...)

Arguments

Value

mg_from_edges() returns a mechgraph object (an S3 list with components nodes, edges, and metadata). When nodes is missing, a node table with type = "unknown" is inferred from the unique edge endpoints. as_mechgraph() returns the coerced object: for a data.frame it returns mg_from_edges(x, ...) and for a mechgraph it returns the object unchanged.

Build a mechgraph from STRING

Description

Download, parse, and convert STRING functional-association networks into a mechgraph object with type = "ppi" edges carrying the STRING combined score and provenance metadata (source, version, taxon_id, network, score threshold, keytype, URL, license). mg_string_species() returns the STRING species list for a release.

Usage

mg_string_versions()

mg_string_species(version = "12.0", cache = TRUE)

mg_string_file_url(taxon_id = 9606, version = "12.0",
  network = c("functional", "physical", "detailed", "aliases", "info"))

mg_string_download(taxon_id = 9606, version = "12.0",
  network = c("functional", "physical", "detailed", "aliases", "info"),
  cache = TRUE, destdir = NULL)

mg_string_parse(links, aliases = NULL, info = NULL, taxon_id = 9606,
  version = "12.0", score_threshold = 400,
  keytype = c("entrez", "symbol", "uniprot", "ensembl_gene",
    "ensembl_protein", "string_id"), labels = TRUE)

mg_from_string(file = NULL, taxon_id = 9606, version = "12.0",
  network = c("functional", "physical"), score_threshold = 400,
  keytype = c("entrez", "symbol", "uniprot", "ensembl_gene",
    "ensembl_protein", "string_id"), labels = TRUE, cache = TRUE)

Arguments

Details

STRING protein ids ("9606.ENSP...") are mapped to the requested identifier type through the STRING protein.aliases table. For keytype = "entrez" the Ensembl_HGNC_entrez_id aliases cover roughly 98% of human STRING proteins. Edges below score_threshold are dropped; self-loops (which can appear after identifier collapse, e.g. isoforms mapping to one gene) and duplicate undirected edges (highest score kept) are removed.

The full human protein.links table is large (~1.5 GB uncompressed); the download is cached, but parsing it requires roughly that much free memory.

The identifier mapping currently assumes the human (9606) protein.aliases table: the Ensembl_HGNC_* alias sources used by "entrez", "symbol", "uniprot" and "ensembl_gene" exist only for human. For other species use keytype = "ensembl_protein" or "string_id" (identity mappings) until per-species alias sources are added.

Value

• mg_string_versions() returns a character vector of supported STRING release versions ("12.0").

• mg_string_species() returns a data.frame of STRING species for the requested release (columns taxon_id, STRING_type, STRING_name_compact, official_name_NCBI, domain).

• mg_string_file_url() returns the download URL as a character string.

• mg_string_download() returns the path to the downloaded (or cached) file as a character string.

• mg_string_parse() returns a list with components nodes and edges, the two data.frames to be passed to mg_from_edges().

• mg_from_string() returns a mechgraph object with type = "ppi" edges carrying the STRING combined_score and provenance metadata (source, version, taxon_id, network, score threshold, keytype, URL, license).

Examples

## Build a mechgraph from a small STRING links table (no download)
links <- data.frame(
    protein1 = c("9606.ENSP00000000233", "9606.ENSP00000000412"),
    protein2 = c("9606.ENSP00000000412", "9606.ENSP00000001008"),
    combined_score = c(800, 700),
    stringsAsFactors = FALSE
)
mg <- mg_from_string(file = links, keytype = "string_id", labels = FALSE)
mg
mg_edges(mg)


## mg_from_string(), mg_string_download() and mg_string_species() download
## STRING tables and therefore need network access. Only the species table
## is small enough to fetch here: building the human network would pull
## protein.links, which is ~80 MB compressed and ~1.5 GB uncompressed.
species <- mg_string_species()
head(species)
species[species$taxon_id == 9606, ]

## For a real download-to-graph run, pick a species with a small network
## and use an identity keytype so no aliases/info tables are fetched, e.g.
##   mg_from_string(taxon_id = 416591, keytype = "string_id",
##                  labels = FALSE)

Create and inspect mechgraph objects

Description

Create the lightweight S3 list object used by mechgraph.

Usage

mg_graph(nodes, edges, metadata = list(), validate = TRUE)

mg_empty(metadata = list())

is_mechgraph(x)

Arguments

Value

mg_graph() returns a mechgraph object: an S3 list with components nodes (a data.frame with columns id, type, label), edges (a data.frame with columns from, to, type), and metadata (a named list). When validate = TRUE the object is checked with mg_validate() before being returned. mg_empty() returns such an object with empty node and edge tables. is_mechgraph() returns TRUE if x inherits from class "mechgraph" and FALSE otherwise.

Access mechgraph tables and metadata

Description

Return the node table, edge table, metadata list, or unique source labels from a mechgraph object.

Usage

mg_nodes(x)

mg_edges(x)

mg_metadata(x)

mg_sources(x)

Arguments

Value

• mg_nodes() returns the node table, a data.frame with the required columns id, type, label plus any additional node columns.

• mg_edges() returns the edge table, a data.frame with the required columns from, to, type plus any additional edge columns.

• mg_metadata() returns the metadata list stored in the graph.

• mg_sources() returns a sorted character vector of the unique non-missing source labels found in the node and edge tables.

Summarize mechgraph quality-control metrics

Description

Return lightweight graph summary metrics including node and edge counts, isolated node count, and type/source distributions.

Usage

mg_qc(x)

Arguments

Value

A named list with components:

• n_nodes: total number of nodes.

• n_edges: total number of edges.

• n_isolated_nodes: number of nodes that are not an endpoint of any edge.

• node_type_distribution: a table of node types.

• edge_type_distribution: a table of edge types.

• edge_source_distribution: a table of edge source labels (empty table when the edge table has no source column).

Validate a mechgraph object

Description

Checks the required node and edge schema and verifies that edge endpoints are present in nodes$id.

Usage

mg_validate(x)

Arguments

Value

Invisible TRUE when x is a valid mechgraph object. An error is raised (with a message describing the problem) when x is not a mechgraph, the node or edge tables are missing required columns, node ids are missing, empty, or duplicated, or edge endpoints reference nodes that are not in nodes$id.