Select Layer By Date And Time (Crime Analysis and Safety)

Summary

Selects records based on date and time ranges or date properties, for example, single date, time range, time period, days of the week, month, or year.

Usage

• The input must be a feature layer or table view.

• The input must contain a date field. If the input does not contain a date field, use the Convert Time Field tool to generate a date field derived from dates formatted as text in a text field.

• This tool performs a selection using all the selection criteria. If any part of the input date does not match the selection criteria, the feature or record will not be selected.

  All date selections are based on the time zone of your computer.

• To use this tool in a model or script, use the Make Table View or Make Feature Layer tool to convert an input feature class to a table view or feature layer, respectively, before running this tool.

Parameters

Dialog

Label	Explanation	Data Type
Input Rows	The data containing a date field to which the selection will be applied.	Table View; Feature Layer
Selection Type	Specifies how the selection will be applied and what will occur if a selection already exists. New selection— The resulting selection will replace the current selection. This is the default. Add to the current selection— The resulting selection will be added to the current selection if one exists. If no selection exists, this is the same as the new selection option. Remove from the current selection— The resulting selection will be removed from the current selection. If no selection exists, this option has no effect. Select subset from the current selection— The resulting selection will be combined with the current selection. Only records that are common to both remain selected.	String
Time Type	Specifies how date and time fields will be used to select records. Single Time Field—Records will be selected based on a single time field on the input feature. Time Range Fields—Records will be selected based on start and end time fields on the input feature.	String
Date Field (Optional)	The date field from the input layer on which the selection will be based. This parameter is only active if the Time Type parameter is set to Single Time Field.	Field
Start Date Field (Optional)	The start date field from the time range on which the selection will be based. This parameter is only active if the Time Type parameter is set to Time Range Fields .	Field
End Date Field (Optional)	The end date field from the time range on which the selection will be based. This parameter is only active if the Time Type parameter is set to Time Range Fields.	Field
Selection Options (Optional)	Specifies how date and time selections will be made. Date—The selection will be by date. Time—The selection will be by time of day. Day of week—The selection will be by day of the week. Month—The selection will be by month. Year—The selection will be by year.	String
Date Selection Type (Optional)	Specifies whether records will be selected based on a date range, single date, recency period, or comparative time period. This parameter is only active when the Selection Options parameter is set to Date. By Date Range—Records will be selected based on a start and end date range. By Single Date—Records will be selected based on the a single specified date. By Recency—Records will be selected based on a time period in relation to the current date (system date and time), for example, within the last 14 days. By Comparative Time Period—Records will be selected based on the time period immediately preceding a recent time period in relation to the current date (system date and time). For example, if the current date is January 29 and the time slice is 14 days, records occurring between January 1 and January 14 will be selected. This option can be used in combination with a subsequent By Recency (RECENCY in Python) selection to compare record counts between two adjacent time periods (for example, the two 14-day time periods of January 1–14 and January 15–28).	String
Date (Optional)	The single date and time to be selected. This parameter is only active when the Date Selection Type parameter is set to By Single Date.	Date
Start Date (Optional)	The start date of the date range. This parameter is only active when the Date Selection Type parameter is set to By Date Range.	Date
End Date (Optional)	The end date of the date range. This parameter is only active when the Date Selection Type parameter is set to By Date Range.	Date
Use Current System time as End Time (Optional)	Specifies whether records from the current day (local system time) will be included in the selection if they exist in the recent time period. Checked—Records from the current day will be included in the selection. Unchecked—Records from the current day will not be included in the selection. For example, the time slice specified is 14 days, the local system time is 5:00 p.m on January 15 when the tool runs, the recency time period includes all records between 5:00 p.m. on the date 14 days ago and 5:00 p.m. on the day the tool runs, and this parameter is checked. In this example, the selection will be January 1, 2017 5:00:00 PM to January 15, 2017 5:00:00 PM for the 14-day time slice. Using this same example with this parameter unchecked, the recent period uses the beginning of the current day as the end time (based on local system time). In this case, the selection will be January 1, 2017 12:00:00 AM to January 15, 12:00:00 AM for the 14-day time slice. This parameter is only active when the Date Selection Type parameter is set to By Comparative Time Period or By Recency.	Boolean
Time Slice (Optional)	The number of time units (minutes, hours, days, weeks, months, or years) defining the recent time period on which the selection will be based, for example, events within the last 14 days. This parameter is only active when the Date Selection Type parameter is set to By Comparative Time Period or By Recency.	Time Unit
Start Time (Optional)	The start time of the time range. This parameter is only active when the Selection Options parameter is set to Time.	Date
End Time (Optional)	The end time of the time range. This parameter is only active when the Selection Options parameter is set to Time.	Date
Days of Week (Optional)	Specifies the day or days of the week that will be used to select records. This parameter is only active when the Selection Options parameter is set to Day of week. Monday—Records occurring on Monday will be selected. Tuesday—Records occurring on Tuesday will be selected. Wednesday—Records occurring on Wednesday will be selected. Thursday—Records occurring on Thursday will be selected. Friday—Records occurring on Friday will be selected. Saturday—Records occurring on Saturday will be selected. Sunday—Records occurring on Sunday will be selected.	String
Months (Optional)	Specifies the month or months that will be used to select records. This parameter is only active when the Selection Options parameter is set to Month. January—Records occurring in January will be selected. February—Records occurring in February will be selected. March—Records occurring in March will be selected. April—Records occurring in April will be selected. May—Records occurring in May will be selected. June—Records occurring in June will be selected. July—Records occurring in July will be selected. August—Records occurring in August will be selected. September—Records occurring in September will be selected. October—Records occurring in October will be selected. November—Records occurring in November will be selected. December—Records occurring in December will be selected.	String
Years (Optional)	The year or years that will be used to select records. This parameter is only active when the Selection Options parameter is set to Years.	Long

