NEWS.md
ibd phyloseq dataset added to microViz, as no longer included in corncob.corncob can now only be installed from GitHub, as is currently not available from CRAN. corncob is a suggested dependency of microViz from which data is borrowed for use in several examples, and which is needed is bbdml models are requested in tax_model.taxatree_models now accepts transformation arguments to allow transformation after aggregation at each ranktaxatree_stats_p_adjust can accept multiple grouping variables without specifying new_var.tax_select() tax_list argument can now actually take a list (Issue #100)taxatree_plots with taxatree_labels and taxatree_plot_labels works properly also with phyloseq object that lack a rooting rank (e.g. kingdom)comp_barplot bars are now in the correct order again when using tax_level = “unique”taxatree_plots with taxatree_labels and taxatree_plot_labels works properly (without losing stats info for any rank)taxatree_plotkey IMPORTANT BUG FIX: layout now matches taxatree_plots againMajor internal changes from S3 ps_extra to S4 psExtra objects. See article about this change
This version also introduces changes around tax_model and taxatree_models functionality.
$ operator to access parts of the old “ps_extra” S3 class will no longer work and must be replaced with accessor functions, e.g. ps_get
upgrade_ps_extra_to_psExtra
tax_model and taxatree_model parallel processing with future and future.apply is off by default, and needs to be enabled with argument use_future = TRUE.tax_model attaches results to psExtra object by default, but you can restore old behaviour with return_psx = FALSEcomp_barplot “other” taxa category renamed to “Other” by defaulttax_model and taxatree_model can now run multiple models per taxon, by accepting lists for formula or variables arguments. This allows running e.g. three simple regression models per taxon with predictors a, b, and c with variables = list(“a”, “b”, “c”)cor_test is a new simple wrapper around stats::cor.test with a y~x formula interface, allowing its use in tax_model
comp_barplot gains x argument, to change default x aesthetic to something other than SAMPLE, which is useful for (faceted) plotting of repeated samples from the same site/individual over time or in different conditions when some samples are missing (see compositions tutorial article)ps_seriate can now aggregate taxa before seriation (returns unaggregated still)comp_barplot is now easier, just name the taxa you want to see first in the tax_order argument, and they will be brought to the fronttax_reorder is exported, and now accepts a subset of all available taxa names (powering the improvement in comp_barplot)tax_palette allows easy creation of a fixed colour palette for taxa, to use with e.g. comp_barplotps_calc_diversity and ps_calc_richness to calculate a diversity or richness index (using microbiome package functions) and add to phyloseq sample datatax_rename allows renaming of taxa using unique combination of classification at any chosen rank and abundance of that taxon (e.g. ASV145 becomes Bifidobacterium-002, which can be interpreted as the second most abundant Bifidobacterium ASV)tax_sort can now sort taxa “asis” (i.e. do nothing), which now permits upfront custom sorting of taxa for use in comp_barplot
tax_sort can now transform taxa temporarily for sorting e.g. to sort by mean compositional (%) relative abundancecomp_heatmap and cor_heatmap and their helpers are largely rewritten. For guidance, see the new website article on heatmaps.
taxAnnotation and varAnnotation annotation helper functions replace the deprecated tax_anno and var_anno functionssampleAnnotation is added for coordinating sample annotations on comp_heatmap
anno_* helpers for each of the annotation coordinating functions aboveord_explore can perform “binary” transformations, unlocking interactive use of Binary Jaccard etc.tax_transform gains add argument to simply add a constant value to all otu_table values before transformation (as an alternative to zero_replace)tax_scale gains keep_counts argument for consistency with tax_transform
The taxatree_* family of functions are largely rewritten. For guidance, see the new website article on statistical modelling of taxa.
taxatree_models now attaches resulting list to ps_extrataxatree_models2stats must be run on the output of taxatree_models before using taxatree_plots
taxatree_plots has different arguments and can now be directly labelled with taxatree_plot_labels when taxatree_label is run first to identify which taxa to label.taxatree_plotkey has different arguments, with more flexible labelling conditions and a smarter label positioning approach.tax_model and taxatree_models now use “lm” type by default, instead of “bbdml”, as corncob is only a suggested dependency.ord_plot default labels now have alpha = 1 for both taxa and constraints (previously 0.8)ord_plot “auto”matic loading/constraint vector length scalar adjustment improvement: now uses both axescomp_barplot now uses bray-curtis by default for sample ordering (instead of aitchison) as this generally looks bettercomp_barplot now expects palette argument colours in first-to-last order, which is more intuitive than the previous reverse orderdistinct_palette now adds “lightgrey” to end by defaulttax_filter’s is_counts argument replaced by use_counts, allowing it to filter ps_extra objects using stored count data (i.e. after tax_transform).comp_heatmap can no longer transform data internally, but accepts data already transformed with tax_transform and uses stored count data in the ps_extra for any taxa annotationstax_anno heatmap annotation default style slightly changed.tax_names2rank replaces deprecated tax_names2tt
ord_plot arrow labels can now be rotated with the help of tax_lab_style() and constraint_lab_style()
ps_calc_dominant function added, for conveniently identifying the dominant taxon in each phyloseq sampledistinct_palette gains “kelly” and “greenArmytage” palettes and helpfully adds “lightgrey” to the end by default for convenient use as the palette argument to comp_barplot
tax_transform can now chain multiple transformations together and records these transformations in the ps_extra outputtax_mutate function added, for modifying the tax_table rank variables with dplyr mutate syntaxtax_sort can now sort ps_extra objectstax_anno no longer requires ‘column’ or ‘row’ to be specified in advanceprev, a low level helper function for calculating taxon prevalence now exportedRelease accompanying JOSS manuscript acceptance.
ord_plot gains vec_* helper functions for generating lists for styling taxa and constraint vectors/arrows (vec_constraint, vec_tax_all and vec_tax_sel)ord_explore shapes selection bug fixed by limiting to 5 shapes returned by new scale_shape_girafe_filled functionord_explore can now draw stat_ellipse or taxa loading vectorstax_agg error messages now include personalised suggested tax_fix codeord_explore Shiny app GUI can now also be used to interactively generate ordination plots, and to generate ord_plot codeord_plot bug fix - can now plot any dimensiontax_fill_unknowns functionord_explore now compatible with Shiny version >=1.5.0tax_fix now sends messages about fixing completely anonymous rows, instead of warningsAllows ps_seriate, ps_arrange, ps_reorder, ps_mutate, and ps_select to work directly with ps_extra objects, as this can be helpful when quickly exploring / printing aggregated data, as in the new “Working with phyloseq objects” tutorial.
ord_plot_iris and ord_explore no longer take ps argument of untransformed counts, because (by default) tax_transform now keeps the untransformed counts otu_table in the ps_extra objectord_explore now allows much better control over selection of points (using ggiraph functionality)ord_plot now has interactive option with ggiraph packageord_plot_iris gains ord_plot argument, allowing a simple pairing of iris plot and ordination to be made more easilycomp_barplot (and by extension ord_plot_iris) can now be made interactive in a simple fashion, using ggiraph for hover/tooltip interaction with taxaThis is the first public release version of microViz. It is still under active development, so pay attention to the following:
tax_agg argument agg_level renamed to rank. tax_agg returns taxa in different order than before (and now different order from, but same aggregation as, microbiome::aggregate_taxa()). tax_agg now checks if taxa cannot be uniquely identified at the specified rank level. (now also about twice as fast)tax_fill_unknowns x arg renamed to ps. Also now stops when unknown values are detected to the left of known values in the tax_table, as this should always be wrong/need fixing. Also, by default it now searches a larger list of probably unknown/uninformative tax_table values e.g. “k__NA”, “p__Unknown” will now be replacedcomp_barplot gets merge_other argument, which, when FALSE, shows full diversity of samples by outlining individual taxa within the (grey) “other” category!tax_sort for sorting taxa in tax_table and otu_table by several name or abundance options (deletes phy_tree if present!)tax_transform can take a rank argument, to perform aggregation (internally using tax_agg) and transformation with one function, and record the results. This is now the recommended usage!
tax_transform new transformation = “binary” can convert to presence/absence data (used by tax_sort for by = “prev”)tax_top for flexibly returning top n taxa, at chosen rank, with ordering by tax_sort
cor_heatmap and comp_heatmap argument changed: ‘taxa_which’ replaced with ‘taxa_side’ for easier control over where taxa annotations are placed (default behaviour stays the same)cor_heatmap with variable distributions using var_anno and its helpers: anno_var_box and anno_var_hist
cor_heatmap gets ‘var_fun’ argument for transforming variables before correlatingphyloseq_validate checks for zero taxa, which can happen after filtering samplestax_filter gets undetected arg (greater than), as optional alternative to prev_detection_threshold (greater than or equal to)cor_heatmap for microbe-metadata correlation heatmapscomp_heatmap for visualising taxonomic composition across samples (ordered/clustered)ord_calc can now guess which method the user wants by default (by checking for presence of distance matrix and constraints)ord_plot auto_caption size can now be set, and it also now exposes the coord_* args: expand and clipord_plot_iris now handles multiple rings of anno_binary annotations, and anno_binary position is now closer when no anno_colour is setord_explore shiny app menu styling is a little cleaner (but still needs some love)tax_scale for applying base::scale() to phyloseq otu_tabletax_name for easily setting informative unique phyloseq taxa_namesdist_permanova replaces permanova for naming consistency and guiding usercomp_barplot replaces plot_comp_bar in anticipation of (a) future heatmap function(s) named comp_heatmap or similarNew “ps_extra” class (S3) conveniently stores phyloseq object alongside any calculated distance matrix, ordination and permanova models, as well as records of tax_agg and tax_transform calls. “ps_extra” class objects have a pretty and compact print method, a simple list structure, and convenient accessor functions to return each component: ps_get, info_get, dist_get, ord_get, perm_get, bdisp_get.
ord_plot_iris the data arg is replaced with ord and conditionally optional ps arg for when data in ord have been transformedpermanova always uses adonis2 now, so that arg is removed, and replaced with by argument to set sums of squares choiceord_plot gets a center argument to center expand the plot limits to center around zero (useful when pairing with ord_plot_iris)ord_explore can now also display ordinations that don’t use distances like PCA and RDA (as well as PCoA of course)ord_explore gains a ps arg (for untransformed version) and other tweaks to facilitate using transformed data in ord
calc_dist –> dist_calc
beta_disper –> dist_bdisp
ordin8 –> ord_calc
plot_ordin8 –> ord_plot
model_tax_corncob –> tax_model_corncob
ps_filter allows filtering of phyloseq samples by values of variables in sample_data (wrapper around dplyr’s filter function)ps_mutate no longer needs .across argument to use dplyr::across()
plot_ordin8 arguments changed to allow easier sizing and styling of all vectors and labelsplot_ordin8 default styling of taxon and constraint vectors and labels is changed: background vectors are now semi-transparent and dashed lines are not used any more by default (but can be set)ordin8 and plot_ordin8 get basic support for CCA and NMDS methods finallyplot_comp_bar gets order_samples_with_all_taxa and tax_transform_for_ordering
plot_comp_bar groups added to Visualising Compositions article on website.phyloseq_validate now fixes otu_tables stored as integers and messages user about suspicious or NA tax_table entries and this happens as part of plot_comp_bar and plot_ordin8
plot_comp_bar and plot_ordin8 gain taxon_renamer argument to allow you to customise the taxon names on these plots
plot_comp_bar can now handle missing values in the grouping variable by converting NAs to “NA”s
Some functions renamed for naming consistency:
prepend_ranks -> tax_prepend_ranks
tax_model_corncob -> model_tax_corncob
corncob_models_to_var_stats -> modelsmodels2stats_corncob
tax_tree_ nodes/edges/plot -> taxatree_ …