Zonal analysis

class pylandstats.ZonalAnalysis(landscape, masks_arr, landscape_crs=None, landscape_transform=None, attribute_name=None, attribute_values=None, **kwargs)

__init__(landscape, masks_arr, landscape_crs=None, landscape_transform=None, attribute_name=None, attribute_values=None, **kwargs)

Parameters:

• landscape (Landscape or str, file object or pathlib.Path object) – A Landscape object or of string/file object/pathlib.Path object that will be passed as the landscape argument of Landscape.__init__
• masks_arr (list-like or np.ndarray) – A list-like of numpy arrays of shape (width, height), i.e., of the same shape as the landscape raster image. Each array will serve to mask the base landscape and define a region of study for which the metrics will be computed separately. The same information can also be provided as a single array of shape (num_masks, width, height).
• landscape_crs (dict, optional) – The coordinate reference system of the landscapes. Used to dump rasters in the compute_zonal_statistics_arr method. Ignored if the passed-in landscape is a path to a GeoTiff raster that already contains such information.
• landscape_transform (affine.Affine) – Transformation from pixel coordinates to coordinate reference system. Used to dump rasters in the compute_zonal_statistics_arr method. Ignored if the passed-in landscape is a path to a GeoTiff raster that already contains such information.
• attribute_name (str, optional) – Name of the attribute that will distinguish each landscape
• attribute_values (str, optional) – Values of the attribute that correspond to each of the landscapes

compute_class_metrics_df(metrics=None, classes=None, metrics_kws=None)

Computes the data frame of class-level metrics, which is multi-indexed by the class and attribute value.

Parameters:

• metrics (list-like, optional) – A list-like of strings with the names of the metrics that should be computed in the context of this analysis case
• classes (list-like, optional) – A list-like of ints or strings with the class values that should be considered in the context of this analysis case
• metrics_kws (dict, optional) – Dictionary mapping the keyword arguments (values) that should be passed to each metric method (key), e.g., to exclude the boundary from the computation of total_edge, metric_kws should map the string ‘total_edge’ (method name) to {‘count_boundary’: False}. The default empty dictionary will compute each metric according to FRAGSTATS defaults.

Returns:

df – Dataframe with the values computed for each class, attribute value (multi-index) and metric (columns)

Return type:

pd.DataFrame

compute_landscape_metrics_df(metrics=None, metrics_kws=None)

Computes the data frame of landscape-level metrics, which is indexed by the attribute value.

Parameters:

• metrics (list-like, optional) – A list-like of strings with the names of the metrics that should be computed. If None, all the implemented landscape-level metrics will be computed.
• metrics_kws (dict, optional) – Dictionary mapping the keyword arguments (values) that should be passed to each metric method (key), e.g., to exclude the boundary from the computation of total_edge, metric_kws should map the string ‘total_edge’ (method name) to {‘count_boundary’: False}. The default empty dictionary will compute each metric according to FRAGSTATS defaults.

Returns:

df – Dataframe with the values computed at the landscape level for each attribute value (index) and metric (columns)

Return type:

pd.DataFrame

compute_zonal_statistics_arr(metric, class_val=None, metric_kws=None, dst_filepath=None, custom_meta=None)

Compute the zonal statistics of a metric over an array with the form of the landscape

Parameters:

• metric (str) – A string indicating the name of the metric for which the zonal statistics will be computed
• class_val (int, optional) – If provided, the zonal statistics will be computed for the metric computed at the level of the corresponding class, otherwise they will be computed at the landscape level
• metric_kws (dict, optional) – Keyword arguments to be passed to the method that computes the metric (specified in the metric argument) for each landscape
• dst_filepath (str, file object or pathlib.Path object, optional) – Path to dump the zonal statistics raster. If not provided, no raster will be dumped.
• custom_meta (dict, optional) – Custom meta data for the output raster, consistent with the rasterio library.

Returns:

zonal_statistics_arr – Two-dimensional array with the computed zonal statistics

Return type:

ndarray

plot_landscapes(cmap=None, legend=True, subplots_kws=None, show_kws=None, subplots_adjust_kws=None)

