r3.scatterplot - GRASS GIS manual (2024)

NAME

r3.scatterplot - Creates a scatter plot of 3D raster maps
Creates a scatter plot of two or more 3D raster maps as a vector map

KEYWORDS

raster3d, statistics, diagram, correlation, scatter plot, vector, voxel

SYNOPSIS

r3.scatterplot

r3.scatterplot --help

r3.scatterplot [-wfsub] input=name[,name,...] output=name [z_raster=name] [color_raster=name] [xscale=float] [yscale=float] [zscale=float] [position=east,north] [spacing=float] [vector_mask=name] [mask_layer=string] [mask_cats=range] [mask_where=sql_query] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-w: Place into the current region south-west corner; The output coordinates will not represent the original values
-f: Automatically offset each scatter plot; The output coordinates will not represent the original values
-s: Put points into a single layer; Even with multiple rasters, put all points into a single layer
-u: Invert mask
-b: Do not build topology; Advantageous when handling a large number of points
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

input=name[,name,...][required]: Name of input 3D raster map(s)
output=name[required]: Name for output vector map
z_raster=name: Name of input 3D raster map to define Z coordinates
color_raster=name: Name of input 3D raster map to define category and color
xscale=float: Scale to apply to X axis; Default: 1.0
yscale=float: Scale to apply to Y axis; Default: 1.0
zscale=float: Scale to apply to Z axis; Default: 1.0
position=east,north: Place to the given coordinates; The output coordinates will not represent the original values
spacing=float: Spacing between scatter plots; Applied when automatic offset is used
vector_mask=name: Areas to use in the scatter plots; Name of vector map with areas from where the scatter plot should be generated
mask_layer=string: Layer number or name for vector mask; Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.; Default: 1
mask_cats=range: Category values for vector mask; Example: 1,3,7-9,13
mask_where=sql_query: WHERE conditions for the vector mask; Example: income < 1000 and population >= 10000

DESCRIPTION
- Multiple variables
- Layout
NOTES
EXAMPLES
- Example with generated data
SEE ALSO
AUTHOR

DESCRIPTION

The r3.scatterplot module takes 3D raster maps and createsa scatter plot which is a vector map and where individual points inthe scatter plot are vector points. As with any scatter plot the Xcoordinates of the points represent values from the first raster mapand the Y coordinates represent values from the second raster map.Consequently, the vector map is placed in the combined value space ofthe original raster maps and its geographic position should be ignored.Typically, it is necessary to zoom or to change computational in orderto view the scatter plot or to perform further computations on the result.

Multiple variables

If more than two raster maps are provided to the input option,r3.scatterplot creates a scatter plot for each unique pairof input maps. For example, if A, B, C, and D are the inputs,r3.scatterplot creates scatter plots for A and B, A and C,A and D, B and C, B and D, and finally C and D. Each pair is part ofdifferent vector map layer. r3.scatterplot provides textualoutput which specifies the pairs and associated layers.

A 3D scatter plot can be generated when the z_raster option isprovided. A third variable is added to each scatter plot and each pointhas Z coordinate which represents this third variable.

Each point can also have a color based on an additional variablebased on the values from color_raster. Values from a raster arestored as categories, i.e. floating point values are truncated tointegers, and a color table based on the input raster color table isassigned to the vector map.

The z_raster and color_raster can be the same. This can helpwith understanding the 3D scatter plot and makes the third variablevisible in 2D as well.When z_raster and color_raster are the same, total of fourvariables are associated with one point.

Figure: One scatter plot of two variables (left), the same scatter plot but with color showing third variable (middle), again the same scatter plot in 3D where Z represents a third variable (right).

Figure: One scatter plot in with one variable as Z coordinate and another variable as color (two rotated views).

Layout

When working only with variable, X axis represents the first oneand Y axis the second one. With more than one variable, the individualscatter plots for individual pairs of variables are at the sameplace. In this case, the coordinates show the actual values of thevariables. Each scatter plot is placed into a separate layer ofthe output vector map.

Figure: Three overlapping scatter plots of three variables A, B, and C. Individual scatter plots are distinguished by color. The colors can be obtained using d.vect layer=-1 -c.

If visualization is more important than preserving the actual values,the -s flag can be used. This will place the scatter plots nextto each other separated by values provided using spacing option.

NOTES

The resulting vector will have as many points as there is 3D rastercells in the current computational region. It might be appropriate touse coarser resolution for the scatter plot than for the othercomputations. However, note that the some values will be skippedwhich may lead, e.g. to missing some outliers.

The color_raster input is expected to be categorical rasteror have values which won't loose anything when converted from floatingpoint to integer. This is because vector categories are used to storethe color_raster values and carry association with the color.

The visualization of the output vector map has potentially the sameissue as visualization of any vector with many points. The pointscover each other and above certain density of points, it is not possibleto compare relative density in the scatter plot. Furthermore, if colorsare associated with the points, the colors of points rendered last arethose which are visible, not actually showing the prevailing color(value). The modules v.mkgrid andv.vect.stats can be used toovercome this issue.

EXAMPLES

Example with generated data

Set the computational region for generating data and subsequentanalysis:

g.region s=0 n=100 w=0 e=100 b=0 t=50 res=10 res3=10 tbres=1 -p3

Generate data using raster algebra:

r3.mapcalc "A = if(depth() < ndepths()/ 2, row()+col()+depth(), col())" -sr3.mapcalc "B = if(row() < nrows()/2, rand(0, nrows()) + col() + depth(), depth() + rand(0, nrows()))" -sr3.mapcalc "C = if(col() < ncols()/3, row() + depth(), rand(0, ncols()))" -sr3.mapcalc "D = depth()"

Create a scatter plot of correlations between A and B.Use C for the Z axes (height) and D for the color.

r3.scatterplot input=A,B output=scatterplot z_raster=C color_raster=D

Figure: 2D scatter plot showing third variable as color and 3D scatter plot showing third variable as color and fourth variable on Z axis which uncovers another group of values not visible from the 2D scatter plot

AUTHOR

Vaclav Petras, NCSU GeoForAll Lab

SOURCE CODE

Available at: r3.scatterplot source code (history)

Latest change: Monday Jan 30 19:49:11 2023 in commit: 5fb6b1a969e72db28df78483d3360b15a17f0c68