# esda.Moran_Local

class esda.Moran_Local(y, w, transformation='r', permutations=999, geoda_quads=False, n_jobs=1, keep_simulations=True, seed=None, island_weight=0)

  Local Moran Statistics.

  Parameters:
    y `array`

      (n,1), attribute array

    w `W` | `Graph`

      spatial weights instance as W or Graph aligned with y

    transformation{‘R’, ‘B’, ‘D’, ‘U’, ‘V’}

      weights transformation, default is row-standardized “r”. Other options include “B”: binary, “D”: doubly-standardized, “O”: restore original transformation (applicable only if `w` is passed as `W`), “V”: variance-stabilizing.

    permutations `int`

      number of random permutations for calculation of pseudo p_values

    geoda_quads bool

      (default=False) If True use GeoDa scheme: HH=1, LL=2, LH=3, HL=4 If False use PySAL Scheme: HH=1, LH=2, LL=3, HL=4

    n_jobs `int`

      Number of cores to be used in the conditional randomisation. If -1, all available cores are used.

    keep_simulations `Boolean`

      (default=True) If True, the entire matrix of replications under the null is stored in memory and accessible; otherwise, replications are not saved

    seed None/int

      Seed to ensure reproducibility of conditional randomizations. Must be set here, and not outside of the function, since numba does not correctly interpret external seeds nor numpy.random.RandomState instances.

    island_weight:

      value to use as a weight for the “fake” neighbor for every island. If numpy.nan, will propagate to the final local statistic depending on the stat_func. If 0, then the lag is always zero for islands.

  Attributes:
    y `array`

      original variable

    w `W` | `Graph`

      original w object

    z `array`

      zero-mean, unit standard deviation normalized y

    permutations `int`

      number of random permutations for calculation of pseudo p_values

    Is `array`

      local Moran’s I values

    q `array`

      (if permutations>0) values indicate quandrant location 1 HH, 2 LH, 3 LL, 4 HL

    sim `array` (`permutations` `by` `n`)

      (if permutations>0) I values for permuted samples

    p_sim `array`

      (if permutations>0) p-values based on permutations (one-sided) null: spatial randomness alternative: the observed Ii is further away or extreme from the median of simulated values. It is either extremely high or extremely low in the distribution of simulated Is.

    EI_sim `array`

      (if permutations>0) average values of local Is from permutations

    VI_sim `array`

      (if permutations>0) variance of Is from permutations

    EI `array`

      analytical expectation of Is under total permutation, from [Ans95]. Is the same at each site, and equal to the expectation of I itself when transformation=’r’. We recommend using EI_sim, not EI, for analysis. This EI is only provided for reproducibility.

    VI `array`

      analytical variance of Is under total permutation, from [Ans95]. Varies according only to cardinality. We recommend using VI_sim, not VI, for analysis. This VI is only provided for reproducibility.

    EIc `array`

      analytical expectation of Is under conditional permutation, from [SOT98]. Varies strongly by site, since it conditions on z_i. We recommend using EI_sim, not EIc, for analysis. This EIc is only provided for reproducibility.

    VIc `array`

      analytical variance of Is under conditional permutation, from [SOT98]. Varies strongly by site, since it conditions on z_i. We recommend using VI_sim, not VIc, for analysis. This VIc is only provided for reproducibility.

    seI_sim `array`

      (if permutations>0) standard deviations of Is under permutations.

    z_sim `arrray`

      (if permutations>0) standardized Is based on permutations

    p_z_sim `array`

      (if permutations>0) p-values based on standard normal approximation from permutations (one-sided) for two-sided tests, these values should be multiplied by 2

    n_jobs `int`

      Number of cores to be used in the conditional randomisation. If -1, all available cores are used.

    keep_simulations `Boolean`

      (default=True) If True, the entire matrix of replications under the null is stored in memory and accessible; otherwise, replications are not saved

    seed None/int

      Seed to ensure reproducibility of conditional randomizations. Must be set here, and not outside of the function, since numba does not correctly interpret external seeds nor numpy.random.RandomState instances.

  Notes

  For technical details see [Ans95].

  Examples

      >>> import libpysal
      >>> import numpy as np
      >>> np.random.seed(10)
      >>> w = libpysal.io.open(libpysal.examples.get_path("desmith.gal")).read()
      >>> f = libpysal.io.open(libpysal.examples.get_path("desmith.txt"))
      >>> y = np.array(f.by_col['z'])
      >>> from esda.moran import Moran_Local
      >>> lm = Moran_Local(y, w, transformation = "r", permutations = 99)
      >>> lm.q
      array([4, 4, 4, 2, 3, 3, 1, 4, 3, 3])
      >>> lm.p_z_sim[0]
      0.24669152541631179
      >>> lm = Moran_Local(y, w, transformation = "r", permutations = 99,                             geoda_quads=True)
      >>> lm.q
      array([4, 4, 4, 3, 2, 2, 1, 4, 2, 2])

  Note random components result is slightly different values across architectures so the results have been removed from doctests and will be moved into unittests that are conditional on architectures.

  __init__(y, w, transformation='r', permutations=999, geoda_quads=False, n_jobs=1, keep_simulations=True, seed=None, island_weight=0)

  Methods

  `__init__`(y, w[, transformation, ...]) |
  `by_col`(df, cols[, w, inplace, pvalue, outvals]) | Function to compute a Moran_Local statistic on a dataframe.
  `explore`(gdf[, crit_value]) | Create interactive map of LISA indicators
  `get_cluster_labels`([crit_value]) | Return LISA cluster labels for each observation.
  `plot`(gdf[, crit_value]) | Create static map of LISA indicators
  `plot_combination`(gdf, attribute[, ...]) | Produce three-plot visualisation of Moran Scatteprlot, LISA cluster and Choropleth maps, with Local Moran region and quadrant masking
  `plot_scatter`([crit_value, ax, scatter_kwds, ...]) | Plot a Moran scatterplot with optional coloring for significant points.

  classmethod by_col(df, cols, w=None, inplace=False, pvalue='sim', outvals=None, **stat_kws)

    Function to compute a Moran_Local statistic on a dataframe.

    Parameters:
      df `pandas.DataFrame`

        a pandas dataframe with a geometry column

      cols `str` or `list` of `str`

        name or list of names of columns to use to compute the statistic

      w `W` | `Graph`

        spatial weights instance as W or Graph aligned with the dataframe. If not provided, this is searched for in the dataframe’s metadata

      inplace bool

        a boolean denoting whether to operate on the dataframe inplace or to return a series contaning the results of the computation. If operating inplace, the derived columns will be named ‘column_moran_local’

      pvalue `str`

        a string denoting which pvalue should be returned. Refer to the the Moran_Local statistic’s documentation for available p-values

      outvals `list` of `strings`

        list of arbitrary attributes to return as columns from the Moran_Local statistic

      **stat_kws `dict`

        options to pass to the underlying statistic. For this, see the documentation for the Moran_Local statistic.

    Returns:
      `If` `inplace`, `None`, `and` `operation` `is` `conducted` `on` `dataframe`
      `in` memory. `Otherwise`, `returns` `a` `copy` of `the` `dataframe` `with`
      `the` `relevant` `columns` attached.
  explore(gdf, crit_value=0.05, **kwargs)

    Create interactive map of LISA indicators

    Parameters:
      gdf `geopandas.GeoDataFrame`

        geodataframe used to conduct the local Moran analysis

      crit_value `float`, optional

        critical value to determine statistical significance, by default 0.05

      kwargs `dict`, optional

        additional keyword arguments passed to the geopandas explore method

    Returns:
      `Folium.Map`

        interactive map with LISA clusters

  get_cluster_labels(crit_value=0.05)

    Return LISA cluster labels for each observation.

    Parameters:
      crit_value `float`, optional

        crititical significance value for statistical inference, by default 0.05

    Returns:
      `numpy.array`

        an array of cluster labels aligned with the input data used to conduct the local Moran analysis

  plot(gdf, crit_value=0.05, **kwargs)

    Create static map of LISA indicators

    Parameters:
      gdf `geopandas.GeoDataFrame`

        geodataframe used to conduct the local Moran analysis

      crit_value `float`, optional

        critical value to determine statistical significance, by default 0.05

      kwargs `dict`, optional

        additional keyword arguments passed to the geopandas explore method

    Returns:
      `ax`

        matplotlib axis

  plot_combination(gdf, attribute, crit_value=0.05, region_column=None, mask=None, mask_color='#636363', quadrant=None, legend=True, scheme='Quantiles', cmap='YlGnBu', figsize=(15, 4), scatter_kwds=None, fitline_kwds=None, legend_kwds=None)

    Produce three-plot visualisation of Moran Scatteprlot, LISA cluster and Choropleth maps, with Local Moran region and quadrant masking

    Parameters:
      gdf `geopandas.GeoDataFrame`

        geodataframe used to conduct the local Moran analysis

      attribute `str`

        Column name of attribute which should be depicted in Choropleth map.

      crit_value `float`, optional

        critical value to determine statistical significance, by default 0.05

      region_column: string, optional

        Column name containing mask region of interest, by default None

      mask: str, float, int, optional

        Identifier or name of the region to highlight, by default None Use the same dtype to specifiy as in original dataset.

      mask_color: str, optional

        Color of mask, by default ‘#636363’.

      quadrant `int`, optional

        Quadrant 1-4 in scatterplot masking values in LISA cluster and Choropleth maps, by default None

      figsize: tuple, optional

        W, h of figure, by default (15,4)

      legend: boolean, optional

        If True, legend for maps will be depicted, by default True

      scheme: str, optional

        Name of mapclassify classifier to be used, by default ‘Quantiles’

      cmap: str, optional

        Name of matplotlib colormap used for plotting the Choropleth. By default ‘YlGnBu’.

      scatter_kwds `keyword` `arguments`, optional

        Keywords used for creating and designing the scatter points, by default None.

      fitline_kwds `keyword` `arguments`, optional

        Keywords used for creating and designing the moran fitline in the scatterplot, by default None.

      legend_kwds `dict`

        Keyword arguments passed to geopandas.GeodataFrame.plot `legend_kwds` allowing repositioning of the legend in LISA cluster plot and choropleth.

    Returns:
      axs `array` of `Matplotlib` `axes`
  plot_scatter(crit_value=0.05, ax=None, scatter_kwds=None, fitline_kwds=None)

    Plot a Moran scatterplot with optional coloring for significant points.

    Parameters:
      crit_value `float`, optional

        Critical value to determine statistical significance, by default 0.05.

      ax `matplotlib.axes.Axes`, optional

        Pre-existing axes for the plot, by default None.

      scatter_kwds `dict`, optional

        Additional keyword arguments for scatter plot, by default None.

      fitline_kwds `dict`, optional

        Additional keyword arguments for fit line, by default None.

    Returns:
      `matplotlib.axes.Axes`

        Axes object with the Moran scatterplot.