Create Space Time Cube

URL:
https://<geoanalytics-url>/CreateSpaceTimeCube
Methods:
GET
Version Introduced:
10.5

Description

Create Space Time Cube

The CreateSpaceTimeCube operation works with a layer of point features that are time enabled. It aggregates the data into a 3D cube of space-time bins. When determining the point in a space-time bin relationship, statistics about all points in the space-time bins are calculated and assigned to the bins. The most basic statistic is the number of points in the bins, but you can calculate other statistics as well.

For example, suppose you have point feature of crimes in a city, and you want to summarize the number of crimes in both space and time. You can calculate the space-time cube for the dataset, and use the cube to further analyze trends such as emerging hot and cold spots.

Request parameters

ParameterDetails

pointLayer (Required)

The point features that will be aggregated into the bins specified in geographical size by the binSize and binSizeUnit parameters and temporal size by the timeStepInterval and timeStepIntervalUnit parameters.

Syntax: As described in Feature input, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A URL to a big data catalog service layer with an optional filter to select specific features
  • A feature collection

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
{"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

//REST scripting example
"pointLayer": {"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

binSize (Required)

The distance for the bins into which the pointLayer value will be aggregated.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
108.3

//REST scripting example
"binSize": 100

binSizeUnit (Required)

The distance unit for the bins into which the pointLayer value will be aggregated.

Values: Meters | Kilometers | Feet | FeetInt | FeetUS | Miles |MilesInt | MilesUS | NauticalMiles | NauticalMilesInt | NauticalMilesUS | Yards | YardsInt | YardsUS

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
Meters

//REST scripting example
"binSizeUnit": "Miles"

timeStepInterval (Required)

A numeric value that specifies the duration of the time bin.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
20

//REST scripting example
"timeStepInterval": 20

timeStepIntervalUnit (Required)

The duration unit of the time bin.

Values: Milliseconds | Seconds | Minutes | Hours | Days | Weeks | Months | Years

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
Minutes

//REST scripting example
"timeStepIntervalUnit": "Minutes"

timeStepAlignment (Optional)

Defines how aggregation will occur based on a given timeInterval value. Options are as follows:

  • StartTime—Time is aligned to the first feature in time.
  • EndTime—Time is aligned to the last feature in time.
  • ReferenceTime—Time is aligned to a specified time.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
StartTime

//REST scripting example
"timeStepAlignment": "StartTime"

timeStepReference (Required if timeStepAlignment is ReferenceTime)

A date that specifies the reference time to align the time bins to if ReferenceTime is specified for timeIntervalAlignment. This time is in milliseconds from epoch.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
946684800000

//REST scripting example
"timeStepReference": 946684800000

summaryFields (Optional)

A list of field names, statistical summary types, and the fill option for empty values that will be calculated for all points in each space-time bin. The count of points in each bin is always returned. By default, all statistics are returned.

onStatisticField specifies the name of the fields in the target layer. statisticType can be specified as one of the following:

  • Sum—Adds the total value of all the points in each polygon. This is used for numeric fields.
  • Mean—Calculates the average of all the points in each polygon. This is used for numeric fields.
  • Min—Finds the smallest value of all the points in each polygon. This is used for numeric fields.
  • Max—Finds the largest value of all the points in each polygon. This is used for numeric fields.
  • Std—Finds the standard deviation of all the points in each polygon. This is used for numeric fields.
  • Count—Totals the number of string for all the points in each polygon. This is used for string fields.

fillTypecan be specified as one of the following:

  • zeros—Fills missing values with zeros. This is most appropriate for fields representing counts.
  • spatialNeighbors—Fills missing values by averaging the spatial neighbors. Neighbors are determined by a second degree queens contiguity.
  • spaceTimeNeighbors—Fills missing values by averaging the space-time neighbors. Neighbors are determined by a second degree queens contiguity in both space and time.
  • temporalTrend—Interpolates values using a univariate spline.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
[{"statisticType": "Count", "onStatisticField": "newEmployees", "fillType": "zeros"},{"statisticType": "Sum", "onStatisticField": "Annual_Sales", "fillType": "temporalTrend"}]

//REST scripting example
"summaryFields": [{"statisticType": "Count", "onStatisticField": "newEmployees", "fillType": "zeros"},{"statisticType": "Sum", "onStatisticField": "Annual_Sales", "fillType": "temporalTrend"}]

outputName (Required)

Defines the name of the space-time cube (netCDF) created by the operation.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
myOutput

//REST scripting example
"outputName": "myOutput"

context (Optional)

The context parameter contains additional settings that affect task execution. For this task, there are two settings:

  • Extent (extent )—A bounding box that defines the analysis area. Only those features that intersect the bounding box will be analyzed.
  • Processing spatial reference (processSR )—The features will be projected into this coordinate system for analysis.

Syntax:

Use dark colors for code blocksCopy
1
2
3
4
{
  "extent" : {extent},
  "processSR" : {spatial reference}
}

f

The response format. The default response format is html .

Values: html | json | pjson

Example usage

The example below is a sample request URL for CreateSpaceTimeCube:

Use dark colors for code blocksCopy
1
https://webadaptor.domain.com/server/rest/services/System/GeoAnalyticsTools/GPServer/CreateSpaceTimeCube/submitJob?pointLayer={"url":"https://webadaptor.domain.com/server/rest/services/Hurricane/hurricaneTrack/0"}&binSize=100&binSizeUnit=Meters&timeStepInterval=20&timeStepIntervalUnit=Minutes&timeStepAlignment=StartTime&summaryFields=[{"statisticType": "Mean", "onStatisticField": "Annual_Sales"},{"statisticType": "Sum", "onStatisticField": "Annual_Sales"}]&outputName=myOutput&context={"extent":{"xmin":-122.68,"ymin":45.53,"xmax":-122.45,"ymax":45.6,"spatialReference":{"wkid":4326}}}&f=json

Response

When you submit a request, the service assigns a unique job ID for the transaction.

Syntax:

Use dark colors for code blocksCopy
1
2
3
4
{
  "jobId": "<unique job identifier>",
  "jobStatus": "<job status>"
}

After the initial request is submitted, you can use jobId to periodically check the status of the job and messages as described in Check job status. Once the job has successfully completed, use jobId to retrieve the results. To track the status, you can make a request of the following form:

Use dark colors for code blocksCopy
1
https://<analysis url>/CreateSpaceTimeCube/jobs/<jobId>

Access results

When the status of the job request is esriJobSucceeded , you can access the results of the analysis by making a request of the following form:

Use dark colors for code blocksCopy
1
https://<analysis-url>/CreateSpaceTimeCube/jobs/<jobId>/results/outputCube?token=<your token>&f=json
ResponseDescription

outputCube

outputCube will always contain a netCDF cube. The number of resulting bins in the cube depends on the location of the inputPoints value and the bin size settings.

If the summaryFields parameter is specified in the task request, the layer will compute the count statistic, as well as anything specified in summaryFields.

Use dark colors for code blocksCopy
1
{"url": "https://<analysis-url>/CreateSpaceTimeCube/jobs/<jobId>/results/outputCube"}

The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter value provided in the initial request. The value parameter contains the URL of the output cube.

Use dark colors for code blocksCopy
1
2
3
4
5
{
"paramName":"outputCube",
"dataType":"GPDataFile",
"value":{"url":"<hosted feature service layer url>"}
}

When you browse to the output URL, the netCDF cube will automatically download to your local machine.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.