ArcGIS Help 10.1 - DataFrameTime (arcpy.mapping)

Summary

The DataFrameTime object provides access to time management operations for time-enabled layers in a data frame.

Discussion

The DataFrameTime object provides capabilities for two basic scenarios:

The first scenario is for map documents that have already been published with time-enabled layers where settings were established via the Time Slider Options dialog box and saved with the map document. With this scenario, those existing properties can be used for automating output. Examples 1 and 2 below are examples for this first scenario.
The second scenario deals with map documents that don't have any time-enabled layers but that time-enabled layers are added by a script and therefore the time slider options need to be set so that the desired output can be automated. Example 3 below represents this second scenario.

The timeStepInterval uses the EsriTimeDelta class. The EsriTimeDelta class is an alternative to the core python datetime.timedelta and uses internal Esri time units for intervals that can't be handled by the core python timedelta object (such as months, weeks, etc.) The timeStepInterval can be used to loop through dates and times. If you want to use a different time interval within a loop, create a new python timedelta object or an EsriTimeDelta object (see example 3 below). Be aware that if the timeWindowUnits are modified and saved, it will affect the timeStepInterval.

Legacy:

Prior to the 10.1 release, the timeStepInterval property from the DataFrameTime class returned a python datetime.timedelta object.

To embed a time stamp within an image when exporting a data frame, use time text.

There are numerous help articles concerning time in ArcGIS. Here are a few that are most related to the methods and properties on the DataFrameTime object:

Properties

Property	Explanation	Data Type
currentTime (Read and Write)	The current date and time for a data frame with time-enabled layers. The same property can be found in the Time Slider Options dialog box in ArcMap.	DateTime
endTime (Read and Write)	The end date and time for a data frame with time-enabled layers. The same property can be found in the Time Slider Options dialog box in ArcMap.	DateTime
startTime (Read and Write)	The start date and time for a data frame with time-enabled layers. The same property can be found in the Time Slider Options dialog box in ArcMap.	DateTime
timeStepInterval (Read Only)	Returns the time step interval that has been set via the Time Slider Options dialog box in ArcMap. This value is a EsriTimeDelta object and is used to iterate over a period of time (e.g., 2 days, 1 month, and so on).	EsriTimeDelta
timeWindow (Read and Write)	The time window that controls how many units (e.g., days) of time-enabled data appear prior to and including the current time. For example, if timeWindow is set to 1 and timeWindowUnits is set to weeks, then the time window will be 2 weeks.	Double
timeWindowUnits (Read and Write)	The units that are used with the TimeStepInterval and the TimeWindow properties. The valid units are: MILLISECONDS SECONDS MINUTES HOURS DAYS WEEKS MONTHS YEARS DECADES CENTURIES	String

Method Overview

Method	Explanation
resetTimeExtent ()	Resets the time extent to the time window extent of all time-enabled layers in a data frame

Methods

resetTimeExtent ()

This performs the same operation as clicking the Min Time and Max Time buttons on the Time Slider Options dialog box in ArcMap.

Code Sample

DataFrameTime example 1

The following script uses time settings (start time, end time, and time interval) published in an existing map document to export a series of images. Each output image is given a unique name using the parsed date information from the time stamp.

import arcpy
import os

mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Traffic Analysis")[0]
df.time.currentTime = df.time.startTime

while df.time.currentTime <= df.time.endTime:
    # An example str(newTime) would be: "2008-12-29 02:19:59"
    # The following line splits the string at the space and takes the first 
    # item in the resulting string.  
    fileName = str(df.time.currentTime).split(" ")[0] + ".png"
    arcpy.mapping.ExportToPNG(mxd, os.path.join(r"C:\Project\Output", fileName), df)
    df.time.currentTime = df.time.currentTime + df.time.timeStepInterval
del mxd

DataFrameTime example 2

The following script is identical to example 1 above but uses a modified start time, end time, and interval that are different from the existing settings that were published in a time-enabled data frame within a map document. The Python datetime module is used to create times and time deltas. Alternatively, the EsriTimeDelta class could also be used to create time deltas.

import arcpy
import datetime
import os

mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Traffic Analysis")[0]
df.time.currentTime = datetime.datetime(2008, 10, 1)
endTime = datetime.datetime(2008, 10, 31)
interval = datetime.timedelta(days=7)

while df.time.currentTime <= endTime:
    # An example str(newTime) would be: "2008-01-29 02:19:59"
    # The following line splits the string at the space and takes the first 
    # item in the resulting string.  
    fileName = str(df.time.currentTime).split(" ")[0] + ".png"
    arcpy.mapping.ExportToPNG(mxd, os.path.join(r"C:\Project\Output", fileName), df)
    df.time.currentTime = df.time.currentTime + interval
del mxd

DataFrameTime example 3

The following script represents a scenario in which a new time-enabled layer file is added to a new data frame that is not time aware; therefore, the time slider properties are not set within the map document. This script adds a time-enabled layer to the data frame using the AddLayer function and then sets the appropriate time settings similar to the scripts above. In this example, the time interval is set using the EsriTimeDelta class. Alternatively, the Python datetime module could be used to create the time delta.

import arcpy
import datetime
import os

mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "New Data Frame")[0]
timeLayer = arcpy.mapping.Layer(r"C:\Project\Data\Accidents.lyr")
arcpy.mapping.AddLayer(df, timeLayer, "AUTO_ARRANGE")
df.time.resetTimeExtent()
df.time.timeWindowUnits = "DAYS"
df.time.timeWindow = 7
df.time.currentTime = datetime.datetime(2008, 10, 1)
endTime = datetime.datetime(2008, 10, 31)
interval = arcpy.time.EsriTimeDelta(1, 'weeks')

while df.time.currentTime <= endTime:
    # An example str(newTime) would be: "2008-01-29 02:19:59"
    # The following line splits the string at the space and takes the first
    # item in the resulting string.
    fileName = str(df.time.currentTime).split(" ")[0] + ".png"
    arcpy.mapping.ExportToPNG(mxd, os.path.join(r"C:\Project\Output", fileName))
    df.time.currentTime = df.time.currentTime + interval
del mxd, timeLayer

5/7/2013