Summary
Summarizes a set of points into a netCDF data structure by aggregating them into space-time bins. Within each bin, the points are counted. For all bin locations, the trend for counts over time are evaluated.
Illustration
Usage
This tool aggregates your point Input Features into space-time bins. The data structure it creates may be thought of as a three-dimensional cube made up of space-time bins with the x and y dimensions representing space and the t dimension representing time.
Every bin has a fixed position in space (x,y) and in time (t). Bins covering the same (x, y) area share the same location ID. Bins encompassing the same duration share the same time-step ID. Because the cube is always rectangular even if your point data is not, some locations will have point counts of zero for all time steps. For many analyses, only locations with data—with at least one point count greater than 1 for at least one time step—will be included in the analysis.
The Input Features should be points representing event data, such as crime or fire events, disease incidents, or traffic accidents. Each point should have a date associated with it. The field containing the event timestamp must be of type Date. The tool requires a minimum of 60 points and a variety of timestamps. The tool will fail if the parameters specified result in a cube with more than two billion bins.
This tool requires projected data to accurately measure distances.
Output from this tool is a netCDF representation of your input points as well as messages summarizing cube characteristics written to the Results window. The netCDF file created may be used as input to the Emerging Hot Spot Analysis tool. See Visualizing the Space Time Cube to get strategies allowing you to look at cube contents.
Select a field of type Date for the Time Field parameter. This field should contain the timestamp associated with each point feature.
The Time Step Interval defines how you want to partition your aggregated points across time. You might decide to aggregate points using one-day, one-week, or one-year intervals, for example. Time-step intervals are always fixed durations, and the tool requires a minimum of ten time steps. If you do not provide a Time Step Interval value, the tool will calculate one for you. See Learn more about how the Create Space Time Cube works for details on how default time-step intervals are computed. Valid time-step interval units are Years, Months, Days, Hours, Minutes, and Seconds.
Type the Time Step Interval as an integer value and a unit value. Example time-step interval entries are 1 Weeks, 2 Weeks, 13 Days, or 1 Months.
You should create a Template Cube to use each time you run your analysis, especially if you want to compare data for a series of time periods. By providing a template cube, you ensure the extent of your analysis, bin size, time-step interval, reference time, and time-step alignment are always consistent.
If you provide a Template Cube, input points that fall outside of the template cube extent will be excluded from analysis. Also, if the spatial reference associated with the input point features is different from the spatial reference associated with the template cube, the tool will project the Input Features to match the template cube before beginning the aggregation process. The spatial reference associated with the template cube will override Output Coordinate System settings as well. In addition, the Template Cube, when specified, will determine the processing extent used, even if you specify a different processing extent.
The Reference Time may be a date and time value or just a date value; it may not be just a time value. The expected format is determined by the computer's regional time settings.
The Distance Interval specifies how large the space-time bins should be. The bins are used to aggregate your point data. You may decide to make each bin 50 meters by 50 meters, for example. Unless a Template Cube is specified, the bin in the upper left corner of the cube will be centered on the upper left corner of the spatial extent for your Input Features. You will want to select a distance interval that makes sense to your analysis. You should find the balance between making your distance interval too large and losing the underlying patterns in your point data, and making your distance interval too small so you end up with a cube filled with zero counts. If you do not provide a Distance Interval value, the tool will calculate one for you. See Learn more about how the Create Space Time Cube works for details on how default distance intervals are computed. The distance interval units supported are Kilometers, Meters, Miles, and Feet.
The trend analysis performed on the aggregated count data is based on the Mann-Kendall statistic.
Syntax
CreateSpaceTimeCube_stpm (in_features, output_cube, time_field, {template_cube}, {time_step_interval}, {time_step_alignment}, {reference_time}, {distance_interval})| Parameter | Explanation | Data Type |
in_features | The input point feature class to be aggregated into space-time bins. | Feature Layer |
output_cube | The output netCDF data cube that will be created to contain counts and summaries of the input feature point data. | File |
time_field |
The field containing the date and time (timestamp) for each point. This field must be of type Date. | Field |
template_cube (Optional) | A reference space-time cube used to define the output_cube extent of analysis, bin dimensions, and bin alignment. The time_step_interval, distance_interval, and reference_time values are also obtained from the template cube. This template cube must be a netCDF (.nc) file that has been created using this tool. | File |
time_step_interval (Optional) | The number of seconds, minutes, hours, days, weeks, or years that will represent a single time step. All points within the same Time Step Interval and Distance Interval will be aggregated. (When a Template Cube is provided, this parameter is ignored, and the Time Step Interval value is obtained from the template cube). Examples of valid entries for this parameter are 1 Weeks, 13 Days, or 1 Years. | String |
time_step_alignment (Optional) | Defines how aggregation will occur based on a given time_step_interval. If a template_cube is provided, the time_step_alignment associated with the template_cube overrides this parameter setting and the time_step_alignment of the template_cube is used.
| String |
reference_time (Optional) | The date/time to use to align the time-step intervals. If you want to bin your data weekly from Monday to Sunday, for example, you could set a reference time of Sunday at midnight to ensure bins break between Sunday and Monday at midnight. (When a template_cube is provided, this parameter is ignored and the reference_time is based on the template_cube.) | Date |
distance_interval (Optional) | The spatial extent of the bins used to aggregate the in_features. All points that fall within the same distance_interval and time_step_interval will be aggregated. (When a template_cube is provided, this parameter is ignored and the distance interval value will be based on the template_cube.) | Double |
Code Sample
CreateSpaceTimeCube example 1 (Python window)
The following Python window script demonstrates how to use the CreateSpaceTimeCube tool.
arcpy.env.workspace = r"C:\STPM"
arcpy.CreateSpaceTimeCube_stpm("Homicides.shp", "Homicides.nc", "OccDate", "#", "3 Months",
"End time", "#", "3 Miles")
CreateSpaceTimeCube example 2 (stand-alone Python script)
The following stand-alone Python script demonstrates how to use the CreateSpaceTimeCube tool.
# Create Space Time Cube of homicide incidents in a metropolitan area
# Import system modules
import arcpy
# Set geoprocessor object property to overwrite existing output, by default
arcpy.env.overwriteOutput = True
# Local variables...
workspace = r"C:\STPM"
try:
# Set the current workspace (to avoid having to specify the full path to the feature
# classes each time)
arcpy.env.workspace = workspace
# Create Space Time Cube of homicide incident data with 3 months and 3 miles settings
# Process: Create Space Time Cube
cube = arcpy.CreateSpaceTimeCube_stpm("Homicides.shp", "Homicides.nc", "MyDate", "#",
"3 Months", "End time", "#", "3 Miles")
# Create a polygon that defines where incidents are possible
# Process: Minimum Bounding Geometry of homicide incident data
arcpy.MinimumBoundingGeometry_management("Homicides.shp", "bounding.shp", "CONVEX_HULL",
"ALL", "#", "NO_MBG_FIELDS")
# Emerging Hot Spot Analysis of homicide incident cube using 5 Miles neighborhood
# distance and 2 neighborhood time step to detect hot spots
# Process: Emerging Hot Spot Analysis
cube = arcpy.EmergingHotSpotAnalysis_stpm("Homicides.nc", "COUNT", "EHS_Homicides.shp",
"5 Miles", 2, "bounding.shp")
except arcpy.ExecuteError:
# If any error occurred when running the tool, print the messages
print(arcpy.GetMessages())
Environments
Licensing Information
- ArcGIS for Desktop Basic: Yes
- ArcGIS for Desktop Standard: Yes
- ArcGIS for Desktop Advanced: Yes