> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spatial statistics

> Clustering, outlier detection, hotspot detection, spatial weights, sampling, and Moran's I for Spark DataFrames.

These functions take a Spark DataFrame with a geometry column and return a new DataFrame with the result columns added.

```python theme={"system"}
from sedona.spark.stats import dbscan, g_local, add_binary_distance_band_column
```

## add\_binary\_distance\_band\_column

```python theme={"system"}
add_binary_distance_band_column(
    dataframe: DataFrame,
    threshold: float,
    include_zero_distance_neighbors: bool = True,
    include_self: bool = False,
    geometry: Optional[str] = None,
    use_spheroid: bool = False,
    saved_attributes: List[str] = None,
    result_name: str = 'weights',
) -> DataFrame
```

Annotates a dataframe with a weights column containing the other records within the threshold and their weight.

Weights will always be 1.0. The dataframe should contain at least one GeometryType column. Rows must be unique. If
one geometry column is present it will be used automatically. If two are present, the one named 'geometry' will be
used. If more than one are present and neither is named 'geometry', the column name must be provided. The new column
will be named 'cluster'.

#### Parameters

<ParamField path="dataframe" type="DataFrame" required>
  DataFrame with geometry column
</ParamField>

<ParamField path="threshold" type="float" required>
  Distance threshold for considering neighbors
</ParamField>

<ParamField path="include_zero_distance_neighbors" type="bool" default="True">
  whether to include neighbors that are 0 distance. If 0 distance neighbors are
  included and binary is false, values are infinity as per the floating point spec (divide by 0)
</ParamField>

<ParamField path="include_self" type="bool" default="False">
  whether to include self in the list of neighbors
</ParamField>

<ParamField path="geometry" type="Optional[str]" default="None">
  name of the geometry column
</ParamField>

<ParamField path="use_spheroid" type="bool" default="False">
  whether to use a cartesian or spheroidal distance calculation. Default is false
</ParamField>

<ParamField path="saved_attributes" type="List[str]" default="None">
  the attributes to save in the neighbor column. Default is all columns.
</ParamField>

<ParamField path="result_name" type="str" default="'weights'">
  the name of the resulting column. Default is 'weights'.
</ParamField>

#### Returns

<ResponseField name="return" type="DataFrame">
  The input DataFrame with a weight column added containing neighbors and their weights (always 1) added to each
  row.
</ResponseField>

## add\_distance\_band\_column

```python theme={"system"}
add_distance_band_column(
    dataframe: DataFrame,
    threshold: float,
    binary: bool = True,
    alpha: float = -1.0,
    include_zero_distance_neighbors: bool = False,
    include_self: bool = False,
    self_weight: float = 1.0,
    geometry: Optional[str] = None,
    use_spheroid: bool = False,
    saved_attributes: List[str] = None,
    result_name: str = 'weights',
) -> DataFrame
```

Annotates a dataframe with a weights column containing the other records within the threshold and their weight.

The dataframe should contain at least one GeometryType column. Rows must be unique. If one
geometry column is present it will be used automatically. If two are present, the one named
'geometry' will be used. If more than one are present and neither is named 'geometry', the
column name must be provided. The new column will be named 'cluster'.

#### Parameters

<ParamField path="dataframe" type="DataFrame" required>
  DataFrame with geometry column
</ParamField>

<ParamField path="threshold" type="float" required>
  Distance threshold for considering neighbors
</ParamField>

<ParamField path="binary" type="bool" default="True">
  whether to use binary weights or inverse distance weights for neighbors (dist^alpha)
</ParamField>

<ParamField path="alpha" type="float" default="-1.0">
  alpha to use for inverse distance weights ignored when binary is true
</ParamField>

<ParamField path="include_zero_distance_neighbors" type="bool" default="False">
  whether to include neighbors that are 0 distance. If 0 distance neighbors are
  included and binary is false, values are infinity as per the floating point spec (divide by 0)
</ParamField>

<ParamField path="include_self" type="bool" default="False">
  whether to include self in the list of neighbors
</ParamField>

<ParamField path="self_weight" type="float" default="1.0">
  the value to use for the self weight
</ParamField>

<ParamField path="geometry" type="Optional[str]" default="None">
  name of the geometry column
</ParamField>

<ParamField path="use_spheroid" type="bool" default="False">
  whether to use a cartesian or spheroidal distance calculation. Default is false
</ParamField>

<ParamField path="saved_attributes" type="List[str]" default="None">
  the attributes to save in the neighbor column. Default is all columns.
</ParamField>

<ParamField path="result_name" type="str" default="'weights'">
  the name of the resulting column. Default is 'weights'.
</ParamField>

#### Returns

<ResponseField name="return" type="DataFrame">
  The input DataFrame with a weight column added containing neighbors and their weights added to each row.
</ResponseField>

## add\_weighted\_distance\_band\_column

