# esda.Moran_BV

class esda.Moran_BV(x, y, w, transformation='r', permutations=999)

  Bivariate Moran’s I

  Parameters:
    x `array`

      x-axis variable

    y `array`

      wy will be on y axis

    w `W` | `Graph`

      spatial weights instance as W or Graph aligned with x and 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

  Attributes:
    zx `array`

      original x variable standardized by mean and std

    zy `array`

      original y variable standardized by mean and std

    w `W` | `Graph`

      original w object

    permutation `int`

      number of permutations

    I `float`

      value of bivariate Moran’s I

    sim `array`

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

    p_sim `float`

      (if permutations>0) p-value based on permutations (one-sided) null: spatial randomness alternative: the observed I is extreme it is either extremely high or extremely low

    EI_sim `array`

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

    VI_sim `array`

      (if permutations>0) variance of I from permutations

    seI_sim `array`

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

    z_sim `array`

      (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

  Inference is only based on permutations as analytical results are not too reliable.

  Examples

      >>> import libpysal
      >>> import numpy as np

  Set random number generator seed so we can replicate the example

      >>> np.random.seed(10)

  Open the sudden infant death dbf file and read in rates for 74 and 79 converting each to a numpy array

      >>> f = libpysal.io.open(libpysal.examples.get_path("sids2.dbf"))
      >>> SIDR74 = np.array(f.by_col['SIDR74'])
      >>> SIDR79 = np.array(f.by_col['SIDR79'])

  Read a GAL file and construct our spatial weights object

      >>> w = libpysal.io.open(libpysal.examples.get_path("sids2.gal")).read()

  Create an instance of Moran_BV

      >>> from esda.moran import Moran_BV
      >>> mbi = Moran_BV(SIDR79,  SIDR74,  w)

  What is the bivariate Moran’s I value

      >>> round(mbi.I, 3)
      0.156

  Based on 999 permutations, what is the p-value of our statistic

      >>> round(mbi.p_z_sim, 3)
      0.001

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

  Methods

  `__init__`(x, y, w[, transformation, permutations]) |
  `by_col`(df, x[, y, w, inplace, pvalue, outvals]) | Function to compute a Moran_BV 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, x, y=None, w=None, inplace=False, pvalue='sim', outvals=None, **stat_kws)

    Function to compute a Moran_BV statistic on a dataframe

    Parameters:
      df `pandas.DataFrame`

        a pandas dataframe with a geometry column

      X `list` of `strings`

        column name or list of column names to use as X values to compute the bivariate statistic. If no Y is provided, pairwise comparisons among these variates are used instead.

      Y `list` of `strings`

        column name or list of column names to use as Y values to compute the bivariate statistic. if no Y is provided, pariwise comparisons among the X variates are used instead.

      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_BV statistic’s documentation for available p-values

      outvals `list` of `strings`

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

      **stat_kws `keyword` `arguments`

        options to pass to the underlying statistic. For this, see the documentation for the Moran_BV 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`.