Subset Space Time Cube (Space Time Pattern Mining)

Summary

Subsets a space-time cube by spatial extent, space, or time.

The tool outputs the locations and bins of the input space-time cube that meet the criteria of the selected subset methods. The tool can spatially subset a space-time cube by features, an extent, or the locations of another space-time cube. The tool can also temporally subset a space-time cube by a time span, the temporal extent of another space-time cube, or removing time steps from the beginning or end of the space-time cube. The output space-time cube will include all of the variables that are created by the tools in the Space Time Cube Creation toolset.

Illustration

Subset 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 following are potential applications for this tool:

    • Use a feature class of Africa to spatially subset a space-time cube that contains global data.
    • Use a space-time cube that contains data for California to spatially subset a space-time cube that includes data for the entire United States.
    • Apply a temporal subset to remove any time steps from the beginning or end of a space-time cube in which many of the bins have a zero count.
    • Apply a temporal subset to remove the forecasted results from a space-time cube. Then use a tool from the Time Series Forecasting toolset on the space-time cube.

  • The analysis variables that are stored in the input space-time cube are not carried over to the subset output space-time cube. The analysis results in the input space-time cube are based on its spatiotemporal structure. If the space-time cube is subset, the analysis results may be invalid. To recover the analysis variables, rerun the tools used from the Space Time Pattern Analysis toolset and the Time Series Forecasting toolset on the subset output space-time cube.on the subset output space-time cube.

  • The tool creates geoprocessing messages. 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:

    • A Subset Summary section that compares the characteristics of the input space-time cube to those of the subset output space-time cube.
    • A Space Time Cube Characteristics section that describes the space and time properties of the space-time cube. In this section, the Input feature time extent value provides the time extent of the features that were used to create the original space-time cube. This value will not change if you subset a space-time cube. For more information about 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 include 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 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. In this section, the time extent used in the forecast provides the time extent of the features that were used to create the original space-time cube. This value will not change if you subset a space-time cube.
    • 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 the Spatial Subset Method parameter is set to Features, ensure that the coordinate system of the input subset features matches the coordinate system of the input space-time cube. Use the Project tool to modify the coordinate system of the input subset features. If the coordinate systems do not match, the subset may not be possible or the locations in the output space-time cube may be in unexpected places.

  • Applying a spatial subset does not modify the geometry of any space-time cube location. Each location is either included in or excluded from the output space-time cube based on the spatial subset criteria selected.

  • Applying a temporal subset does not change the time-step interval in the space-time cube or the time extent of the bins. Each bin is either included in or excluded from the output space-time cube based on the temporal subset criteria selected. If the Temporal Subset Method parameter is set to User defined or Space time cube and the specified start or end time falls within a bin, the entire bin will be included in the output space-time cube. In which case, the time range of the output space-time cube may not match the specified start or end time or the time interval of the temporal subset cube. For example, if a space-time cube has a time-step interval of one month and it is temporally subset by a space-time cube with a time interval that spans from 1/24/2020 to 12/24/2020, the time interval of the output space-time cube will range from 1/1/2020 to 12/31/2020.

  • Each time step in a space-time cube is exclusive of the bin's start time and inclusive of the bin's end time. For example, if a bin's start time is 1/1/2020 12:00:00 AM and its end time is 1/1/2021 12:00:00 AM, the bin will include data after 1/1/2020 12:00:00 AM and up to, on, or before 1/1/2021 12:00:00 AM. If the Time Span of Subsetparameter's Start Time column is specified as 1/1/2021 12:00:00 AM, the subset output space-time cube will start from 1/1/2020 12:00:00 AM so that the data from 1/1/2021 12:00:00 AM will be included in the output space-time cube.

  • If a space-time cube is temporally subset, the output space-time cube must contain at least 10 time steps for the tool to run.

  • If the tools subsets a defined locations cube, any location that does not meet the subset criteria will be removed from the output space-time cube. However, if the tool subsets a grid cube, any location that fails the subset criteria will only be masked in the output space-time cube. Masked locations remain in the space-time cube, but they are excluded from analysis.

    Learn more about the structure of space-time cubes

  • If a space-time cube was created using the Create Space Time Cube By Aggregating Points tool, it may contain variables that have different masked locations. This impacts how the Subset Space Time Cube tool applies a spatial subset.

    • If the space-time cube is set as the Input Spatial Subset Cube parameter value, the locations of the count variable will be used to spatially subset the input space-time cube.
    • If the space-time cube is the input space-time cube and the tool applies a spatial subset, each variable must exist in at least one location in the subset output space-time cube; otherwise, the tool will fail.
    • Control which variable in the space-time cube determines the spatial subset by re-creating the space-time cube using only the variable of interest. First, use the Visualize Space Time Cube In 3D tool to visualize the space-time cube values. Then apply the Create Space Time Cube From Defined Locations tool to create a new space-time cube from the output feature. Select the variable of interest.
  • If you temporally subset a forecast cube and remove all the forecasted time steps, the output space-time cube is no longer a forecast cube. The resulting space-time cube can be used as input to any tool in the Time Series Forecasting toolset.

