Create a Pagoo Object — pagoo • pagoo

Usage

pagoo(
  data,
  org_meta,
  cluster_meta,
  sequences,
  core_level = 95,
  sep = "__",
  verbose = TRUE
)

Arguments

data: A data.frame or DataFrame containing at least the following columns: gene (gene name), org (organism name to which the gene belongs to), and cluster (group of orthologous to which the gene belongs to). More columns can be added as metadata for each gene.
org_meta: (optional) A data.frame or DataFrame containing additional metadata for organisms. This data.frame must have a column named "org" with valid organisms names (that is, they should match with those provided in data, column org), and additional columns will be used as metadata. Each row should correspond to each organism.
cluster_meta: (optional) A data.frame or DataFrame containing additional metadata for clusters. This data.frame must have a column named "cluster" with valid organisms names (that is, they should match with those provided in data, column cluster), and additional columns will be used as metadata. Each row should correspond to each cluster.
sequences: (optional) Can accept: 1) a named list of named character vector. Name of list are names of organisms, names of character vector are gene names; or 2) a named list of DNAStringSetList objects (same requirements as (1), but with BStringSet names as gene names); or 3) a DNAStringSetList (same requirements as (2) but DNAStringSetList names are organisms names). If this parameter is used, then a PgR6MS class object is returned.
core_level: The initial core_level (that's the percentage of organisms a core cluster must be in to be considered as part of the core genome). Must be a number between 100 and 85, (default: 95). You can change it later by using the $core_level field once the object was created.
sep: A separator. By default is '__'(two underscores). It will be used to create a unique gid (gene identifier) for each gene. gids are created by pasting org to gene, separated by sep.
verbose: logical. Whether to display progress messages when loading class.

Details

This package uses [R6](https://r6.r-lib.org/articles/Introduction.html) classes to provide a unified, comprehensive, standardized, but at the same time flexible, way to analyze a pangenome. The idea is to have a single object which contains both the data and the basic methods to analyze them, as well as manipulate fields, explore, and to use in harmony with the already existing and extensive list of R packages available created for comparative genomics and genetics.

For more information, tutorials, and resources, please visit https://iferres.github.io/pagoo/ .

Index

Active bindings

Methods

Add metadata

Description:

Add metadata to the object. You can add metadata to each organism, to each group of orthologous, or to each gene. Elements with missing data should be filled by NA (dimensions of the provided data.frame must be coherent with object data).

Usage:

$add_metadata(map = 'org', df)

Arguments:

map: character identifying the metadata to map. Can be one of "org", "group", or "gid".
df: data.frame or DataFrame with the metadata to add. For each case, a column named as "map" must exists, which should contain identifiers for each element. In the case of adding gene (gid) metadata,each gene should be referenced by the name of the organism and the name of the gene as provided in the "data" data.frame, separated by the "sep" argument.

Return:

self invisibly, but with additional metadata.

Drop an organism

Description:

Drop an organism from the dataset. This method allows to hide an organism from the real dataset, ignoring it in downstream analyses. All the fields and methods will behave as it doesn't exist. For instance, if you decide to drop organism 1, the $pan_matrix field (see below) would not show it when called.

Usage:

$drop(x)

Arguments:

x: character or numeric. The name of the organism wanted to be dropped, or its numeric id as returned in $organism field (see below).

Return:

self invisibly, but with x dropped. It isn't necessary to assign the function call to a new object, nor to re-write it as R6 objects are mutable.

Recover a dropped organism

Description:

Recover a previously $drop()ped organism (see above). All fields and methods will start to behave considering this organism again.

Usage:

$recover(x)

Arguments:

x: character or numeric. The name of the organism wanted to be recover, or its numeric id as returned in $dropped field (see below).

Return:

self invisibly, but with x recovered. It isn't necessary to assign the function call to a new object, nor to re-write it as R6 objects are mutable.

Write a pangenome as flat (text) files.

Description:

Write the pangenome data as flat tables (text). Is not the most recommended way to save a pangenome, since you can loose information as numeric precision, column classes (factor, numeric, integer), and the state of the object itself (i.e. dropped organisms, or core_level), loosing reproducibility. Use save_pangenomeRDS for a more precise way of saving a pagoo object. Still, it is useful if you want to work with the data outside R, just keep the above in mind.

Usage:

$write_pangenome(dir = "pangenome", force = FALSE)

Arguments:

dir: The unexisting directory name where to put the data files. Default is "pangenome".
force: logical. Whether to overwrite the directory if it already exists. Default: FALSE.

Return:

A directory with at least 3 files. "data.tsv" contain the basic pangenome data as it is provided to the data argument in the initialization method ($new(...)). "clusters.tsv" contain any metadata associated to the clusters. "organisms.tsv" contain any metadata associated to the organisms. The latter 2 files will contain a single column if no metadata was provided.

Save a pangenome as a RDS (binary) file.

Description:

Save a pagoo pangenome object. This function provides a method for saving a pagoo object and its state into a "RDS" file. To load the pangenome, use the load_pangenomeRDS function in this package. It *should* be compatible between pagoo versions, so you could update pagoo and still recover the same pangenome. Even sep and core_level are restored unless the user provides those arguments in load_pangenomeRDS. dropped organisms also kept hidden, as you where working with the original object.

Usage:

$save_pangenomeRDS(file = "pangenome.rds")

Arguments:

file: The name of the file to save. Default: "pangenome.rds".

Return:

Writes a list with all the information needed to restore the object by using the load_pangenomeRDS function, into an RDS (binary) file.

Clone a pagoo object.

Description:

The objects of this class are clonable with this method.

Usage:

$clone(deep = FALSE)

Arguments:

deep: character identifying the metadata to map. Can be one of "org", "group", or "gid".

Return:

Whether to make a deep clone.

Compute distances

Description:

Compute distance between all pairs of genomes. The default dist method is "bray" (Bray-Curtis distance). Another used distance method is "jaccard", but you should set binary = FALSE (see below) to obtain a meaningful result. See vegdist for details, this is just a wrapper function.

Usage:

$dist( method = "bray", binary = FALSE, diag = FALSE, upper = FALSE, na.rm = FALSE, ... )

Arguments:

method: The distance method to use. See vegdist for available methods, and details for each one.
binary: Transform abundance matrix into a presence/absence matrix before computing distance.
diag: Compute diagonals.
upper: Return only the upper diagonal.
na.rm: Pairwise deletion of missing observations when computing dissimilarities.
...: Other parameters. See vegdist for details.

Return:

A dist object containing all pairwise dissimilarities between genomes.

Compute a Principal Component Analysis

Description:

Performs a principal components analysis on the panmatrix.

Usage:

$pan_pca( center = TRUE, scale. = FALSE, ...)

Arguments:

center: a logical value indicating whether the variables should be shifted to be zero centered. Alternately, a vector of length equal the number of columns of x can be supplied. The value is passed to scale.
scale.: a logical value indicating whether the variables should be scaled to have unit variance before the analysis takes place. The default is TRUE.
...: Other arguments. See prcomp

Return:

Returns a list with class "prcomp". See prcomp for more information.

Fit a Power Law Function for the Pangenome

Description:

Fits a power law curve for the pangenome rarefaction simulation.

Usage:

$pg_power_law_fit(raref, ...)

Arguments:

raref: (Optional) A rarefaction matrix, as returned by rarefact().
...: Further arguments to be passed to rarefact(). If raref is missing, it will be computed with default arguments, or with the ones provided here.

Return:

A list of two elements: $formula with a fitted function, and $params with fitted parameters. An attribute "alpha" is also returned (If alpha>1, then the pangenome is closed, otherwise is open.

Fit an Exponential Decay Function for the Coregenome

Description:

Fits an exponential decay curve for the coregenome rarefaction simulation.

Usage:

$cg_exp_decay_fit(raref, pcounts = 10, ...)

Arguments:

raref: (Optional) A rarefaction matrix, as returned by rarefact().
pcounts: An integer of pseudo-counts. This is used to better fit the function at small numbers, as the linearization method requires to subtract a constant C, which is the coregenome size, from y. As y becomes closer to the coregenome size, this operation tends to 0, and its logarithm goes crazy. By default pcounts=10.
...: Further arguments to be passed to rarefact(). If raref is missing, it will be computed with default arguments, or with the ones provided here.

Return:

A list of two elements: $formula with a fitted function, and $params with fitted intercept and decay parameters.

Compute Genomic Fluidity

Description:

Computes the genomic fluidity, which is a measure of population diversity. See fluidity for more details.

Usage:

$fluidity(nsim = 10)

Arguments:

nsim:An integer specifying the number of random samples to use in the computations.

Return:

A list with two elements, the mean fluidity and its sample standard deviation over the n.sim computed values.

Plot Accessory Frequency Plot

Description:

Plot a barplot with the frequency of genes within the total number of genomes.

Usage:

$gg_barplot()

Return:

A barplot, and a gg object (ggplot2 package) invisibly.

Plot a Distance Heatmap

Description:

Plot a heatmap showing the computed distance between all pairs of organisms.

Usage:

$gg_dist(method = "bray", ...)

Arguments:

method: Distance method. One of "Jaccard" (default), or "Manhattan",see above.
...: More arguments to be passed to distManhattan

Return:

A heatmap (ggplot2::geom_tile()), and a gg object (ggplot2 package) invisibly.

Plot a Pangenome Binary Map

Description:

Plot a pangenome binary map representing the presence/absence of each gene within each organism.

Usage:

$gg_binmap()

Return:

A binary map (ggplot2::geom_raster()), and a gg object (ggplot2 package) invisibly.

Plot a PCA

Description:

Plot a scatter plot of a Principal Components Analysis.

Usage:

$gg_pca(colour = NULL, ...))

Arguments:

colour:The name of the column in $organisms field from which points will take color (if provided). NULL (default) renders black points.
...: More arguments to be passed to ggplot2::autoplot().

Return:

A scatter plot (ggplot2::autoplot()), and a gg object (ggplot2 package) invisibly.

Plot a Pie with Pangenome Categories

Description:

Plot a pie chart showing the number of clusters of each pangenome category: core, shell, or cloud.

Usage:

$gg_pie()

Return:

A pie chart (ggplot2::geom_bar() + coord_polar()), and a gg object (ggplot2 package) invisibly.

Plot Pangenome Curves

Description:

Plot pangenome and/or coregenome curves with the fitted functions returned by pg_power_law_fit() and cg_exp_decay_fit(). You can add points by adding + geom_points(), of ggplot2 package.

Usage:

$gg_curves(what = c("pangenome", "coregenome", ...)

Arguments:

what: "pangenome" and/or "coregenome".
...: ignored

Return:

A scatter plot, and a gg object (ggplot2 package) invisibly.

Run a Shiny App

Description:

Launch an interactive shiny app. It contains a sidebar with controls and switches to interact with the pagoo object. You can drop/recover organisms from the dataset, modify the core_level, visualize statistics, plots, and browse cluster and gene information. In the main body, it contains 2 tabs to switch between summary statistics plots and core genome information on one side, and accessory genome plots and information on the other.

The lower part of each tab contains two tables, side by side. On the "Summary" tab, the left one contain information about core clusters, with one cluster per row. When one of them is selected (click), the one on the right is updated to show information about its genes (if provided), one gene per row. On the "Accessory" tab, a similar configuration is shown, but on this case only accessory clusters/genes are displayed. There is a slider on the sidebar where one can select the accessory frequency range to display.

Give it a try!

Take into account that big pangenomes can slow down the performance of the app. More than 50-70 organisms often leads to a delay in the update of the plots/tables.

Usage:

$runShinyApp()

Return:

Opens a shiny app on the browser.

Retrieve Core Genes for Phylogeny

Description:

A field for obtaining core gene sequences is available (see below), but for creating a phylogeny with this sets is useful to: 1) have the possibility of extracting just one sequence of each organism on each cluster, in case paralogues are present, and 2) filling gaps with empty sequences in case the core_level was set below 100%, allowing more genes (some not in 100% of organisms) to be incorporated to the phylogeny. That is the purpose of this special function.

Usage:

$core_seqs_4_phylo(max_per_org = 1, fill = TRUE)

Arguments:

max_per_org: Maximum number of sequences of each organism to be taken from each cluster.
fill: logical. If fill DNAStringSet with empty DNAString in cases where core_level is set below 100%, and some clusters with missing organisms are also considered.

Return:

A DNAStringSetList with core genes. Order of organisms on each cluster is conserved, so it is easier to concatenate them into a super-gene suitable for phylogenetic inference.