updated geo guides to address PR feedback
Scott Anderson
parent
0582681680
commit
eb218e8993
|
|
@ -11,19 +11,31 @@ weight: 220
|
|||
|
||||
Use the [Flux Geo package](/v2.0/reference/flux/stdlib/experimental/geo) to
|
||||
filter geo-temporal data and group by geographic location or track.
|
||||
Import the `experimental/geo` package.
|
||||
|
||||
```js
|
||||
import "experimental/geo"
|
||||
```
|
||||
|
||||
{{% warn %}}
|
||||
The Geo package is experimental and subject to change at any time.
|
||||
By using it, you agree to the [risks of experimental functions](/v2.0/reference/flux/stdlib/experimental/#use-experimental-functions-at-your-own-risk).
|
||||
{{% /warn %}}
|
||||
|
||||
**To work with geo-temporal data:**
|
||||
|
||||
1. Import the `experimental/geo` package.
|
||||
|
||||
```js
|
||||
import "experimental/geo"
|
||||
```
|
||||
|
||||
2. Load geo-temporal data. _See below for [sample geo-temporal data](#sample-data)._
|
||||
3. Do one or more of the following:
|
||||
|
||||
- [Shape data to work with the Geo package](#shape-data-to-work-with-the-geo-package)
|
||||
- [Filter data by region](#filter-geo-temporal-data-by-region) (using strict or non-strict filters)
|
||||
- [Group data by area or by track](#group-geo-temporal-data)
|
||||
|
||||
{{< children >}}
|
||||
|
||||
---
|
||||
|
||||
## Sample data
|
||||
Many of the examples in this section use a `sampleGeoData` variable that represents
|
||||
a sample set of geo-temporal data.
|
||||
|
|
@ -44,7 +56,7 @@ sampleGeoData = csv.from(
|
|||
```
|
||||
|
||||
{{% note %}}
|
||||
This downloads all the sample data each time you execute the query **(~1.3 MB)**.
|
||||
`csv.from(url: ...)` downloads sample data each time you execute the query **(~1.3 MB)**.
|
||||
If bandwidth is a concern, use the [`to()` function](/v2.0/reference/flux/stdlib/built-in/outputs/to/)
|
||||
to write the data to a bucket, and then query the bucket with [`from()`](/v2.0/reference/flux/stdlib/built-in/inputs/from/).
|
||||
{{% /note %}}
|
||||
|
|
|
|||
|
|
@ -19,13 +19,11 @@ list_code_example: |
|
|||
```
|
||||
---
|
||||
|
||||
Use the [`geo.fitlerRows` function](/v2.0/reference/flux/stdlib/geo/filterrows/)
|
||||
to filter geo-temporal data by geographic region.
|
||||
Define a box-shaped, circular, or polygonal region to filter by.
|
||||
Enable or disable strict filtering.
|
||||
Use the [`geo.filterRows` function](/v2.0/reference/flux/stdlib/geo/filterrows/)
|
||||
to filter geo-temporal data by geographic region:
|
||||
|
||||
- [Define geographic regions](#define-geographic-regions)
|
||||
- [Strict and non-strict filtering](#strict-and-non-strict-filtering)
|
||||
1. [Define a geographic region](#define-geographic-regions)
|
||||
2. [Use strict or non-strict filtering](#strict-and-non-strict-filtering)
|
||||
|
||||
The following example uses the [sample bird migration data](/v2.0/query-data/flux/geo/#sample-data)
|
||||
and queries data points **within 200km of Cairo, Egypt**:
|
||||
|
|
@ -40,9 +38,9 @@ sampleGeoData
|
|||
)
|
||||
```
|
||||
|
||||
## Define geographic regions
|
||||
## Define a geographic region
|
||||
Many functions in the Geo package filter data based on geographic region.
|
||||
Define geographic regions using the following shapes:
|
||||
Define a geographic region using one of the the following shapes:
|
||||
|
||||
- [box](#box)
|
||||
- [circle](#circle)
|
||||
|
|
@ -83,7 +81,8 @@ Define a circular region by specifying an object containing the following proper
|
|||
```
|
||||
|
||||
### polygon
|
||||
Define a custom polygon region using an object containing the following properties:
|
||||
Define a polygonal region with an object containing the latitude and longitude for
|
||||
each point in the polygon:
|
||||
|
||||
- **points**: points that define the custom polygon _(Array of objects)_
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
title: Group geo-temporal data
|
||||
description: >
|
||||
Use the `geo.groupByArea()` and `geo.groupByTrack()` functions to group geo-temporal
|
||||
data points by area or by tracks or routes.
|
||||
Use the `geo.groupByArea()` to group geo-temporal data by area and `geo.asTracks()`
|
||||
to group data into tracks or routes.
|
||||
menu:
|
||||
v2_0:
|
||||
parent: Geo-temporal data
|
||||
|
|
@ -17,8 +17,8 @@ list_code_example: |
|
|||
```
|
||||
---
|
||||
|
||||
Use the `geo.groupByArea()` and `geo.asTracks()` functions to group geo-temporal
|
||||
data points by area or by tracks or routes.
|
||||
Use the `geo.groupByArea()` to group geo-temporal data by area and `geo.asTracks()`
|
||||
to group data into tracks or routes.
|
||||
|
||||
- [Group data by area](#group-data-by-area)
|
||||
- [Group data into tracks or routes](#group-data-into-tracks-or-routes)
|
||||
|
|
@ -28,9 +28,9 @@ Use the [`geo.groupByArea()` function](/v2.0/reference/flux/stdlib/experimental/
|
|||
to group geo-temporal data points by geographic area.
|
||||
Areas are determined by [S2 grid cells](https://s2geometry.io/devguide/s2cell_hierarchy.html#s2cellid-numbering)
|
||||
|
||||
- Use the `newColumn` parameter to specify a new column in which to store the unique area identifier for each point.
|
||||
- Use the `level` parameter to specify the [S2 cell level](https://s2geometry.io/resources/s2cell_statistics)
|
||||
to use when calculating geographic areas.
|
||||
- Specify a new column to store the unique area identifier for each point with the `newColumn` parameter.
|
||||
- Specify the [S2 cell level](https://s2geometry.io/resources/s2cell_statistics)
|
||||
to use when calculating geographic areas with the `level` parameter.
|
||||
|
||||
The following example uses the [sample bird migration data](/v2.0/query-data/flux/geo/#sample-data)
|
||||
to query data points within 200km of Cairo, Egypt and group them by geographic area:
|
||||
|
|
@ -46,13 +46,13 @@ sampleGeoData
|
|||
)
|
||||
```
|
||||
|
||||
### Group data into tracks or routes
|
||||
### Group data by track or route
|
||||
Use [`geo.asTracks()` function](/v2.0/reference/flux/stdlib/experimental/geo/astracks/)
|
||||
to group data points into tracks or routes and order them by time or other columns.
|
||||
Data must contain a unique identifier for each track. For example: `id` or `tid`.
|
||||
|
||||
- Use the `groupBy` parameter to specify columns that uniquely identify each track or route.
|
||||
- Use the `sortBy` parameter to specify which columns to sort by. Default is `["_time"]`.
|
||||
- Specify columns that uniquely identify each track or route with the `groupBy` parameter.
|
||||
- Specify which columns to sort by with the `sortBy` parameter. Default is `["_time"]`.
|
||||
|
||||
The following example uses the [sample bird migration data](/v2.0/query-data/flux/geo/#sample-data)
|
||||
to query data points within 200km of Cairo, Egypt and group them into routes unique
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ Functions in the Geo package require the following data schema:
|
|||
|
||||
## Rename latitude and longitude fields
|
||||
Use [`map()`](/v2.0/reference/flux/stdlib/built-in/transformations/map/) to rename
|
||||
existing latitude and longitude fields keys using other names.
|
||||
existing latitude and longitude fields using other names.
|
||||
|
||||
```js
|
||||
from(bucket: "example-bucket")
|
||||
|
|
@ -53,31 +53,29 @@ from(bucket: "example-bucket")
|
|||
```
|
||||
|
||||
## Generate S2 cell ID tokens
|
||||
The Geo package uses the [S2 Geometry Library](https://s2geometry.io/) which
|
||||
represents geographic coordinates on a three-dimensional sphere.
|
||||
The Geo package uses the [S2 Geometry Library](https://s2geometry.io/) to represent
|
||||
geographic coordinates on a three-dimensional sphere.
|
||||
The sphere is divided into [cells](https://s2geometry.io/devguide/s2cell_hierarchy),
|
||||
each with a unique 64-bit identifier (S2 cell ID).
|
||||
Grid and S2 cell ID accuracy are defined by a [level](https://s2geometry.io/resources/s2cell_statistics).
|
||||
|
||||
{{% note %}}
|
||||
For faster filtering, use higher S2 Cell ID levels.
|
||||
But know that that higher levels increase [series cardinality](/v2.0/reference/glossary/#series-cardinality).
|
||||
To filter more quickly, use higher S2 Cell ID levels,
|
||||
but know that that higher levels increase [series cardinality](/v2.0/reference/glossary/#series-cardinality).
|
||||
{{% /note %}}
|
||||
|
||||
The Geo package requires S2 cell IDs as tokens.
|
||||
Use one of the following options to generate and add S2 cell IDs to your geo-temporal data:
|
||||
To generate add S2 cell IDs tokens to your data, use one of the following options:
|
||||
|
||||
- [Use the Telegraf S2 Geo processor](#use-the-telegraf-s2-geo-processor)
|
||||
- [Use language-specific S2 libraries](#use-language-specific-s2-libraries)
|
||||
- [Add S2 cell ID token with Flux](#add-s2-cell-id-token-with-flux)
|
||||
- [Generate S2 cell ID tokens with Telegraf](#generate-s2-cell-id-tokens-with-telegraf)
|
||||
- [Generate S2 cell ID tokens language-specific libraries](#generate-s2-cell-id-tokens-language-specific-libraries)
|
||||
- [Generate S2 cell ID tokens with Flux](#generate-s2-cell-id-tokens-with-flux)
|
||||
|
||||
### Use the Telegraf S2 Geo processor
|
||||
The [Telegraf S2 Geo (`s2geo`) processor](https://github.com/influxdata/telegraf/tree/master/plugins/processors/s2geo)
|
||||
uses `lat` and `lon` field values to generate S2 cell ID tokens at a specified `cell_level`.
|
||||
### Generate S2 cell ID tokens with Telegraf
|
||||
Enable the [Telegraf S2 Geo (`s2geo`) processor](https://github.com/influxdata/telegraf/tree/master/plugins/processors/s2geo)
|
||||
to generate S2 cell ID tokens at a specified `cell_level` using `lat` and `lon` field values.
|
||||
|
||||
To have Telegraf use existing latitude
|
||||
and longitude values to generate S2 cell ID tokens and assign them to the `s2_cell_id`
|
||||
tag in each line of line protocol, add the following to your `telegraf.conf`:
|
||||
Add the `processors.s2geo` configuration to your Telegraf configuration file (`telegraf.conf`):
|
||||
|
||||
```toml
|
||||
[[processors.s2geo]]
|
||||
|
|
@ -93,7 +91,9 @@ tag in each line of line protocol, add the following to your `telegraf.conf`:
|
|||
cell_level = 9
|
||||
```
|
||||
|
||||
### Use language-specific S2 libraries
|
||||
Telegraf stores the S2 cell ID token in the `s2_cell_id` tag.
|
||||
|
||||
### Generate S2 cell ID tokens language-specific libraries
|
||||
Many programming languages offer S2 Libraries with methods for generating S2 cell ID tokens.
|
||||
Use latitude and longitude with the `s2.CellID.ToToken` endpoint of the S2 Geometry
|
||||
Library to generate `s2_cell_id` tags. For example:
|
||||
|
|
@ -102,7 +102,7 @@ Library to generate `s2_cell_id` tags. For example:
|
|||
- **Python:** [s2sphere.CellId.to_token()](https://s2sphere.readthedocs.io/en/latest/api.html#s2sphere.CellId)
|
||||
- **JavaScript:** [s2.cellid.toToken()](https://github.com/mapbox/node-s2/blob/master/API.md#cellidtotoken---string)
|
||||
|
||||
### Add S2 cell ID tokens with Flux
|
||||
### Generate S2 cell ID tokens with Flux
|
||||
Use the [`geo.s2CellIDToken()` function](/v2.0/reference/flux/stdlib/experimental/geo/s2cellidtoken/)
|
||||
with existing longitude (`lon`) and latitude (`lat`) field values to generate and add the S2 cell ID token.
|
||||
First, use the [`geo.toRows()` function](/v2.0/reference/flux/stdlib/experimental/geo/torows/)
|
||||
|
|
|
|||
|
|
@ -48,9 +48,8 @@ Geometry Library to generate `s2_cell_id` tags.
|
|||
Specify your [S2 Cell ID level](https://s2geometry.io/resources/s2cell_statistics.html).
|
||||
|
||||
{{% note %}}
|
||||
For faster filtering, use higher S2 Cell ID levels.
|
||||
But know that that higher levels increase
|
||||
[series cardinality](/v2.0/reference/glossary/#series-cardinality).
|
||||
To filter more quickly, use higher S2 Cell ID levels,
|
||||
but know that that higher levels increase [series cardinality](/v2.0/reference/glossary/#series-cardinality).
|
||||
{{% /note %}}
|
||||
|
||||
Language-specific implementations of the S2 Geometry Library provide methods for
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@
|
|||
{{ $title := cond ( isset .Params "list_title" ) .Params.list_title .Title }}
|
||||
{{ $url := cond ( isset .Params "external_url" ) .Params.external_url .RelPermalink }}
|
||||
{{ $target := cond ( isset .Params "external_url" ) "_blank" "" }}
|
||||
<h3><a href="{{ $url }}" target="{{ $target }}">{{ $title }}</a></h3>
|
||||
<h3 id="{{ anchorize $title }}"><a href="{{ $url }}" target="{{ $target }}">{{ $title }}</a></h3>
|
||||
<p>
|
||||
{{- if .Description }}{{- .Description | markdownify -}}
|
||||
{{ else }}{{- .Summary | markdownify -}}
|
||||
|
|
|
|||
Loading…
Reference in New Issue