Parameters

LabelExplanationData Type
Input Space Time Cube

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

File
Output Space Time Cube

The subset of the input space-time cube that meets the spatial and temporal criteria specified by the Spatial Subset Method and Temporal Subset Method parameters. The analysis variables stored in the input space-time cube will be excluded from the output space-time cube.

File
Spatial Subset Method

Specifies the method that will be used to spatially subset the input space-time cube. Any location in the input space-time cube that satisfies this spatial subset criteria will be included in the output space-time cube.

  • FeaturesA feature class with polygons, points, or lines will be used to subset the input space-time cube. The Spatial Relationship parameter specifies how the feature layer will subset the space-time cube.
  • ExtentThe extent specified by the Extent parameter will be used to subset the input space-time cube. The output space-time cube will include all the locations in the input space-time cube that intersect the extent.
  • Space Time CubeThe location of the space-time cube specified by the Input Spatial Subset Cube parameter will be used to subset a space-time cube. The Spatial Relationship parameter specifies how this space-time cube will subset the input space-time cube.
  • NoneNo spatial subset will be applied to the input space-time cube.
  • FeaturesA feature class with polygons, points, or lines will be used to subset the input space-time cube. The spatial_relationship parameter specifies how the feature layer will subset the space-time cube.
  • ExtentThe extent specified by the spatial_extent parameter will be used to subset the input space-time cube. The output space-time cube will include all the locations in the input space-time cube that intersect the extent.
  • Space Time CubeThe locations of the space-time cube specified by the in_spatial_cube parameter will be used to subset a space-time cube. The spatial_relationship parameter specifies how this space-time cube will subset the input space-time cube.
  • NoneNo spatial subset will be applied to the input space-time cube.
String
Temporal Subset Method

Specifies the method that will be used to temporally subset a space-time cube. Any time step in the input space-time cube that satisfies the temporal subset criteria will be included in the output space-time cube.

  • User definedThe temporal range specified by the Start Time or End Time values in the Time Span of Subset parameter will be used to temporally subset the input space-time cube.
  • Number of time stepsA number of time steps from the start and the end of the input space-time cube will be used to temporally subset the space-time cube. The number of time steps to remove is specified by the From the Start or From the End values in the Number of Time Steps to Remove parameter.
  • Space time cubeThe temporal extent of the space-time cube specified by the Input Temporal Subset Cube parameter will be used to temporally subset the input space-time cube.
  • NoneNo temporal subset will be applied to the input space-time cube.
String
Input Subset Features
(Optional)

A feature class that contains polygons, points, or lines to subset a space-time cube. The spatial relationship between the input subset features and the space-time cube is specified by the Spatial Relationship parameter.

Feature Layer
Spatial Relationship
(Optional)

