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 your 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 will not be selected.

  • 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, prior to executing this tool.

Syntax

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})
ParameterExplanationData Type
in_layer_or_view

The data containing a date field to which the selection will be applied.

Table View
selection_type

Specifies how the selection will be applied and what will occur if a selection already exists.

  • NEW_SELECTION The resulting selection replaces the current selection. This is the default.
  • ADD_TO_SELECTION The resulting selection is 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 is removed from the current selection. If no selection exists, this option has no effect.
  • SUBSET_SELECTION The resulting selection is 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_FIELDRecords will be selected based on a single time field on the input feature.
  • TIME_RANGE_FIELDSRecords will be selected based on a 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 inactive if Time Type is not 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 inactive if Time Type is not 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 inactive if Time Type is not set toTime Range Fields.

Field
selection_options
[selection_options,...]
(Optional)

Specifies how date and time selections will be made.

  • DATEThe selection will be by date.
  • TIMEThe selection will be by time of day.
  • DAY_OF_WEEKThe selection will be by day of the week.
  • MONTHThe selection will be by month.
  • YEARThe selection will be by year.
String
date_selection_type
(Optional)

Specifies whether records will be selected based on a date range, singular date, recency period, or comparative time period.

This parameter is only active when Date is specified for the Selection Options parameter.

  • DATE_RANGERecords will be selected based on a start and end date range.
  • SINGLE_DATERecords will be selected based on the date specified.
  • RECENCYRecords 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.
  • COMPARATIVERecords 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 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 By Single Date is specified for the Date Selection Type parameter.

Date
start_date
(Optional)

The start date of the date range.

This parameter is only active when By Date Range is specified for the Date Selection Type parameter.

Date
end_date
(Optional)

The end date of the date range.

This parameter is only active when By Date Range is specified for the Date Selection Type parameter.

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_TIMERecords from the current day will be included in the selection.
  • NO_SYSTEM_TIMERecords 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 executes, 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 is executed, 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.

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 By Comparative Time Period and By Regency are specified for the Date Selection Type parameter.

Time Unit
start_time
(Optional)

The start time of the time range.

Date
end_time
(Optional)

The end time of the time range.

Date
days_of_week
[days_of_week,...]
(Optional)

Specifies the days of the week used to select records.

  • MONDAYRecords occurring on Monday will be selected.
  • TUESDAYRecords occurring on Tuesday will be selected.
  • WEDNESDAYRecords occurring on Wednesday will be selected.
  • THURSDAYRecords occurring on Thursday will be selected.
  • FRIDAYRecords occurring on Friday will be selected.
  • SATURDAYRecords occurring on Saturday will be selected.
  • SUNDAYRecords occurring on Sunday will be selected.
String
months
[months,...]
(Optional)

Specifies the months used to select records.

  • JANUARYRecords occurring in January will be selected.
  • FEBRUARYRecords occurring in February will be selected.
  • MARCHRecords occurring in March will be selected.
  • APRILRecords occurring in April will be selected.
  • MAYRecords occurring in May will be selected.
  • JUNERecords occurring in June will be selected.
  • JULYRecords occurring in July will be selected.
  • AUGUSTRecords occurring in August will be selected.
  • SEPTEMBERRecords occurring in September will be selected.
  • OCTOBERRecords occurring in October will be selected.
  • NOVEMBERRecords occurring in November will be selected.
  • DECEMBERRecords occurring in December will be selected.
String
years
[years,...]
(Optional)

Specifies the years used to select records.

Long

Derived Output

NameExplanationData Type
out_layer_or_view

The updated inputs with selections applied.

Table View
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.

Licensing information

  • Basic: Yes
  • Standard: Yes
  • Advanced: Yes

Related topics