# esda.Moran

class esda.Moran(y, w, transformation='r', permutations=999, two_tailed=True)

  Moran’s I Global Autocorrelation Statistic

  Parameters:
    y `array`

      variable measured across n spatial units

    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

    two_tailed bool

      If True (default) analytical p-values for Moran are two tailed, otherwise if False, they are one-tailed.

  Attributes:
    y `array`

      original variable

    w `W` | `Graph`

      original w object

    z `array`

      zero-mean, unit standard deviation normalized y

    permutations `int`

      number of permutations

    I `float`

      value of Moran’s I

    EI `float`

      expected value under normality assumption

    VI_norm `float`

      variance of I under normality assumption

    seI_norm `float`

      standard deviation of I under normality assumption

    z_norm `float`

      z-value of I under normality assumption

    p_norm `float`

      p-value of I under normality assumption

    VI_rand `float`

      variance of I under randomization assumption

    seI_rand `float`

      standard deviation of I under randomization assumption

    z_rand `float`

      z-value of I under randomization assumption

    p_rand `float`

      p-value of I under randomization assumption

    two_tailed bool

      If True p_norm and p_rand are two-tailed, otherwise they are one-tailed.

    sim `array`

      (if permutations>0) vector of I values for permuted samples

    p_sim `array`

      (if permutations>0) p-value based on permutations (one-tailed) null: spatial randomness alternative: the observed I is extreme if it is either extremely greater or extremely lower than the values obtained based on permutations

    EI_sim `float`

      (if permutations>0) average value of I from permutations

    VI_sim `float`

      (if permutations>0) variance of I from permutations

    seI_sim `float`

      (if permutations>0) standard deviation of I under permutations.

    z_sim `float`

      (if permutations>0) standardized I based on permutations

    p_z_sim `float`

      (if permutations>0) p-value based on standard normal approximation from permutations

  Notes

  Technical details and derivations can be found in [CO81].

  Examples

      >>> import libpysal
      >>> w = libpysal.io.open(libpysal.examples.get_path("stl.gal")).read()
      >>> f = libpysal.io.open(libpysal.examples.get_path("stl_hom.txt"))
      >>> y = np.array(f.by_col['HR8893'])
      >>> from esda.moran import Moran
      >>> mi = Moran(y,  w)
      >>> round(mi.I, 3)
      0.244
      >>> mi.EI
      -0.012987012987012988
      >>> mi.p_norm
      0.00027147862770937614

  SIDS example replicating OpenGeoda

      >>> w = libpysal.io.open(libpysal.examples.get_path("sids2.gal")).read()
      >>> f = libpysal.io.open(libpysal.examples.get_path("sids2.dbf"))
      >>> SIDR = np.array(f.by_col("SIDR74"))
      >>> mi = Moran(SIDR,  w)
      >>> round(mi.I, 3)
      0.248
      >>> mi.p_norm
      0.0001158330781489969

  One-tailed

      >>> mi_1 = Moran(SIDR,  w, two_tailed=False)
      >>> round(mi_1.I, 3)
      0.248
      >>> round(mi_1.p_norm, 4)
      0.0001

  __init__(y, w, transformation='r', permutations=999, two_tailed=True)

  Methods

  `__init__`(y, w[, transformation, ...]) |
  `by_col`(df, cols[, w, inplace, pvalue, outvals]) | Function to compute a Moran statistic on a dataframe
  `plot_scatter`([ax, scatter_kwds, fitline_kwds]) | Plot a Moran scatterplot with optional coloring for significant points.
  `plot_simulation`([ax, legend, fitline_kwds]) | Global Moran's I simulated reference distribution.

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

    Function to compute a Moran 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’

      pvalue `str`

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

      outvals `list` of `strings`

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

      **stat_kws `dict`

        options to pass to the underlying statistic. For this, see the documentation for the Moran 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.
  plot_scatter(ax=None, scatter_kwds=None, fitline_kwds=None)

    Plot a Moran scatterplot with optional coloring for significant points.

    Parameters:
      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.

  plot_simulation(ax=None, legend=False, fitline_kwds=None, **kwargs)

    Global Moran’s I simulated reference distribution.

    Parameters:
      ax `matplotlib.axes.Axes`, optional

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

      legend bool, optional

        Plot a legend, by default False

      fitline_kwds `dict`, optional

        Additional keyword arguments for vertical Moran fit line, by default None.

      **kwargs `keyword` `arguments`, optional

        Additional keyword arguments for KDE plot passed to `seaborn.kdeplot`, by default None.

    Returns:
      `matplotlib.axes.Axes`

        Axes object with the Moran scatterplot.

    Notes

    This requires optional dependencies `matplotlib` and `seaborn`.

    Examples

        >>> import libpysal
        >>> w = libpysal.io.open(libpysal.examples.get_path("stl.gal")).read()
        >>> f = libpysal.io.open(libpysal.examples.get_path("stl_hom.txt"))
        >>> y = np.array(f.by_col['HR8893'])
        >>> from esda.moran import Moran
        >>> mi = Moran(y,  w)

    Default plot:

        >>> mi.plot_simulation()

    Customized styling that turns the distribution into a pink line and line indicating I to a black line:

        >>> mi.plot_simulation(fitline_kwds={"color": "k"}, color="pink", shade=False)