Specifies the spatial relationship that will be applied between the Input Subset Features or Input Spatial Subset Cube parameter value and the input space-time cube to spatially subset the space-time cube. The available spatial relationship options will depend on the geometry of the input space-time cube and the input subset features or the input spatial subset cube.

  • IntersectThe output space-time cube will include the locations in the input space-time cube that intersect the Input Subset Features or Input Spatial Subset Cube parameter value. This is the default.
  • ContainsThe output space-time cube will include the locations in the input space-time cube that contain the Input Subset Features or Input Spatial Subset Cube parameter value.
  • WithinThe output space-time cube will include the locations in the input space-time cube that are within the Input Subset Features or Input Spatial Subset Cube parameter value.
  • Have their center inThe output space-time cube will include the locations in the input space-time cube that have their center in the Input Subset Features or Input Spatial Subset Cube parameter value.
String
Extent
(Optional)

The spatial extent that will spatially subset the input space-time cube. The output space-time cube will include the locations in the input space-time cube that intersect the extent.

Extent
Input Spatial Subset Cube
(Optional)

A space-time cube that will spatially subset the input space-time cube. The spatial relationship between the input spatial subset cube and the space-time cube is specified by the Spatial Relationship parameter.

File
Time Span of Subset
(Optional)

The time interval to temporally subset the input space-time cube. Any time step that is within this time interval or that contains the Start Time or End Time column values will be included in the output space-time cube.

Value Table
Number of Time Steps to Remove
(Optional)

The number of time steps from the start and the end of the input space-time cube that will be removed from the output space-time cube.

Value Table
Input Temporal Subset Cube
(Optional)

A space-time cube that will temporally subset the input space-time cube. The temporal extent of the temporal subset cube defines the temporal extent of the output space-time cube. Any time step that is within the temporal extent of the input temporal subset cube or that contains the start time or end time of the temporal subset cube will be included in the output space-time cube.

File

arcpy.stpm.SubsetSpaceTimeCube(in_cube, out_cube, spatial_subset_method, temporal_subset_method, {in_subset_features}, {spatial_relationship}, {spatial_extent}, {in_spatial_cube}, {time_span_subset}, {remove_time_steps}, {in_temporal_cube})
NameExplanationData Type
in_cube

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

File
out_cube

The subset of the input space-time cube that meets the spatial and temporal criteria specified by the spatial_subset_method and temporal_subset_method parameters. The analysis variables stored in the input space-time cube will be excluded from the output space-time cube.

File
spatial_subset_method

Specifies the method that will be used to spatially subset the input space-time cube. Any location in the input space-time cube that satisfies this spatial subset criteria will be included in the output space-time cube.

  • FEATURESA feature class with polygons, points, or lines will be used to subset the input space-time cube. The spatial_relationship parameter specifies how the feature layer will subset the space-time cube.
  • EXTENTThe extent specified by the spatial_extent parameter will be used to subset the input space-time cube. The output space-time cube will include all the locations in the input space-time cube that intersect the extent.
  • SPACE_TIME_CUBEThe locations of the space-time cube specified by the in_spatial_cube parameter will be used to subset a space-time cube. The spatial_relationship parameter specifies how this space-time cube will subset the input space-time cube.
  • NONENo spatial subset will be applied to the input space-time cube.
String
temporal_subset_method

Specifies the method that will be used to temporally subset a space-time cube. Any time step in the input space-time cube that satisfies the temporal subset criteria will be included in the output space-time cube.

  • USER_DEFINEDThe temporal range specified by the start time or end time values in the time_span_subset parameter will be used to temporally subset the input space-time cube.
  • NUMBER_OF_TIME_STEPSA number of time steps from the start and the end of the input space-time cube will be used to temporally subset the space-time cube. The number of time steps to remove is specified by the from the start or from the end values in the remove_time_steps parameter.
  • SPACE_TIME_CUBEThe temporal extent of the space-time cube specified by the in_temporal_cube parameter will be used to temporally subset the input space-time cube.
  • NONENo temporal subset will be applied to the input space-time cube.
