# 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>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xunli.gitbook.io/jsgeoda/spatial-weights/distance-based-weights.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.