```python theme={"system"}
add_weighted_distance_band_column(
    dataframe: DataFrame,
    threshold: float,
    alpha: float,
    include_zero_distance_neighbors: bool = True,
    include_self: bool = False,
    self_weight: float = 1.0,
    geometry: Optional[str] = None,
    use_spheroid: bool = False,
    saved_attributes: List[str] = None,
    result_name: str = 'weights',
) -> DataFrame
```

Annotates a dataframe with a weights column containing the other records within the threshold and their weight.

Weights will be distance^alpha. The dataframe should contain at least one GeometryType column. Rows must be unique. If
one geometry column is present it will be used automatically. If two are present, the one named 'geometry' will be
used. If more than one are present and neither is named 'geometry', the column name must be provided. The new column
will be named 'cluster'.

#### Parameters

<ParamField path="dataframe" type="DataFrame" required>
  DataFrame with geometry column
</ParamField>

<ParamField path="threshold" type="float" required>
  Distance threshold for considering neighbors
</ParamField>

<ParamField path="alpha" type="float" required>
  alpha to use for inverse distance weights. Computation is dist^alpha. Default is -1.0
</ParamField>

<ParamField path="include_zero_distance_neighbors" type="bool" default="True">
  whether to include neighbors that are 0 distance. If 0 distance neighbors are
  included and binary is false, values are infinity as per the floating point spec (divide by 0)
</ParamField>

<ParamField path="include_self" type="bool" default="False">
  whether to include self in the list of neighbors
</ParamField>

<ParamField path="self_weight" type="float" default="1.0">
  the value to use for the self weight. Default is 1.0
</ParamField>

<ParamField path="geometry" type="Optional[str]" default="None">
  name of the geometry column
</ParamField>

<ParamField path="use_spheroid" type="bool" default="False">
  whether to use a cartesian or spheroidal distance calculation. Default is false
</ParamField>

<ParamField path="saved_attributes" type="List[str]" default="None">
  the attributes to save in the neighbor column. Default is all columns.
</ParamField>

<ParamField path="result_name" type="str" default="'weights'">
  the name of the resulting column. Default is 'weights'.
</ParamField>

#### Returns

<ResponseField name="return" type="DataFrame">
  The input DataFrame with a weight column added containing neighbors and their weights (always 1) added to each
  row.
</ResponseField>

## dbscan

```python theme={"system"}
dbscan(
    dataframe: DataFrame,
    epsilon: float,
    min_pts: int,
    geometry: Optional[str] = None,
    include_outliers: bool = True,
    use_sphere=False,
    is_core_column_name='isCore',
    cluster_column_name='cluster',
)
```

Annotates a dataframe with a cluster label for each data record using the DBSCAN algorithm.

The dataframe should contain at least one GeometryType column. Rows must be unique. If one geometry column is
present it will be used automatically. If two are present, the one named 'geometry' will be used. If more than one
are present and neither is named 'geometry', the column name must be provided.

#### Parameters

<ParamField path="dataframe" type="DataFrame" required>
  spark dataframe containing the geometries
</ParamField>

<ParamField path="epsilon" type="float" required>
  minimum distance parameter of DBSCAN algorithm
</ParamField>

<ParamField path="min_pts" type="int" required>
  minimum number of points parameter of DBSCAN algorithm
</ParamField>

<ParamField path="geometry" type="Optional[str]" default="None">
  name of the geometry column
</ParamField>

<ParamField path="include_outliers" type="bool" default="True">
  whether to return outlier points. If True, outliers are returned with a cluster value of -1.
  Default is False
</ParamField>

<ParamField path="use_sphere" default="False">
  whether to use a cartesian or sphere distance calculation. Default is false
</ParamField>

<ParamField path="is_core_column_name" default="'isCore'">
  what the name of the column indicating if this is a core point should be. Default is "isCore"
</ParamField>

<ParamField path="cluster_column_name" default="'cluster'">
  what the name of the column indicating the cluster id should be. Default is "cluster"
</ParamField>

#### Returns

<ResponseField name="return">
  A PySpark DataFrame containing the cluster label for each row
</ResponseField>

## g\_local

```python theme={"system"}
g_local(
    dataframe: DataFrame,
    x: str,
    weights: str = 'weights',
    permutations: int = 0,
    star: bool = False,
    island_weight: float = 0.0,
) -> DataFrame
```

Performs the Gi or Gi\* statistic on the x column of the dataframe.

Weights should be the neighbors of this row. The members of the weights should be comprised of structs containing a
value column and a neighbor column. The neighbor column should be the contents of the neighbors with the same types
as the parent row (minus neighbors). You can use `wherobots.weighing.add_distance_band_column` to achieve this. To
calculate the Gi\* statistic, ensure the focal observation is in the neighbors array (i.e. the row is in the weights
column) and `star=true`. Significance is calculated with a z score. Permutation tests are not yet implemented and
thus island weight does nothing. The following columns will be added: G, E\[G], V\[G], Z, P.