Derived Output

Label	Explanation	Data Type
Updated Layer or Table View	The updated inputs with selections applied.	Table View; Feature Layer
Row Count	The number of selected records.	Long

Python

arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view, selection_type, time_type, {date_field}, {start_date_field}, {end_date_field}, {selection_options}, {date_selection_type}, {single_date}, {start_date}, {end_date}, {use_system_time}, {time_slice}, {start_time}, {end_time}, {days_of_week}, {months}, {years})

Name	Explanation	Data Type
in_layer_or_view	The data containing a date field to which the selection will be applied.	Table View; Feature Layer
selection_type	Specifies how the selection will be applied and what will occur if a selection already exists. NEW_SELECTION— The resulting selection will replace the current selection. This is the default. ADD_TO_SELECTION— The resulting selection will be added to the current selection if one exists. If no selection exists, this is the same as the new selection option. REMOVE_FROM_SELECTION— The resulting selection will be removed from the current selection. If no selection exists, this option has no effect. SUBSET_SELECTION— The resulting selection will be combined with the current selection. Only records that are common to both remain selected.	String
time_type	Specifies how date and time fields will be used to select records. SINGLE_TIME_FIELD—Records will be selected based on a single time field on the input feature. TIME_RANGE_FIELDS—Records will be selected based on start and end time fields on the input feature.	String
date_field (Optional)	The date field from the input layer on which the selection will be based. This parameter is only active if the time_type parameter is set to SINGLE_TIME_FIELD.	Field
start_date_field (Optional)	The start date field from the time range on which the selection will be based. This parameter is only active if the time_type parameter is set to TIME_RANGE_FIELDS.	Field
end_date_field (Optional)	The end date field from the time range on which the selection will be based. This parameter is only active if the time_type parameter is set to TIME_RANGE_FIELDS.	Field
selection_options [selection_options,...] (Optional)	Specifies how date and time selections will be made. DATE—The selection will be by date. TIME—The selection will be by time of day. DAY_OF_WEEK—The selection will be by day of the week. MONTH—The selection will be by month. YEAR—The selection will be by year.	String
date_selection_type (Optional)	Specifies whether records will be selected based on a date range, single date, recency period, or comparative time period. This parameter is only active when the selection_options parameter is set to DATE. DATE_RANGE—Records will be selected based on a start and end date range. SINGLE_DATE—Records will be selected based on the a single specified date. RECENCY—Records will be selected based on a time period in relation to the current date (system date and time), for example, within the last 14 days. COMPARATIVE—Records will be selected based on the time period immediately preceding a recent time period in relation to the current date (system date and time). For example, if the current date is January 29 and the time slice is 14 days, records occurring between January 1 and January 14 will be selected. This option can be used in combination with a subsequent By Recency (RECENCY in Python) selection to compare record counts between two adjacent time periods (for example, the two 14-day time periods of January 1–14 and January 15–28).	String
single_date (Optional)	The single date and time to be selected. This parameter is only active when the date_selection_type parameter is set to SINGLE_DATE.	Date
start_date (Optional)	The start date of the date range. This parameter is only active when the date_selection_type parameter is set to DATE_RANGE.	Date
end_date (Optional)	The end date of the date range. This parameter is only active when the date_selection_type parameter is set to DATE_RANGE.	Date
use_system_time (Optional)	Specifies whether records from the current day (local system time) will be included in the selection if they exist in the recent time period. SYSTEM_TIME—Records from the current day will be included in the selection. NO_SYSTEM_TIME—Records from the current day will not be included in the selection. This is the default. For example, the time slice specified is 14 days, the local system time is 5:00 p.m. on January 15 when the tool runs, the recency time period includes all records between 5:00 p.m. on the date 14 days ago and 5:00 p.m. on the day the tool runs, and SYSTEM_TIME is selected. In this example, the selection will be January 1, 2017 5:00:00 PM to January 15, 2017 5:00:00 PM. Using this same example with NO_SYSTEM_TIME selected, the recent period uses the beginning of the current day as the end time (based on local system time). In this case, the selection will be January 1, 2017 12:00:00 AM to January 15, 12:00:00 AM for the 14-day time slice. This parameter is only active when the date_selection_type parameter is set to COMPARATIVE or RECENCY.	Boolean
time_slice (Optional)	The number of time units (minutes, hours, days, weeks, months, or years) defining the recent time period on which the selection will be based, for example, events within the last 14 days. This parameter is only active when the date_selection_type parameter is set to COMPARATIVE or RECENCY.	Time Unit
start_time (Optional)	The start time of the time range. This parameter is only active when the selection_options parameter is set to TIME.	Date
end_time (Optional)	The end time of the time range. This parameter is only active when the selection_options parameter is set to TIME.	Date
days_of_week [days_of_week,...] (Optional)	Specifies the day or days of the week that will be used to select records. MONDAY—Records occurring on Monday will be selected. TUESDAY—Records occurring on Tuesday will be selected. WEDNESDAY—Records occurring on Wednesday will be selected. THURSDAY—Records occurring on Thursday will be selected. FRIDAY—Records occurring on Friday will be selected. SATURDAY—Records occurring on Saturday will be selected. SUNDAY—Records occurring on Sunday will be selected. This parameter is only active when the selection_options parameter is set to DAY_OF_WEEK.	String
months [months,...] (Optional)	Specifies the month or months that will be used to select records. JANUARY—Records occurring in January will be selected. FEBRUARY—Records occurring in February will be selected. MARCH—Records occurring in March will be selected. APRIL—Records occurring in April will be selected. MAY—Records occurring in May will be selected. JUNE—Records occurring in June will be selected. JULY—Records occurring in July will be selected. AUGUST—Records occurring in August will be selected. SEPTEMBER—Records occurring in September will be selected. OCTOBER—Records occurring in October will be selected. NOVEMBER—Records occurring in November will be selected. DECEMBER—Records occurring in December will be selected. This parameter is only active when the selection_options parameter is set to MONTH.	String
years [years,...] (Optional)	The year or years that will be used to select records. This parameter is only active when the selection_options parameter is set to YEAR.	Long

