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 the ModelBuilder ribbon 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, you can 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 in other tools.

• 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 Date To Data and Snap Iteration End Date To Data parameters with the Iteration Start Time and Iteration End Time parameters to align the start and end of iteration to the closest datetime 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 has a datetime extent 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

• When the same datetime 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 datetime 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 see 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 datetime 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 Step Interval	Specifies the time interval that will be used to create temporal slices. Only whole numbers are valid inputs. Minutes—The data will be divided by minutes. Hours—The data will be divided by hours. Days—The data will be divided by days. Weeks—The data will be divided by weeks. Months—The data will be divided by months. Years—The data will be divided by years. Decades—The data will be divided by decades. Centuries—The data will be divided by centuries.	Time Unit
Start Time Field	A field that will be used to define the temporal extent and query to create temporal slices. The temporal extent can be altered by specifying a different datetime value in 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. The 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)	Creates a subset of the data starting on and after the specified datetime 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)	Creates a subset of the data ending on and before the specified datetime 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 datetime 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 datetime values will be included. This parameter is available when the Start Time Field and End Time Field parameter values have different date fields. Checked—Rows with null datetime values will not be included. This is the default. Unchecked—Rows with null datetimes 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 until the end of the time extent from 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 unless it doesn't fall within the time slice query for that temporal slice. Both the Start Time Field and End Time Field parameter values are null—Any row with a null value 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 datetime 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 (row count = 0) 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 allows you to skip these two 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 allows you to 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.