Spatiotemporal zonal analysis

class pylandstats.SpatioTemporalZonalAnalysis(landscape_filepaths, zones, *, zone_index=None, zone_nodata=None, dates=None, neighborhood_rule=None)

Spatio-temporal zonal analysis.

__init__(landscape_filepaths, zones, *, zone_index=None, zone_nodata=None, dates=None, neighborhood_rule=None)

Initialize the spatio-temporal zonal analysis.

Parameters:

• landscape_filepaths (list-like) – A list-like of strings/file-like/pathlib.Path objects so that each is passed as the landscape argument of Landscape.__init__.

• zones (geopandas.GeoSeries, geopandas.GeoDataFrame, list-like, str, file-like object, pathlib.Path object, numpy.ndarray, optional) –

  This can either be:

  • A geopandas geo-series or geo-data frame.

  • A list-like of shapely geometries, in the CRS of the landscape.

  • A filename or URL, a file-like object opened in binary (‘rb’) mode, or a Path object that will be passed to geopandas.read_file.

  • A numpy array of the same shape as the landscape raster image, where each zone is labelled by a unique integer value. The values will be used to identify the zones (i.e., as index) - unless a different zone_index is provided.

• zone_index (list-like or str, optional) –

  Index used to identify zones (i.e., index of the metrics data frames). This can either be:

  • A list-like of index labels that will be positionally mapped to each zone.

  • A str with the name of a column only when zones is a geo-data frame or a geo-data frame file, e.g., a shapefile.

• zone_nodata (numeric, optional, default 0) – Value of the zones array that corresponds to no data. Only considered if zones is a numpy array of integer types.

• dates (list-like, optional) – A list-like of ints or strings that label the date of each snapshot of landscapes (for DataFrame indices and plot labels).

• neighborhood_rule ({'8', '4'}, optional) – Neighborhood rule to determine patch adjacencies, i.e: ‘8’ (queen’s case/Moore neighborhood) or ‘4’ (rook’s case/Von Neumann neighborhood). Ignored if landscape is a Landscape instance. If no value is provided, the default value set in settings.DEFAULT_NEIGHBORHOOD_RULE will be taken.

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

Compute the data frame of class-level metrics, which is multi-indexed by the zone, class and date.

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.

• fillna (bool, optional) – Whether NaN values representing landscapes with no occurrences of patches of the provided class should be replaced by zero when appropriate, e.g., area and edge metrics (no ocurrences mean zero area/edge). If the provided value is None (default), the value will be taken from settings.CLASS_METRICS_DF_FILLNA.

Returns:

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

Return type:

pandas.DataFrame

compute_landscape_metrics_df(*, metrics=None, metrics_kws=None)

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

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, date (multi-index) and metric (columns).

Return type:

pandas.DataFrame

compute_zonal_statistics_gdf(metrics, *, class_val=None, metrics_kws=None)

Compute the zonal statistics geo-data frame over the landscape raster.

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 class-level metrics will be computed.

• class_val (int, optional) – If provided, the zonal statistics will be computed at the level of the corresponding class, otherwise they will be computed at the landscape level.

• 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}. If None, each metric will be computed according to FRAGSTATS defaults.

Returns:

zonal_statistics_gdf – Geo-data frame with the computed zonal statistics.

Return type:

geopandas.GeoDataFrame

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

Plot each landscape snapshot in a dedicated matplotlib axis.

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 matplotlib.pyplot.subplots.

• show_kws (dict, default None) – Keyword arguments to be passed to rasterio.plot.show.

• subplots_adjust_kws (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.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, zone_legend=True, fmt='--o', plot_kws=None, subplots_kws=None, metric_kws=None)

Plot the time series of the metric accross zones.

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.

• zone_legend (bool, default True) – Whether a legend linking each plotted line to a zone should be displayed within the plot.

• fmt (str, default '--o') – A format string for matplotlib.pyplot.plot.

