LayerTime

Summary

The LayerTime object provides information about how time is stored and configured in time-enabled layers.

Discussion

Time information, such as the fields containing the time values associated with the features, start and end time of the data, the time-step interval, and so on, can be used for not only gaining knowledge about the time properties on the time-enabled layer but also for performing further data management and analysis tasks over time. Example 1 below shows how you can get the time extent of your time-enabled layer using the startTime and endTime. Example 2 below shows how you can select features based on a time query, then save those features to a separate feature class. You can also use the time information to ensure that the time specified for selecting the features lies within the start and end time of the layer.

The enableTime method on the Layer class allows you to enable time on a layer that has time information and therefore making access to LayerTime properties possible. The second example below demonstrates enableTime.

Tip:

You can use the MapTime class to access map time settings if a MapFrame on a Layout contains time-enabled layers.

Properties

Property	Explanation	Data Type
daylightSavings (Read and Write)	Indicates whether the time values in the time field of the time-enabled layer were collected while observing daylight saving time rules in the input time zone.	Boolean
endTime (Read and Write)	The end date and time for a time-enabled layer.	DateTime
endTimeField (Read and Write)	The name of the field containing the end time values. Not all layers use an end time field. If each feature has a single time field, only the startTimeField will be used and endTimeField will be None. If each feature has a start and end time field, both the startTimeField and endTimeField will be used.	String
startTime (Read and Write)	The start date and time for a time-enabled layer.	DateTime
startTimeField (Read and Write)	The name of the field containing the start time values. If each feature has a single time field, only the startTimeField will be used and endTimeField will be None. If each feature has a start and end time field, both the startTimeField and endTimeField will be used.	String
timeFormat (Read and Write)	The format in which the time values were stored in the startTimeField and endTimeField. The time format is important when formulating a time query.	String
timeOffset (Read and Write)	The time offset applied to the time values in your data.	Double
timeOffsetUnits (Read and Write)	The time offset unit that describes the timeOffset applied to the time values in your data. MILLISECONDS SECONDS MINUTES HOURS DAYS WEEKS MONTHS YEARS DECADES CENTURIES	String
timeStepInterval (Read and Write)	The time-step interval defines the granularity of the temporal data. The time-step interval can be thought of as how often the time values were recorded in your data.	Double
timeStepIntervalUnits (Read and Write)	The time-step interval unit that describes the timeStepInterval applied to the time values in your data. MILLISECONDS SECONDS MINUTES HOURS DAYS WEEKS MONTHS YEARS DECADES CENTURIES	String
timeZone (Read and Write)	The time zone for the time-enabled layer. Tip: For a list of valid time zone strings, see ListTimeZones.	String

Code sample

LayerTime example 1

The following script tests whether layers in a layer file support time and whether time properties have been set. It then uses time information (start time and end time) to calculate the time extent of a time-enabled layer.

import arcpy
lyrFile = arcpy.mp.LayerFile(r'C:\Projects\Time\ShipPositions.lyrx')
for lyr in lyrFile.listLayers():
    if lyr.supports('TIME'):
        if lyr.isTimeEnabled:
            lyrTime = lyr.time
            startTime = lyrTime.startTime
            endTime = lyrTime.endTime
            timeDelta = endTime - startTime
            print(f"Layer: {lyr.name}")
            print(f"  Start Time: {str(startTime.strftime('%m-%d-%Y'))}")
            print(f"  End Time:   {str(endTime.strftime('%m-%d-%Y'))}")
            print(f"  Time Extent: {str(timeDelta.days)} days")
        else:
            print("No time properties have been set on the layer")
    else:
        print("Time is not supported on this layer")

LayerTime example 2

The following script creates a feature class from input features valid at a certain time, while ensuring that the selection time is within the time extent (start time and end time) of the time-enabled layer.

import arcpy, os

# Setup output location and overwrite status
arcpy.env.overwriteOutput = True
path = r"C:\Projects\Time\Ships"
output_GDB = os.path.join(path, "Ships.gdb")

# Get time information from a layer in a layer file    
lyrFile = arcpy.mp.LayerFile(os.path.join(path, "ShipPositions.lyrx"))
lyr = lyrFile.listLayers()[0]
lyrTime = lyr.time

# Set the time for which you want to select features in the time-enabled layer
fromTimeSelection = datetime.datetime(1776, 1, 1)
toTimeSelection = datetime.datetime(1777, 1, 1)

# Get the start and end time of the time enabled layer and its time field
startTime = lyrTime.startTime
endTime = lyrTime.endTime
timeField = lyrTime.startTimeField

# Check to see if the time for which you want to select features lies within the start and end time of the time enabled layer
if (fromTimeSelection < startTime or toTimeSelection > endTime):
    print("The time specified for selecting features is not within the time extent of the layer")
else:
    # Formulate the time query
    timeQuery = f"{timeField} >= timestamp '{fromTimeSelection}' And \
                  {timeField} < timestamp '{toTimeSelection}'"
    # Process: Feature Class to Feature Class
    arcpy.FeatureClassToFeatureClass_conversion(lyr, output_GDB, "Ships_1776", timeQuery, "", "")

# Add the new layer to a map and enable time
p = arcpy.mp.ArcGISProject(os.path.join(path, "ships.aprx"))
lyt = p.listLayouts('Ships')[0]
mf = lyt.listElements('MAPFRAME_ELEMENT', 'NoTimeMF')[0]
m = mf.map
m.addDataFromPath(os.path.join(output_GDB, "Ships_1776"))
l = m.listLayers("Ships_1776")[0]
l.enableTime()
mt = mf.time
mt.isTimeEnabled = True

# Save a copy of the project
p.saveACopy(os.path.join(path, "ships2.aprx"))