Plots each landscape snapshot in a dedicated matplotlib axis by means of the Landscape.plot_landscape method of each instance

Parameters:

• cmap (str or ~matplotlib.colors.Colormap, optional) – A Colormap instance
• legend (bool, optional) – If True, display the legend of the land use/cover color codes
• subplots_kws (dict, default None) – Keyword arguments to be passed to plt.subplots
• show_kws (dict, default Nonte) – Keyword arguments to be passed to rasterio.plot.show
• subplots_adjust_kws (dict, default None) – Keyword arguments to be passed to plt.subplots_adjust

Returns:

fig – The figure with its corresponding plots drawn into its axes

Return type:

matplotlib.figure.Figure

plot_metric(metric, class_val=None, ax=None, metric_legend=True, metric_label=None, fmt='--o', plot_kws=None, subplots_kws=None, metric_kws=None)

Parameters:

• metric (str) – A string indicating the name of the metric to plot
• class_val (int, optional) – If provided, the metric will be plotted at the level of the corresponding class, otherwise it will be plotted at the landscape level
• ax (axis object, optional) – Plot in given axis; if None creates a new figure
• metric_legend (bool, default True) – Whether the metric label should be displayed within the plot (as label of the y-axis)
• metric_label (str, optional) – Label of the y-axis to be displayed if metric_legend is True. If the provided value is None, the label will be taken from the settings module
• fmt (str, default '--o') – A format string for plt.plot
• plot_kws (dict, default None) – Keyword arguments to be passed to plt.plot
• subplots_kws (dict, default None) – Keyword arguments to be passed to plt.subplots, only if no axis is given (through the ax argument)
• metric_kws (dict, default None) – Keyword arguments to be passed to the method that computes the metric (specified in the metric argument) for each landscape

Returns:

ax – Returns the Axes object with the plot drawn onto it

Return type:

axis object

class pylandstats.BufferAnalysis(landscape, base_mask, buffer_dists, buffer_rings=False, base_mask_crs=None, landscape_crs=None, landscape_transform=None)

__init__(landscape, base_mask, buffer_dists, buffer_rings=False, base_mask_crs=None, landscape_crs=None, landscape_transform=None)

Parameters:

• landscape (Landscape or str, file object or pathlib.Path object) – A Landscape object or of string/file object/pathlib.Path object that will be passed as the landscape argument of Landscape.__init__
• base_mask (shapely geometry or geopandas GeoSeries) – Geometry that will serve as a base mask to buffer around
• buffer_dists (list-like) – Buffer distances
• buffer_rings (bool, default False) – If False, each buffer zone will consist of the whole region that lies within the respective buffer distance around the base mask. If True, buffer zones will take the form of rings around the base mask.
• base_mask_crs (dict, optional) – The coordinate reference system of the base mask. Required if the base mask is a shapely geometry or a geopandas GeoSeries without the crs attribute set
• landscape_crs (dict, optional) – The coordinate reference system of the landscapes. Required if the passed-in landscapes are Landscape objects, ignored if they are paths to GeoTiff rasters that already contain such information.
• landscape_transform (affine.Affine) – Transformation from pixel coordinates to coordinate reference system. Required if the passed-in landscapes are Landscape objects, ignored if they are paths to GeoTiff rasters that already contain such information.

compute_class_metrics_df(metrics=None, classes=None, metrics_kws=None)

Computes the data frame of class-level metrics, which is multi-indexed by the class and buffer distance.

Parameters:

• metrics (list-like, optional) – A list-like of strings with the names of the metrics that should be computed in the context of this analysis case
• classes (list-like, optional) – A list-like of ints or strings with the class values that should be considered in the context of this analysis case
• metrics_kws (dict, optional) – Dictionary mapping the keyword arguments (values) that should be passed to each metric method (key), e.g., to exclude the boundary from the computation of total_edge, metric_kws should map the string ‘total_edge’ (method name) to {‘count_boundary’: False}. The default empty dictionary will compute each metric according to FRAGSTATS defaults.

Returns:

df – Dataframe with the values computed for each class, buffer distance (multi-index) and metric (columns)

Return type:

pd.DataFrame

compute_landscape_metrics_df(metrics=None, metrics_kws=None)

