Spatial signature analysis#

class pylandstats.SpatialSignatureAnalysis(landscapes, *, class_metrics=None, landscape_metrics=None, classes=None, class_metrics_fillna=None, class_metrics_kwargs=None, landscape_metrics_kwargs=None)[source]#

Pattern-based analysis of landscapes based on spatial signatures.

__init__(landscapes, *, class_metrics=None, landscape_metrics=None, classes=None, class_metrics_fillna=None, class_metrics_kwargs=None, landscape_metrics_kwargs=None)[source]#

Initialize the spatial signature analysis.

Parameters:

  • landscapes (pylandstats.MultiLandscape or list-like of pylandstats.Landscape) – A MultiLandscape object or list of the landscapes to be analyzed.

  • class_metrics (list-like of str, optional) – A list-like of strings with the names of the metrics that should be computed. If None, no class-level metric will be computed.

  • 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. If None and class-level metrics are computed, all unique class values will be considered. Ignored if no class-level metrics are computed.

  • class_metrics_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 occurrences mean zero area/edge). If the provided value is None (default), the value will be taken from settings.CLASS_METRICS_DF_FILLNA.

  • class_metrics_kwargs (dict, optional) – Dictionary mapping the keyword arguments (values) that should be passed to each metric method (key) for the class and landscape-level metrics respectively. For instance, to exclude the boundary from the computation of total_edge, metric_kwargs should map the string ‘total_edge’ (method name) to {‘count_boundary’: False}. If None, each metric will be computed according to FRAGSTATS defaults.

  • landscape_metrics_kwargs (dict, optional) – Dictionary mapping the keyword arguments (values) that should be passed to each metric method (key) for the class and landscape-level metrics respectively. For instance, to exclude the boundary from the computation of total_edge, metric_kwargs should map the string ‘total_edge’ (method name) to {‘count_boundary’: False}. If None, each metric will be computed according to FRAGSTATS defaults.

decompose(*, decomposer=None, preprocessor=None, preprocessor_kwargs=None, imputer=None, imputer_kwargs=None, **decomposer_kwargs)[source]#

Factorize the spatial signature matrix into components.

Parameters:

  • decomposer (class, optional) – A class that implements the decomposition algorithm. It can be any scikit-learn like transformer that implements the fit, transform and fit_transform methods and with the components_ and n_components attributes. If no value is provided, the default value set in settings.DEFAULT_DECOMPOSER will be taken.

  • preprocessor (class, optional) – A class that implements the preprocessing algorithm. It can be any scikit-learn like transformer that implements the fit_transform method. If no value is provided, the default value set in settings.DEFAULT_PREPROCESSOR will be taken.

  • preprocessor_kwargs (dict, optional) – Keyword arguments to be passed to the initializationof preprocessor.

  • imputer (class, optional) – A class that implements the imputation algorithm. It can be any scikit-learn like transformer that implements the fit_transform method. If no value is provided, no imputation will be performed.

  • imputer_kwargs (dict, optional) – Keyword arguments to be passed to the initialization of imputer. Ignored if imputer is None.

  • **decomposer_kwargs (dict, optional) – Keyword arguments to be passed to the initialization of decomposer.

Returns:

  • components_df (pandas.DataFrame) – A DataFrame with the components of the decomposition. Each row corresponds to a landscape and each column to a component.

  • decomposer_model (object) – The fitted decomposer model.

get_cgram(*, k_range=None, decomposer=None, decomposer_kwargs=None, preprocessor=None, preprocessor_kwargs=None, imputer=None, imputer_kwargs=None, **clustergram_kwargs)[source]#

Get the clustergram of the spatial signature matrix.

Parameters:

  • k_range (list-like, optional) – A list-like of integer values with the number of clusters to be tested. If no value is provided, the default value set in settings.DEFAULT_K_RANGE will be taken.

  • decomposer (class, optional) – A class that implements the decomposition algorithm. It can be any scikit-learn like transformer that implements the fit, transform and fit_transform methods and with the components_ and n_components attributes. If no value is provided, the clustering algorithm will be applied to the original spatial signature matrix.

  • decomposer_kwargs (dict, optional) – Keyword arguments to be passed to the initialization of decomposer. Ignored if decomposer is None.

  • preprocessor (class, optional) – A class that implements the preprocessing algorithm. It can be any scikit-learn like transformer that implements the fit_transform method. If no value is provided, the default value set in settings.DEFAULT_PREPROCESSOR will be taken.

  • preprocessor_kwargs (dict, optional) – Keyword arguments to be passed to the initializationof preprocessor.

  • imputer (class, optional) – A class that implements the imputation algorithm. It can be any scikit-learn like transformer that implements the fit_transform method. If no value is provided, no imputation will be performed.

  • imputer_kwargs (dict, optional) – Keyword arguments to be passed to the initialization of imputer. Ignored if imputer is None.

  • **clustergram_kwargs (dict, optional) – Keyword arguments to be passed to the initialization of Clustergram.

Returns:

cgram – The fitted clustergram object.

Return type:

clustergram.Clustergram

get_loading_df(decompose_model, *, columns=None, index=None, **df_kwargs)[source]#

Get components loadings for each metric.

Parameters:

  • decompose_model (object) – The decomposition model fitted to the spatial signature matrix.

  • columns (list-like, optional) – Column names for the components. If no value is provided, an integer range from 0 to n_components_ - 1 will be used.

  • index (list-like, optional) – Index names for the metrics. If no value is provided, the column names of metrics_df will be used.

  • **df_kwargs (dict, optional) – Keyword arguments to be passed to the initialization of pandas.DataFrame

Returns:

loading_df – A DataFrame with the loadings of the components. Each row corresponds to a metric and each column to a component.

Return type:

pandas.DataFrame

