# libpysal.weights.Kernel

class libpysal.weights.Kernel(data, bandwidth=None, fixed=True, k=2, function='triangular', eps=1.0000001, ids=None, diagonal=False, distance_metric='euclidean', radius=None, normalize=True, **kwargs)

  Spatial weights based on kernel functions.

  Parameters:
    data `array`

      (n,k) or KDTree where KDtree.data is array (n,k) n observations on k characteristics used to measure distances between the n objects

    bandwidth `python:float`

      or array-like (optional) the bandwidth \(h_i\) for the kernel.

    fixed bool

      If True then \(h_i=h \forall i\). If False then bandwidth is adaptive across observations.

    k `python:int`

      the number of nearest neighbors to use for determining bandwidth. For fixed bandwidth, \(h_i=max(dknn) \forall i\) where \(dknn\) is a vector of k-nearest neighbor distances (the distance to the kth nearest neighbor for each observation). For adaptive bandwidths, \(h_i=dknn_i\)

    diagonal bool

      If true, set diagonal weights = 1.0, if false (default), diagonals weights are set to value according to kernel function.

    function{‘triangular’,’uniform’,’quadratic’,’quartic’,’gaussian’}

      kernel function defined as follows with

      \[z_{i,j} = d_{i,j}/h_i\]

      triangular

      \[K(z) = (1 - |z|) \ if |z| \le 1\]

      uniform

      \[K(z) = 1/2 \ if |z| \le 1\]

      quadratic

      \[K(z) = (3/4)(1-z^2) \ if |z| \le 1\]

      quartic

      \[K(z) = (15/16)(1-z^2)^2 \ if |z| \le 1\]

      gaussian

      \[K(z) = (2\pi)^{(-1/2)} exp(-z^2 / 2)\]
    eps `python:float`

      adjustment to ensure knn distance range is closed on the knnth observations

    normalize bool

      If True (default) Gaussian kernel is normalized to integrate to 1. If False K(0)=1.

  Attributes:
    weights `python:dict`

      Dictionary keyed by id with a list of weights for each neighbor

    neighbors `python:dict`

      of lists of neighbors keyed by observation id

    bandwidth `array`

      array of bandwidths

  Examples

      >>> from libpysal.weights import Kernel
      >>> points=[(10, 10), (20, 10), (40, 10), (15, 20), (30, 20), (30, 30)]
      >>> kw=Kernel(points)
      >>> kw.weights[0]
      [1.0, 0.500000049999995, 0.4409830615267465]
      >>> kw.neighbors[0]
      [0, 1, 3]
      >>> kw.bandwidth
      array([[20.000002],
             [20.000002],
             [20.000002],
             [20.000002],
             [20.000002],
             [20.000002]])
      >>> kw15=Kernel(points,bandwidth=15.0)
      >>> kw15[0]
      {0: 1.0, 1: 0.33333333333333337, 3: 0.2546440075000701}
      >>> kw15.neighbors[0]
      [0, 1, 3]
      >>> kw15.bandwidth
      array([[15.],
             [15.],
             [15.],
             [15.],
             [15.],
             [15.]])

  Adaptive bandwidths user specified

      >>> bw=[25.0,15.0,25.0,16.0,14.5,25.0]
      >>> kwa=Kernel(points,bandwidth=bw)
      >>> kwa.weights[0]
      [1.0, 0.6, 0.552786404500042, 0.10557280900008403]
      >>> kwa.neighbors[0]
      [0, 1, 3, 4]
      >>> kwa.bandwidth
      array([[25. ],
             [15. ],
             [25. ],
             [16. ],
             [14.5],
             [25. ]])

  Endogenous adaptive bandwidths

      >>> kwea=Kernel(points,fixed=False)
      >>> kwea.weights[0]
      [1.0, 0.10557289844279438, 9.99999900663795e-08]
      >>> kwea.neighbors[0]
      [0, 1, 3]
      >>> kwea.bandwidth
      array([[11.18034101],
             [11.18034101],
             [20.000002  ],
             [11.18034101],
             [14.14213704],
             [18.02775818]])

  Endogenous adaptive bandwidths with Gaussian kernel

      >>> kweag=Kernel(points,fixed=False,function='gaussian')
      >>> kweag.weights[0]
      [0.3989422804014327, 0.2674190291577696, 0.2419707487162134]
      >>> kweag.bandwidth
      array([[11.18034101],
             [11.18034101],
             [20.000002  ],
             [11.18034101],
             [14.14213704],
             [18.02775818]])

  Diagonals to 1.0

      >>> kq = Kernel(points,function='gaussian')
      >>> kq.weights
      {0: [0.3989422804014327, 0.35206533556593145, 0.3412334260702758], 1: [0.35206533556593145, 0.3989422804014327, 0.2419707487162134, 0.3412334260702758, 0.31069657591175387], 2: [0.2419707487162134, 0.3989422804014327, 0.31069657591175387], 3: [0.3412334260702758, 0.3412334260702758, 0.3989422804014327, 0.3011374490937829, 0.26575287272131043], 4: [0.31069657591175387, 0.31069657591175387, 0.3011374490937829, 0.3989422804014327, 0.35206533556593145], 5: [0.26575287272131043, 0.35206533556593145, 0.3989422804014327]}
      >>> kqd = Kernel(points, function='gaussian', diagonal=True)
      >>> kqd.weights
      {0: [1.0, 0.35206533556593145, 0.3412334260702758], 1: [0.35206533556593145, 1.0, 0.2419707487162134, 0.3412334260702758, 0.31069657591175387], 2: [0.2419707487162134, 1.0, 0.31069657591175387], 3: [0.3412334260702758, 0.3412334260702758, 1.0, 0.3011374490937829, 0.26575287272131043], 4: [0.31069657591175387, 0.31069657591175387, 0.3011374490937829, 1.0, 0.35206533556593145], 5: [0.26575287272131043, 0.35206533556593145, 1.0]}

  __init__(data, bandwidth=None, fixed=True, k=2, function='triangular', eps=1.0000001, ids=None, diagonal=False, distance_metric='euclidean', radius=None, normalize=True, **kwargs)

  Methods

  `__init__`(data[, bandwidth, fixed, k, ...]) |
  `asymmetry`([intrinsic]) | Asymmetry check.
  `from_WSP`(WSP[, silence_warnings]) | Create a pysal W from a pysal WSP object (thin weights matrix).
  `from_adjlist`(adjlist[, focal_col, ...]) | Return an adjacency list representation of a weights object.
  `from_array`(array, **kwargs) | Construct a Kernel weights from an array.
  `from_dataframe`(df[, geom_col, ids, use_index]) | Make Kernel weights from a dataframe.
  `from_file`([path, format]) | Read a weights file into a W object.
  `from_networkx`(graph[, weight_col]) | Convert a `networkx` graph to a PySAL `W` object.
  `from_shapefile`(filepath[, idVariable]) | Kernel based weights from shapefile
  `from_sparse`(sparse) | Convert a `scipy.sparse` array to a PySAL `W` object.
  `full`() | Generate a full `numpy.ndarray`.
  `get_transform`() | Getter for transform property.
  `plot`(gdf[, indexed_on, ax, color, node_kws, ...]) | Plot spatial weights objects.
  `remap_ids`(new_ids) | In place modification throughout `W` of id values from `w.id_order` to `new_ids` in all.
  `set_shapefile`(shapefile[, idVariable, full]) | Adding metadata for writing headers of `.gal` and `.gwt` files.
  `set_transform`([value]) | Transformations of weights.
  `symmetrize`([inplace]) | Construct a symmetric KNN weight.
  `to_WSP`() | Generate a `WSP` object.
  `to_adjlist`([remove_symmetric, drop_islands, ...]) | Compute an adjacency list representation of a weights object.
  `to_file`([path, format]) | Write a weights to a file.
  `to_networkx`() | Convert a weights object to a `networkx` graph.
  `to_sparse`([fmt]) | Generate a `scipy.sparse` array object from a pysal W.

  Attributes

  `asymmetries` | List of id pairs with asymmetric weights sorted in ascending index location order.
  `cardinalities` | Number of neighbors for each observation.
  `component_labels` | Store the graph component in which each observation falls.
  `diagW2` | Diagonal of \(WW\).
  `diagWtW` | Diagonal of \(W^{'}W\).
  `diagWtW_WW` | Diagonal of \(W^{'}W + WW\).
  `histogram` | Cardinality histogram as a dictionary where key is the id and value is the number of neighbors for that unit.
  `id2i` | Dictionary where the key is an ID and the value is that ID's index in `W.id_order`.
  `id_order` | Returns the ids for the observations in the order in which they would be encountered if iterating over the weights.
  `id_order_set` | Returns `True` if user has set `id_order`, `False` if not.
  `islands` | List of ids without any neighbors.
  `max_neighbors` | Largest number of neighbors.
  `mean_neighbors` | Average number of neighbors.
  `min_neighbors` | Minimum number of neighbors.
  `n` | Number of units.
  `n_components` | Store whether the adjacency matrix is fully connected.
  `neighbor_offsets` | Given the current `id_order`, `neighbor_offsets[id]` is the offsets of the id's neighbors in `id_order`.
  `nonzero` | Number of nonzero weights.
  `pct_nonzero` | Percentage of nonzero weights.
  `s0` | `s0` is defined as
  `s1` | `s1` is defined as
  `s2` | `s2` is defined as
  `s2array` | Individual elements comprising `s2`.
  `sd` | Standard deviation of number of neighbors.
  `sparse` | Sparse matrix object.
  `transform` | Getter for transform property.
  `trcW2` | Trace of \(WW\).
  `trcWtW` | Trace of \(W^{'}W\).
  `trcWtW_WW` | Trace of \(W^{'}W + WW\).

  classmethod from_array(array, **kwargs)

    Construct a Kernel weights from an array. Supports all the same options as `libpysal.weights.Kernel`

    See also

    `libpysal.weights.weights.W`
  classmethod from_dataframe(df, geom_col=None, ids=None, use_index=True, **kwargs)

    Make Kernel weights from a dataframe.

    Parameters:
      df `pandas.dataframe`

        a dataframe with a geometry column that can be used to construct a W object

      geom_col `python:str`

        the name of the column in df that contains the geometries. Defaults to active geometry column.

      ids list-like, `python:str`

        a list-like of ids to use to index the spatial weights object or the name of the column to use as IDs. If nothing is provided, the dataframe index is used if use_index=True or a positional index is used if use_index=False. Order of the resulting W is not respected from this list.

      use_index bool

        use index of df as ids to index the spatial weights object.

    See also

    `libpysal.weights.weights.W`
  classmethod from_shapefile(filepath, idVariable=None, **kwargs)

    Kernel based weights from shapefile

    Parameters:
      shapefile `python:str`

        shapefile name with shp suffix

      idVariable `python:str`

        name of column in shapefile’s DBF to use for ids

    Returns:
      `Kernel` `Weights` `Object`

    See also

    `libpysal.weights.weights.W`