#### Parameters

<ParamField path="dataframe" type="DataFrame" required>
  the dataframe to perform the G statistic on
</ParamField>

<ParamField path="x" type="str" required>
  The column name we want to perform hotspot analysis on
</ParamField>

<ParamField path="weights" type="str" default="'weights'">
  The column name containing the neighbors array. The neighbor column should be the contents of
  the neighbors with the same types as the parent row (minus neighbors). You can use
  `wherobots.weighing.add_distance_band_column` to achieve this.
</ParamField>

<ParamField path="permutations" type="int" default="0">
  Not used. Permutation tests are not supported yet. The number of permutations to use for the
  significance test.
</ParamField>

<ParamField path="star" type="bool" default="False">
  Whether the focal observation is in the neighbors array. If true this calculates Gi\*, otherwise Gi
</ParamField>

<ParamField path="island_weight" type="float" default="0.0">
  Not used. The weight for the simulated neighbor used for records without a neighbor in perm tests
</ParamField>

#### Returns

<ResponseField name="return" type="DataFrame">
  A dataframe with the original columns plus the columns G, E\[G], V\[G], Z, P.
</ResponseField>

## local\_outlier\_factor

```python theme={"system"}
local_outlier_factor(
    dataframe: DataFrame,
    k: int = 20,
    geometry: Optional[str] = None,
    approximate_knn: bool = False,
    handle_ties: bool = False,
    use_spheroid=False,
    result_column_name: str = 'lof',
)
```

Annotates a dataframe with a column containing the local outlier factor for each data record.

The dataframe should contain at least one GeometryType column. Rows must be unique. If one geometry column is
present it will be used automatically. If two are present, the one named 'geometry' will be used. If more than one
are present and neither is named 'geometry', the column name must be provided.

#### Parameters

<ParamField path="dataframe" type="DataFrame" required>
  apache sedona idDataframe containing the point geometries
</ParamField>

<ParamField path="k" type="int" default="20">
  number of nearest neighbors that will be considered for the LOF calculation
</ParamField>

<ParamField path="geometry" type="Optional[str]" default="None">
  name of the geometry column
</ParamField>

<ParamField path="approximate_knn" type="bool" default="False">
  whether to use approximate KNN. When false will use exact KNN join. Default is False
</ParamField>

<ParamField path="handle_ties" type="bool" default="False">
  whether to handle ties in the k-distance calculation. Default is false
</ParamField>

<ParamField path="use_spheroid" default="False">
  whether to use a cartesian or spheroidal distance calculation. Default is false
</ParamField>

<ParamField path="result_column_name" type="str" default="'lof'">
  the name of the column containing the lof for each row. Default is "lof"
</ParamField>

#### Returns

<ResponseField name="return">
  A PySpark DataFrame containing the lof for each row
</ResponseField>

## Moran

```python theme={"system"}
Moran()
```

### get\_global()

```python theme={"system"}
Moran.get_global(
    df: DataFrame,
    two_tailed: bool = True,
    id_column: str = 'id',
    value_column: str = 'value',
) -> MoranResult
```

#### Parameters

<ParamField path="df" type="DataFrame" required />

<ParamField path="two_tailed" type="bool" default="True" />

<ParamField path="id_column" type="str" default="'id'" />

<ParamField path="value_column" type="str" default="'value'" />

## MoranResult

```python theme={"system"}
MoranResult(i: float, p_norm: float, z_norm: float)
```

#### Parameters

<ParamField path="i" type="float" required />

<ParamField path="p_norm" type="float" required />

<ParamField path="z_norm" type="float" required />

## spatially\_stratified\_sample

Import from `sedona.stats.sampling.spatially_stratified_sampling`.

```python theme={"system"}
spatially_stratified_sample(
    dataframe: DataFrame,
    fraction: float,
    partition_count: int,
    geometry: Optional[str] = None,
    seed: int = 42,
)
```

Spatially stratified sampling of a DataFrame containing spatial data.

#### Parameters

<ParamField path="dataframe" type="DataFrame" required>
  DataFrame containing spatial data to be sampled. Must contain a geometry column.
</ParamField>

<ParamField path="fraction" type="float" required>
  Sampling rate between 0 and 1
</ParamField>

<ParamField path="partition_count" type="int" required>
  Number of partitions to divide the data into. If not a perfect square, the number of partitions
  in each dimension will be rounded to the nearest integer.
</ParamField>

<ParamField path="geometry" type="Optional[str]" default="None">
  Column containing the geometry data. Default is "geometry"
</ParamField>

<ParamField path="seed" type="int" default="42">
  Seed for sampling the data
</ParamField>

#### Returns

<ResponseField name="return">
  the input DataFrame sampled down to the specified rate
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.