# libpysal.weights.lag_categorical

libpysal.weights.lag_categorical(w, y, ties='tryself')

  Spatial lag operator for categorical variables.

  Constructs the most common categories of neighboring observations, weighted by their weight strength.

  Parameters:
    w `W`

      PySAL spatial weightsobject

    y python:iterable

      iterable collection of categories (either int or string) with dimensionality conforming to w (see examples)

    ties `python:str`

      string describing the method to use when resolving ties. By default, the option is “tryself”, and the category of the focal observation is included with its neighbors to try and break a tie. If this does not resolve the tie, a winner is chosen randomly. To just use random choice to break ties, pass “random” instead.

  Returns:
    `an` (`n` `x` `k`) `column` `vector` `containing` `the` `most` `common` `neighboring` `observation`

  Notes

  This works on any array where the number of unique elements along the column axis is less than the number of elements in the array, for any dtype. That means the routine should work on any dtype that np.unique() can compare.

  Examples

  Set up a 9x9 weights matrix describing a 3x3 regular lattice. Lag one list of categorical variables with no ties.

      >>> import libpysal
      >>> import numpy as np
      >>> np.random.seed(12345)
      >>> w = libpysal.weights.lat2W(3, 3)
      >>> y = ['a','b','a','b','c','b','c','b','c']
      >>> y_l = libpysal.weights.lag_categorical(w, y)
      >>> np.array_equal(y_l, np.array(['b', 'a', 'b', 'c', 'b', 'c', 'b', 'c', 'b']))
      True

  Explicitly reshape y into a (9x1) array and calculate lag again

      >>> yvect = np.array(y).reshape(9,1)
      >>> yvect_l = libpysal.weights.lag_categorical(w,yvect)
      >>> check = np.array(
      ...     [ [i] for i in  ['b', 'a', 'b', 'c', 'b', 'c', 'b', 'c', 'b']]
      ... )
      >>> np.array_equal(yvect_l, check)
      True

  compute the lag of a 9x2 matrix of categories

      >>> y2 = ['a', 'c', 'c', 'd', 'b', 'a', 'd', 'd', 'c']
      >>> ym = np.vstack((y,y2)).T
      >>> ym_lag = libpysal.weights.lag_categorical(w,ym)
      >>> check = np.array([['b', 'd'], ['a', 'c'], ['b', 'c'], ['c', 'd'], ['b', 'd'], ['c', 'c'], ['b', 'd'], ['c', 'd'], ['b', 'c']])
      >>> np.array_equal(check, ym_lag)
      True