Describe Space Time Cube (Space Time Pattern Mining)

Summary

Summarizes the contents and characteristics of a space-time cube. The tool describes the temporal and spatial extent of the space-time cube, the variables in the space-time cube, the analyses performed on each variable, and the 2D and 3D display themes available for each variable.

Illustration

Describe Space Time Cube tool illustration

Usage

  • This tool accepts netCDF files created by various tools in the Space Time Pattern Mining toolbox.

    Learn more about creating a space-time cube

  • The tool has the following potential applications:

  • The geoprocessing messages describe the characteristics and contents of the input space-time cube. To access the messages, hover over the progress bar, click the pop-out button, or expand the messages section in the Geoprocessing pane. The messages include the following information:

    • The date and time that the space-time cube was created.
    • The version of ArcGIS AllSource used to create the space-time cube.
    • The type of space-time cube. The possible types include Defined Location Cube, Grid Cube, Defined Location Cube (from a multidimensional raster), Forecast Cube, and Subset Cube. To learn more about the different types of space-time cubes, see How Create Space Time Cube works.
      Note:

      If the space-time cube was created using the Create Space Time Cube From Multidimensional Raster Layer tool in ArcGIS Pro 2.8 or earlier, the displayed type will be Defined Locations Cube rather than Defined Locations Cube (from a multidimensional raster).

    • A Space Time Cube Characteristics section that describes the space and time properties of the space-time cube. For details on these characteristics, see How Create Space Time Cube works.
    • A Space Time Cube Contents section in which each row corresponds to a variable in the input space-time cube. Each row includes the summary statistics of the variable, the tool that created the variable (along with the aggregation and fill type), and the display theme options that are available in the Visualize Space Time Cube in 2D and Visualize Space Time Cube in 3D tools.
    • If the space-time cube was created using the Create Space Time Cube By Aggregating Points tool, the messages will include one or more subsections under the Space Time Cube Location and Bins section. The Count subsection and each optional Summary Field subsection includes the number of bins and locations that contained at least one point. The sparseness (percentage of bins containing a zero count) is also listed in the table in the Count subsection.
    • If the space-time cube was created using a tool from the Time Series Forecasting toolset, the messages will include a Forecast Details section that summarizes the forecast methods that were applied.
    • The messages will include one or more sections under Space Time Cube Trends. The sections include the overall Mann-Kendall trend statistic for each variable in the space-time cube.
  • If a value is specified for the Output Characteristics Table parameter, the tool creates a table that includes the space and time characteristics of the input space-time cube. The values in the characteristics table are also displayed in the geoprocessing messages. These values can be used in ModelBuilder to create a space-time analysis workflow.

  • If a value is specified for the Output Spatial Extent Features parameter, the tool outputs a polygon feature class with a single rectangle that represents the extent of the input space-time cube. If the input space-time cube was created using the Create Space Time Cube by Defined Locations tool using a single point, a point feature class is created instead of a polygon feature class. If the space-time cube was created from a template cube, the extent reflects the extent of the template cube.

  • The Output Spatial Extent Features parameter value may not reflect the extent of the space-time cube locations if a template cube or the Extent environment was used when the space-time cube was created.

Parameters

LabelExplanationData Type
Input Space Time Cube

The space-time cube to be described. Space-time cubes have an .nc file extension and are created using various tools in the Space Time Pattern Mining toolbox.

File
Output Characteristics Table
(Optional)

The table containing summary information about the input space-time cube.

Table
Output Spatial Extent Features
(Optional)

A feature class with a single rectangle that represents the spatial extent of the input space-time cube.

Feature Class

arcpy.stpm.DescribeSpaceTimeCube(in_cube, {out_characteristics_table}, {out_spatial_extent})
NameExplanationData Type
in_cube

The space-time cube to be described. Space-time cubes have an .nc file extension and are created using various tools in the Space Time Pattern Mining toolbox.

File
out_characteristics_table
(Optional)

The table containing summary information about the input space-time cube.

Table
out_spatial_extent
(Optional)

A feature class with a single rectangle that represents the spatial extent of the input space-time cube.

Feature Class

Code sample

DescribeSpaceTimeCube example 1 (Python Window)

The following Python window script demonstrates how to use the DescribeSpaceTimeCube function.

import arcpy
arcpy.stpm.DescribeSpaceTimeCube("input_cube.nc")
DescribeSpaceTimeCube example 2 (stand-alone script)

The following stand-alone Python script demonstrates how to use the DescribeSpaceTimeCube function.

# Use the output from the Describe Space Time Cube tool to 
# test whether a set of space-time cubes match a set of criteria. Input the 
# space-time cubes that pass the criteria to the Evaluate Forecast by Location 
# tool.

# Import system modules
import os
import glob
import arcpy

# Set Workspace
arcpy.env.workspace = r"C:\Describe"
out_gdb = os.path.join(arcpy.env.workspace, "GDB.gdb")
arcpy.env.overwriteOutput = True

# Assign global variables
check_fields = ['MIN_X', 'MIN_Y', 'MAX_X', 'MAX_Y', 'NUM_FORECAST', 
          'FIRST_FORECAST_START', 'FIRST_FORECAST_END',
          'LAST_FORECAST_START','LAST_FORECAST_END', 'VALIDATION_TIME_STEPS']

# Iterate through all the space-time cubes in a folder
evaluate_cubes = ''

for cube in glob.glob(os.path.join(arcpy.env.workspace, '*.nc')):
    cube_suffix = os.path.basename(cube)
    cube_name = os.path.splitext(cube_suffix)[0]

    out_describe_fc_name = ("describe" + "_{}").format(cube_name)
    out_table = os.path.join(out_gdb, out_describe_fc_name)
    
    # Run the Describe Space Time Cube tool and save a characteristics table into a GDB
    arcpy.stpm.DescribeSpaceTimeCube(cube, out_table, None)
    lstFields = arcpy.ListFields(out_table)

    for field in lstFields:
        # Check if the space-time cube is a forecast cube
        if field.name == "NUM_FORECAST":     
            with arcpy.da.SearchCursor(out_table, check_fields) as cursor:       
                # Check if the extent, start forecast, end forecast, and validation steps  
                # are all the same
                for row in cursor:
                    if str(row[0]) == '-13847325.1116' and str(row[1]) == '3833847.5631' and \
                       str(row[2]) == '-12704362.5439' and str(row[3]) == '5161307.7693' and \
                       str(row[4]) == '14' and str(row[5]) == '2022-02-27 00:00:02' and \
                       str(row[6]) == '2022-02-28 00:00:01' and str(row[7]) == '2022-03-12 00:00:01' and \
                       str(row[8]) == '2022-03-13 00:00:01' and str(row[9]) == '14':
               
                        # Add the space-time cubes that match the criteria to a string 
                        # that will be input into the Evaluate Forecast by Location tool
                        evaluate_cubes += cube + ';'


# Run the Evaluate Forecast by Location tool
evaluate_output = os.path.join(out_gdb, "Evaluate_Covid19_Forecasts")

arcpy.stpm.EvaluateForecastsByLocation(evaluate_cubes.replace('\\', '/'), evaluate_output, None, "USE_VALIDATION")

Environments

This tool does not use any geoprocessing environments.