# esda.correlogram

esda.correlogram(geometry: ~geopandas.geoseries.GeoSeries, variable: str | list | ~pandas.core.series.Series | None, support: list | None = None, statistic: ~collections.abc.Callable | str = <class 'esda.moran.Moran'>, distance_type: str = 'band', weights_kwargs: dict = None, stat_kwargs: dict = None, select_numeric: bool = False, n_jobs: int = -1, n_bins: int | None = 50) → DataFrame

  Generate a spatial correlogram

  A spatial profile is a set of spatial autocorrelation statistics calculated for a set of increasing distances. It is a useful exploratory tool for examining how the relationship between spatial units changes over different notions of scale.

  Parameters:
    geometry `gpd.GeoSeries`

      geodataframe holding spatial and attribute data

    variable: pd.Series or list

      pandas series matching input geometries

    support `list` or `None`

      list of values at which to compute the autocorrelation statistic

    statistic `callable()` or `str`

      statistic to be computed for a range of libpysal.Graph specifications. This should be a class with a signature like `Statistic(y,w, **kwargs)` where `y` is a array and `w` is a `libpysal.weights.W` object Generally, this is a class from pysal’s `esda` package defaults to `esda.Moran`, which computes the Moran’s I statistic. If `'lowess'` is provided, a non-parametric correlogram is computed using lowess regression on the spatial-covariation model, see Notes.

    distance_type `str`, optional

      which concept of distance to increment. Options are `{`band`, `knn`}`. by default `'band'` (for `libpysal.weights.DistanceBand` weights)

    weights_kwargs `dict`

      additional keyword arguments passed to the `libpysal.weights.W` class

    stat_kwargs `dict`

      additional keyword arguments passed to the `esda` autocorrelation statistic class. For example for faster results with no statistical inference, set the number of permutations to zero with `stat_kwargs={permutations: 0}`

    select_numeric bool

      if True, only return numeric attributes from the original class. This is useful e.g. to prevent lists inside a “cell” of a dataframe

    n_jobs `int`

      number of jobs to pass to joblib. If -1 (default), all cores will be used

    n_bins `int`

      number of distance bands or k-nearest neighbor values to use if `support` is not provided. Ignored if `support` is provided. by default 10. If `distance_type` is ‘knn’, the number of neighbors will be capped at n-1, where n is the number of observations. Further, if n-1 is not divisible by `n_bins`, the actual number of bins will be may be off by one bin.

  Returns:
    outputs `pandas.DataFrame`

      table of autocorrelation statistics at increasing distance bandwidths

  Notes

  The nonparametric correlogram uses a lowess regression to estimate the spatial-covariation model:

  \[zi*zj = f(d_{ij}) + e_ij\]

  where \(f\) is a smooth function of distance \(d_{ij}\) between points \(i\) and \(j\). This function requires the statsmodels package to be installed.

  For the nonparametric correlogram, a precomputed distance matrix can be used. To do this, set `stat_kwargs={'metric':'precomputed', 'coordinates':distance_matrix}` where `distance_matrix` is a square matrix of pairwise distances that aligns with the `geometry` rows.