Flexible representation of morphospaces, including their combination with either other variables or a phylogeny.
plot_mspace(
mspace,
axes = NULL,
links = NULL,
template = NULL,
x = NULL,
y = NULL,
nh,
nv,
mag,
rescale,
invax = NULL,
adj_frame = c(1, 1),
points = TRUE,
models = TRUE,
groups = TRUE,
phylo = TRUE,
shapeax = TRUE,
landsc = TRUE,
legend = FALSE,
scalebar = FALSE,
cex.legend = 1,
asp = NA,
xlab,
ylab,
xlim = NULL,
ylim = NULL,
size.models,
asp.models,
rot.models,
col.models,
bg.models,
lwd.models,
alpha.models,
cex.ldm,
col.ldm,
pch.points = 1,
col.points = 1,
bg.points = 1,
cex.points = 1,
density.points = TRUE,
col.groups = 1,
bg.groups = 1,
pch.groups = 16,
cex.groups = 1,
ellipse.groups = mspace$plotinfo$ellipse.groups,
conflev.groups = 0.95,
lwd.groups = 1,
lty.groups = 1,
alpha.groups = 0,
density.groups = TRUE,
col.phylo = 1,
lwd.phylo = 1,
lty.phylo = 1,
col.nodes,
pch.nodes,
bg.nodes,
cex.nodes,
col.tips,
pch.tips,
bg.tips,
cex.tips,
type.axis,
lwd.axis = 1,
lty.axis = 1,
col.axis = 1,
palette.landsc = grDevices::heat.colors,
display.landsc,
alpha.landsc,
nlevels.landsc = 50,
drawlabels.landsc = FALSE,
lty.landsc = 1,
lwd.landsc = 1
)An "mspace" object created using the
mspace %>% proj_* pipeline.
Numeric of length 1 or 2, indicating the axes to be plotted.
A list with the indices of the coordinates defining the
wireframe (following the format used in Morpho).
Either a 2-column matrix with landmarks/semilandmarks and
template curves coordinates (for 2D shape data) or a "mesh3d"
object representing the mean shape of the sample (for 3D shape data).
Optional vector with a non-morphometric variable to be plotted in
the x or y axis. Alternatively, a "phylo" object can be provided.
Positive integers; the number of shape models along the x
(nh) and the y (nv) axes.
Numeric; magnifying factor for shape models.
Logical; whether to re-scale background shape models so shape variation is shown more clearly.
Optional numeric indicating which of the axes provided in
axes needs to be inverted (options are 1, 2 or
c(1,2)).
Numeric of length 2, providing a posteriori scaling factors for the width and height of the frame, respectively.
Logical; whether to plot the scatter points corresponding
to the sampled shapes stored in mspace$projected$scores.
Logical; whether to plot background shape models (stored
in mspace$projected$shapemodels).
Logical; whether to plot the convex hulls/confidence
ellipses enclosing the groups stored in
mspace$projected$gr_class.
Logical; whether to plot phylogenetic relationships stored
in mspace$projected$phylo.
Logical; whether to plot morphometric axes stored in
mspace$projected$shape_axis.
Logical; whether to plot landscape surface stored in
mspace$projected$landsc.
Logical; whether to show legend for groups.
Logical; whether to show scalebar for landscapes.
Numeric; size of legend labels/symbols.
Standard arguments passed to the generic
graphics::plot() function.
Numeric; size factor for shape models.
Numeric; y/x aspect ratio of shape models.
Numeric; angle (in degrees) to rotate shape models.
Color for wireframes/outlines of shape models.
Background color for outlines/meshes of shape models.
Integer; width of border lines in wireframes/outlines of shape models.
Numeric; transparency factor for background models (3D only).
Numeric; size of landmarks/semilandmarks in the background models.
Color of landmarks/semilandmarks in the background models.
Symbol of the scatterpoints.
Color of the scatterpoints.
Background color of the scatterpoints.
Numeric; size of the scatterpoints
Logical; whether to add density distribution for
points (univariate ordinations only). Overriden by
density.groups = TRUE
Color of the hulls/ellipses and/or scatterpoints corresponding to groups' mean shapes.
Background color of the scatterpoints corresponding to groups' mean shapes.
Symbol of the scatterpoints corresponding to groups' mean shapes.
Numeric; size of the scatterpoints corresponding to groups' mean shapes.
Logical; whether to use confidence ellipses to
delimit groups (if FALSE convex hulls are used instead).
Numeric; confidence level used for confidence ellipse(s).
Integer; width of the lines in groups' ellipses/hulls.
Integer; type of the lines in groups' ellipses/hulls.
Numeric; transparency factor for groups' ellipses/hulls/density distributions.
Logical; whether to add density distribution for groups (univariate ordinations only).
Color of the lines depicting phylogenetic branches.
Integer; width of the lines depicting phylogenetic branches.
Integer; type of the lines depicting phylogenetic branches.
Color of the scatterpoints representing the nodes of the phylogeny.
Symbol of the scatterpoints representing the nodes of the phylogeny.
Background color of the scatterpoints representing the nodes of the phylogeny.
Numeric; size of the scatterpoints representing the nodes of the phylogeny.
Color of the scatterpoints representing the tips of the phylogeny.
Symbol of the scatterpoints representing the tips of the phylogeny.
Background color of the scatterpoints representing the tips of the phylogeny.
Numeric; size of the scatterpoints representing the tips of the phylogeny.
Integer; type of arrows (0 = no arrow;
1 = pointing towards the maximum; 2 = pointing towards
the maximum, 3 = pointing in both directions).
Integer; width of the lines depicting a morphometric axis.
Integer; type of the lines depicting a morphometric axis.
Color of the lines depicting a morphometric axis.
A function defining a color palette to use for landscape representation.
How to display landscape representation; options
are "contour" and "filled.contour". For bivariate
landscapes only.
Numeric; transparency factor for filled contours depicting landscapes.
Number of levels (i.e., contours) to use in landscape representation.
Logical; should the labels indicating the value of each surface contour be plotted?
Integer; type of the contour lines depicting landscapes.
Integer; width of the contour lines depicting landscapes.
This function allows to regenerate/tweak morphospaces contained in
"mspace" objects already in existence. By default, plot_mspace
regenerates the morphospace with all its projected elements, preserving
graphical parameters used originally during the mspace +
proj_* pipeline (and stored in mspace$plotinfo). However,
all the graphical parameters can be modified to customize graphical
representations. Also, plot_mspace can be used to add a legend and/or a
scalebar to aid identification of groups and interpretation of landscapes,
respectively.
In addition, this function expands the range of graphical options available
beyond 'pure' morphospaces. If a numeric non-shape variable (assumed to be
measured for the same specimens in mspace$projected$scores) is fed
to one of x or y, a 'hybrid' morphospace is produced (i.e.
the bivariate plot will be constructed from the combination of x or
y and a morphometric axis; background shape models will represent
variation only for the latter). If instead a "phylo" object (assumed
to describe the phylogenetic relationships among tips scores stored in
mspace$projected$phylo_scores) is provided for either x or
y, a vertical or horizontal phenogram will be deployed (the x/y axis
range will correspond to branch lengths, so caution should be exercised
when interpreting the output).
Note: when regenerating landscapes, it's important to keep in mind
that this surface has been calculated for a specific set of shapes and
ordination axes. Hence, its regeneration using plot_mspace is only
warranted if the axes being depicted are the same than those used when the
surface landscape was originally computed using mspace +
proj_landscape. The only exception is when one of the
original axes (i.e., those specified with the axes argument in
mspace) is dropped (i.e., not specified with the axes
argument of plot_mspace). This will result in the collapse of
the 3D landscape projected into a bivariate morphospace into a 2D landscape
projected into a univariate one.
#load and extract relevant data, packages and information
library(magrittr)
data("tails")
shapes <- tails$shapes
species <- tails$data$species
sizes <- tails$sizes
sp_shapes <- expected_shapes(shapes, species)
sp_sizes <- cbind(tapply(sizes, species, mean))
tree <- tails$tree
links <- tails$links
#generate basic morphospace, add sampled shapes, species classification, and
#phylogenetic structure
msp <- mspace(shapes, axes = c(1,2), plot = FALSE) %>%
proj_shapes(shapes = shapes) %>%
proj_groups(groups = species) %>%
proj_phylogeny(shapes = sp_shapes, tree = tree)
#> Error in plot.xy(xy.coords(x, y), type = type, ...): plot.new has not been called yet
##Plotting 'pure' morphospaces:
#plot mspace object as it is
plot_mspace(msp)
#> Error in eval(expr, envir, enclos): object 'msp' not found
#add colors for points, by species
plot_mspace(msp, col.points = species,
col.groups = 1:nlevels(species))
#> Error in eval(expr, envir, enclos): object 'msp' not found
#add links for landmark configurations
plot_mspace(msp, links = links,
col.points = species, col.groups = 1:nlevels(species))
#> Error in eval(expr, envir, enclos): object 'msp' not found
#change number and sizes of shape models in the background
plot_mspace(msp, nh = 2, nv = 2, links = links,
size.models = 0.5,
col.points = species, col.groups = 1:nlevels(species))
#> Error in eval(expr, envir, enclos): object 'msp' not found
#magnify deformation and highlight landmarks
plot_mspace(msp, mag = 1.5, nh = 2, nv = 2, links = links,
size.models = 0.5, col.points = species,
col.groups = 1:nlevels(species), cex.ldm = 5, col.ldm = "red")
#> Error in eval(expr, envir, enclos): object 'msp' not found
#change axes 1,2 for 1,3
plot_mspace(msp, axes = c(1,3), mag = 1.5, nh = 2, nv = 2, links = links,
size.models = 0.5, col.points = species,
col.groups = 1:nlevels(species), cex.ldm = 5, col.ldm = "red")
#> Error in eval(expr, envir, enclos): object 'msp' not found
#change colors for as tips and nodes of the phylogeny
plot_mspace(msp, axes = c(1,3), mag = 1.5, nh = 2, nv = 2, links = links,
size.models = 0.5, cex.ldm = 5, col.ldm = "red",
col.tips = "red", col.nodes = "blue")
#> Error in eval(expr, envir, enclos): object 'msp' not found
#plot only first PC axis, with general distribution of specimens
plot_mspace(msp, axes = 1, mag = 1.5, nh = 2, nv = 2, links = links,
size.models = 0.5, cex.ldm = 5, density.groups = FALSE,
col.ldm = "red", col.tips = "red", col.nodes = "blue")
#> Error in eval(expr, envir, enclos): object 'msp' not found
#plot only first PC axis, with distribution of specimens by group
plot_mspace(msp, axes = 1, mag = 1.5, nh = 2, nv = 2, links = links,
alpha.groups = 0.5, size.models = 0.5, cex.ldm = 5,
density.groups = TRUE, col.ldm = "red", col.tips = "red",
col.nodes = "blue")
#> Error in eval(expr, envir, enclos): object 'msp' not found
#add legend
plot_mspace(msp, axes = 1, mag = 1.5, nh = 2, nv = 2, links = links,
alpha.groups = 0.5, size.models = 0.5, cex.ldm = 5,
density.groups = TRUE, col.ldm = "red", col.tips = "red",
col.nodes = "blue", legend = TRUE, cex.legend = 1.3,
pch.groups = 16)
#> Error in eval(expr, envir, enclos): object 'msp' not found
#remove all the other elements to see only shape variation captured by the
#first two PCs
plot_mspace(msp, axes = c(1,2), links = links,
col.points = species, col.groups = 1:nlevels(species),
points = FALSE, groups = FALSE, phylo = FALSE)
#> Error in eval(expr, envir, enclos): object 'msp' not found
##Plotting 'hybrid' morphospaces:
#plot size against first PC
plot_mspace(msp, x = sizes, axes = 1, links = links, col.points = species,
col.groups = 1:nlevels(species), pch.points = 16,
xlab = "Centroid size")
#> Error in eval(expr, envir, enclos): object 'msp' not found
##Plotting phenograms:
#plot vertical phenogram against PC1
plot_mspace(msp, y = tree, axes = 1, links = links, col.points = species,
col.groups = 1:nlevels(species), pch.points = 16,
xlab = "Branch lengths", pch.tips = 21, bg.tips = "red",
pch.nodes = 21, bg.nodes = "blue")
#> Error in eval(expr, envir, enclos): object 'msp' not found
#plot horizontal phenogram against PC2
plot_mspace(msp, x = tree, axes = 2, links = links, col.points = species,
col.groups = 1:nlevels(species), pch.points = 16,
ylab = "Branch lengths", pch.tips = 21, bg.tips = "red",
pch.nodes = 21, bg.nodes = "blue")
#> Error in eval(expr, envir, enclos): object 'msp' not found