@turf/nearest-neighbor-analysis 7.1.0 → 7.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -21
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/cjs/index.d.cts +25 -6
- package/dist/esm/index.d.ts +25 -6
- package/dist/esm/index.js.map +1 -1
- package/package.json +17 -17
package/README.md
CHANGED
|
@@ -2,16 +2,42 @@
|
|
|
2
2
|
|
|
3
3
|
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
|
|
4
4
|
|
|
5
|
+
## NearestNeighborStatistics
|
|
6
|
+
|
|
7
|
+
Nearest neighbour statistics.
|
|
8
|
+
|
|
9
|
+
Type: [object][1]
|
|
10
|
+
|
|
11
|
+
### Properties
|
|
12
|
+
|
|
13
|
+
* `arealUnits` **[string][2]** 
|
|
14
|
+
* `observedMeanDistance` **[number][3]** 
|
|
15
|
+
* `expectedMeanDistance` **[number][3]** 
|
|
16
|
+
* `numberOfPoints` **[number][3]** 
|
|
17
|
+
* `zScore` **[number][3]** 
|
|
18
|
+
|
|
19
|
+
## NearestNeighborStudyArea
|
|
20
|
+
|
|
21
|
+
Nearest neighbour study area polygon feature.
|
|
22
|
+
|
|
23
|
+
Type: [object][1]
|
|
24
|
+
|
|
25
|
+
### Properties
|
|
26
|
+
|
|
27
|
+
* `properties` **[GeoJsonProperties][4]** 
|
|
28
|
+
|
|
29
|
+
* `properties.nearestNeighborAnalysis` **[NearestNeighborStatistics][5]** 
|
|
30
|
+
|
|
5
31
|
## nearestNeighborAnalysis
|
|
6
32
|
|
|
7
33
|
Nearest Neighbor Analysis calculates an index based the average distances
|
|
8
34
|
between points in the dataset, thereby providing inference as to whether the
|
|
9
35
|
data is clustered, dispersed, or randomly distributed within the study area.
|
|
10
36
|
|
|
11
|
-
It returns a [Feature
|
|
37
|
+
It returns a [Feature][4]<[Polygon][6]> of the study area, with the results of
|
|
12
38
|
the analysis attached as part of of the `nearestNeighborAnalysis` property
|
|
13
39
|
of the study area's `properties`. The attached
|
|
14
|
-
[*z*-score][
|
|
40
|
+
[*z*-score][7] indicates how many
|
|
15
41
|
standard deviations above or below the expected mean distance the data's
|
|
16
42
|
observed mean distance is. The more negative, the more clustered. The more
|
|
17
43
|
positive, the more evenly dispersed. A *z*-score between -2 and 2 indicates
|
|
@@ -21,11 +47,11 @@ dispersed.
|
|
|
21
47
|
|
|
22
48
|
**Remarks**
|
|
23
49
|
|
|
24
|
-
* Though the analysis will work on any [FeatureCollection][
|
|
25
|
-
works best with [Point][
|
|
50
|
+
* Though the analysis will work on any [FeatureCollection][8] type, it
|
|
51
|
+
works best with [Point][9] collections.
|
|
26
52
|
|
|
27
53
|
* This analysis is *very* sensitive to the study area provided.
|
|
28
|
-
If no [Feature
|
|
54
|
+
If no [Feature][4]<[Polygon][6]> is passed as the study area, the function draws a box
|
|
29
55
|
around the data, which may distort the findings. This analysis works best
|
|
30
56
|
with a bounded area of interest within with the data is either clustered,
|
|
31
57
|
dispersed, or randomly distributed. For example, a city's subway stops may
|
|
@@ -37,16 +63,15 @@ dispersed.
|
|
|
37
63
|
|
|
38
64
|
Philip J. Clark and Francis C. Evans, “Distance to Nearest Neighbor as a
|
|
39
65
|
Measure of Spatial Relationships in Populations,” *Ecology* 35, no. 4
|
|
40
|
-
(1954): 445–453, doi:[10.2307/1931034][
|
|
66
|
+
(1954): 445–453, doi:[10.2307/1931034][10].
|
|
41
67
|
|
|
42
68
|
### Parameters
|
|
43
69
|
|
|
44
|
-
* `dataset` **[FeatureCollection][
|
|
45
|
-
* `options` **[Object][
|
|
70
|
+
* `dataset` **[FeatureCollection][8]\<any>** FeatureCollection (pref. of points) to study
|
|
71
|
+
* `options` **[Object][1]** Optional parameters (optional, default `{}`)
|
|
46
72
|
|
|
47
|
-
* `options.studyArea` **[Feature][
|
|
48
|
-
* `options.
|
|
49
|
-
* `options.properties` **[Object][6]** properties (optional, default `{}`)
|
|
73
|
+
* `options.studyArea` **[Feature][4]<[Polygon][6]>?** polygon representing the study area
|
|
74
|
+
* `options.properties` **[GeoJsonProperties][4]** properties (optional, default `{}`)
|
|
50
75
|
|
|
51
76
|
### Examples
|
|
52
77
|
|
|
@@ -59,25 +84,29 @@ var nearestNeighborStudyArea = turf.nearestNeighborAnalysis(dataset);
|
|
|
59
84
|
var addToMap = [dataset, nearestNeighborStudyArea];
|
|
60
85
|
```
|
|
61
86
|
|
|
62
|
-
Returns **[
|
|
87
|
+
Returns **[NearestNeighborStudyArea][11]** A polygon of the study area or an approximation of one.
|
|
88
|
+
|
|
89
|
+
[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
|
|
90
|
+
|
|
91
|
+
[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
|
|
63
92
|
|
|
64
|
-
[
|
|
93
|
+
[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
|
|
65
94
|
|
|
66
|
-
[
|
|
95
|
+
[4]: https://tools.ietf.org/html/rfc7946#section-3.2
|
|
67
96
|
|
|
68
|
-
[
|
|
97
|
+
[5]: #nearestneighborstatistics
|
|
69
98
|
|
|
70
|
-
[
|
|
99
|
+
[6]: https://tools.ietf.org/html/rfc7946#section-3.1.6
|
|
71
100
|
|
|
72
|
-
[
|
|
101
|
+
[7]: https://en.wikipedia.org/wiki/Standard_score
|
|
73
102
|
|
|
74
|
-
[
|
|
103
|
+
[8]: https://tools.ietf.org/html/rfc7946#section-3.3
|
|
75
104
|
|
|
76
|
-
[
|
|
105
|
+
[9]: https://tools.ietf.org/html/rfc7946#section-3.1.2
|
|
77
106
|
|
|
78
|
-
[
|
|
107
|
+
[10]: http://doi.org/10.2307/1931034
|
|
79
108
|
|
|
80
|
-
[
|
|
109
|
+
[11]: #nearestneighborstudyarea
|
|
81
110
|
|
|
82
111
|
<!-- This file is automatically generated. Please don't edit it directly. If you find an error, edit the source file of the module in question (likely index.js or index.ts), and re-run "yarn docs" from the root of the turf project. -->
|
|
83
112
|
|
package/dist/cjs/index.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../index.ts"],"names":[],"mappings":";
|
|
1
|
+
{"version":3,"sources":["/home/runner/work/turf/turf/packages/turf-nearest-neighbor-analysis/dist/cjs/index.cjs","../../index.ts"],"names":[],"mappings":"AAAA;ACOA,kCAAqB;AACrB,kCAAqB;AACrB,iDAA4B;AAC5B,0CAAyB;AACzB,0CAAyB;AACzB,mDAA6B;AAC7B,kCAA4B;AAC5B;AACE;AACA;AAAA,wCAGK;AAwFP,SAAS,uBAAA,CACP,OAAA,EACA,OAAA,EAK0B;AAE1B,EAAA,QAAA,EAAU,QAAA,GAAW,CAAC,CAAA;AACtB,EAAA,MAAM,UAAA,EAAY,OAAA,CAAQ,UAAA,GAAa,sCAAA,wBAAY,OAAY,CAAC,CAAA;AAChE,EAAA,MAAM,WAAA,EAAa,OAAA,CAAQ,WAAA,GAAc,CAAC,CAAA;AAC1C,EAAA,MAAM,MAAA,EAAQ,OAAA,CAAQ,MAAA,GAAS,YAAA;AAE/B,EAAA,MAAM,SAAA,EAAkC,CAAC,CAAA;AACzC,EAAA,+BAAA,OAAY,EAAS,CAAC,OAAA,EAAA,GAAY;AAChC,IAAA,QAAA,CAAS,IAAA,CAAK,gCAAA,OAAgB,CAAC,CAAA;AAAA,EACjC,CAAC,CAAA;AACD,EAAA,MAAM,EAAA,EAAI,QAAA,CAAS,MAAA;AACnB,EAAA,MAAM,qBAAA,EACJ,QAAA,CACG,GAAA,CAAI,CAAC,OAAA,EAAS,KAAA,EAAA,GAAU;AACvB,IAAA,MAAM,cAAA,EAAgB,wCAAA;AAAA,MACpB,QAAA,CAAS,MAAA,CAAO,CAAC,CAAA,EAAG,CAAA,EAAA,GAAM;AACxB,QAAA,OAAO,EAAA,IAAM,KAAA;AAAA,MACf,CAAC;AAAA,IACH,CAAA;AAGA,IAAA,OAAO,gCAAA;AAAA,MACL,OAAA;AAAA,MACA,wCAAA,OAAa,EAAS,aAAa,CAAA,CAAE,QAAA,CAAU,WAAA;AAAA,MAC/C,EAAE,MAAM;AAAA,IACV,CAAA;AAAA,EACF,CAAC,CAAA,CACA,MAAA,CAAO,CAAC,GAAA,EAAK,KAAA,EAAA,GAAU;AACtB,IAAA,OAAO,IAAA,EAAM,KAAA;AAAA,EACf,CAAA,EAAG,CAAC,EAAA,EAAI,CAAA;AAEZ,EAAA,MAAM,kBAAA,EAAoB,EAAA,EAAI,kCAAA,wBAAY,SAAc,CAAA,EAAG,QAAA,EAAU,KAAK,CAAA;AAC1E,EAAA,MAAM,qBAAA,EAAuB,EAAA,EAAA,CAAK,EAAA,EAAI,IAAA,CAAK,IAAA,CAAK,iBAAiB,CAAA,CAAA;AACjE,EAAA,MAAM,SAAA,EAAW,QAAA,EAAU,IAAA,CAAK,IAAA,CAAK,EAAA,EAAI,iBAAiB,CAAA;AAC1D,EAAA,UAAA,CAAW,wBAAA,EAA0B;AAAA,IACnC,KAAA;AAAA,IACA,UAAA,EAAY,MAAA,EAAQ,MAAA;AAAA,IACpB,oBAAA;AAAA,IACA,oBAAA;AAAA,IACA,oBAAA,EAAsB,qBAAA,EAAuB,oBAAA;AAAA,IAC7C,cAAA,EAAgB,CAAA;AAAA,IAChB,MAAA,EAAA,CAAS,qBAAA,EAAuB,oBAAA,EAAA,EAAwB;AAAA,EAC1D,CAAA;AACA,EAAA,SAAA,CAAU,WAAA,EAAa,UAAA;AAEvB,EAAA,OAAO,SAAA;AACT;AAOA,IAAO,uCAAA,EAAQ,uBAAA;ADpHf;AACE;AACA;AACF,oHAAC","file":"/home/runner/work/turf/turf/packages/turf-nearest-neighbor-analysis/dist/cjs/index.cjs","sourcesContent":[null,"import {\n FeatureCollection,\n Feature,\n Point,\n Polygon,\n GeoJsonProperties,\n} from \"geojson\";\nimport { area } from \"@turf/area\";\nimport { bbox } from \"@turf/bbox\";\nimport { bboxPolygon } from \"@turf/bbox-polygon\";\nimport { centroid } from \"@turf/centroid\";\nimport { distance } from \"@turf/distance\";\nimport { nearestPoint } from \"@turf/nearest-point\";\nimport { featureEach } from \"@turf/meta\";\nimport {\n convertArea,\n featureCollection,\n Units,\n AreaUnits,\n} from \"@turf/helpers\";\n\n/**\n * Nearest neighbour statistics.\n *\n * @typedef {object} NearestNeighborStatistics\n * @property {(Units & AreaUnits)} units\n * @property {string} arealUnits\n * @property {number} observedMeanDistance\n * @property {number} expectedMeanDistance\n * @property {number} numberOfPoints\n * @property {number} zScore\n */\ninterface NearestNeighborStatistics {\n units: Units & AreaUnits;\n arealUnits: string;\n observedMeanDistance: number;\n expectedMeanDistance: number;\n numberOfPoints: number;\n zScore: number;\n}\n\n/**\n * Nearest neighbour study area polygon feature.\n *\n * @typedef {object} NearestNeighborStudyArea\n * @extends Feature<Polygon>\n * @property {GeoJsonProperties} properties\n * @property {NearestNeighborStatistics} properties.nearestNeighborAnalysis\n */\ninterface NearestNeighborStudyArea extends Feature<Polygon> {\n properties: {\n nearestNeighborAnalysis: NearestNeighborStatistics;\n [key: string]: any;\n };\n}\n\n/**\n * Nearest Neighbor Analysis calculates an index based the average distances\n * between points in the dataset, thereby providing inference as to whether the\n * data is clustered, dispersed, or randomly distributed within the study area.\n *\n * It returns a {@link Feature}<{@link Polygon}> of the study area, with the results of\n * the analysis attached as part of of the `nearestNeighborAnalysis` property\n * of the study area's `properties`. The attached\n * [_z_-score](https://en.wikipedia.org/wiki/Standard_score) indicates how many\n * standard deviations above or below the expected mean distance the data's\n * observed mean distance is. The more negative, the more clustered. The more\n * positive, the more evenly dispersed. A _z_-score between -2 and 2 indicates\n * a seemingly random distribution. That is, within _p_ of less than 0.05, the\n * distribution appears statistically significantly neither clustered nor\n * dispersed.\n *\n * **Remarks**\n *\n * - Though the analysis will work on any {@link FeatureCollection} type, it\n * works best with {@link Point} collections.\n *\n * - This analysis is _very_ sensitive to the study area provided.\n * If no {@link Feature}<{@link Polygon}> is passed as the study area, the function draws a box\n * around the data, which may distort the findings. This analysis works best\n * with a bounded area of interest within with the data is either clustered,\n * dispersed, or randomly distributed. For example, a city's subway stops may\n * look extremely clustered if the study area is an entire state. On the other\n * hand, they may look rather evenly dispersed if the study area is limited to\n * the city's downtown.\n *\n * **Bibliography**\n *\n * Philip J. Clark and Francis C. Evans, “Distance to Nearest Neighbor as a\n * Measure of Spatial Relationships in Populations,” _Ecology_ 35, no. 4\n * (1954): 445–453, doi:[10.2307/1931034](http://doi.org/10.2307/1931034).\n *\n * @function\n * @param {FeatureCollection<any>} dataset FeatureCollection (pref. of points) to study\n * @param {Object} [options={}] Optional parameters\n * @param {Feature<Polygon>} [options.studyArea] polygon representing the study area\n * @param {Units & AreaUnits} [options.units='kilometers'] unit of measurement for distances and, squared, area.\n * @param {GeoJsonProperties} [options.properties={}] properties\n * @returns {NearestNeighborStudyArea} A polygon of the study area or an approximation of one.\n * @example\n * var bbox = [-65, 40, -63, 42];\n * var dataset = turf.randomPoint(100, { bbox: bbox });\n * var nearestNeighborStudyArea = turf.nearestNeighborAnalysis(dataset);\n *\n * //addToMap\n * var addToMap = [dataset, nearestNeighborStudyArea];\n */\nfunction nearestNeighborAnalysis(\n dataset: FeatureCollection<any>,\n options?: {\n studyArea?: Feature<Polygon>;\n units?: Units & AreaUnits;\n properties?: GeoJsonProperties;\n }\n): NearestNeighborStudyArea {\n // Optional params\n options = options || {};\n const studyArea = options.studyArea || bboxPolygon(bbox(dataset));\n const properties = options.properties || {};\n const units = options.units || \"kilometers\";\n\n const features: Array<Feature<Point>> = [];\n featureEach(dataset, (feature) => {\n features.push(centroid(feature));\n });\n const n = features.length;\n const observedMeanDistance =\n features\n .map((feature, index) => {\n const otherFeatures = featureCollection<Point>(\n features.filter((f, i) => {\n return i !== index;\n })\n );\n // Have to add the ! to make typescript validation pass\n // see https://stackoverflow.com/a/40350534/1979085\n return distance(\n feature,\n nearestPoint(feature, otherFeatures).geometry!.coordinates,\n { units }\n );\n })\n .reduce((sum, value) => {\n return sum + value;\n }, 0) / n;\n\n const populationDensity = n / convertArea(area(studyArea), \"meters\", units);\n const expectedMeanDistance = 1 / (2 * Math.sqrt(populationDensity));\n const variance = 0.26136 / Math.sqrt(n * populationDensity);\n properties.nearestNeighborAnalysis = {\n units: units,\n arealUnits: units + \"²\",\n observedMeanDistance: observedMeanDistance,\n expectedMeanDistance: expectedMeanDistance,\n nearestNeighborIndex: observedMeanDistance / expectedMeanDistance,\n numberOfPoints: n,\n zScore: (observedMeanDistance - expectedMeanDistance) / variance,\n };\n studyArea.properties = properties;\n\n return studyArea as NearestNeighborStudyArea;\n}\n\nexport {\n nearestNeighborAnalysis,\n NearestNeighborStatistics,\n NearestNeighborStudyArea,\n};\nexport default nearestNeighborAnalysis;\n"]}
|
package/dist/cjs/index.d.cts
CHANGED
|
@@ -1,6 +1,17 @@
|
|
|
1
1
|
import { Feature, Polygon, FeatureCollection, GeoJsonProperties } from 'geojson';
|
|
2
2
|
import { Units, AreaUnits } from '@turf/helpers';
|
|
3
3
|
|
|
4
|
+
/**
|
|
5
|
+
* Nearest neighbour statistics.
|
|
6
|
+
*
|
|
7
|
+
* @typedef {object} NearestNeighborStatistics
|
|
8
|
+
* @property {(Units & AreaUnits)} units
|
|
9
|
+
* @property {string} arealUnits
|
|
10
|
+
* @property {number} observedMeanDistance
|
|
11
|
+
* @property {number} expectedMeanDistance
|
|
12
|
+
* @property {number} numberOfPoints
|
|
13
|
+
* @property {number} zScore
|
|
14
|
+
*/
|
|
4
15
|
interface NearestNeighborStatistics {
|
|
5
16
|
units: Units & AreaUnits;
|
|
6
17
|
arealUnits: string;
|
|
@@ -9,6 +20,14 @@ interface NearestNeighborStatistics {
|
|
|
9
20
|
numberOfPoints: number;
|
|
10
21
|
zScore: number;
|
|
11
22
|
}
|
|
23
|
+
/**
|
|
24
|
+
* Nearest neighbour study area polygon feature.
|
|
25
|
+
*
|
|
26
|
+
* @typedef {object} NearestNeighborStudyArea
|
|
27
|
+
* @extends Feature<Polygon>
|
|
28
|
+
* @property {GeoJsonProperties} properties
|
|
29
|
+
* @property {NearestNeighborStatistics} properties.nearestNeighborAnalysis
|
|
30
|
+
*/
|
|
12
31
|
interface NearestNeighborStudyArea extends Feature<Polygon> {
|
|
13
32
|
properties: {
|
|
14
33
|
nearestNeighborAnalysis: NearestNeighborStatistics;
|
|
@@ -20,7 +39,7 @@ interface NearestNeighborStudyArea extends Feature<Polygon> {
|
|
|
20
39
|
* between points in the dataset, thereby providing inference as to whether the
|
|
21
40
|
* data is clustered, dispersed, or randomly distributed within the study area.
|
|
22
41
|
*
|
|
23
|
-
* It returns a {@link Feature<Polygon>
|
|
42
|
+
* It returns a {@link Feature}<{@link Polygon}> of the study area, with the results of
|
|
24
43
|
* the analysis attached as part of of the `nearestNeighborAnalysis` property
|
|
25
44
|
* of the study area's `properties`. The attached
|
|
26
45
|
* [_z_-score](https://en.wikipedia.org/wiki/Standard_score) indicates how many
|
|
@@ -37,7 +56,7 @@ interface NearestNeighborStudyArea extends Feature<Polygon> {
|
|
|
37
56
|
* works best with {@link Point} collections.
|
|
38
57
|
*
|
|
39
58
|
* - This analysis is _very_ sensitive to the study area provided.
|
|
40
|
-
* If no {@link Feature<Polygon>
|
|
59
|
+
* If no {@link Feature}<{@link Polygon}> is passed as the study area, the function draws a box
|
|
41
60
|
* around the data, which may distort the findings. This analysis works best
|
|
42
61
|
* with a bounded area of interest within with the data is either clustered,
|
|
43
62
|
* dispersed, or randomly distributed. For example, a city's subway stops may
|
|
@@ -51,13 +70,13 @@ interface NearestNeighborStudyArea extends Feature<Polygon> {
|
|
|
51
70
|
* Measure of Spatial Relationships in Populations,” _Ecology_ 35, no. 4
|
|
52
71
|
* (1954): 445–453, doi:[10.2307/1931034](http://doi.org/10.2307/1931034).
|
|
53
72
|
*
|
|
54
|
-
* @
|
|
73
|
+
* @function
|
|
55
74
|
* @param {FeatureCollection<any>} dataset FeatureCollection (pref. of points) to study
|
|
56
75
|
* @param {Object} [options={}] Optional parameters
|
|
57
76
|
* @param {Feature<Polygon>} [options.studyArea] polygon representing the study area
|
|
58
|
-
* @param {
|
|
59
|
-
* @param {
|
|
60
|
-
* @returns {
|
|
77
|
+
* @param {Units & AreaUnits} [options.units='kilometers'] unit of measurement for distances and, squared, area.
|
|
78
|
+
* @param {GeoJsonProperties} [options.properties={}] properties
|
|
79
|
+
* @returns {NearestNeighborStudyArea} A polygon of the study area or an approximation of one.
|
|
61
80
|
* @example
|
|
62
81
|
* var bbox = [-65, 40, -63, 42];
|
|
63
82
|
* var dataset = turf.randomPoint(100, { bbox: bbox });
|
package/dist/esm/index.d.ts
CHANGED
|
@@ -1,6 +1,17 @@
|
|
|
1
1
|
import { Feature, Polygon, FeatureCollection, GeoJsonProperties } from 'geojson';
|
|
2
2
|
import { Units, AreaUnits } from '@turf/helpers';
|
|
3
3
|
|
|
4
|
+
/**
|
|
5
|
+
* Nearest neighbour statistics.
|
|
6
|
+
*
|
|
7
|
+
* @typedef {object} NearestNeighborStatistics
|
|
8
|
+
* @property {(Units & AreaUnits)} units
|
|
9
|
+
* @property {string} arealUnits
|
|
10
|
+
* @property {number} observedMeanDistance
|
|
11
|
+
* @property {number} expectedMeanDistance
|
|
12
|
+
* @property {number} numberOfPoints
|
|
13
|
+
* @property {number} zScore
|
|
14
|
+
*/
|
|
4
15
|
interface NearestNeighborStatistics {
|
|
5
16
|
units: Units & AreaUnits;
|
|
6
17
|
arealUnits: string;
|
|
@@ -9,6 +20,14 @@ interface NearestNeighborStatistics {
|
|
|
9
20
|
numberOfPoints: number;
|
|
10
21
|
zScore: number;
|
|
11
22
|
}
|
|
23
|
+
/**
|
|
24
|
+
* Nearest neighbour study area polygon feature.
|
|
25
|
+
*
|
|
26
|
+
* @typedef {object} NearestNeighborStudyArea
|
|
27
|
+
* @extends Feature<Polygon>
|
|
28
|
+
* @property {GeoJsonProperties} properties
|
|
29
|
+
* @property {NearestNeighborStatistics} properties.nearestNeighborAnalysis
|
|
30
|
+
*/
|
|
12
31
|
interface NearestNeighborStudyArea extends Feature<Polygon> {
|
|
13
32
|
properties: {
|
|
14
33
|
nearestNeighborAnalysis: NearestNeighborStatistics;
|
|
@@ -20,7 +39,7 @@ interface NearestNeighborStudyArea extends Feature<Polygon> {
|
|
|
20
39
|
* between points in the dataset, thereby providing inference as to whether the
|
|
21
40
|
* data is clustered, dispersed, or randomly distributed within the study area.
|
|
22
41
|
*
|
|
23
|
-
* It returns a {@link Feature<Polygon>
|
|
42
|
+
* It returns a {@link Feature}<{@link Polygon}> of the study area, with the results of
|
|
24
43
|
* the analysis attached as part of of the `nearestNeighborAnalysis` property
|
|
25
44
|
* of the study area's `properties`. The attached
|
|
26
45
|
* [_z_-score](https://en.wikipedia.org/wiki/Standard_score) indicates how many
|
|
@@ -37,7 +56,7 @@ interface NearestNeighborStudyArea extends Feature<Polygon> {
|
|
|
37
56
|
* works best with {@link Point} collections.
|
|
38
57
|
*
|
|
39
58
|
* - This analysis is _very_ sensitive to the study area provided.
|
|
40
|
-
* If no {@link Feature<Polygon>
|
|
59
|
+
* If no {@link Feature}<{@link Polygon}> is passed as the study area, the function draws a box
|
|
41
60
|
* around the data, which may distort the findings. This analysis works best
|
|
42
61
|
* with a bounded area of interest within with the data is either clustered,
|
|
43
62
|
* dispersed, or randomly distributed. For example, a city's subway stops may
|
|
@@ -51,13 +70,13 @@ interface NearestNeighborStudyArea extends Feature<Polygon> {
|
|
|
51
70
|
* Measure of Spatial Relationships in Populations,” _Ecology_ 35, no. 4
|
|
52
71
|
* (1954): 445–453, doi:[10.2307/1931034](http://doi.org/10.2307/1931034).
|
|
53
72
|
*
|
|
54
|
-
* @
|
|
73
|
+
* @function
|
|
55
74
|
* @param {FeatureCollection<any>} dataset FeatureCollection (pref. of points) to study
|
|
56
75
|
* @param {Object} [options={}] Optional parameters
|
|
57
76
|
* @param {Feature<Polygon>} [options.studyArea] polygon representing the study area
|
|
58
|
-
* @param {
|
|
59
|
-
* @param {
|
|
60
|
-
* @returns {
|
|
77
|
+
* @param {Units & AreaUnits} [options.units='kilometers'] unit of measurement for distances and, squared, area.
|
|
78
|
+
* @param {GeoJsonProperties} [options.properties={}] properties
|
|
79
|
+
* @returns {NearestNeighborStudyArea} A polygon of the study area or an approximation of one.
|
|
61
80
|
* @example
|
|
62
81
|
* var bbox = [-65, 40, -63, 42];
|
|
63
82
|
* var dataset = turf.randomPoint(100, { bbox: bbox });
|
package/dist/esm/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../index.ts"],"sourcesContent":["import {\n FeatureCollection,\n Feature,\n Point,\n Polygon,\n GeoJsonProperties,\n} from \"geojson\";\nimport { area } from \"@turf/area\";\nimport { bbox } from \"@turf/bbox\";\nimport { bboxPolygon } from \"@turf/bbox-polygon\";\nimport { centroid } from \"@turf/centroid\";\nimport { distance } from \"@turf/distance\";\nimport { nearestPoint } from \"@turf/nearest-point\";\nimport { featureEach } from \"@turf/meta\";\nimport {\n convertArea,\n featureCollection,\n Units,\n AreaUnits,\n} from \"@turf/helpers\";\n\ninterface NearestNeighborStatistics {\n units: Units & AreaUnits;\n arealUnits: string;\n observedMeanDistance: number;\n expectedMeanDistance: number;\n numberOfPoints: number;\n zScore: number;\n}\n\ninterface NearestNeighborStudyArea extends Feature<Polygon> {\n properties: {\n nearestNeighborAnalysis: NearestNeighborStatistics;\n [key: string]: any;\n };\n}\n\n/**\n * Nearest Neighbor Analysis calculates an index based the average distances\n * between points in the dataset, thereby providing inference as to whether the\n * data is clustered, dispersed, or randomly distributed within the study area.\n *\n * It returns a {@link Feature<Polygon>
|
|
1
|
+
{"version":3,"sources":["../../index.ts"],"sourcesContent":["import {\n FeatureCollection,\n Feature,\n Point,\n Polygon,\n GeoJsonProperties,\n} from \"geojson\";\nimport { area } from \"@turf/area\";\nimport { bbox } from \"@turf/bbox\";\nimport { bboxPolygon } from \"@turf/bbox-polygon\";\nimport { centroid } from \"@turf/centroid\";\nimport { distance } from \"@turf/distance\";\nimport { nearestPoint } from \"@turf/nearest-point\";\nimport { featureEach } from \"@turf/meta\";\nimport {\n convertArea,\n featureCollection,\n Units,\n AreaUnits,\n} from \"@turf/helpers\";\n\n/**\n * Nearest neighbour statistics.\n *\n * @typedef {object} NearestNeighborStatistics\n * @property {(Units & AreaUnits)} units\n * @property {string} arealUnits\n * @property {number} observedMeanDistance\n * @property {number} expectedMeanDistance\n * @property {number} numberOfPoints\n * @property {number} zScore\n */\ninterface NearestNeighborStatistics {\n units: Units & AreaUnits;\n arealUnits: string;\n observedMeanDistance: number;\n expectedMeanDistance: number;\n numberOfPoints: number;\n zScore: number;\n}\n\n/**\n * Nearest neighbour study area polygon feature.\n *\n * @typedef {object} NearestNeighborStudyArea\n * @extends Feature<Polygon>\n * @property {GeoJsonProperties} properties\n * @property {NearestNeighborStatistics} properties.nearestNeighborAnalysis\n */\ninterface NearestNeighborStudyArea extends Feature<Polygon> {\n properties: {\n nearestNeighborAnalysis: NearestNeighborStatistics;\n [key: string]: any;\n };\n}\n\n/**\n * Nearest Neighbor Analysis calculates an index based the average distances\n * between points in the dataset, thereby providing inference as to whether the\n * data is clustered, dispersed, or randomly distributed within the study area.\n *\n * It returns a {@link Feature}<{@link Polygon}> of the study area, with the results of\n * the analysis attached as part of of the `nearestNeighborAnalysis` property\n * of the study area's `properties`. The attached\n * [_z_-score](https://en.wikipedia.org/wiki/Standard_score) indicates how many\n * standard deviations above or below the expected mean distance the data's\n * observed mean distance is. The more negative, the more clustered. The more\n * positive, the more evenly dispersed. A _z_-score between -2 and 2 indicates\n * a seemingly random distribution. That is, within _p_ of less than 0.05, the\n * distribution appears statistically significantly neither clustered nor\n * dispersed.\n *\n * **Remarks**\n *\n * - Though the analysis will work on any {@link FeatureCollection} type, it\n * works best with {@link Point} collections.\n *\n * - This analysis is _very_ sensitive to the study area provided.\n * If no {@link Feature}<{@link Polygon}> is passed as the study area, the function draws a box\n * around the data, which may distort the findings. This analysis works best\n * with a bounded area of interest within with the data is either clustered,\n * dispersed, or randomly distributed. For example, a city's subway stops may\n * look extremely clustered if the study area is an entire state. On the other\n * hand, they may look rather evenly dispersed if the study area is limited to\n * the city's downtown.\n *\n * **Bibliography**\n *\n * Philip J. Clark and Francis C. Evans, “Distance to Nearest Neighbor as a\n * Measure of Spatial Relationships in Populations,” _Ecology_ 35, no. 4\n * (1954): 445–453, doi:[10.2307/1931034](http://doi.org/10.2307/1931034).\n *\n * @function\n * @param {FeatureCollection<any>} dataset FeatureCollection (pref. of points) to study\n * @param {Object} [options={}] Optional parameters\n * @param {Feature<Polygon>} [options.studyArea] polygon representing the study area\n * @param {Units & AreaUnits} [options.units='kilometers'] unit of measurement for distances and, squared, area.\n * @param {GeoJsonProperties} [options.properties={}] properties\n * @returns {NearestNeighborStudyArea} A polygon of the study area or an approximation of one.\n * @example\n * var bbox = [-65, 40, -63, 42];\n * var dataset = turf.randomPoint(100, { bbox: bbox });\n * var nearestNeighborStudyArea = turf.nearestNeighborAnalysis(dataset);\n *\n * //addToMap\n * var addToMap = [dataset, nearestNeighborStudyArea];\n */\nfunction nearestNeighborAnalysis(\n dataset: FeatureCollection<any>,\n options?: {\n studyArea?: Feature<Polygon>;\n units?: Units & AreaUnits;\n properties?: GeoJsonProperties;\n }\n): NearestNeighborStudyArea {\n // Optional params\n options = options || {};\n const studyArea = options.studyArea || bboxPolygon(bbox(dataset));\n const properties = options.properties || {};\n const units = options.units || \"kilometers\";\n\n const features: Array<Feature<Point>> = [];\n featureEach(dataset, (feature) => {\n features.push(centroid(feature));\n });\n const n = features.length;\n const observedMeanDistance =\n features\n .map((feature, index) => {\n const otherFeatures = featureCollection<Point>(\n features.filter((f, i) => {\n return i !== index;\n })\n );\n // Have to add the ! to make typescript validation pass\n // see https://stackoverflow.com/a/40350534/1979085\n return distance(\n feature,\n nearestPoint(feature, otherFeatures).geometry!.coordinates,\n { units }\n );\n })\n .reduce((sum, value) => {\n return sum + value;\n }, 0) / n;\n\n const populationDensity = n / convertArea(area(studyArea), \"meters\", units);\n const expectedMeanDistance = 1 / (2 * Math.sqrt(populationDensity));\n const variance = 0.26136 / Math.sqrt(n * populationDensity);\n properties.nearestNeighborAnalysis = {\n units: units,\n arealUnits: units + \"²\",\n observedMeanDistance: observedMeanDistance,\n expectedMeanDistance: expectedMeanDistance,\n nearestNeighborIndex: observedMeanDistance / expectedMeanDistance,\n numberOfPoints: n,\n zScore: (observedMeanDistance - expectedMeanDistance) / variance,\n };\n studyArea.properties = properties;\n\n return studyArea as NearestNeighborStudyArea;\n}\n\nexport {\n nearestNeighborAnalysis,\n NearestNeighborStatistics,\n NearestNeighborStudyArea,\n};\nexport default nearestNeighborAnalysis;\n"],"mappings":";AAOA,SAAS,YAAY;AACrB,SAAS,YAAY;AACrB,SAAS,mBAAmB;AAC5B,SAAS,gBAAgB;AACzB,SAAS,gBAAgB;AACzB,SAAS,oBAAoB;AAC7B,SAAS,mBAAmB;AAC5B;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AAwFP,SAAS,wBACP,SACA,SAK0B;AAE1B,YAAU,WAAW,CAAC;AACtB,QAAM,YAAY,QAAQ,aAAa,YAAY,KAAK,OAAO,CAAC;AAChE,QAAM,aAAa,QAAQ,cAAc,CAAC;AAC1C,QAAM,QAAQ,QAAQ,SAAS;AAE/B,QAAM,WAAkC,CAAC;AACzC,cAAY,SAAS,CAAC,YAAY;AAChC,aAAS,KAAK,SAAS,OAAO,CAAC;AAAA,EACjC,CAAC;AACD,QAAM,IAAI,SAAS;AACnB,QAAM,uBACJ,SACG,IAAI,CAAC,SAAS,UAAU;AACvB,UAAM,gBAAgB;AAAA,MACpB,SAAS,OAAO,CAAC,GAAG,MAAM;AACxB,eAAO,MAAM;AAAA,MACf,CAAC;AAAA,IACH;AAGA,WAAO;AAAA,MACL;AAAA,MACA,aAAa,SAAS,aAAa,EAAE,SAAU;AAAA,MAC/C,EAAE,MAAM;AAAA,IACV;AAAA,EACF,CAAC,EACA,OAAO,CAAC,KAAK,UAAU;AACtB,WAAO,MAAM;AAAA,EACf,GAAG,CAAC,IAAI;AAEZ,QAAM,oBAAoB,IAAI,YAAY,KAAK,SAAS,GAAG,UAAU,KAAK;AAC1E,QAAM,uBAAuB,KAAK,IAAI,KAAK,KAAK,iBAAiB;AACjE,QAAM,WAAW,UAAU,KAAK,KAAK,IAAI,iBAAiB;AAC1D,aAAW,0BAA0B;AAAA,IACnC;AAAA,IACA,YAAY,QAAQ;AAAA,IACpB;AAAA,IACA;AAAA,IACA,sBAAsB,uBAAuB;AAAA,IAC7C,gBAAgB;AAAA,IAChB,SAAS,uBAAuB,wBAAwB;AAAA,EAC1D;AACA,YAAU,aAAa;AAEvB,SAAO;AACT;AAOA,IAAO,yCAAQ;","names":[]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@turf/nearest-neighbor-analysis",
|
|
3
|
-
"version": "7.
|
|
3
|
+
"version": "7.2.0",
|
|
4
4
|
"description": "turf nearest-neighbor-analysis module",
|
|
5
5
|
"author": "Turf Authors",
|
|
6
6
|
"contributors": [
|
|
@@ -52,29 +52,29 @@
|
|
|
52
52
|
"test:tape": "tsx test.ts"
|
|
53
53
|
},
|
|
54
54
|
"devDependencies": {
|
|
55
|
-
"@turf/truncate": "^7.
|
|
55
|
+
"@turf/truncate": "^7.2.0",
|
|
56
56
|
"@types/benchmark": "^2.1.5",
|
|
57
|
-
"@types/tape": "^4.
|
|
57
|
+
"@types/tape": "^4.13.4",
|
|
58
58
|
"benchmark": "^2.1.4",
|
|
59
59
|
"load-json-file": "^7.0.1",
|
|
60
60
|
"npm-run-all": "^4.1.5",
|
|
61
|
-
"tape": "^5.
|
|
62
|
-
"tsup": "^8.
|
|
63
|
-
"tsx": "^4.
|
|
64
|
-
"typescript": "^5.
|
|
61
|
+
"tape": "^5.9.0",
|
|
62
|
+
"tsup": "^8.3.5",
|
|
63
|
+
"tsx": "^4.19.2",
|
|
64
|
+
"typescript": "^5.5.4",
|
|
65
65
|
"write-json-file": "^5.0.0"
|
|
66
66
|
},
|
|
67
67
|
"dependencies": {
|
|
68
|
-
"@turf/area": "^7.
|
|
69
|
-
"@turf/bbox": "^7.
|
|
70
|
-
"@turf/bbox-polygon": "^7.
|
|
71
|
-
"@turf/centroid": "^7.
|
|
72
|
-
"@turf/distance": "^7.
|
|
73
|
-
"@turf/helpers": "^7.
|
|
74
|
-
"@turf/meta": "^7.
|
|
75
|
-
"@turf/nearest-point": "^7.
|
|
68
|
+
"@turf/area": "^7.2.0",
|
|
69
|
+
"@turf/bbox": "^7.2.0",
|
|
70
|
+
"@turf/bbox-polygon": "^7.2.0",
|
|
71
|
+
"@turf/centroid": "^7.2.0",
|
|
72
|
+
"@turf/distance": "^7.2.0",
|
|
73
|
+
"@turf/helpers": "^7.2.0",
|
|
74
|
+
"@turf/meta": "^7.2.0",
|
|
75
|
+
"@turf/nearest-point": "^7.2.0",
|
|
76
76
|
"@types/geojson": "^7946.0.10",
|
|
77
|
-
"tslib": "^2.
|
|
77
|
+
"tslib": "^2.8.1"
|
|
78
78
|
},
|
|
79
|
-
"gitHead": "
|
|
79
|
+
"gitHead": "7b0f0374c4668cd569f8904c71e2ae7d941be867"
|
|
80
80
|
}
|