Iterate Time (ModelBuilder)

Summary

Iterates over time in a date field.

Learn more about temporal data

Learn how Iterate Time works in ModelBuilder

Usage

• This tool is only available from ModelBuilder for use in models. The tool is not available from the Geoprocessing pane or from Python.

• The tool accepts features and tables with a date field.

• The tool iterates and filters rows that fall in different time intervals and time extents. For example, iterate over hourly data for the full temporal extent of the data or a subset of it. The tool creates different temporal slices that can used as input to other tools.

• Use the Time Definition parameter to filter rows for specific months or weekdays. For example, if iterating data by week with a Time Step Interval value of 1 Weeks, when Time Definition is set to Saturday and Sunday, each temporal slice only returns the data from Saturday and Sunday.

• Use the Subset parameter to create one or more subsets of each temporal slice. The table below shows examples of different Subset Delay and Subset Duration values with the assumption that the temporal slice is from January 1, 2022, 1 AM (2022-01-01 01:00:00) to January 2, 2022, 1 AM (2022-01-02 01:00:00).

  Case	Subset value	Result
  	Subset Delay: 2 Hours Subset Duration: 2 Hours	Data from 3 AM (2022-01-01 00:03:00) to 5 AM (2022-01-01 00:05:00) will be returned.
  	Subset Delay: 2 Hours Subset Duration: 2 Hours Subset Delay: 8 Hours Subset Duration: 4 Hours	Data from 3 AM (2022-01-01 00:03:00) to 5 AM (2022-01-01 00:05:00), and from 9AM (2022-01-01 00:09:00) to 1 PM (2022-01-01 00:13:00) will be returned
  	Subset Delay: 2 Hours Subset Duration: None	Data from 3 AM (2022-01-01 00:03:00) to the next day 1 AM (2022-01-02 00:01:00) will be returned.
  	Subset Delay: 2 Hours Subset Duration: 0 Hours	Data from 3 AM (2022-01-01 00:03:00) will be returned.

  

• Use the Iteration Start Time and Iteration End Time parameters to create temporal slices from a temporal subset of the data.

• Use the Snap Iteration Start Datetime To Data and Snap Iteration End Datetime To Data parameters with the Iteration Start Time and Iteration End Time parameters to align the start and end of iteration to the closest date and time value in the data.

• The start and end of temporal slices are calculated based on the combination of the parameter values. The table below shows the expected outcomes based on different parameter combinations with the Skip Empty Slices parameter unchecked. For example, the data extent is from 2022-01-03 to 2022-01-31. With a one day interval, if the Iteration Start Time and Iteration End Time parameter values are not specified, the first temporal slice will start from 2022-01-03 based on the start of the data, and will end on 2022-02-01.

  Iteration Start Time	Snap Iteration Start Datetime To Data	Iteration End Time	Snap Iteration End Datetime To Data	Start of first temporal slice	End of last temporal slice
  				2022-01-03	2022-02-01
  2022-01-01	Unchecked			2022-01-01	2022-02-01
  2022-01-01	Checked			2022-01-03	2022-02-01
  		2022-02-01	Unchecked	2022-01-03	2022-02-01
  		2022-02-01	Checked	2022-01-03	2022-01-31
  2022-01-01	Unchecked	2022-02-01	Unchecked	2022-01-01	2022-02-01
  2022-01-01	Checked	2022-02-01	Unchecked	2022-01-03	2022-02-01
  2022-01-01	Unchecked	2022-02-01	Checked	2022-01-01	2022-01-31
  2022-01-01	Checked	2022-02-01	Checked	2022-01-03	2022-01-31

• The Include Start parameter is always honored for the first temporal slice, and the Include End parameter is always honored for the last temporal slice regardless of the Include Start and Include End parameter values. For each temporal slice in between, the inclusion or exclusion of data is based on the parameter values. For example, if the data has values from 2022-01-01 to 2022-01-03, the table below shows the expected count outcome with a 1-day interval for the iterations from 2022-01-01 to 2022-01-03.

  Time slice	Count with both parameters unchecked	Count with only Include Start checked	Count with only Include End checked	Count with both parameters checked
  2022-01-01 to 2022-01-02	1	1	2 (Include Start is always honored for the first temporal slice)	2
  2022-01-02 to 2022-01-03	0	1	1	2
  2022-01-03 to 2022-01-04	0	1	0	1

• The Subset parameter honors the inclusion settings in the Include Start and Include End parameters.

