Skip to content

r.stats.quantile

Compute category quantiles using two passes.

r.stats.quantile [-rpt] base=name cover=name [quantiles=integer] [percentiles=float [,float,...]] [bins=integer] [output=name [,name,...]] [file=name] [separator=character] format=name [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.stats.quantile base=name cover=name format=plain

grass.script.parse_command("r.stats.quantile", base, cover, quantiles=None, percentiles=50, bins=1000, output=None, file=None, separator=None, format="plain", flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.parse_command("r.stats.quantile", base="name", cover="name", format="json")

Parameters

base=name [required]
    Name of base raster map
cover=name [required]
    Name of cover raster map
quantiles=integer
    Number of quantiles
percentiles=float [,float,...]
    List of percentiles
    Default: 50
bins=integer
    Number of bins to use
    Default: 1000
output=name [,name,...]
    Resultant raster map(s)
file=name
    Name for output file (if omitted or "-" output to stdout)
separator=character
    Field separator
    Special characters: pipe, comma, space, tab, newline
format=name [required]
    Output format
    Allowed values: plain, csv, json
    Default: plain
    plain: Human readable text output
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)
-r
    Create reclass map with statistics as category labels
-p
    Do not create output maps; just print statistics
-t
    Print statistics in table format [deprecated]
    This flag is deprecated and will be removed in a future release. Use format=csv instead.
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

base : str, required
    Name of base raster map
    Used as: input, raster, name
cover : str, required
    Name of cover raster map
    Used as: input, raster, name
quantiles : int, optional
    Number of quantiles
percentiles : float | list[float] | str, optional
    List of percentiles
    Default: 50
bins : int, optional
    Number of bins to use
    Default: 1000
output : str | list[str], optional
    Resultant raster map(s)
    Used as: output, raster, name
file : str, optional
    Name for output file (if omitted or "-" output to stdout)
    Used as: output, file, name
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
format : str, required
    Output format
    Used as: name
    Allowed values: plain, csv, json
    plain: Human readable text output
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)
    Default: plain
flags : str, optional
    Allowed values: r, p, t
    r
        Create reclass map with statistics as category labels
    p
        Do not create output maps; just print statistics
    t
        Print statistics in table format [deprecated]
        This flag is deprecated and will be removed in a future release. Use format=csv instead.
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.stats.quantile is a tool to analyse exploratory statistics of a floating-point "cover layer" according to how it intersects with objects in a "base layer". It provides quantile calculations as selected "zonal statistics".

NOTES

r.stats.quantile is intended to be a partial replacement for r.statistics, with support for floating-point cover maps. It provides quantile calculations, which are absent from r.stats.zonal.

Quantiles are calculated following algorithm 7 from Hyndman and Fan (1996), which is also the default in R and numpy.

The t flag has been deprecated and replaced by the format=csv option.

The default separator will be : to maintain backward compatibility; however, if format=csv is given, then the default separator will be comma.

EXAMPLE

In this example, the raster polygon map zipcodes in the North Carolina sample dataset is used to calculate quantile raster statistics using the elevation raster map:

g.region raster=zipcodes -p

# print quantiles
r.stats.quantile base=zipcodes cover=elevation quantiles=3 -p
27511:0:33.333333:134.717392
27511:1:66.666667:143.985723
27513:0:33.333333:140.669993
27513:1:66.666667:146.279449
27518:0:33.333333:115.140101
27518:1:66.666667:129.893723
[...]

# write out percentile raster maps
r.stats.quantile base=zipcodes cover=elevation percentiles=25,50,75 \
  output=zipcodes_elev_q25,zipcodes_elev_q50,zipcodes_elev_q75

Using the JSON format option and Python to parse the output:

import grass.script as gs

data = gs.parse_command(
    "r.stats.quantile", base="zipcodes", cover="elevation", flags="p", format="json"
)
print(data[0])

Possible output:

{'category': 27511, 'percentiles': [{'percentile': 50, 'value': 139.62598419189453}]}

The whole JSON may look like this:

[
 {
  "category": 27511,
  "percentiles": [
   {
    "percentile": 50,
    "value": 139.62598419189453
   }
  ]
 },
 {
  "category": 27513,
  "percentiles": [
   {
    "percentile": 50,
    "value": 143.7049102783203
   }
  ]
 },
 {
  "category": 27518,
  "percentiles": [
   {
    "percentile": 50,
    "value": 122.53437805175781
   }
  ]
 }
]

REFERENCES

SEE ALSO

r.quantile, r.stats.zonal, r.statistics

AUTHORS

Glynn Clements
Markus Metz

SOURCE CODE

Available at: r.stats.quantile source code (history)
Latest change: Wednesday Jul 02 22:57:11 2025 in commit 170d644