Derived Output

Name	Explanation	Data Type
out_layer_or_view	The updated inputs with selections applied.	Table View; Feature Layer
count	The number of selected records.	Long

Code sample

SelectLayerByDateAndTime example 1 (Python window)

The following script demonstrates how to use the SelectLayerByDateAndTime function in immediate mode.

import arcpy
arcpy.env.workspace = r"C:/data/city_pd.gdb"

arcpy.ca.SelectLayerByDateAndTime("Crimes",
                                "NEW_SELECTION",
                                "SINGLE_TIME_FIELD",
                                "offendate",
                                None,
                                None,
                                "DATE",
                                "DATE_RANGE",
                                None,
                                "8/1/2018",
                                "8/31/2018")

SelectLayerByDateAndTime example 2 (stand-alone window)

The stand-alone script below is an example of how to use the SelectLayerByDateAndTime function in a script:

# Name: SelectLayerByDateAndTime.py
# Description: Select crimes that occurred in the past 28 days, from 9 PM to 1 PM, on the weekend, from the month of October to December,
#              in the year 2018, and show the selection count. Finally, make a selection based on all the queries above.

# Import script modules
import arcpy

# Set the workspace
arcpy.env.workspace = r"C:\data\city_pd.gdb"

# Convert Feature class to table view
arcpy.management.MakeTableView("Crimes", "Crimes_View")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="DATE",
                                                date_selection_type="RECENCY",
                                                time_slice="28 Days")

arcpy.AddMessage("Crimes that occurred in past 28 days: {}".format(str(count)))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="TIME",
                                                start_time="9:00 PM",
                                                end_time="1:00 AM")

arcpy.AddMessage("All crimes that occurred between 9PM and 1AM: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="DAY_OF_WEEK",
                                                days_of_week=["SATURDAY", "SUNDAY"])

arcpy.AddMessage("All crimes that occurred on the weekend: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")

lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="MONTH",
                                                months=["OCTOBER", "NOVEMBER", "DECEMBER"])

arcpy.AddMessage("All crimes that occurred October through December: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")


lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options="YEAR",
                                                years=[2018])

arcpy.AddMessage("All crimes that occurred in the year 2018: {}".format(count))
arcpy.management.SelectLayerByAttribute("Crimes_View","CLEAR_SELECTION")


# Combine selection options for more detailed time queries
lyr, count = arcpy.ca.SelectLayerByDateAndTime(in_layer_or_view="Crimes_View",
                                                selection_type="NEW_SELECTION",
                                                time_type="SINGLE_TIME_FIELD",
                                                date_field="offendate",
                                                selection_options=["TIME", "DAY_OF_WEEK", "MONTH","YEAR"],
                                                start_time="9:00 PM",
                                                end_time="1:00 AM",
                                                days_of_week=["SATURDAY", "SUNDAY"],
                                                months=["OCTOBER", "NOVEMBER", "DECEMBER"],
                                                years=[2018])

message = """All crimes that occurred in the year 2018 during the months
of October through November on the weekends from 9PM to 1AM: {}
""".format(count)

arcpy.AddMessage(message)
arcpy.management.SelectLayerByAttribute("Crimes_View", "CLEAR_SELECTION")

Environments

This tool does not use any geoprocessing environments.