String
in_subset_features
(Optional)

A feature class that contains polygons, points, or lines to subset a space-time cube. The spatial relationship between the input subset features and the space-time cube is specified by the spatial_relationship parameter.

Feature Layer
spatial_relationship
(Optional)

The spatial relationship that will be applied between the in_subset_features or in_spatial_cube parameter value and the input space-time cube to spatially subset the space-time cube. The available spatial relationship options will depend on the geometry of the input space-time cube and the input subset features or the input spatial subset cube.

  • INTERSECTThe output space-time cube will include the locations in the input space-time cube that intersect the in_subset_features or in_spatial_cube parameter value. This is the default.
  • CONTAINSThe output space-time cube will include the locations in the input space-time cube that contain the in_subset_features or in_spatial_cube parameter value.
  • WITHINThe output space-time cube will include the locations in the input space-time cube that are within the in_subset_features or in_spatial_cube parameter value.
  • HAVE_THEIR_CENTER_INThe output space-time cube will include the locations in the input space-time cube that have their center in the in_subset_features or in_spatial_cube parameter value.
String
spatial_extent
(Optional)

The spatial extent that will spatially subset the input space-time cube. The output space-time cube will include the locations in the input space-time cube that intersect the extent.

Extent
in_spatial_cube
(Optional)

A space-time cube that will spatially subset the input space-time cube. The spatial relationship between the input spatial subset cube and the space-time cube is specified by the spatial_relationship parameter.

File
time_span_subset
[time_span_subset,...]
(Optional)

The time interval to temporally subset the input space-time cube. Any time step that is within this time interval or that contains the start time or end time values will be included in the output space-time cube.

Value Table
remove_time_steps
[remove_time_steps,...]
(Optional)

The number of time steps from the start and the end of the input space-time cube that will be removed from the output space-time cube.

Value Table
in_temporal_cube
(Optional)

A space-time cube that will temporally subset the input space-time cube. The temporal extent of the temporal subset cube defines the temporal extent of the output space-time cube. Any time step that is within the temporal extent of the input temporal subset cube or that contains the start time or end time of the temporal subset cube will be included in the output space-time cube.

File

Code sample

SubsetSpaceTimeCube example 1 (Python window)

The following Python script demonstrates how to use the SubsetSpaceTimeCube function.


import arcpy
arcpy.env.workspace = "C:\STPM"
arcpy.stpm.SubsetSpaceTimeCube("input_cube.nc", "subset_cube.nc", 
                               "SPACE_TIME_CUBE", "NONE", None, None, None, 
                               "spatial_subset_cube.nc")
SubsetSpaceTimeCube example 2 (stand-alone script)

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


# Use the Subset Space Time Cube tool to subset a space-time cube by time 
# and space.

# Import system modules
import arcpy
import os

# Set workspace
arcpy.env.workspace = r"C:\Analysis"
gdb = os.path.join(arcpy.env.workspace, "continents.gdb")
arcpy.env.overwriteOutput = True

# Temporally subset a space-time cube
temperature_stc = "Temperature_STC.nc"
temporal_subset_stc = "Temperature_STC_temporal_subset.nc"

arcpy.stpm.SubsetSpaceTimeCube(temperature_stc, temporal_subset_stc, "NONE", 
                               "USER_DEFINED", None, "", "DEFAULT", None, 
                               "1/1/2012 1/1/2022")

# Spatially subset the data for every continent in the space-time cube
continents = ["Africa", "North_America", "Antarctica", "South_America", "Asia", 
              "Europe", "Australia"]
for continent in continents:
    feature = os.path.join(gdb, c)
    arcpy.stpm.SubsetSpaceTimeCube(temporal_subset_stc, 
                                   continent + "_temperature_subset.nc", 
                                   "FEATURES", "NONE", feature, "INTERSECT")