Computes the data frame of landscape-level metrics, which is indexed by the buffer distance.

Parameters:

• metrics (list-like, optional) – A list-like of strings with the names of the metrics that should be computed. If None, all the implemented landscape-level metrics will be computed.
• metrics_kws (dict, optional) – Dictionary mapping the keyword arguments (values) that should be passed to each metric method (key), e.g., to exclude the boundary from the computation of total_edge, metric_kws should map the string ‘total_edge’ (method name) to {‘count_boundary’: False}. The default empty dictionary will compute each metric according to FRAGSTATS defaults.

Returns:

df – Dataframe with the values computed at the landscape level for each buffer distance (index) and metric (columns)

Return type:

pd.DataFrame

compute_zonal_statistics_arr(metric, class_val=None, metric_kws=None, dst_filepath=None, custom_meta=None)

Compute the zonal statistics of a metric over an array with the form of the landscape

Parameters:

• metric (str) – A string indicating the name of the metric for which the zonal statistics will be computed
• class_val (int, optional) – If provided, the zonal statistics will be computed for the metric computed at the level of the corresponding class, otherwise they will be computed at the landscape level
• metric_kws (dict, optional) – Keyword arguments to be passed to the method that computes the metric (specified in the metric argument) for each landscape
• dst_filepath (str, file object or pathlib.Path object, optional) – Path to dump the zonal statistics raster. If not provided, no raster will be dumped.
• custom_meta (dict, optional) – Custom meta data for the output raster, consistent with the rasterio library.

Returns:

zonal_statistics_arr – Two-dimensional array with the computed zonal statistics

Return type:

ndarray

plot_landscapes(cmap=None, legend=True, subplots_kws=None, show_kws=None, subplots_adjust_kws=None)

Plots each landscape snapshot in a dedicated matplotlib axis by means of the Landscape.plot_landscape method of each instance

Parameters:

• cmap (str or ~matplotlib.colors.Colormap, optional) – A Colormap instance
• legend (bool, optional) – If True, display the legend of the land use/cover color codes
• subplots_kws (dict, default None) – Keyword arguments to be passed to plt.subplots
• show_kws (dict, default Nonte) – Keyword arguments to be passed to rasterio.plot.show
• subplots_adjust_kws (dict, default None) – Keyword arguments to be passed to plt.subplots_adjust

Returns:

fig – The figure with its corresponding plots drawn into its axes

Return type:

matplotlib.figure.Figure

plot_metric(metric, class_val=None, ax=None, metric_legend=True, metric_label=None, fmt='--o', plot_kws=None, subplots_kws=None, metric_kws=None)

Parameters:

• metric (str) – A string indicating the name of the metric to plot
• class_val (int, optional) – If provided, the metric will be plotted at the level of the corresponding class, otherwise it will be plotted at the landscape level
• ax (axis object, optional) – Plot in given axis; if None creates a new figure
• metric_legend (bool, default True) – Whether the metric label should be displayed within the plot (as label of the y-axis)
• metric_label (str, optional) – Label of the y-axis to be displayed if metric_legend is True. If the provided value is None, the label will be taken from the settings module
• fmt (str, default '--o') – A format string for plt.plot
• plot_kws (dict, default None) – Keyword arguments to be passed to plt.plot
• subplots_kws (dict, default None) – Keyword arguments to be passed to plt.subplots, only if no axis is given (through the ax argument)
• metric_kws (dict, default None) – Keyword arguments to be passed to the method that computes the metric (specified in the metric argument) for each landscape

Returns:

ax – Returns the Axes object with the plot drawn onto it

Return type:

axis object

class pylandstats.ZonalGridAnalysis(landscape, num_zone_rows=None, num_zone_cols=None, zone_pixel_width=None, zone_pixel_height=None, landscape_crs=None, landscape_transform=None)

__init__(landscape, num_zone_rows=None, num_zone_cols=None, zone_pixel_width=None, zone_pixel_height=None, landscape_crs=None, landscape_transform=None)

Parameters:

