| Label | Explanation | Data 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.
| 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.
| 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.
| 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 |
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
Usage
This tool accepts netCDF files created by various tools in the Space Time Pattern Mining toolbox.
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.
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
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})| Name | Explanation | Data 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.
| 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.
| 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.
| 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
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")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")