Skip to content

v.vect.stats.multi

Computes isochrones from collection point in a sewershed

v.vect.stats.multi points=name areas=name [type=string [,string,...]] [points_layer=string] [points_cats=range] [points_where=sql_query] [areas_layer=string] [areas_cats=range] [areas_where=sql_query] method=string [,string,...] [points_columns=name [,name,...]] count_column=name [stats_columns=name] [--verbose] [--quiet] [--qq] [--ui]

Example:

v.vect.stats.multi points=name areas=name method=string count_column=name

grass.script.run_command("v.vect.stats.multi", points, areas, type="point", points_layer="1", points_cats=None, points_where=None, areas_layer="1", areas_cats=None, areas_where=None, method, points_columns=None, count_column, stats_columns=None, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("v.vect.stats.multi", points="name", areas="name", method="string", count_column="name")

Parameters

points=name [required]
    Name of existing vector map with points
    Vector map with one or more attributes
areas=name [required]
    Name of existing vector map with points
    Vector map with one or more attributes
type=string [,string,...]
    Input feature type
    Allowed values: point, centroid
    Default: point
points_layer=string
    Layer number for points map
    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
points_cats=range
    Category values for points map
    Example: 1,3,7-9,13
points_where=sql_query
    WHERE conditions of SQL statement without 'where' keyword for points map
    Example: income < 1000 and population >= 10000
areas_layer=string
    Layer number for area map
    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
areas_cats=range
    Category values for area map
    Example: 1,3,7-9,13
areas_where=sql_query
    WHERE conditions of SQL statement without 'where' keyword for area map
    Example: income < 1000 and population >= 10000
method=string [,string,...] [required]
    Method for aggregate statistics
    Allowed values: sum, average, median, mode, minimum, maximum, range, stddev, variance, diversity
points_columns=name [,name,...]
    Column names of points map to compute statistics from
    Defaults to all numeric columns. The specified columns must be numeric
count_column=name [required]
    Column name to upload points count
    Column to hold points count, must be of type integer, will be created if not existing
stats_columns=name
    Column names to upload statistics (generated by default)
    By default, generated as source column name underscore method name
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

points : str, required
    Name of existing vector map with points
    Vector map with one or more attributes
    Used as: input, vector, name
areas : str, required
    Name of existing vector map with points
    Vector map with one or more attributes
    Used as: input, vector, name
type : str | list[str], optional
    Input feature type
    Allowed values: point, centroid
    Default: point
points_layer : str, optional
    Layer number for points map
    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.
    Used as: input, layer
    Default: 1
points_cats : str, optional
    Category values for points map
    Example: 1,3,7-9,13
    Used as: input, cats, range
points_where : str, optional
    WHERE conditions of SQL statement without 'where' keyword for points map
    Example: income < 1000 and population >= 10000
    Used as: input, sql_query, sql_query
areas_layer : str, optional
    Layer number for area map
    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.
    Used as: input, layer
    Default: 1
areas_cats : str, optional
    Category values for area map
    Example: 1,3,7-9,13
    Used as: input, cats, range
areas_where : str, optional
    WHERE conditions of SQL statement without 'where' keyword for area map
    Example: income < 1000 and population >= 10000
    Used as: input, sql_query, sql_query
method : str | list[str], required
    Method for aggregate statistics
    Allowed values: sum, average, median, mode, minimum, maximum, range, stddev, variance, diversity
points_columns : str | list[str], optional
    Column names of points map to compute statistics from
    Defaults to all numeric columns. The specified columns must be numeric
    Used as: input, dbcolumn, name
count_column : str, required
    Column name to upload points count
    Column to hold points count, must be of type integer, will be created if not existing
    Used as: input, dbcolumn, name
stats_columns : str, optional
    Column names to upload statistics (generated by default)
    By default, generated as source column name underscore method name
    Used as: input, dbcolumn, name
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

v.vect.stats.multi computes attribute statistics of points in vector map points falling into each area in vector map areas. The results are uploaded to the attribute table of the vector map areas.

By default, statistics are computed for all integer and floating point attributes (columns), e.g., DOUBLE PRECISION and INTEGER columns will be used, but TEXT will not. Specific (multiple) columns can be selected using points_columns. The type of the selected columns again need to be some integer and floating point type.

Statistical methods

Using numeric attribute values of all points falling into a given area, a new value is determined with the selected method.

v.vect.stats can perform the following operations:

  • sum
    The sum of values.
  • average
    The average value of all point attributes (sum / count).
  • median
    The value found half-way through a list of the attribute values, when these are ranged in numerical order.
  • mode
    The most frequently occurring value.
  • minimum
    The minimum observed value.
  • maximum
    The maximum observed value.
  • range
    The range of the observed values.
  • stddev
    The statistical standard deviation of the attribute values.
  • variance
    The statistical variance of the attribute values.
  • diversity
    The number of different attribute values.

The count (number of points) is always computed and stored in count_column.

Column names

The stats_columns can be used to provide custom column names instead of the generated ones. If provided, the number of columns must be number of points_columns times number of methods requested (in method). The order of names is that first come all statistics for one column, then all statistics for another column, etc. If only one statistical method is requested, then it is simply one column from points_columns after another. Note that the number of names stats_columns is checked against the number of columns that will be created. However, whether the names correspond to what is being computed for the columns cannot be checked, so, for example, providing names for one statistic for all columns, followed by another statistic, etc. will result in a mismatch between column names and what was actually computed.

NOTES

This module is using v.vect.stats underneath to do the actual statistical computations. See v.vect.stats for details about behavior in special cases.

EXAMPLES

ZIP codes and POIs

The following example is using points of interest (POIs) and ZIP code areas vector from the basic North Carolina sample database: Create a copy of ZIP code areas in the current mapset to allow for adding attributes (using a name which expresses what you will add later on):

g.copy vector=zipcodes@PERMANENT,zipcodes_with_poi_stats

Compute minimum and maximum for each numerical colum in the attribute table of points of interest:

v.vect.stats.multi points=points_of_interest areas=zipcodes_with_poi_stats method=minimum,maximum count_column=point_count

Use v.info to see all the newly created columns:

v.info -c map=zipcodes_with_poi_stats

Use v.db.select (or GUI) to examine the values (you can see subset of the data by selecting only specific columns or using the where cause to get only certain rows):

v.db.select map=zipcodes_with_poi_stats

Each of the new columns separately can be assigned color using v.colors:

v.colors map=zipcodes_with_poi_stats use=attr column=elev_m_maximum color=viridis rgb_column=elev_m_maximum_color

Specifying columns by name

Assuming a similar setup as in the previous example (g.copy used to create a copy in the current mapset), you can ask for statistics only on columns PUMPERS, TANKER, and AERIAL and specify the names of new columns using: (wrapping a long line here using Bash-like syntax):

v.vect.stats.multi points=firestations areas=zipcodes method=sum \
    count_column=count point_columns=PUMPERS,TANKER,AERIAL \
    stats_columns=all_pumpers,all_tankers,all_aerials

SEE ALSO

  • v.vect.stats for printing information instead of storing it in the attribute table,
  • v.what.rast.multi for querying multiple raster maps by one vector points map,
  • g.copy for creating a copy of vector map to update (to preserve the original data given that this module performs a large automated operation).

AUTHOR

Vaclav Petras, NCSU Center for Geospatial Analytics

SOURCE CODE

Available at: v.vect.stats.multi source code (history)
Latest change: Friday Feb 21 10:10:05 2025 in commit 7d78fe3