CALANGO is a first-principles, phylogeny-aware comparative genomics package to search for annotation terms (e.g Pfam IDs, GO terms or superfamilies), formally described in a dictionary-like structure and used to annotate genomic components, associated with a quantitative/rank variable (e.g. number of cell types, genome size or density of specific genomic elements).
Our software has been freely inspired by (and explicitly modeled to take into account information from) ideas and tools as diverse as comparative phylogenetics, genome annotation, gene enrichment analysis, and data visualization and interactivity.
The latest version of CALANGO can be installed directly from the repository using devtools::install_github():
devtools::install_github("LABpackages/CALANGO")Alternatively, you should soon be able to install the last release version from CRAN by simply doing:
install.packages("CALANGO")In either case, please make sure that you have the latest R version (at least 3.6.1) as well as updated versions of all installed packages.
CALANGO depends on some packages from Bioconductor. This requires an extra installation step before CALANGO can be used. Just run:
library(CALANGO)
install_bioc_dependencies(which = "all")to install / update all dependencies (packages listed as CALANGO’s imports and suggests) to their latest versions.
genome annotation file
A text file for each species describing their set of biologically meaningful genomic elements and their respective annotation IDs (e.g. non redundant proteomes annotated to GO terms, or non-redundant protein domains annotated to protein domain IDs). An example of such file, where gene products are annotated using Gene Ontology (GO) terms and Kegg Orthology (KO) identifiers would be as follows:
Entry GO_IDs KEGG_Orthology_ID
Q7L8J4 GO:0017124;GO:0005737;GO:0035556;GO:1904030;GO:0061099;GO:0004860
Q8WW27 GO:0016814;GO:0006397;GO:0008270 K18773
Q96P50 GO:0005096;GO:0046872 K12489And is specified as:
Fixed number of columns per file (minimum 2) separated by tabs, or ".
First line as the header, each column having a unique column name.
Each following line having an instance of a genomic feature represented by an unique ID (a specific coding-gene locus found in a genome, for instance) identifier.
Multiple terms of the same entry (e.g. a gene annotated to multiple GO terms) should be in the same column and separated by “;”, with any number of spaces before and after it. It’s use after the last term is optional.
A column can have no terms in any given row.
In a more abstract representation, files representing genome annotations for a single annotation schema would have two columns and the following general structure:
genomic_element_name/ID_1 annotation_ID_1;(...);annotation_ID_N
genomic_element_name/ID_2 annotation_ID_12A metadata file
Containing species-specific information:
genome ID column (same name of text files and of species in phylogenetic trees, must be the first column);
The quantitative/rank variable used to sort/rank genomes;
A normalizing factor (e.g. proteome size or length; number of annotation terms) to correct for potential biases in datasets (e.g. organisms with different annotation levels or with highly discrepant proteome sizes) If users are using GO as annotation schema, CALANGO can compute a normalizing factor that takes into account all GO counts, including internal nodes, and therefore may not provide any normalizing factor for this case.
The tabular format for the correlation analysis where column 1 contains the genome IDs, column 2 contains the variable to rank genomes and column 3 contains the normalizing factor could be as follows:
../projects/my_project/genome_ID_1 1.7 2537
../projects/my_project/genome_ID_2 1.2 10212
../projects/my_project/genome_ID_3 0.9 1534Metadada files are specified as follows:
Fixed number of columns (minimum 2) separated by tabs.
No header.
Each line having a unique identifier (first column) with the path of the genome it is referring to or to genome ID. Referred as “genome ID column”.
One mandatory numeric value in every other column, referred as “variable columns”.
A dictionary
Tab delimited, linking annotation IDs to their biologically meaningful descriptions. Our software currently supports two dictionary types:
Gene Ontology (GO) - in this case, CALANGO will automatically recover annotation description and compute values for internal GOs not explicitly used to describe data annotation.
other - in this case, users need to describe a new dictionary linking annotation term IDs (e.g. “46456”) to their descriptions (e.g. “All alpha proteins”), separated by tabs. An example of such file would be:
Annotation_ID Annotation_definition
annotation_ID_1 All alpha proteins
annotation_ID_2 Globin-like
annotation_ID_3 Globin-like
annotation_ID_4 Truncated hemoglobin
(...)
annotation_ID_N annotation_ID_descriptionCALANGO can treat each identifier as its own description, preventing the need to prepare an ontology that isn’t natively supported. For that, do not specify any ontology file and set the ontology = "other".
CALANGO’s parameters are listed in the documentation of run_CALANGO(), as well as in the examples file provided (./data/parameters/). They are, for the current version:
annotation.files.dir (required, string) - Folder where annotation files are located.
output.dir (required, string) - output folder for results
dataset.info (required, string) - genome metadata file, it should contain at least:
x.column (required, numeric) - which column in “dataset.info” contains the phenotype data?
ontology (required, string) - which dictionary data type to use? Possible values are “GO” and “other”. For GO, CALANGO can compute normalization data.
dict.path (required, string) - file for dictionary file (two-column file containing annotation IDs and their descriptions, not needed for GO
column (required, string) - which column in annotation files should be used (column name)
denominator.column (optional, numeric) - which column contains normalization data?
tree.path (required, string) - path for tree file in either newick or nexus format
tree.type (required, string) - tree file type (either “nexus” or “newick”, case-sensitive)
cores (optional, numeric) - how many cores to use? If not provided the function defaults to 1.
linear.model.cutoff = 0.5 (required, numeric) - Parameter that regulates how much graphical output is produced. We configure it to generate plots only for annotation terms with corrected q-values for phylogenetically independent contrasts smaller than 0.5.
MHT.method = “BH” (optional, string) - type of multiple hypothesis correction to be used. Accepts all methods listed by stats::p.adjust.methods(). If not provided the function defaults to “BH”.
type = “correlation” (optional, string) type of analysis to perform. Currently only “correlation” is supported.
Live examples of CALANGO output HTML5 pages can be found here.
CALANGO produces as its main output a dynamic HMTL5 website containing:
Please check our examples page at https://labpackages.github.io/CALANGO/ to explore the full output of CALANGO for a variety of examples. The required data to fully reproduce these examples can be obtained by using CALANGO::retrieve_data_files().