Check out this app<\/a>, where I used several Arcade expressions to answer time-related questions about 311 data in New York City<\/a>. These questions include:<\/p>\n Arcade has several out-of-the-box date functions that simplify the process for answering these questions. Functions such as DateAdd()<\/a>, DateDiff()<\/a>, toUTC()<\/a>, Hour()<\/a>, Weekday()<\/a>, and others are available for your convenience when exploring and displaying time data. These functions can be used to quickly make several unique time-based visualizations that show various patterns throughout the city. <\/p>\n In the 311 app<\/a>, the following expressions help us answer the questions listed above. Different patterns emerge depending on filters to the time of day, and the type of incident. <\/p>\n Was the incident overdue at the time of closure? If so, by how long?<\/strong><\/p>\n How long was the incident open at the time of its closure?<\/strong><\/p>\n At what time of day was the incident reported (morning, afternoon, evening)?<\/strong><\/p>\n Easy, right? Not so fast…<\/p>\n Date and time data are notoriously difficult<\/a> to work with. If date calculations haven\u2019t caused you to bang your head against the wall or pull your hair out with frustration, then you probably haven\u2019t spent enough time working with them.<\/p>\n A lot of the confusion stems from time zone offsets<\/a> and locations that observe Daylight Savings Time<\/a> (and those that don’t). Those concepts are further compounded when you consider that the client (browser) interprets the date in the time zone in which it is located regardless of where the data is located. To further add to the confusion, dates can either be published in the time zone in which they were collected, or in UTC time<\/a>. Is your head spinning yet?<\/p>\n It is important to keep these considerations in mind when attempting to visualize time of day for the location of each feature. For example, see the expression below, which was referenced earlier.<\/p>\n Before proceeding to accept this as a valid expression, we need to understand how the data was published (or should be published). Do the recorded times represent the local time where the data was collected? Or do they represent UTC time? Are the data points located in one time zone, or do they span multiple time zones? If the timestamps reflect UTC time, then you’re good to go. If they represent local times then the timestamps should include the UTC offset. <\/p>\n This is particularly important for data that spans more than one time zone. Even if the data was collected in the same time zone, the offset helps determine if it represents time during Daylight Savings Time or Standard Time. For example, if you collect data in the Eastern Time Zone, then the offset to append to the time would be -4 during Daylight Savings Time and -5 during Standard Time. See the image below for an example of how to indicate this in a CSV file intended for publishing as a hosted feature service in ArcGIS Online.<\/p>\n However, publishing data from a CSV file to ArcGIS Online simplifies the process for you. If the data is collected in the same time zone but doesn\u2019t include the offset information, you can indicate the time zone offset when you publish the data to ArcGIS Online. Check out this blog<\/a>, which goes more in depth about the various things you should consider when publishing time data to ArcGIS Online, whether from CSV or from ArcGIS Pro.<\/p>\n When entering date and time data, just remember to either record dates using UTC times or to include the UTC offset in the date field. Consistency is the key. It will make your project much easier to work with later. Read the ArcGIS Online documentation for working with date fields<\/a> for more information about the publishing process.<\/p>\n In the 311 exploration app<\/a> referenced above, the data was recorded in Eastern time. So we know we can publish the CSV data as a hosted feature service with the appropriate time offset of -4 or -5. Remember, we attempted to visualize incidents based on the time of day in the locations where they were reported. Features are visualized with unique values depending on whether they occurred in the morning, midday, afternoon, evening, or night. Here’s the starting expression for reference (note that my interpretation of “time of day” may be different from yours):<\/p>\n The But this is where we need to hit the brakes. It is important to note that Arcade, like JavaScript, interprets dates in the locale of the browser running the app. Since we\u2019re dealing with data collected in New York City, this expression would only display the proper visualization for browsers running the app in the Eastern Time Zone.<\/p>\n If I run this expression in the Pacific Time Zone, I see the visualization on the left (click the images to view larger versions of them). The correct visualization is on the right (as seen in the Eastern Time Zone).<\/p>\n\n
Date functions in Arcade<\/h2>\n
\r\nvar<\/span> closed = $feature.Closed_Date;\r\nvar<\/span> due = $feature.Due_Date;\r\nvar<\/span> closureDueDiff = DateDiff(closed, due, \"days\"<\/span>);\r\nIIF(IsEmpty(closed) || IsEmpty(due), 0<\/span>, closureDueDiff);\r\n<\/pre>\n![\"\"](\"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2017\/10\/1-overdue-clusters.png\")
<\/a><\/p>\n\r\nvar<\/span> closed = $feature.Closed_Date;\r\nvar<\/span> created = $feature.Created_Date;\r\nIIF(IsEmpty(closed) || IsEmpty(created), 0<\/span>, DateDiff(closed, created, \"days\"<\/span>));\r\n<\/pre>\n![\"\"](\"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2017\/10\/2-age-clusters.png\")
<\/a><\/p>\n\r\nvar<\/span> t = Hour($feature.Created_Date);\r\nWhen(\r\n t >= 22<\/span> || t < 6<\/span>, \"Night\"<\/span>,\r\n t >= 6<\/span> && t < 11<\/span>, \"Morning\"<\/span>,\r\n t >= 11<\/span> && t < 13<\/span>, \"Midday\"<\/span>, \r\n t >= 13<\/span> && t < 17<\/span>, \"Afternoon\"<\/span>,\r\n t >= 17<\/span> && t < 22<\/span>, \"Evening\"<\/span>,\r\n\"Invalid date\"<\/span> );\r\n<\/pre>\n![\"\"](\"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2017\/10\/3-tod-clusters.png\")
<\/a><\/p>\nDates are confusing<\/h2>\n
\r\nvar<\/span> t = Hour($feature.Created_Date);\r\nWhen(\r\n t >= 22<\/span> || t < 6<\/span>, \"Night\"<\/span>,\r\n t >= 6<\/span> && t < 11<\/span>, \"Morning\"<\/span>,\r\n t >= 11<\/span> && t < 13<\/span>, \"Midday\"<\/span>, \r\n t >= 13<\/span> && t < 17<\/span>, \"Afternoon\"<\/span>,\r\n t >= 17<\/span> && t < 22<\/span>, \"Evening\"<\/span>,\r\n\"Invalid date\"<\/span> );\r\n<\/pre>\nPublishing times and dates<\/h2>\n
![\"\"](\"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2017\/10\/4-table-offsets.png\")
<\/a><\/p>\n![\"\"](\"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2017\/10\/5-ago-offset-option.png\")
<\/a><\/p>\nTime of day \u2013 in one time zone<\/h2>\n
\r\nvar<\/span> t = Hour($feature.Created_Date);\r\nWhen(\r\n t >= 22<\/span> || t < 6<\/span>, \"Night\"<\/span>,\r\n t >= 6<\/span> && t < 11<\/span>, \"Morning\"<\/span>,\r\n t >= 11<\/span> && t < 13<\/span>, \"Midday\"<\/span>, \r\n t >= 13<\/span> && t < 17<\/span>, \"Afternoon\"<\/span>,\r\n t >= 17<\/span> && t < 22<\/span>, \"Evening\"<\/span>,\r\n\"Invalid date\"<\/span> );\r\n<\/pre>\nt<\/code> variable represents the hour<\/a> of the day the incident was created. The When()<\/a> logical function is used to evaluate the hour in several predefined ranges. It then returns a string indicating the relative time of day the incident occurred. <\/p>\n
![\"\"](\"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2017\/10\/6a-ptz-viz-300x183.png\")
<\/a><\/td>\n![\"\"](\"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2017\/10\/6b-etz-viz-300x201.png\")
<\/a><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n