• When the same field is used for the Iteration Start Time and Iteration End Time parameters, rows with null values will be skipped because they do not fall within any time extent.

  When different fields are used for the Iteration Start Time and Iteration End Time parameters, rows with null values will be skipped by default. Uncheck the Skip Null Values parameter to include them in the iteration. The tables below show whether a row will be included for the output time slices from 2022-01-01 to 2022-01-03 with a 1-day interval and the Include Start parameter checked.

  For example, a row has a null start time field value and the end time field value is 2022-01-02:

  Time slice	Expected outcome
  2022-01-01 to 2022-01-02	Included (because a null row value is in the start field)
  2022-01-02 to 2022-01-03	Included (because the Include Start parameter is checked)
  2022-01-03 to 2022-01-04	Not included

  For example, a row has 2022-01-02 as a start time field and the end time field value is null:

  Time slice	Expected outcome
  2022-01-01 to 2022-01-02	Not included
  2022-01-02 to 2022-01-03	Included (because a null row value is in the end field)
  2022-01-03 to 2022-01-04	Included (because a null row value is in the end field)

  If a row has null values in both start and end time fields, the row will be included in every output time slice.

• Uncheck the Skip Empty Slices parameter to show all temporal slices in the output, including those with a row count of zero. By default, the empty slices will be hidden.

• For each iteration, the tool returns the following outputs:

  • Output Layer—The layer with selected rows that match the temporal slicing criteria
  • Start Time—The start time for each temporal slice
  • End Time—The end time for each temporal slice
  • Count—The count of rows in each temporal slice

• The two output parameters, Start Time and End Time, are in 24 hour format. If no time is specified in the data or in any parameter values, the default cutoff time is 00:00:00.

• The Start Time and End Time parameter values can be used as inline variable substitution to define the output names in other tools. To do so, check the Format Output Time String parameter to return a date and time string without special characters as in the example below.

  

  The time is always appended to the start and end time strings. To remove time from that string, use the Calculate Value tool and set the expression to "%Start Time%"[:11] + "_to_" + "%End Time%"[:11]. The output of the Calculate Value tool can then be used as inline variable substitution in the output of the Copy Features tool.

  

Parameters

Dialog

