11_main_plotting_functions: Main Plotting Functions
In barsurf: Contour Plots, 3D Plots, Vector Fields and Heatmaps
Description
Usage
Arguments
Details
References
See Also
Examples
Description
Selected multivariate plots, including:
Combined contour-heatmap plots, 3d bar and surface plots, triangular plots, isosurface plots, 3d-based contour-heatmap plots, and 2d/3d vector fields.
Note that there are wrappers for most of these plotting functions, which take a mathematical function as their main argument.
Refer to Functional Versions.
Usage
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
####################################
#combined contour-heatmap plots
####################################
plot_dfield (x, y, fv, ..., fb,
main="", xlab="x", ylab="y",
contours=TRUE, grid=FALSE, heatmap=TRUE,
contour.labels=FALSE, bin.labels=FALSE,
add=FALSE, axes=TRUE, reverse=FALSE, swap.sides=FALSE,
xyrel, continuous.axes=FALSE,
ncontours=2, clabs, blabs,
xat, yat, xlabs, ylabs,
raster=FALSE,
contour.color="#000000", grid.color="#888888",
colf, colff, theme, colors, hcv=FALSE)
plot_cfield (x, y, fv, ..., fb,
main="", xlab="x", ylab="y",
contours=TRUE, heatmap=TRUE, contour.labels=FALSE,
add=FALSE, axes=TRUE, reverse=FALSE, swap.sides=FALSE,
ncontours=6, clabs,
xyrel, xat, yat, xlabs, ylabs,
raster=FALSE,
contour.color="#000000", colf, colff, theme, hcv=FALSE)
####################################
#3d plots
#2 variables, f (x, y)
####################################
plot_bar (x, y, fv, ...,
main="", xlab="x", ylab="y", zlab="z",
axes=TRUE, z.axis=FALSE,
ref.arrows = opt.ref.arrows (), reverse=FALSE,
continuous.axes=FALSE,
zlim, xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
top.color = st.top.color (theme), side.color = st.side.color (theme),
theme)
plot_surface (x, y, fv, ...,
main="", xlab="x", ylab="y", zlab="z",
grid=TRUE, gradient.shading=TRUE,
axes=TRUE, z.axis=FALSE,
ref.arrows = opt.ref.arrows (), reverse=FALSE,
zlim, xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
grid.color = st.sgrid.color (theme),
colf, colff, theme)
####################################
#triangular plots
####################################
plot_tricontour (x, y, fv, ..., fb,
main="", xlab="x", ylab="y",
contours=TRUE, heatmap=TRUE, contour.labels=FALSE,
axes=TRUE, ncontours=6, clabs, xyrel="s",
xat, yat, xlabs, ylabs,
contour.color="#000000", colf, colff, theme, hcv=FALSE)
plot_trisurface (x, y, fv, ...,
main="", xlab="x", ylab="y", zlab="z",
grid=TRUE,
axes=TRUE, z.axis=FALSE,
ref.arrows = opt.ref.arrows (),
zlim,
xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
grid.color = st.sgrid.color (theme),
colf, colff, theme)
####################################
#3d plots
#3 variables, f (x, y, z)
####################################
plot_isosurface (x, y, z, fv, ..., fb, fq,
main="", xlab="x", ylab="y", zlab="z",
wire.frame=FALSE, texture=TRUE,
axes=TRUE, z.axis = all (axes),
ref.arrows = opt.ref.arrows (), z.ref.arrow = any (ref.arrows),
reverse=FALSE, z.reverse=FALSE,
nsurfaces=2,
nested=TRUE, maximal,
xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
wire.color="#808080", iso.colors = st.iso.colors (theme),
theme)
plot_cfield3 (x, y, z, fv, ..., fb,
main="", xlab="x", ylab="y", zlab="z",
contours=TRUE, heatmap=TRUE,
axes=TRUE, ref.arrows = opt.ref.arrows (),
slide.labels = any (axes),
reverse=FALSE, z.reverse=FALSE,
ncontours=6, emph="n",
xat, yat, xlabs, ylabs, zlabs,
nhl = opt.nhl (),
colf, colff, theme)
####################################
#matrix visualization
####################################
plot_matrix (x, y, fv, ..., transpose=TRUE,
xlab, ylab,
contours=FALSE, grid, bin.labels,
reverse = c (FALSE, transpose), swap.sides=reverse,
blabs, colors,
hcv=TRUE)
####################################
#vector fields
####################################
plot_vec (x, y, dx, dy, ...,
main="", xlab="x", ylab="y",
vectors=TRUE, heatmap=TRUE,
include.outermost.vectors=FALSE,
add=FALSE, axes=TRUE, reverse=FALSE, swap.sides=FALSE,
xyrel, xat, yat, xlabs, ylabs,
arrowh.length=1.75, arrowh.width = 0.75 * arrowh.length,
arrow.color="#000000", fill.color="#08080810",
colf, colff, theme, hcv=FALSE)
plot_vec3 (x, y, z, dx, dy, dz, ..., P = 1 / 3,
main="", xlab="x", ylab="y", zlab="z",
include.outermost.vectors=FALSE,
axes=TRUE, z.axis = all (axes),
ref.arrows = opt.ref.arrows (), z.ref.arrow = any (ref.arrows),
xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
head.color="#0000B0", mid.color="#8080FF", tail.color="#B0B0B0")
Arguments
x, y, z
In plot_dfield, plot_bar and plot_matrix:
Optional sorted numeric vectors of bin midpoints or breakpoints.
(Refer to the details section for plot_dfield).
In plot_cfield, plot_surface, plot_vec and plot_vec3:
Optional sorted numeric vectors of grid point coordinates.
Note, I recommend that the lengths of x and y are different for 3d vector fields.
In plot_tricontour and plot_trisurface:
Ignored.
In plot_isosurface:
Same as plot_cfield, except that:
(1) They can also be iso-lists of such vectors.
(2) They're required, if fv is an iso-list, and the corresponding array dimension, has different sizes.
Refer to the details section for plot_isosurface.
In plot_cfield3:
Same as plot_cfield, except that z is the vertical slide/slice position.
Note that where x, y and z are missing, they default to:
1:nrows, 1:ncols, 1:nsheets (the third array dimension) or 1:nslides.
fv
In plot_dfield, plot_bar and plot_matrix:
A numeric matrix of function (bin) values.
By default, if fv has row/column names, they will be used.
In plot_cfield and plot_surface:
A numeric matrix of function (point) values.
In plot_tricontour and plot_trisurface:
A numeric square matrix of function values.
Only the top-left triangle is used, including the diagonal.
In plot_isosurface:
A numeric 3d array, or an iso-list of such arrays.
(Refer to the details section for plot_isosurface).
In plot_cfield3:
A list of numeric matrices of function values.
Each matrix corresponds to one z value.
Note that in discretely-spaced plots, fv may contain missing values.
In other plots, missing values are not allowed.
dx, dy, dz
In plot_vec:
Numeric matrices, of equal size, giving the x and y components of a vector field.
In plot_vec3:
Numeric 3d arrays, of equal size, giving the x, y and z components of a vector field.
In plot_vec, they may include missing values.
Note, I recommend that x-dim and y-dim are different for 3d vector fields.
(i.e. dim (dx)[1] != dim (dx)[2]).
This is to minimize possible over plotting.
fb
Optional numeric vector of function values (or "levels"), for contours/isosurfaces.
fq
Alternative way of specifying fb, above.
Numeric vector of probabilities (between zero and one), for quantiles of fv.
P
Numeric, between zero and one, giving the proportion of (highest magnitude) vectors to plot.
main, xlab, ylab, zlab
Optional strings, main/axes titles.
transpose
Logical, if true, transpose fv, along with the any bin labels and colors.
contours
Logical, include contour lines.
grid
Logical, include grid lines.
For plot_matrix, defaults to true, if both the number of rows and columns don't exceed twenty.
wire.frame
Logical, include the wire.frame lines.
gradient.shading
Logical, use gradient shading.
vectors
Logical, include vector arrows.
heatmap
Logical, include heatmap.
contour.labels
Logical, include contour labels.
slide.labels
Logical, include the slide labels.
bin.labels
Logical, include bin labels.
For plot_matrix, defaults to true, if both the number of rows and columns don't exceed ten.
include.outermost.vectors
Logical, plot all vector arrows.
Otherwise (the default), exclude the outermost rows and columns.
texture
Logical, if true, add a small amount of random variation to isosurface colors.
add
Logical, if true, add contours/heatmap to an existing plot.
axes
Logical vector of length one or two, if true, plot reference arrows or axis ticks with labels.
z.axis
Logical, if true, include a z axis.
ref.arrows
Logical vector of length one or two, if true, plot reference arrows, if false plot axis labels.
z.ref.arrow
Logical, if true, plot a z reference arrow, if false, plot z axis labels.
reverse
Logical vector of length one or two, if true, reverse the x and y axes.
z.reverse
Logical, if true, reverse the z axis.
swap.sides
Logical vector of length one or two, if true, swap the axes.
xyrel
Single character, either "f", "s" or "m".
"f" produces a plot with a fixed aspect ratio of one,
"s" produces a square plot, and "m" a maximized plot.
The default is determined by the test.xyrel function.
continuous.axes
Logical of length one or two.
If true, plot the axes in the same was as continuous plots.
zlim
Optional length-2 numeric vector, the vertical range, corresponding to function value.
ncontours, nsurfaces
Integer, the number of contours/surfaces.
Ignored, if fb or fq supplied.
nested, maximal
nested
Logical value, if true (the default), assume that the isosurfaces are nested.
maximal
Logical value, if true, assume that (nested) isosurfaces are centered around local maxima, if false, assume that they're centered around local minima.
These determine the default fb values, including their order.
(Ascending for low-valued focal points, and descending for high-valued focal points).
emph
What to emphasize:
"n" (for nothing).
"b" for both (low and high regions).
"l" for low regions.
"h" for high regions.
"B", "L" or "H" for the same but with a stronger effect.
clabs
Optional character vector of contour labels.
Ignored, unless contour.labels is true.
blabs
Optional character matrix of bin labels.
Its dimensions need to match fv.
Ignored, unless bin.labels is true.
Defaults to the values of fv.
xat, yat
Optional numeric vectors, the x and y axes tick/label points.
xlabs, ylabs
Optional character vectors, the x and y axes tick labels.
In 3d plots, ignored unless axes is true and arrows is false.
zlabs
Optional character vectors, the slide labels.
nhl
Integer, the number of header lines.
arrowh.length, arrowh.width
Numerics, arrow head length and width, in mm.
raster
Logical, if true, use raster-based graphics for the heatmap.
Note that it's possible the default value (false) may change, in the future.
Please refer to the subsection on raster-based heatmaps in the details section, if you're interested in setting this to true.
contour.color
Character vector (or R color strings) of length one or with the same length as the number of contours, giving the contour line colors.
grid.color
String (R color string), giving the grid line color.
wire.color
Sring (R color string), giving the wire frame color.
colf
A litmus object (or equivalent color function), refer to details section for color functions.
colff
A litmus-fitting function, refer to details section for color functions.
top.color, side.color
Strings (R color strings) giving the top and side colors of bars.
Also, can be character matrices.
If matrices, then their dimensions need to match fv.
iso.colors
Character vector (R color strings), giving the (initial) isosurface colors.
colors
Optional character matrix (R color strings), for the bin colors.
Its dimensions need to match fv.
arrow.color, fill.color
Strings (R color strings), arrow line and fill colors.
head.color, mid.color, tail.color
Strings (R color strings), the arrow colors.
theme
String, the name of a supported theme.
If missing, default color values are determined by global options.
Refer to set.bs.theme.
hcv
Logical, if true, use the high color variation option.
...
Ignored.
Details
FUNCTIONS OF TWO DISCRETE VARIABLES
(AND DISCRETELY-SPACED SCALAR FIELDS)
(plot_dfield and plot_bar)
In plot_dfield and plot_bar, the main argument is fv, which is a numeric matrix of function values.
(Each fv value is a bin value).
Increasing row indices (i.e. moving down the matrix) correspond to increasing x values, and increasing column indices (i.e. moving right across the matrix) correspond to increasing y values.
x and y arguments, are numeric vectors of midpoints or breakpoints, of the bins.
If midpoints, then the length of x needs to be equal to the number of rows and the length of y needs to equal the number of columns. If breakpoints, then the length of x needs to be equal to the number of rows plus one, and the length of y needs to equal the number of columns plus one.
FUNCTIONS OF TWO CONTINUOUS VARIABLES
(AND CONTINUOUSLY-SPACED SCALAR FIELDS)
(plot_cfield and plot_surface)
In plot_cfield and plot_surface, the main argument is fv, which is also a numeric matrix of function values.
(However, each fv value is a point value, and the resulting heatmap is for interpolated bin values).
As with the discretely spaced case, increasing row indices (i.e. moving down the matrix) correspond to increasing x values, and increasing column indices (i.e. moving right across the matrix) correspond to increasing y values.
However, optional x and y arguments, give the coordinates of the points.
The length of x needs to be equal to the number of rows, and the length of y needs to equal the number of columns.
TRIANGULAR PLOTS
(plot_tricontour and plot_trisurface)
These functions are similar to plot_cfield and plot_surface, except that the fv matrix, needs to be square, and the x and y coordinates are ignored.
ISOSURFACE PLOTS
(plot_isosurface)
THIS FUNCTION REQUIRES THE misc3d PACKAGE TO BE INSTALLED AND LOADED
(There's no requirement for the package to be attached).
The number of isosurfaces is determined by nsurfaces.
Or by fb or fq, if provided.
The order of fb is important.
If the isosurfaces are nested, and the default colors are used, then the fb values should be in order of the innermost to the outermost.
This package supports two types of isosurface plots, simple isosurface plots, and multi-array isosurface plots.
For simplicity, an "iso-list" is shorthand, for a list, with the same length as the number of isosurfaces.
SIMPLE ISOSURFACE PLOTS
In simple isosurface plots, fv is a numeric 3d array of function values.
Increasing along the first array dimension corresponds to increasing x values, increasing along the second array dimension corresponds to increasing y values, and increasing along the third array dimension corresponds to increasing z values.
There are optional x, y and z arguments, which are numeric vectors, giving the coordinates of the points.
The length of x needs to be equal the x-dim size, the length of y needs to equal the y-dim size, and the length of z needs to equal the z-dim size, where x-dim, y-dim and z-dim refer to dim (fv)[1], dim (fv)[2] and dim (fv)[3], respectively.
MULTI-ARRAY ISOSURFACE PLOTS
In multi-array isosurface plots, fv is an iso-list of numeric 3d arrays.
If the number of arrays is not equal to two (the default value for nsurfaces), then you will need to set nsurfaces, fb or fq.
x, y, z can be numeric vectors or iso-lists of numeric vectors.
If coordinates are iso-lists and fv is an iso-list, then their sizes need to match, surface-wise.
i.e.
length (x [[k]]) needs to equal dim (fv [[k]])[1], for all k
length (y [[k]]) needs to equal dim (fv [[k]])[2], for all k
length (z [[k]]) needs to equal dim (fv [[k]])[3], for all k
where k is the kth isosurface.
OTHER 3D-BASED CONTOUR PLOTS AND HEATMAPS
(plot_cfield3)
plot_slides is similar to plot_cfield, but produces a set of overlapping slides/slices.
Here, fv is a list of numeric matrices.
(One matrix for each slide).
And z, is the coordinate vector for the slides/slices.
(One z value for each slide, and the corresponding fv matrix).
The function contains an emph (emphasis) argument.
Note that setting heatmap to false, will increase the rendering speed.
MATRIX VISUALISATION
(plot_matrix)
The plot_matrix function is a wrapper for plot_dfield.
By default, it transposes the matrix, and then calls plot_dfield with different default values.
This causes the resulting plots to have the same orientation as matrices, in textual form.
Note that in principle, this transposes the matrix, twice.
Because plot_dfield transposes the matrix, in terms of visual interpretation.
Without transposed input, increasing row indices (going down) map to increasing x values (going right).
Note that if bin labels or bin colors are supplied, they're also transposed.
All other arguments (x, y, etc) apply to the transposed matrix, not the original.
2D VECTOR FIELDS
(plot_vec)
plot_vec is similar to plot_cfield, except that there are two dx and dy matrices, instead of a single fv matrix.
The color of the heatmap bins reflects the magnitude of the four surrounding vectors.
3D VECTOR FIELDS
(plot_vec3)
plot_vec3 is similar to plot_vec.
Instead of two numeric matrices, we have three numeric 3d arrays, including dz.
Increasing along the first array dimension corresponds to increasing x values, increasing along the second array dimension corresponds to increasing y values, and increasing along the third array dimension corresponds to increasing z values.
Note that this function has had less testing than other plotting functions in this package.
3D COORDINATE SYSTEM
Currently, 3d plots use a diamond-like orthographic/dimetric projection, with a fixed viewing angle.
By default, (min (x), min (y) ) is at the bottom center.
And increasing x values, run diagonally up-right, and increasing y value run diagonally up-left.
It's not possible to rotate the plots, but the x and y axis can be reversed.
In functions of two variables, the z coordinate represents the function value, and increasing z values run up.
RASTER-BASED HEATMAPS
Raster-based heatmaps, are rendered via the graphics::rasterImage function, so please refer to that function, for further technical details. The plot_dfield function sets the interpolate argument in rasterImage to false, and the plot_cfield functions sets it to true. However, it's possible that results may vary across graphics devices.
Note that this feature is relatively new, and has not had extensive testing.
Currently, only the first and last x and y values are used, in the rendering step.
(However, you still need the whole sequences, because the x and y values are used in other parts of the code).
Which means that, x and y, if provided, need to be equally-spaced.
There's no test for this, and plots with unequally-spaced x and y values will produce incorrect output.
Raster-based heatmaps are likely to render faster, which is especially noticeable for high resolution heatmaps.
PLOT COLORS
The color function (colf) can be any function that maps a numeric vector/matrix (as its first argument) to a character vector/matrix of R colors, however, I recommend using litmus objects. The litmus-fitting function (colff), is a function that maps a numeric vector (also, as its first argument) to a valid color function, however, I recommend using a function that returns a litmus object.
Assuming that colf, colff and colors are missing, a litmus-fitting function is determined by calling one of the "st" functions.
Refer to Standardized Palette Interface.
The default litmus-fitting function will be determined by the theme argument, if the theme argument is provided, otherwise, it will be determined by global options.
Then the litmus object is fitted to the input values (usually, fv), then the colors are computed from the litmus object.
Similar principles apply to top.color, side.color and iso.colors, except that the "st" functions returns the colors rather than litmus-fitting functions.
In some cases, it may be useful to wrap a predefined litmus-fitting function.
e.g. To use nonstandard hot and cold colors, wrap the hot.and.cold.fit function, then set the colff argument to the wrapper function.
Opaque color functions are preferable in 2d heatmaps.
ADDITIONAL NOTES
If using plot_bar, plot_surface or plot_trisurface to plot constant or near-constant values, set zlim, for a better result.
Noting that functions that are constant in theory, may produce non-constant values when computed via floating point arithmetic.
In applied mathematics and applied statistics, you may want to set z.axis=TRUE and ref.arrows=FALSE (in 3d plots), and xyrel="m" (in 2d plots).
The default for reference arrows, can also be set via global options.
Often, it may be useful to create wrapper functions, that set the default argument values, accordingly.
There's no guarantee that default contour lines will be suitable.
References
Refer to the vignette for an overview, references and better examples.
See Also
Functional Versions
Which take a function as their main argument.
litmus, litmus.fit
Predefined Litmus Objects, Predefined Litmus-Fitting Functions
With predefined colors.
Standardized Palette Interface, Global Options
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#NOTE THAT THERE ARE MORE EXAMPLES IN:
#(1) THE PACKAGE VIGNETTE
#(2) THE HELP PAGE FOR FUNCTIONAL VERSIONS
#discretely-spaced example
fv <- matrix (1:100, 10, 10, byrow=TRUE)
plot_dfield (,,fv)
plot_bar (,,fv)
plot_matrix (,,fv)
#continuously-spaced example
x <- y <- seq (-15.5, 15.5,, 40)
fv <- outer (x, y, rotated.sinc)
plot_cfield (x, y, fv, fb=0, hcv=TRUE)
plot_surface (x, y, fv)
barsurf documentation built on Jan. 20, 2021, 5:08 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details References See Also Examples
Description
Selected multivariate plots, including:
Combined contour-heatmap plots, 3d bar and surface plots, triangular plots, isosurface plots, 3d-based contour-heatmap plots, and 2d/3d vector fields.
Note that there are wrappers for most of these plotting functions, which take a mathematical function as their main argument.
Refer to Functional Versions.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 | ####################################
#combined contour-heatmap plots
####################################
plot_dfield (x, y, fv, ..., fb,
main="", xlab="x", ylab="y",
contours=TRUE, grid=FALSE, heatmap=TRUE,
contour.labels=FALSE, bin.labels=FALSE,
add=FALSE, axes=TRUE, reverse=FALSE, swap.sides=FALSE,
xyrel, continuous.axes=FALSE,
ncontours=2, clabs, blabs,
xat, yat, xlabs, ylabs,
raster=FALSE,
contour.color="#000000", grid.color="#888888",
colf, colff, theme, colors, hcv=FALSE)
plot_cfield (x, y, fv, ..., fb,
main="", xlab="x", ylab="y",
contours=TRUE, heatmap=TRUE, contour.labels=FALSE,
add=FALSE, axes=TRUE, reverse=FALSE, swap.sides=FALSE,
ncontours=6, clabs,
xyrel, xat, yat, xlabs, ylabs,
raster=FALSE,
contour.color="#000000", colf, colff, theme, hcv=FALSE)
####################################
#3d plots
#2 variables, f (x, y)
####################################
plot_bar (x, y, fv, ...,
main="", xlab="x", ylab="y", zlab="z",
axes=TRUE, z.axis=FALSE,
ref.arrows = opt.ref.arrows (), reverse=FALSE,
continuous.axes=FALSE,
zlim, xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
top.color = st.top.color (theme), side.color = st.side.color (theme),
theme)
plot_surface (x, y, fv, ...,
main="", xlab="x", ylab="y", zlab="z",
grid=TRUE, gradient.shading=TRUE,
axes=TRUE, z.axis=FALSE,
ref.arrows = opt.ref.arrows (), reverse=FALSE,
zlim, xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
grid.color = st.sgrid.color (theme),
colf, colff, theme)
####################################
#triangular plots
####################################
plot_tricontour (x, y, fv, ..., fb,
main="", xlab="x", ylab="y",
contours=TRUE, heatmap=TRUE, contour.labels=FALSE,
axes=TRUE, ncontours=6, clabs, xyrel="s",
xat, yat, xlabs, ylabs,
contour.color="#000000", colf, colff, theme, hcv=FALSE)
plot_trisurface (x, y, fv, ...,
main="", xlab="x", ylab="y", zlab="z",
grid=TRUE,
axes=TRUE, z.axis=FALSE,
ref.arrows = opt.ref.arrows (),
zlim,
xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
grid.color = st.sgrid.color (theme),
colf, colff, theme)
####################################
#3d plots
#3 variables, f (x, y, z)
####################################
plot_isosurface (x, y, z, fv, ..., fb, fq,
main="", xlab="x", ylab="y", zlab="z",
wire.frame=FALSE, texture=TRUE,
axes=TRUE, z.axis = all (axes),
ref.arrows = opt.ref.arrows (), z.ref.arrow = any (ref.arrows),
reverse=FALSE, z.reverse=FALSE,
nsurfaces=2,
nested=TRUE, maximal,
xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
wire.color="#808080", iso.colors = st.iso.colors (theme),
theme)
plot_cfield3 (x, y, z, fv, ..., fb,
main="", xlab="x", ylab="y", zlab="z",
contours=TRUE, heatmap=TRUE,
axes=TRUE, ref.arrows = opt.ref.arrows (),
slide.labels = any (axes),
reverse=FALSE, z.reverse=FALSE,
ncontours=6, emph="n",
xat, yat, xlabs, ylabs, zlabs,
nhl = opt.nhl (),
colf, colff, theme)
####################################
#matrix visualization
####################################
plot_matrix (x, y, fv, ..., transpose=TRUE,
xlab, ylab,
contours=FALSE, grid, bin.labels,
reverse = c (FALSE, transpose), swap.sides=reverse,
blabs, colors,
hcv=TRUE)
####################################
#vector fields
####################################
plot_vec (x, y, dx, dy, ...,
main="", xlab="x", ylab="y",
vectors=TRUE, heatmap=TRUE,
include.outermost.vectors=FALSE,
add=FALSE, axes=TRUE, reverse=FALSE, swap.sides=FALSE,
xyrel, xat, yat, xlabs, ylabs,
arrowh.length=1.75, arrowh.width = 0.75 * arrowh.length,
arrow.color="#000000", fill.color="#08080810",
colf, colff, theme, hcv=FALSE)
plot_vec3 (x, y, z, dx, dy, dz, ..., P = 1 / 3,
main="", xlab="x", ylab="y", zlab="z",
include.outermost.vectors=FALSE,
axes=TRUE, z.axis = all (axes),
ref.arrows = opt.ref.arrows (), z.ref.arrow = any (ref.arrows),
xat, yat, xlabs, ylabs,
nhl = opt.nhl (),
head.color="#0000B0", mid.color="#8080FF", tail.color="#B0B0B0")
|
Arguments
x, y, z |
In plot_dfield, plot_bar and plot_matrix: In plot_cfield, plot_surface, plot_vec and plot_vec3: In plot_tricontour and plot_trisurface: In plot_isosurface: (1) They can also be iso-lists of such vectors. Refer to the details section for plot_isosurface. In plot_cfield3: Note that where x, y and z are missing, they default to: |
fv |
In plot_dfield, plot_bar and plot_matrix: In plot_cfield and plot_surface: In plot_tricontour and plot_trisurface: In plot_isosurface: In plot_cfield3: Note that in discretely-spaced plots, fv may contain missing values. |
dx, dy, dz |
In plot_vec: In plot_vec3: In plot_vec, they may include missing values. |
fb |
Optional numeric vector of function values (or "levels"), for contours/isosurfaces. |
fq |
Alternative way of specifying fb, above. |
P |
Numeric, between zero and one, giving the proportion of (highest magnitude) vectors to plot. |
main, xlab, ylab, zlab |
Optional strings, main/axes titles. |
transpose |
Logical, if true, transpose fv, along with the any bin labels and colors. |
contours |
Logical, include contour lines. |
grid |
Logical, include grid lines. |
wire.frame |
Logical, include the wire.frame lines. |
gradient.shading |
Logical, use gradient shading. |
vectors |
Logical, include vector arrows. |
heatmap |
Logical, include heatmap. |
contour.labels |
Logical, include contour labels. |
slide.labels |
Logical, include the slide labels. |
bin.labels |
Logical, include bin labels. |
include.outermost.vectors |
Logical, plot all vector arrows. |
texture |
Logical, if true, add a small amount of random variation to isosurface colors. |
add |
Logical, if true, add contours/heatmap to an existing plot. |
axes |
Logical vector of length one or two, if true, plot reference arrows or axis ticks with labels. |
z.axis |
Logical, if true, include a z axis. |
ref.arrows |
Logical vector of length one or two, if true, plot reference arrows, if false plot axis labels. |
z.ref.arrow |
Logical, if true, plot a z reference arrow, if false, plot z axis labels. |
reverse |
Logical vector of length one or two, if true, reverse the x and y axes. |
z.reverse |
Logical, if true, reverse the z axis. |
swap.sides |
Logical vector of length one or two, if true, swap the axes. |
xyrel |
Single character, either "f", "s" or "m". |
continuous.axes |
Logical of length one or two. |
zlim |
Optional length-2 numeric vector, the vertical range, corresponding to function value. |
ncontours, nsurfaces |
Integer, the number of contours/surfaces. |
nested, maximal |
nested |
emph |
What to emphasize: |
clabs |
Optional character vector of contour labels. |
blabs |
Optional character matrix of bin labels. |
xat, yat |
Optional numeric vectors, the x and y axes tick/label points. |
xlabs, ylabs |
Optional character vectors, the x and y axes tick labels. |
zlabs |
Optional character vectors, the slide labels. |
nhl |
Integer, the number of header lines. |
arrowh.length, arrowh.width |
Numerics, arrow head length and width, in mm. |
raster |
Logical, if true, use raster-based graphics for the heatmap. |
contour.color |
Character vector (or R color strings) of length one or with the same length as the number of contours, giving the contour line colors. |
grid.color |
String (R color string), giving the grid line color. |
wire.color |
Sring (R color string), giving the wire frame color. |
colf |
A litmus object (or equivalent color function), refer to details section for color functions. |
colff |
A litmus-fitting function, refer to details section for color functions. |
top.color, side.color |
Strings (R color strings) giving the top and side colors of bars. |
iso.colors |
Character vector (R color strings), giving the (initial) isosurface colors. |
colors |
Optional character matrix (R color strings), for the bin colors. |
arrow.color, fill.color |
Strings (R color strings), arrow line and fill colors. |
head.color, mid.color, tail.color |
Strings (R color strings), the arrow colors. |
theme |
String, the name of a supported theme. |
hcv |
Logical, if true, use the high color variation option. |
... |
Ignored. |
Details
FUNCTIONS OF TWO DISCRETE VARIABLES
(AND DISCRETELY-SPACED SCALAR FIELDS)
(plot_dfield and plot_bar)
In plot_dfield and plot_bar, the main argument is fv, which is a numeric matrix of function values.
(Each fv value is a bin value).
Increasing row indices (i.e. moving down the matrix) correspond to increasing x values, and increasing column indices (i.e. moving right across the matrix) correspond to increasing y values.
x and y arguments, are numeric vectors of midpoints or breakpoints, of the bins.
If midpoints, then the length of x needs to be equal to the number of rows and the length of y needs to equal the number of columns. If breakpoints, then the length of x needs to be equal to the number of rows plus one, and the length of y needs to equal the number of columns plus one.
FUNCTIONS OF TWO CONTINUOUS VARIABLES
(AND CONTINUOUSLY-SPACED SCALAR FIELDS)
(plot_cfield and plot_surface)
In plot_cfield and plot_surface, the main argument is fv, which is also a numeric matrix of function values.
(However, each fv value is a point value, and the resulting heatmap is for interpolated bin values).
As with the discretely spaced case, increasing row indices (i.e. moving down the matrix) correspond to increasing x values, and increasing column indices (i.e. moving right across the matrix) correspond to increasing y values.
However, optional x and y arguments, give the coordinates of the points.
The length of x needs to be equal to the number of rows, and the length of y needs to equal the number of columns.
TRIANGULAR PLOTS
(plot_tricontour and plot_trisurface)
These functions are similar to plot_cfield and plot_surface, except that the fv matrix, needs to be square, and the x and y coordinates are ignored.
ISOSURFACE PLOTS
(plot_isosurface)
THIS FUNCTION REQUIRES THE misc3d PACKAGE TO BE INSTALLED AND LOADED
(There's no requirement for the package to be attached).
The number of isosurfaces is determined by nsurfaces.
Or by fb or fq, if provided.
The order of fb is important.
If the isosurfaces are nested, and the default colors are used, then the fb values should be in order of the innermost to the outermost.
This package supports two types of isosurface plots, simple isosurface plots, and multi-array isosurface plots.
For simplicity, an "iso-list" is shorthand, for a list, with the same length as the number of isosurfaces.
SIMPLE ISOSURFACE PLOTS
In simple isosurface plots, fv is a numeric 3d array of function values.
Increasing along the first array dimension corresponds to increasing x values, increasing along the second array dimension corresponds to increasing y values, and increasing along the third array dimension corresponds to increasing z values.
There are optional x, y and z arguments, which are numeric vectors, giving the coordinates of the points.
The length of x needs to be equal the x-dim size, the length of y needs to equal the y-dim size, and the length of z needs to equal the z-dim size, where x-dim, y-dim and z-dim refer to dim (fv)[1], dim (fv)[2] and dim (fv)[3], respectively.
MULTI-ARRAY ISOSURFACE PLOTS
In multi-array isosurface plots, fv is an iso-list of numeric 3d arrays.
If the number of arrays is not equal to two (the default value for nsurfaces), then you will need to set nsurfaces, fb or fq.
x, y, z can be numeric vectors or iso-lists of numeric vectors.
If coordinates are iso-lists and fv is an iso-list, then their sizes need to match, surface-wise.
i.e.
length (x [[k]]) needs to equal dim (fv [[k]])[1], for all k
length (y [[k]]) needs to equal dim (fv [[k]])[2], for all k
length (z [[k]]) needs to equal dim (fv [[k]])[3], for all k
where k is the kth isosurface.
OTHER 3D-BASED CONTOUR PLOTS AND HEATMAPS
(plot_cfield3)
plot_slides is similar to plot_cfield, but produces a set of overlapping slides/slices.
Here, fv is a list of numeric matrices.
(One matrix for each slide).
And z, is the coordinate vector for the slides/slices.
(One z value for each slide, and the corresponding fv matrix).
The function contains an emph (emphasis) argument.
Note that setting heatmap to false, will increase the rendering speed.
MATRIX VISUALISATION
(plot_matrix)
The plot_matrix function is a wrapper for plot_dfield.
By default, it transposes the matrix, and then calls plot_dfield with different default values.
This causes the resulting plots to have the same orientation as matrices, in textual form.
Note that in principle, this transposes the matrix, twice.
Because plot_dfield transposes the matrix, in terms of visual interpretation.
Without transposed input, increasing row indices (going down) map to increasing x values (going right).
Note that if bin labels or bin colors are supplied, they're also transposed.
All other arguments (x, y, etc) apply to the transposed matrix, not the original.
2D VECTOR FIELDS
(plot_vec)
plot_vec is similar to plot_cfield, except that there are two dx and dy matrices, instead of a single fv matrix.
The color of the heatmap bins reflects the magnitude of the four surrounding vectors.
3D VECTOR FIELDS
(plot_vec3)
plot_vec3 is similar to plot_vec.
Instead of two numeric matrices, we have three numeric 3d arrays, including dz.
Increasing along the first array dimension corresponds to increasing x values, increasing along the second array dimension corresponds to increasing y values, and increasing along the third array dimension corresponds to increasing z values.
Note that this function has had less testing than other plotting functions in this package.
3D COORDINATE SYSTEM
Currently, 3d plots use a diamond-like orthographic/dimetric projection, with a fixed viewing angle.
By default, (min (x), min (y) ) is at the bottom center. And increasing x values, run diagonally up-right, and increasing y value run diagonally up-left.
It's not possible to rotate the plots, but the x and y axis can be reversed.
In functions of two variables, the z coordinate represents the function value, and increasing z values run up.
RASTER-BASED HEATMAPS
Raster-based heatmaps, are rendered via the graphics::rasterImage function, so please refer to that function, for further technical details. The plot_dfield function sets the interpolate argument in rasterImage to false, and the plot_cfield functions sets it to true. However, it's possible that results may vary across graphics devices.
Note that this feature is relatively new, and has not had extensive testing.
Currently, only the first and last x and y values are used, in the rendering step.
(However, you still need the whole sequences, because the x and y values are used in other parts of the code).
Which means that, x and y, if provided, need to be equally-spaced.
There's no test for this, and plots with unequally-spaced x and y values will produce incorrect output.
Raster-based heatmaps are likely to render faster, which is especially noticeable for high resolution heatmaps.
PLOT COLORS
The color function (colf) can be any function that maps a numeric vector/matrix (as its first argument) to a character vector/matrix of R colors, however, I recommend using litmus objects. The litmus-fitting function (colff), is a function that maps a numeric vector (also, as its first argument) to a valid color function, however, I recommend using a function that returns a litmus object.
Assuming that colf, colff and colors are missing, a litmus-fitting function is determined by calling one of the "st" functions.
Refer to Standardized Palette Interface.
The default litmus-fitting function will be determined by the theme argument, if the theme argument is provided, otherwise, it will be determined by global options.
Then the litmus object is fitted to the input values (usually, fv), then the colors are computed from the litmus object.
Similar principles apply to top.color, side.color and iso.colors, except that the "st" functions returns the colors rather than litmus-fitting functions.
In some cases, it may be useful to wrap a predefined litmus-fitting function.
e.g. To use nonstandard hot and cold colors, wrap the hot.and.cold.fit function, then set the colff argument to the wrapper function.
Opaque color functions are preferable in 2d heatmaps.
ADDITIONAL NOTES
If using plot_bar, plot_surface or plot_trisurface to plot constant or near-constant values, set zlim, for a better result.
Noting that functions that are constant in theory, may produce non-constant values when computed via floating point arithmetic.
In applied mathematics and applied statistics, you may want to set z.axis=TRUE and ref.arrows=FALSE (in 3d plots), and xyrel="m" (in 2d plots).
The default for reference arrows, can also be set via global options.
Often, it may be useful to create wrapper functions, that set the default argument values, accordingly.
There's no guarantee that default contour lines will be suitable.
References
Refer to the vignette for an overview, references and better examples.
See Also
Functional Versions
Which take a function as their main argument.
litmus, litmus.fit
Predefined Litmus Objects, Predefined Litmus-Fitting Functions
With predefined colors.
Standardized Palette Interface, Global Options
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | #NOTE THAT THERE ARE MORE EXAMPLES IN:
#(1) THE PACKAGE VIGNETTE
#(2) THE HELP PAGE FOR FUNCTIONAL VERSIONS
#discretely-spaced example
fv <- matrix (1:100, 10, 10, byrow=TRUE)
plot_dfield (,,fv)
plot_bar (,,fv)
plot_matrix (,,fv)
#continuously-spaced example
x <- y <- seq (-15.5, 15.5,, 40)
fv <- outer (x, y, rotated.sinc)
plot_cfield (x, y, fv, fb=0, hcv=TRUE)
plot_surface (x, y, fv)
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.