plot_cluster_landscapes(cgram, n_clusters, *, n_cluster_landscapes=4, n_cols=4, sample_kwargs=None, figure_kwargs=None, subfigures_kwargs=None, subplots_kwargs=None, supylabel_kwargs=None, **plot_landscape_kwargs)[source]#

Scatterplot the landscape samples colored by their cluster.

Parameters:

  • cgram (Clustergram) – Fitted clustergram object.

  • n_clusters (int) – Number of clusters to use.

  • n_cluster_landscapes (int, optional, default 4) – Number of landscapes to plot for each cluster. Providing a value of None will plot all landscapes.

  • n_cols (int, optional, default 4) – Number of columns for the figure.

  • sample_kwargs (dict, optional) – Keyword arguments to be passed to pandas.DataFrame.sample, matplotlib.pyplot.figure, matplotlib.figure.Figure.subfigures, matplotlib.figure.SubFigure.subplots, matplotlib.figure.SubFigure.supylabel and pylandstats.Landscape.plot_landscape respectively.

  • figure_kwargs (dict, optional) – Keyword arguments to be passed to pandas.DataFrame.sample, matplotlib.pyplot.figure, matplotlib.figure.Figure.subfigures, matplotlib.figure.SubFigure.subplots, matplotlib.figure.SubFigure.supylabel and pylandstats.Landscape.plot_landscape respectively.

  • subfigures_kwargs (dict, optional) – Keyword arguments to be passed to pandas.DataFrame.sample, matplotlib.pyplot.figure, matplotlib.figure.Figure.subfigures, matplotlib.figure.SubFigure.subplots, matplotlib.figure.SubFigure.supylabel and pylandstats.Landscape.plot_landscape respectively.

  • subplots_kwargs (dict, optional) – Keyword arguments to be passed to pandas.DataFrame.sample, matplotlib.pyplot.figure, matplotlib.figure.Figure.subfigures, matplotlib.figure.SubFigure.subplots, matplotlib.figure.SubFigure.supylabel and pylandstats.Landscape.plot_landscape respectively.

  • supylabel_kwargs (dict, optional) – Keyword arguments to be passed to pandas.DataFrame.sample, matplotlib.pyplot.figure, matplotlib.figure.Figure.subfigures, matplotlib.figure.SubFigure.subplots, matplotlib.figure.SubFigure.supylabel and pylandstats.Landscape.plot_landscape respectively.

  • plot_landscape_kwargs (dict, optional) – Keyword arguments to be passed to pandas.DataFrame.sample, matplotlib.pyplot.figure, matplotlib.figure.Figure.subfigures, matplotlib.figure.SubFigure.subplots, matplotlib.figure.SubFigure.supylabel and pylandstats.Landscape.plot_landscape respectively.

Returns:

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

Return type:

matplotlib.figure.Figure

plot_cluster_zones(cgram, n_clusters, *, legend=True, categorical=True, ax=None, subplots_kwargs=None, **plot_kwargs)[source]#

Plot the landscape zones colored by their cluster.

Only available if the SpatialSignatureAnalysis object has been initialized with a zonal analysis class (or subclass). If the SpatialSignatureAnalysis object has been initialized with a spatio-temporal zonal analysis class (or subclass), each date snapshot will be plotted separately.

Parameters:

  • cgram (Clustergram) – Fitted clustergram object.

  • n_clusters (int) – Number of clusters to use.

  • ax (matplotlib.axes.Axes, optional) – Axes object to draw the plot onto, otherwise create a new figure. Ignored if the SpatialSignatureAnalysis object has been initialized with a spatio-temporal zonal analysis class (or subclass).

  • legend (bool, optional, default True) – Whether to show the legend.

  • categorical (bool, optional, default True) – Whether the cluster color map should be categorical.

  • subplots_kwargs (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.subplots and geopandas.GeoDataFrame.plot respectively.

  • plot_kwargs (dict, default None) – Keyword arguments to be passed to matplotlib.pyplot.subplots and geopandas.GeoDataFrame.plot respectively.

Returns:

If the SpatialSignatureAnalysis object has been initialized with a spatio-temporal zonal analysis class (or subclass), returns the figure with its corresponding plots drawn into its axes. Otherwise, returns the axes object with the plot drawn onto it.

Return type:

matplotlib.figure.Figure or matplotlib.axes.Axes

static scatterplot_cluster_metrics(cgram, n_clusters, metric_x, metric_y, *, ax=None, palette_name=None, center_marker='x', center_plot_kwargs=None, **scatterplot_kwargs)[source]#

Scatterplot the landscape samples colored by their cluster.

Parameters:

  • cgram (clustergram.Clustergram) – Fitted clustergram object.

  • n_clusters (int) – Number of clusters to use.

  • metric_x (str) – Strings with the names of the metrics to be plotted on the x and y axes respectively. Should be a column of cgram.data. Note thus that for class-level metrics, the passed string should be of the form “{metric}_{class_val}”.

  • metric_y (str) – Strings with the names of the metrics to be plotted on the x and y axes respectively. Should be a column of cgram.data. Note thus that for class-level metrics, the passed string should be of the form “{metric}_{class_val}”.

  • ax (matplotlib.axes.Axes, optional) – Axes object to draw the plot onto, otherwise create a new figure.

  • palette_name (str, optional) – Name of palette or None to return current palette.

  • center_marker (str, optional, default "x") – Marker to be used for the cluster centers.

  • center_plot_kwargs (dict, optional) – Keyword arguments to plot the cluster centers, which will be passed to matplotlib.axes.Axes.plot.

  • scatterplot_kwargs (dict, optional) – Keyword arguments to be passed to seaborn.scatterplot.

Returns:

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

Return type:

matplotlib.axes.Axes