r.random.surface(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💖 r.random.surface 💖

okay bestie, welcome to the manual page for r.random.surface(1grass) — she lives in the GRASS User's Manual and she MAKES random surfaces with spatial dependence. iconic behavior honestly.

✨ NAME ✨

r.random.surface — generates random surface(s) with spatial dependence. that's the whole job. that's the vibe. 🦋

🌈 KEYWORDS 🌈

raster, surface, random

🎀 SYNOPSIS 🎀

r.random.surface
r.random.surface --help
r.random.surface [-u] output=string[,string,...]  [distance=float]
[exponent=float]   [flat=float]   [seed=integer]   [high=integer]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

⭐ Flags ⭐

  • -u — uniformly distributed cell values. yes queen, uniform, not normal. 💅
  • --overwrite — allow output files to overwrite existing files (let her eat, respectfully)
  • --help — print usage summary
  • --verbose — verbose module output (she will NOT stop talking)
  • --quiet — quiet module output (she will say nothing at all)
  • --ui — force launching GUI dialog

🌸 Parameters 🌸

  • output=string[,string,...] — [required] name for output raster map(s)
  • distance=float — maximum distance of spatial correlation (value >= 0.0). default: 0.0
  • exponent=float — distance decay exponent (value > 0.0). default: 1.0
  • flat=float — distance filter remains flat before beginning exponent. default: 0.0
  • seed=integer — seed value for the random number generator. using the same seed ensures identical results, while a randomly generated seed produces different outcomes in each run.
  • high=integer — maximum cell value of distribution. default: 255

💜 DESCRIPTION 💜

so r.random.surface generates a spatially dependent random surface, periodt. the random surface is made of values that represent the deviation from the mean of the initial random values that drive the algorithm. those initial random values? they're independent Gaussian random deviates with a mean of 0 and a standard deviation of 1. 💫

the initial values get spread over each output map using filter(s) of diameter distance. the influence of each random value on nearby cells is determined by a distance decay function based on exponent. and if multiple filters are passed over the output maps, each filter is given a weight based on the weight inputs. the resulting random surface can have any mean and variance, but the theoretical mean of an infinitely large map is 0.0 and a variance of 1.0. the full description of the algorithm lives in the NOTES section, so keep scrolling bestie.

the random surfaces generated are made of floating point numbers, and they get saved in the category description files of the output map(s). cell values are uniformly or normally distributed between 1 and high values inclusive — that's determined by whether you used the -u flag or not. the category names tell you the average floating point value and the range of floating point values that each cell value represents. so thoughtful of her. 🫶

fun fact: r.random.surface's original goal is to generate random fields for spatial error modeling. a whole procedure to use r.random.surface in spatial error modeling is down in the NOTES section. iykyk.

🦋 Detailed parameter description 🦋

output

Random surface(s). the cell values are a random distribution between the low and high values inclusive. the category values of the output map(s) are in the form #.# #.# to #.# where each #.# is a floating point number. the first number is the average of the random values the cell value represents. the other two numbers are the range of random values for that cell value. the average mean value of generated output map(s) is 0. the average variance of map(s) generated is 1. the random values represent the standard deviation from the mean of that random surface. no cap. ✨

distance

distance determines the spatial dependence of the output map(s). the distance value indicates the minimum distance at which two map cells have no relationship to each other. a distance value of 0.0 means there is no spatial dependence — i.e., adjacent cell values have no relationship to each other, they're basically strangers. as the distance value increases, adjacent cell values will have values closer to each other. but the range and distribution of cell values over the output map(s) will remain the same. visually? the clumps of lower and higher values get larger as distance increases. 👑

if multiple values are given, each output map will have multiple filters, one for each set of distance, exponent, and weight values.

exponent

exponent determines the distance decay exponent for a particular filter. the exponent value(s) have the property of determining the texture of the random surface. texture will decrease as the exponent value(s) get closer to 1.0. normally, exponent will be 1.0 or less. if there are no exponent values given, each filter will be given an exponent value of 1.0. if there is at least one exponent value given, there must be one exponent value for each distance value. match the count, bestie, it's giving accountability. 😤

flat

flat determines the distance at which the filter. (that's genuinely the whole sentence the page gives us — she said what she said. 🙈)

weight

weight determines the relative importance of each filter. for example, if there were two filters driving the algorithm and weight=1.0, 2.0 was given in the command line: the second filter would be twice as important as the first filter. main character energy for filter #2 honestly. if no weight values are given, each filter will be just as important as the other filters defining the random field. and if weight values exist, there must be a weight value for each filter of the random field. fairness first. 💅

high

specifies the high end of the range of cell values in the output map(s). specifying a very large high value will minimize the errors caused by the random surface's discretization. the word "errors" is in quotes because errors in discretization are often going to cancel each other out and the spatial statistics are far more sensitive to the initial independent random deviates than any potential discretization errors. so like. breathe. 🌸

seed

specifies the random seed(s), one for each map, that r.random.surface will use to generate the initial set of random values that the resulting map is based on. if the random seed is not given, r.random.surface will get a seed from the process ID number. 🎲

🔥 NOTES 🔥

while most literature uses the term random field instead of random surface, this algorithm always generates a surface. thus, its use of random surface. she's committed to the bit. 💖

r.random.surface builds the random surface using a filter algorithm smoothing a map of independent random deviates. the size of the filter is determined by the largest distance of spatial dependence. the shape of the filter is determined by the distance decay exponent(s), and the various weights if different sets of spatial parameters are used.

the map of independent random deviates will be as large as the current region PLUS the extent of the filter. this will eliminate edge effects caused by the reduction of degrees of freedom. and the map of independent random deviates will ignore the current mask for the same reason. yep, ignoring the mask, on purpose, for science. 🧚

one of the most important uses for r.random.surface is to determine how the error inherent in raster maps might effect the analyses done with those maps. that's the whole point, bestie.

🌟 EXAMPLE 🌟

generate a random surface (using extent of North Carolina sample dataset):

g.region raster=elevation res=100 -p
r.surf.random output=randomsurf min=10 max=100
# verify distribution
r.univar -e map=randomsurf

Figure: Random surface example (min: 10; max: 100)

with the histogram tool the cell values versus count can be shown.

Figure: Histogram of random surface example (min: 10; max: 100)

📚 REFERENCES 📚

Random Field Software for GRASS by Chuck Ehlschlaeger

as part of my dissertation, i put together several programs that help GRASS (4.1 and beyond) develop uncertainty models of spatial data. i hope you find it useful and dependable. the following papers might clarify their use:

  • Ehlschlaeger, C.R., Shortridge, A.M., Goodchild, M.F., 1997. Visualizing spatial data uncertainty using animation. Computers & Geosciences 23, 387-395. doi:10.1016/S0098-3004(97)00005-8
  • Ehlschlaeger, C.R., Shortridge, A.M., 1996. Modeling Uncertainty in Elevation Data for Geographical Analysis. Proceedings of the 7th International Symposium on Spatial Data Handling, Delft, Netherlands, August 1996.
  • Ehlschlaeger, C.R., Goodchild, M.F., 1994. Dealing with Uncertainty in Categorical Coverage Maps: Defining, Visualizing, and Managing Data Errors. Proceedings, Workshop on Geographic Information Systems at the Conference on Information and Knowledge Management, Gaithersburg MD, 1994.
  • Ehlschlaeger, C.R., Goodchild, M.F., 1994. Uncertainty in Spatial Data: Defining, Visualizing, and Managing Data Errors. Proceedings, GIS/LIS'94, pp. 246-253, Phoenix AZ, 1994.

👀 SEE ALSO 👀

r.random, r.random.cells, r.mapcalc, r.surf.random

👑 AUTHORS 👑

Charles Ehlschlaeger, Michael Goodchild, and Chih-chang Lin; National Center for Geographic Information and Analysis, University of California, Santa Barbara

💾 SOURCE CODE 💾

Available at: r.random.surface source code (history)

Latest change: Friday Apr 17 01:04:26 2026 in commit: 32a143358df26b2e518b03c7e0d79541e8d1e5b1

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

and that's the tea, bestie 🫶 this whole page was served to you fresh from GRASS 8.5.0, r.random.surface(1grass), so go make some spatially dependent chaos and slay ✨💅🌈

📦 where this page comes from