• landscape (Landscape or str, file object or pathlib.Path object) – A Landscape object or of string/file object/pathlib.Path object that will be passed as the landscape argument of Landscape.__init__
• num_zone_cols (num_zone_rows,) – The number of zone rows/columns into which the landscape will be separated. If the landscape dimensions and the desired zones do not divide evenly, the zones will be defined for the maximum subset (starting from the top, left corner) for which there is an even division. If not provided, then num_pixel_width/ num_pixel_height must be provided.
• num_pixel_height (num_pixel_width,) – The width/height of each zone (in pixels). If the landscape dimensions and the desired zones do not divide evenly, the zones will be defined for the maximum subset (starting from the top, left corner) for which there is an even division. If not provided, then num_zone_rows/num_zone_cols must be provided.
• landscape_crs (dict, optional) – The coordinate reference system of the landscapes. Required to reconstruct the zonal statistics rasters if the passed-in landscapes are Landscape objects, ignored if they are paths to GeoTiff rasters that already contain such information.
• landscape_transform (affine.Affine) – Transformation from pixel coordinates to coordinate reference system. Required if the passed-in landscapes are Landscape objects, ignored if they are paths to GeoTiff rasters that already contain such information.

compute_class_metrics_df(metrics=None, classes=None, metrics_kws=None)

Computes the data frame of class-level metrics, which is multi-indexed by the class and attribute value.

Parameters:

• metrics (list-like, optional) – A list-like of strings with the names of the metrics that should be computed in the context of this analysis case
• classes (list-like, optional) – A list-like of ints or strings with the class values that should be considered in the context of this analysis case
• metrics_kws (dict, optional) – Dictionary mapping the keyword arguments (values) that should be passed to each metric method (key), e.g., to exclude the boundary from the computation of total_edge, metric_kws should map the string ‘total_edge’ (method name) to {‘count_boundary’: False}. The default empty dictionary will compute each metric according to FRAGSTATS defaults.

Returns:

df – Dataframe with the values computed for each class, attribute value (multi-index) and metric (columns)

Return type:

pd.DataFrame

compute_landscape_metrics_df(metrics=None, metrics_kws=None)

Computes the data frame of landscape-level metrics, which is indexed by the attribute value.

Parameters:

• metrics (list-like, optional) – A list-like of strings with the names of the metrics that should be computed. If None, all the implemented landscape-level metrics will be computed.
• metrics_kws (dict, optional) – Dictionary mapping the keyword arguments (values) that should be passed to each metric method (key), e.g., to exclude the boundary from the computation of total_edge, metric_kws should map the string ‘total_edge’ (method name) to {‘count_boundary’: False}. The default empty dictionary will compute each metric according to FRAGSTATS defaults.

Returns:

df – Dataframe with the values computed at the landscape level for each attribute value (index) and metric (columns)

Return type:

pd.DataFrame

compute_zonal_statistics_arr(metric, class_val=None, metric_kws=None, dst_filepath=None, custom_meta=None)

Compute the zonal statistics of a metric over an array with the form of the landscape

Parameters:

• metric (str) – A string indicating the name of the metric for which the zonal statistics will be computed
• class_val (int, optional) – If provided, the zonal statistics will be computed for the metric computed at the level of the corresponding class, otherwise they will be computed at the landscape level
• metric_kws (dict, optional) – Keyword arguments to be passed to the method that computes the metric (specified in the metric argument) for each landscape
• dst_filepath (str, file object or pathlib.Path object, optional) – Path to dump the zonal statistics raster. If not provided, no raster will be dumped.
• custom_meta (dict, optional) – Custom meta data for the output raster, consistent with the rasterio library.

Returns:

zonal_statistics_arr – Two-dimensional array with the computed zonal statistics

Return type:

ndarray

plot_landscapes(cmap=None, ax=None, figsize=None, **show_kws)

Plots the spatial distribution of the landscape zones

Parameters:

• cmap (str or ~matplotlib.colors.Colormap, optional) – A Colormap instance
• ax (axis object, optional) – Plot in given axis; if None creates a new figure
• figsize (tuple of two numeric types, optional) – Size of the figure to create. Ignored if axis ax is provided
• **show_kws (optional) – Keyword arguments to be passed to rasterio.plot.show

Returns:

ax – axis with plot data

Return type:

matplotlib axis