Label	Explanation	Data Type
Input Table	The input table to iterate.	Table View; Feature Layer
Time Definition (Optional)	Specifies the filter that will be applied to the data. None—No filter will be applied. Weekdays—Data will be filtered using the Days parameter value. Months—Data will be filtered using the Months parameter value.	String
Months (Optional)	Specifies the month that will be used to filter the data. This parameter is active if the Time Definition parameter value is specified as Months. January—Data from January will be returned. February—Data from February will be returned. March—Data from March will be returned. April—Data from April will be returned. May—Data from May will be returned. June—Data from June will be returned. July—Data from July will be returned. August—Data from August will be returned. September—Data from September will be returned. October—Data from October will be returned. November—Data from November will be returned. December—Data from December will be returned.	String
Days (Optional)	Specifies the weekday that will be used to filter the data. This parameter is active if the Time Definition parameter value is specified as Days. Monday—Data from Monday will be returned. Tuesday—Data from Tuesday will be returned. Wednesday—Data from Wednesday will be returned. Thursday—Data from Thursday will be returned. Friday—Data from Friday will be returned. Saturday—Data from Saturday will be returned. Sunday—Data from Sunday will be returned.	String
Time Step Interval	The time interval that will be used to create temporal slices. Only whole numbers are valid inputs.	Time Unit
Subset (Optional)	One or more temporal subsets of each iteration. Each subset is defined by a pair of Subset Delay and Subset Duration values. The start of each temporal slice is offset by the Subset Delay value, and the temporal range of the slice is defined by the Subset Duration value. For example, a temporal slice is between January 1, 2022, 1 AM (2022-01-01 01:00:00) and January 2, 2022, 1 AM (2022-01-02 01:00:00), with a Subset Delay value of 2 hours. When the Subset Duration value is 2 hours, the temporal slice will start at 3 AM (2022-01-01 00:03:00) and end at 5 AM (2022-01-01 00:05:00). When the Subset Duration value is empty, the temporal slice will start at 3 AM (2022-01-01 00:03:00) and end at 1 AM the next day (2022-01-02 01:00:00). When the Subset Duration value is 0, the subset will only return the data at 3 AM (2022-01-01 00:03:00).	Value Table
Start Time Field	A field that will be used to define the temporal extent (or the start of the temporal extent) and query to create temporal slices. The temporal extent can be altered by specifying a different date and time value for the Iteration Start Time parameter.	Field
End Time Field (Optional)	A field that will be used to define the end of the temporal extent and query to create temporal slices. This field can be added if the data has separate date fields for start and end time. If the data has a single field for start and end time, leave this parameter blank or set it to the same field as the Start Time Field value.	Field
Iteration Start Time (Optional)	A start time that creates a subset of the data starting on and after the specified date and time value.	Date
Snap Iteration Start Datetime To Data (Optional)	Specifies whether the start of the iteration will be aligned with the closest date in the data. Checked—The start of the iteration will be aligned with the closest date in the data that is on or after the date specified for the Iteration Start Time parameter. For example, if the Iteration Start Time parameter value is 2022-01-01 and the data starts from 2022-01-06, the iteration will start from 2022-01-06 and divide the data by the time interval defined by the Time Step Interval parameter. In the case of a one-month step interval, the slice with be 2022-01-06 to 2022-02-06, and so on. Unchecked—The start of the iteration will be aligned with the date specified for the Iteration Start Time parameter. This is the default. For example, if the Iteration Start Time parameter value is 2022-01-01 and the data starts from 2022-01-06, the iteration will still start from 2022-01-01 and divide the data by the time interval defined by the Time Step Interval parameter. In the case of a one-month step interval, the slice with be 2022-01-01 to 2022-02-01, and so on.	Boolean
Iteration End Time (Optional)	The end time that creates a subset of the data ending on and before the specified date and time value.	Date
Snap Iteration End Datetime To Data (Optional)	Specifies whether the end of iteration will be aligned with the closest date in the data. Checked—The end of iteration will be aligned with the closest date in the data that is on or before the date specified for the Iteration End Time parameter. For example, if the Iteration End Time parameter value is 2022-12-31 and the data ends at 2022-12-28, the iteration will end at 2022-12-28. The last slice can be smaller than the defined time step interval. Unchecked—The end of iteration will be aligned with the closest date specified for the Iteration End Time parameter. This is the default. For example, if the Iteration End Time parameter value is 2022-12-31 and the data ends at 2022-12-28, the iteration will end at 2022-12-31. The last slice will be divided pursuant to the time interval but will end based on the Iteration End Time value specified.	Boolean
Include Start (Optional)	Specifies whether the start time will be included in each time slice. Checked—The start time will be included in each time slice. This is the default. Unchecked—The start time will not be included in each time slice.	Boolean
Include End (Optional)	Specifies whether the end time will be included in each time slice. Checking both Include Start and Include End will result in counting the same event twice. If an event occurred at the ending of the previous slice, it will also be counted in the following slice (include start). This may be useful in continuous events. For example, a fire has been burning for three days and you want to know the total number of new and existing fire records Checked—Values less than or equal to the end time will be included. Unchecked—Values less than the end time will be included. This is the default.	Boolean
Skip Null Values (Optional)	Specifies whether rows with null date and time values will be included. This parameter is available when the Start Time Field and End Time Field parameters have different date fields. Checked—Rows with null date and time values will not be included. This is the default. Unchecked—Rows with null date and time values will be included. Uncheck this parameter in the following cases: The Start Time Field parameter value is null—Any row with a null value in the Start Time Field parameter value will be included in every temporal slice that ends on or before the End Field parameter value. The End Time Field parameter value is null—Any row with a null value in the End Time Field parameter value will be included in every temporal slice that starts on or after the Start Field parameter value. Both the Start Time Field and End Time Field parameter values are null—Any row with null values in the Start Field and End Field parameter values will be included in each temporal slice.	Boolean
Format Output Time String (Optional)	Specifies whether reserved characters will be removed from the output Start Time and End Time parameter values. Only alphanumeric and underscore characters will be retained. Checked—Reserved characters will be removed from the output Start Time and End Time parameter values. For example, if the date and time value is 2022-01-01 08:30:00, the formatted string will be 2022_01_01_08_30_00. Unchecked—Reserved characters will not be removed from the output Start Time and End Time parameter values. This is the default.	Boolean
Skip Empty Slices (Optional)	Specifies whether empty time slices will be removed. An empty time slice contains no rows. Checked—Empty time slices will be removed. For example, the input data has no records for 2022-01-02 and 2022-01-03. With a one-day interval from 2022-01-01 to 2022-01-05, this option will skip these two empty time slices and no empty layer will be returned. This is the default. Unchecked—Empty times slices will not be removed. For example, the input data has no records for 2022-01-02 and 2022-01-03. With a one-day interval from 2022-01-01 to 2022-01-05, this option will keep these two time slices and empty layers will be returned.	Boolean

Derived Output

Label	Explanation	Data Type
Output Time Layer	The layer with selected rows that match the time slicing criteria.	Any Value
Start Time	The start time for each slice.	String
End Time	The end time for each slice.	String
Count	The count of rows in each slice.	Long

Environments

This tool does not use any geoprocessing environments.