# Distance-Based Weights

Distance-based weights are constructed using distance measures between all pairs of observations. The neighbor relation can be determined by a given ***distance band*****,** so every other observation that falls within the distance band is considered as neighbors of one observation. Another way to determine neighbor relation is to find ***K nearest neighbors*** (***KNN***) for each observation. 

For more information, please read: <https://geodacenter.github.io/workbook/4b_dist_weights/lab4b.html>

### 1. getMinDistancethreshold()

In order to avoid isolates (islands) that would result from too stringent a critical distance, the distance must be chosen such that each location has at least one neighbor. Such a distance conforms to a *max-min* criterion, i.e., it is the largest of the nearest neighbor distances.

```sql
function getMinDistancethreshold(String mapUid, Boolean isArc, Boolean isMile)
```

**Arguments**

| Input Arguments | Type    | Description                                                         |
| --------------- | ------- | ------------------------------------------------------------------- |
| mapUid          | String  | the unique map id                                                   |
| isArc           | boolean | if compute arc distance between two observations. Default: FALSE.   |
| isMile          | boolean | if convert distance unit from mile to kilometer(KM). Default: TRUE. |

**Return**

| **Value** | Description                                                                     |
| --------- | ------------------------------------------------------------------------------- |
| Number    | the minimum distance that makes sure each observation has at least one neighbor |

### 2. getDistanceWeights()

With the distance band, one can create a distance-based spatial weights using WINDOW function distance\_weights()

Short version:

```sql
function getDistanceWeights(String mapUid, Number distBand,
    Number power, 
    Boolean isInverse, 
    Boolean isArc,
    Boolean isMile)
```

**Arguments:**

| Input Arguments | Type    | Description                                                                                                  |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| map\_uid        | String  | the unique map id                                                                                            |
| distBand        | Number  | the distance band/threshold that makes sure each observation has at least one neighbor                       |
| power           | Number  | the power/exponent corresponds to the number of times the base (dist\_band) is used as a factor. Default: 1. |
| isInverse       | Boolean | if apply inverse on distance value. Default: False.                                                          |
| isArc           | Boolean | if compute arc distance between two observations. Default: FALSE.                                            |
| isMile          | Boolean | if convert distance unit from mile to kilometer(KM). Default: TRUE.                                          |

**Return**

| **Value**     | Description                                 |
| ------------- | ------------------------------------------- |
| WeightsResult | the weights structure for each observation. |

### 3. getKnnWeights()

```sql
function getKnnWeights(String mapUid, Number k,
    Number power, 
    Boolean isInverse, 
    Boolean isArc,
    Boolean isMile)
```

**Arguments:**

| Input Arguments | Type    | Description                                                                                                  |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| mapUid          | String  | the unique map id                                                                                            |
| k               | Number  | the k nearest neighbors                                                                                      |
| power           | Number  | the power/exponent corresponds to the number of times the base (dist\_band) is used as a factor. Default: 1. |
| isInverse       | Boolean | if apply inverse on distance value. Default: False.                                                          |
| isArc           | Boolean | if compute arc distance between two observations. Default: FALSE.                                            |
| isMile          | Boolean | if convert distance unit from mile to kilometer(KM). Default: TRUE.                                          |

**Return**

| **Value**     | Description                                 |
| ------------- | ------------------------------------------- |
| WeightsResult | the weights structure for each observation. |

**Try it yourself in the playground (jsgeoda + deck.gl):**

{% embed url="<https://codesandbox.io/s/4spatial-weights-owi84>" %}