• plot_kws (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.plot.

• subplots_kws (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.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:

matplotlib.axes.Axes

class pylandstats.SpatioTemporalBufferAnalysis(landscape_filepaths, base_geom, buffer_dists, *, buffer_rings=False, base_geom_crs=None, dates=None, neighborhood_rule=None)

Spatio-temporal buffer analysis around a feature of interest.

__init__(landscape_filepaths, base_geom, buffer_dists, *, buffer_rings=False, base_geom_crs=None, dates=None, neighborhood_rule=None)

Initialize the spatio-temporal buffer analysis.

Parameters:

• landscape_filepaths (list-like) – A list-like of strings/file-like/pathlib.Path objects so that each is passed as the landscape argument of Landscape.__init__.

• base_geom (shapely geometry, geopandas.GeoSeries or geopandas.GeoDataFrame) – Geometry that will serve as a base to buffer around.

• buffer_dists (list-like) – Buffer distances, in units of the landscape CRS.

• 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 geometry. If True, buffer zones will take the form of rings around the base geometry.

• base_geom_crs (str, dict or pyproj.CRS, optional) – The coordinate reference system of the base geometry. Required if the base geometry is a shapely geometry or a geopandas GeoSeries without the crs attribute set.

• dates (list-like, optional) – A list-like of ints or strings that label the date of each snapshot of landscapes (for DataFrame indices and plot labels).

• neighborhood_rule ({'8', '4'}, optional) – Neighborhood rule to determine patch adjacencies, i.e: ‘8’ (queen’s case/Moore neighborhood) or ‘4’ (rook’s case/Von Neumann neighborhood). Ignored if the passed-in landscapes are Landscape instances. If no value is provided and the passed-in landscapes are file-like objects or paths, the default value set in settings.DEFAULT_NEIGHBORHOOD_RULE will be taken.

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

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

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.

• fillna (bool, optional) – Whether NaN values representing landscapes with no occurrences of patches of the provided class should be replaced by zero when appropriate, e.g., area and edge metrics (no ocurrences mean zero area/edge). If the provided value is None (default), the value will be taken from settings.CLASS_METRICS_DF_FILLNA.

Returns:

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

Return type:

pandas.DataFrame

compute_landscape_metrics_df(*, metrics=None, metrics_kws=None)

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

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, date (multi-index) and metric (columns).

Return type:

pandas.DataFrame

compute_zonal_statistics_gdf(metrics, *, class_val=None, metrics_kws=None)

Compute the zonal statistics geo-data frame over the landscape raster.

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 class-level metrics will be computed.

• class_val (int, optional) – If provided, the zonal statistics will be computed at the level of the corresponding class, otherwise they will be computed at the landscape level.

• 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}. If None, each metric will be computed according to FRAGSTATS defaults.

Returns:

zonal_statistics_gdf – Geo-data frame with the computed zonal statistics.

Return type:

geopandas.GeoDataFrame

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

Plot each landscape snapshot in a dedicated matplotlib axis.

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 matplotlib.pyplot.subplots.

• show_kws (dict, default None) – Keyword arguments to be passed to rasterio.plot.show.

• subplots_adjust_kws (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.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, buffer_dist_legend=True, fmt='--o', plot_kws=None, subplots_kws=None, metric_kws=None)

Plot the time series of the metric accross buffer zones.

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.

• buffer_dist_legend (bool, default True) – Whether a legend linking each plotted line to a buffer zone should be displayed within the plot.

• fmt (str, default '--o') – A format string for matplotlib.pyplot.plot.

• plot_kws (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.plot.

• subplots_kws (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.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:

matplotlib.axes.Axes

class pylandstats.SpatioTemporalZonalGridAnalysis(landscape_filepaths, *, num_zone_cols=None, num_zone_rows=None, zone_width=None, zone_height=None, offset=None, dates=None, neighborhood_rule=None)

Spatio-temporal zonal analysis around a grid.

__init__(landscape_filepaths, *, num_zone_cols=None, num_zone_rows=None, zone_width=None, zone_height=None, offset=None, dates=None, neighborhood_rule=None)

Initialize the spatio-temporal zonal grid analysis.

Parameters:

• landscape_filepaths (str, file-like object or pathlib.Path object) – A string/file-like object/pathlib.Path object with the landscape data.

• num_zone_cols (int, optional) – The number of zone columns/rows 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 minimum superset that covers the landscape bounds. If not provided, then num_width/num_height must be provided.

• num_zone_rows (int, optional) – The number of zone columns/rows 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 minimum superset that covers the landscape bounds. If not provided, then num_width/num_height must be provided.

• zone_width (numeric, optional) – The width/height of each zone (in units of the landscape CRS). If the landscape dimensions and the desired zones do not divide evenly, the zones will be defined for the minimum superset that covers the landscape bounds. If not provided, then num_width/num_height must be provided.

• zone_height (numeric, optional) – The width/height of each zone (in units of the landscape CRS). If the landscape dimensions and the desired zones do not divide evenly, the zones will be defined for the minimum superset that covers the landscape bounds. If not provided, then num_width/num_height must be provided.

• offset (str, optional) – If set to “center”, the and the landscape dimensions and the desired zones do not divide evenly, the grid is offsetted so that the landscape bounds are in the center of the grid. Otherwise, the grid starts at the top-left corner of the landscape. Ignored if the landscape dimensions and the desired zones divide evenly.

• dates (list-like, optional) – A list-like of ints or strings that label the date of each snapshot of landscapes (for DataFrame indices and plot labels).

• neighborhood_rule ({'8', '4'}, optional) – Neighborhood rule to determine patch adjacencies, i.e: ‘8’ (queen’s case/Moore neighborhood) or ‘4’ (rook’s case/Von Neumann neighborhood). If no value is provided, the default value set in settings.DEFAULT_NEIGHBORHOOD_RULE will be taken.

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

Compute the data frame of class-level metrics, which is multi-indexed by the grid cell, class and date.

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.

• fillna (bool, optional) – Whether NaN values representing landscapes with no occurrences of patches of the provided class should be replaced by zero when appropriate, e.g., area and edge metrics (no ocurrences mean zero area/edge). If the provided value is None (default), the value will be taken from settings.CLASS_METRICS_DF_FILLNA.

Returns:

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

Return type:

pandas.DataFrame

compute_landscape_metrics_df(*, metrics=None, metrics_kws=None)

Computes the data frame of landscape-level metrics, which is multi-indexed by the grid cell and date.

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 grid cell, date (multi-index) and metric (columns).

Return type:

pandas.DataFrame

compute_zonal_statistics_gdf(metrics, *, class_val=None, metrics_kws=None)

Compute the zonal statistics geo-data frame over the landscape raster.

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 class-level metrics will be computed.

• class_val (int, optional) – If provided, the zonal statistics will be computed at the level of the corresponding class, otherwise they will be computed at the landscape level.

• 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}. If None, each metric will be computed according to FRAGSTATS defaults.

Returns:

zonal_statistics_gdf – Geo-data frame with the computed zonal statistics.

Return type:

geopandas.GeoDataFrame

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

Plot each landscape snapshot in a dedicated matplotlib axis.

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 matplotlib.pyplot.subplots.

• show_kws (dict, default None) – Keyword arguments to be passed to rasterio.plot.show.

• subplots_adjust_kws (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.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, grid_cell_legend=True, fmt='--o', plot_kws=None, subplots_kws=None, metric_kws=None)

Plot the time series of the metric accross zone grids.

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.

• grid_cell_legend (bool, default True) – Whether a legend linking each plotted line to a zone grid should be displayed within the plot.

• fmt (str, default '--o') – A format string for matplotlib.pyplot.plot.

• plot_kws (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.plot.

• subplots_kws (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.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:

matplotlib.axes.Axes