0byt3m1n1
Path:
C:
/
Program Files
/
R
/
R-4.2.2
/
library
/
lubridate
/
doc
/
[
Home
]
File: lubridate.html
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="generator" content="pandoc" /> <meta http-equiv="X-UA-Compatible" content="IE=EDGE" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Do more with dates and times in R</title> <script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to // be compatible with the behavior of Pandoc < 2.8). document.addEventListener('DOMContentLoaded', function(e) { var hs = document.querySelectorAll("div.section[class*='level'] > :first-child"); var i, h, a; for (i = 0; i < hs.length; i++) { h = hs[i]; if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6 a = h.attributes; while (a.length > 0) h.removeAttribute(a[0].name); } }); </script> <script>// Hide empty <a> tag within highlighted CodeBlock for screen reader accessibility (see https://github.com/jgm/pandoc/issues/6352#issuecomment-626106786) --> // v0.0.1 // Written by JooYoung Seo (jooyoung@psu.edu) and Atsushi Yasumoto on June 1st, 2020. document.addEventListener('DOMContentLoaded', function() { const codeList = document.getElementsByClassName("sourceCode"); for (var i = 0; i < codeList.length; i++) { var linkList = codeList[i].getElementsByTagName('a'); for (var j = 0; j < linkList.length; j++) { if (linkList[j].innerHTML === "") { linkList[j].setAttribute('aria-hidden', 'true'); } } } }); </script> <style type="text/css"> code{white-space: pre-wrap;} span.smallcaps{font-variant: small-caps;} span.underline{text-decoration: underline;} div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} </style> <style type="text/css"> code { white-space: pre; } .sourceCode { overflow: visible; } </style> <style type="text/css" data-origin="pandoc"> pre > code.sourceCode { white-space: pre; position: relative; } pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } pre > code.sourceCode > span:empty { height: 1.2em; } code.sourceCode > span { color: inherit; text-decoration: inherit; } div.sourceCode { margin: 1em 0; } pre.sourceCode { margin: 0; } @media screen { div.sourceCode { overflow: auto; } } @media print { pre > code.sourceCode { white-space: pre-wrap; } pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } } pre.numberSource code { counter-reset: source-line 0; } pre.numberSource code > span { position: relative; left: -4em; counter-increment: source-line; } pre.numberSource code > span > a:first-child::before { content: counter(source-line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; padding: 0 4px; width: 4em; color: #aaaaaa; } pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } div.sourceCode { } @media screen { pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } } code span.al { color: #ff0000; font-weight: bold; } /* Alert */ code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ code span.at { color: #7d9029; } /* Attribute */ code span.bn { color: #40a070; } /* BaseN */ code span.bu { } /* BuiltIn */ code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ code span.ch { color: #4070a0; } /* Char */ code span.cn { color: #880000; } /* Constant */ code span.co { color: #60a0b0; font-style: italic; } /* Comment */ code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ code span.do { color: #ba2121; font-style: italic; } /* Documentation */ code span.dt { color: #902000; } /* DataType */ code span.dv { color: #40a070; } /* DecVal */ code span.er { color: #ff0000; font-weight: bold; } /* Error */ code span.ex { } /* Extension */ code span.fl { color: #40a070; } /* Float */ code span.fu { color: #06287e; } /* Function */ code span.im { } /* Import */ code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ code span.kw { color: #007020; font-weight: bold; } /* Keyword */ code span.op { color: #666666; } /* Operator */ code span.ot { color: #007020; } /* Other */ code span.pp { color: #bc7a00; } /* Preprocessor */ code span.sc { color: #4070a0; } /* SpecialChar */ code span.ss { color: #bb6688; } /* SpecialString */ code span.st { color: #4070a0; } /* String */ code span.va { color: #19177c; } /* Variable */ code span.vs { color: #4070a0; } /* VerbatimString */ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ </style> <script> // apply pandoc div.sourceCode style to pre.sourceCode instead (function() { var sheets = document.styleSheets; for (var i = 0; i < sheets.length; i++) { if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue; try { var rules = sheets[i].cssRules; } catch (e) { continue; } var j = 0; while (j < rules.length) { var rule = rules[j]; // check if there is a div.sourceCode rule if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") { j++; continue; } var style = rule.style.cssText; // check if color or background-color is set if (rule.style.color === '' && rule.style.backgroundColor === '') { j++; continue; } // replace div.sourceCode by a pre.sourceCode rule sheets[i].deleteRule(j); sheets[i].insertRule('pre.sourceCode{' + style + '}', j); } } })(); </script> <style type="text/css">body { background-color: #fff; margin: 1em auto; max-width: 700px; overflow: visible; padding-left: 2em; padding-right: 2em; font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-size: 14px; line-height: 1.35; } #TOC { clear: both; margin: 0 0 10px 10px; padding: 4px; width: 400px; border: 1px solid #CCCCCC; border-radius: 5px; background-color: #f6f6f6; font-size: 13px; line-height: 1.3; } #TOC .toctitle { font-weight: bold; font-size: 15px; margin-left: 5px; } #TOC ul { padding-left: 40px; margin-left: -1.5em; margin-top: 5px; margin-bottom: 5px; } #TOC ul ul { margin-left: -2em; } #TOC li { line-height: 16px; } table { margin: 1em auto; border-width: 1px; border-color: #DDDDDD; border-style: outset; border-collapse: collapse; } table th { border-width: 2px; padding: 5px; border-style: inset; } table td { border-width: 1px; border-style: inset; line-height: 18px; padding: 5px 5px; } table, table th, table td { border-left-style: none; border-right-style: none; } table thead, table tr.even { background-color: #f7f7f7; } p { margin: 0.5em 0; } blockquote { background-color: #f6f6f6; padding: 0.25em 0.75em; } hr { border-style: solid; border: none; border-top: 1px solid #777; margin: 28px 0; } dl { margin-left: 0; } dl dd { margin-bottom: 13px; margin-left: 13px; } dl dt { font-weight: bold; } ul { margin-top: 0; } ul li { list-style: circle outside; } ul ul { margin-bottom: 0; } pre, code { background-color: #f7f7f7; border-radius: 3px; color: #333; white-space: pre-wrap; } pre { border-radius: 3px; margin: 5px 0px 10px 0px; padding: 10px; } pre:not([class]) { background-color: #f7f7f7; } code { font-family: Consolas, Monaco, 'Courier New', monospace; font-size: 85%; } p > code, li > code { padding: 2px 0px; } div.figure { text-align: center; } img { background-color: #FFFFFF; padding: 2px; border: 1px solid #DDDDDD; border-radius: 3px; border: 1px solid #CCCCCC; margin: 0 5px; } h1 { margin-top: 0; font-size: 35px; line-height: 40px; } h2 { border-bottom: 4px solid #f7f7f7; padding-top: 10px; padding-bottom: 2px; font-size: 145%; } h3 { border-bottom: 2px solid #f7f7f7; padding-top: 10px; font-size: 120%; } h4 { border-bottom: 1px solid #f7f7f7; margin-left: 8px; font-size: 105%; } h5, h6 { border-bottom: 1px solid #ccc; font-size: 105%; } a { color: #0033dd; text-decoration: none; } a:hover { color: #6666ff; } a:visited { color: #800080; } a:visited:hover { color: #BB00BB; } a[href^="http:"] { text-decoration: underline; } a[href^="https:"] { text-decoration: underline; } code > span.kw { color: #555; font-weight: bold; } code > span.dt { color: #902000; } code > span.dv { color: #40a070; } code > span.bn { color: #d14; } code > span.fl { color: #d14; } code > span.ch { color: #d14; } code > span.st { color: #d14; } code > span.co { color: #888888; font-style: italic; } code > span.ot { color: #007020; } code > span.al { color: #ff0000; font-weight: bold; } code > span.fu { color: #900; font-weight: bold; } code > span.er { color: #a61717; background-color: #e3d2d2; } </style> </head> <body> <h1 class="title toc-ignore">Do more with dates and times in R</h1> <p>(This vignette is an updated version of the blog post first published at <a href="https://www.r-statistics.com/2012/03/do-more-with-dates-and-times-in-r-with-lubridate-1-1-0/">r-statistics</a>_</p> <p>Lubridate is an R package that makes it easier to work with dates and times. Below is a concise tour of some of the things lubridate can do for you. Lubridate was created by Garrett Grolemund and Hadley Wickham, and is now maintained by Vitalie Spinu.</p> <div id="parsing-dates-and-times" class="section level2"> <h2>Parsing dates and times</h2> <p>Getting R to agree that your data contains the dates and times you think it does can be tricky. Lubridate simplifies that. Identify the order in which the year, month, and day appears in your dates. Now arrange “y”, “m”, and “d” in the same order. This is the name of the function in lubridate that will parse your dates. For example,</p> <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true"></a><span class="kw">library</span>(lubridate)</span> <span id="cb1-2"><a href="#cb1-2" aria-hidden="true"></a><span class="co">#> </span></span> <span id="cb1-3"><a href="#cb1-3" aria-hidden="true"></a><span class="co">#> Attaching package: 'lubridate'</span></span> <span id="cb1-4"><a href="#cb1-4" aria-hidden="true"></a><span class="co">#> The following objects are masked from 'package:base':</span></span> <span id="cb1-5"><a href="#cb1-5" aria-hidden="true"></a><span class="co">#> </span></span> <span id="cb1-6"><a href="#cb1-6" aria-hidden="true"></a><span class="co">#> date, intersect, setdiff, union</span></span> <span id="cb1-7"><a href="#cb1-7" aria-hidden="true"></a><span class="kw">ymd</span>(<span class="st">"20110604"</span>)</span> <span id="cb1-8"><a href="#cb1-8" aria-hidden="true"></a><span class="co">#> [1] "2011-06-04"</span></span> <span id="cb1-9"><a href="#cb1-9" aria-hidden="true"></a><span class="kw">mdy</span>(<span class="st">"06-04-2011"</span>)</span> <span id="cb1-10"><a href="#cb1-10" aria-hidden="true"></a><span class="co">#> [1] "2011-06-04"</span></span> <span id="cb1-11"><a href="#cb1-11" aria-hidden="true"></a><span class="kw">dmy</span>(<span class="st">"04/06/2011"</span>)</span> <span id="cb1-12"><a href="#cb1-12" aria-hidden="true"></a><span class="co">#> [1] "2011-06-04"</span></span></code></pre></div> <p>Lubridate’s parse functions handle a wide variety of formats and separators, which simplifies the parsing process.</p> <p>If your date includes time information, add h, m, and/or s to the name of the function. <code>ymd_hms</code> is probably the most common date time format. To read the dates in with a certain time zone, supply the official name of that time zone in the <code>tz</code> argument.</p> <div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true"></a>arrive <-<span class="st"> </span><span class="kw">ymd_hms</span>(<span class="st">"2011-06-04 12:00:00"</span>, <span class="dt">tz =</span> <span class="st">"Pacific/Auckland"</span>)</span> <span id="cb2-2"><a href="#cb2-2" aria-hidden="true"></a>arrive</span> <span id="cb2-3"><a href="#cb2-3" aria-hidden="true"></a><span class="co">#> [1] "2011-06-04 12:00:00 NZST"</span></span> <span id="cb2-4"><a href="#cb2-4" aria-hidden="true"></a>leave <-<span class="st"> </span><span class="kw">ymd_hms</span>(<span class="st">"2011-08-10 14:00:00"</span>, <span class="dt">tz =</span> <span class="st">"Pacific/Auckland"</span>)</span> <span id="cb2-5"><a href="#cb2-5" aria-hidden="true"></a>leave</span> <span id="cb2-6"><a href="#cb2-6" aria-hidden="true"></a><span class="co">#> [1] "2011-08-10 14:00:00 NZST"</span></span></code></pre></div> </div> <div id="setting-and-extracting-information" class="section level2"> <h2>Setting and Extracting information</h2> <p>Extract information from date times with the functions <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>wday</code>, <code>yday</code>, <code>week</code>, <code>month</code>, <code>year</code>, and <code>tz</code>. You can also use each of these to set (i.e, change) the given information. Notice that this will alter the date time. <code>wday</code> and <code>month</code> have an optional <code>label</code> argument, which replaces their numeric output with the name of the weekday or month.</p> <div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true"></a><span class="kw">second</span>(arrive)</span> <span id="cb3-2"><a href="#cb3-2" aria-hidden="true"></a><span class="co">#> [1] 0</span></span> <span id="cb3-3"><a href="#cb3-3" aria-hidden="true"></a><span class="kw">second</span>(arrive) <-<span class="st"> </span><span class="dv">25</span></span> <span id="cb3-4"><a href="#cb3-4" aria-hidden="true"></a>arrive</span> <span id="cb3-5"><a href="#cb3-5" aria-hidden="true"></a><span class="co">#> [1] "2011-06-04 12:00:25 NZST"</span></span> <span id="cb3-6"><a href="#cb3-6" aria-hidden="true"></a><span class="kw">second</span>(arrive) <-<span class="st"> </span><span class="dv">0</span></span> <span id="cb3-7"><a href="#cb3-7" aria-hidden="true"></a></span> <span id="cb3-8"><a href="#cb3-8" aria-hidden="true"></a><span class="kw">wday</span>(arrive)</span> <span id="cb3-9"><a href="#cb3-9" aria-hidden="true"></a><span class="co">#> [1] 7</span></span> <span id="cb3-10"><a href="#cb3-10" aria-hidden="true"></a><span class="kw">wday</span>(arrive, <span class="dt">label =</span> <span class="ot">TRUE</span>)</span> <span id="cb3-11"><a href="#cb3-11" aria-hidden="true"></a><span class="co">#> [1] Sat</span></span> <span id="cb3-12"><a href="#cb3-12" aria-hidden="true"></a><span class="co">#> Levels: Sun < Mon < Tue < Wed < Thu < Fri < Sat</span></span></code></pre></div> </div> <div id="time-zones" class="section level2"> <h2>Time Zones</h2> <p>There are two very useful things to do with dates and time zones. First, display the same moment in a different time zone. Second, create a new moment by combining an existing clock time with a new time zone. These are accomplished by <code>with_tz</code> and <code>force_tz</code>.</p> <p>For example, a while ago I was in Auckland, New Zealand. I arranged to meet the co-author of lubridate, Hadley, over skype at 9:00 in the morning Auckland time. What time was that for Hadley who was back in Houston, TX?</p> <div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true"></a>meeting <-<span class="st"> </span><span class="kw">ymd_hms</span>(<span class="st">"2011-07-01 09:00:00"</span>, <span class="dt">tz =</span> <span class="st">"Pacific/Auckland"</span>)</span> <span id="cb4-2"><a href="#cb4-2" aria-hidden="true"></a><span class="kw">with_tz</span>(meeting, <span class="st">"America/Chicago"</span>)</span> <span id="cb4-3"><a href="#cb4-3" aria-hidden="true"></a><span class="co">#> [1] "2011-06-30 16:00:00 CDT"</span></span></code></pre></div> <p>So the meetings occurred at 4:00 Hadley’s time (and the day before no less). Of course, this was the same actual moment of time as 9:00 in New Zealand. It just appears to be a different day due to the curvature of the Earth.</p> <p>What if Hadley made a mistake and signed on at 9:00 his time? What time would it then be my time?</p> <div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true"></a>mistake <-<span class="st"> </span><span class="kw">force_tz</span>(meeting, <span class="st">"America/Chicago"</span>)</span> <span id="cb5-2"><a href="#cb5-2" aria-hidden="true"></a><span class="kw">with_tz</span>(mistake, <span class="st">"Pacific/Auckland"</span>)</span> <span id="cb5-3"><a href="#cb5-3" aria-hidden="true"></a><span class="co">#> [1] "2011-07-02 02:00:00 NZST"</span></span></code></pre></div> <p>His call would arrive at 2:00 am my time! Luckily he never did that.</p> </div> <div id="time-intervals" class="section level2"> <h2>Time Intervals</h2> <p>You can save an interval of time as an Interval class object with lubridate. This is quite useful! For example, my stay in Auckland lasted from June 4, 2011 to August 10, 2011 (which we’ve already saved as arrive and leave). We can create this interval in one of two ways:</p> <div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true"></a>auckland <-<span class="st"> </span><span class="kw">interval</span>(arrive, leave)</span> <span id="cb6-2"><a href="#cb6-2" aria-hidden="true"></a>auckland</span> <span id="cb6-3"><a href="#cb6-3" aria-hidden="true"></a><span class="co">#> [1] 2011-06-04 12:00:00 NZST--2011-08-10 14:00:00 NZST</span></span> <span id="cb6-4"><a href="#cb6-4" aria-hidden="true"></a>auckland <-<span class="st"> </span>arrive <span class="op">%--%</span><span class="st"> </span>leave</span> <span id="cb6-5"><a href="#cb6-5" aria-hidden="true"></a>auckland</span> <span id="cb6-6"><a href="#cb6-6" aria-hidden="true"></a><span class="co">#> [1] 2011-06-04 12:00:00 NZST--2011-08-10 14:00:00 NZST</span></span></code></pre></div> <p>My mentor at the University of Auckland, Chris, traveled to various conferences that year including the Joint Statistical Meetings (JSM). This took him out of the country from July 20 until the end of August.</p> <div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true"></a>jsm <-<span class="st"> </span><span class="kw">interval</span>(<span class="kw">ymd</span>(<span class="dv">20110720</span>, <span class="dt">tz =</span> <span class="st">"Pacific/Auckland"</span>), <span class="kw">ymd</span>(<span class="dv">20110831</span>, <span class="dt">tz =</span> <span class="st">"Pacific/Auckland"</span>))</span> <span id="cb7-2"><a href="#cb7-2" aria-hidden="true"></a>jsm</span> <span id="cb7-3"><a href="#cb7-3" aria-hidden="true"></a><span class="co">#> [1] 2011-07-20 NZST--2011-08-31 NZST</span></span></code></pre></div> <p>Will my visit overlap with and his travels? Yes.</p> <div class="sourceCode" id="cb8"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true"></a><span class="kw">int_overlaps</span>(jsm, auckland)</span> <span id="cb8-2"><a href="#cb8-2" aria-hidden="true"></a><span class="co">#> [1] TRUE</span></span></code></pre></div> <p>Then I better make hay while the sun shines! For what part of my visit will Chris be there?</p> <div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true"></a><span class="kw">setdiff</span>(auckland, jsm)</span> <span id="cb9-2"><a href="#cb9-2" aria-hidden="true"></a><span class="co">#> [1] 2011-06-04 12:00:00 NZST--2011-07-20 NZST</span></span></code></pre></div> <p>Other functions that work with intervals include <code>int_start</code>, <code>int_end</code>, <code>int_flip</code>, <code>int_shift</code>, <code>int_aligns</code>, <code>union</code>, <code>intersect</code>, <code>setdiff</code>, and <code>%within%</code>.</p> </div> <div id="arithmetic-with-date-times" class="section level2"> <h2>Arithmetic with date times</h2> <p>Intervals are specific time spans (because they are tied to specific dates), but lubridate also supplies two general time span classes: Durations and Periods. Helper functions for creating periods are named after the units of time (plural). Helper functions for creating durations follow the same format but begin with a “d” (for duration) or, if you prefer, and “e” (for exact).</p> <div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true"></a><span class="kw">minutes</span>(<span class="dv">2</span>) <span class="co">## period</span></span> <span id="cb10-2"><a href="#cb10-2" aria-hidden="true"></a><span class="co">#> [1] "2M 0S"</span></span> <span id="cb10-3"><a href="#cb10-3" aria-hidden="true"></a><span class="kw">dminutes</span>(<span class="dv">2</span>) <span class="co">## duration</span></span> <span id="cb10-4"><a href="#cb10-4" aria-hidden="true"></a><span class="co">#> [1] "120s (~2 minutes)"</span></span></code></pre></div> <p>Why two classes? Because the timeline is not as reliable as the number line. The Duration class will always supply mathematically precise results. A duration year will always equal 365 days. Periods, on the other hand, fluctuate the same way the timeline does to give intuitive results. This makes them useful for modeling clock times. For example, durations will be honest in the face of a leap year, but periods may return what you want:</p> <div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true"></a><span class="kw">leap_year</span>(<span class="dv">2011</span>) <span class="co">## regular year</span></span> <span id="cb11-2"><a href="#cb11-2" aria-hidden="true"></a><span class="co">#> [1] FALSE</span></span> <span id="cb11-3"><a href="#cb11-3" aria-hidden="true"></a><span class="kw">ymd</span>(<span class="dv">20110101</span>) <span class="op">+</span><span class="st"> </span><span class="kw">dyears</span>(<span class="dv">1</span>)</span> <span id="cb11-4"><a href="#cb11-4" aria-hidden="true"></a><span class="co">#> [1] "2012-01-01 06:00:00 UTC"</span></span> <span id="cb11-5"><a href="#cb11-5" aria-hidden="true"></a><span class="kw">ymd</span>(<span class="dv">20110101</span>) <span class="op">+</span><span class="st"> </span><span class="kw">years</span>(<span class="dv">1</span>)</span> <span id="cb11-6"><a href="#cb11-6" aria-hidden="true"></a><span class="co">#> [1] "2012-01-01"</span></span> <span id="cb11-7"><a href="#cb11-7" aria-hidden="true"></a></span> <span id="cb11-8"><a href="#cb11-8" aria-hidden="true"></a><span class="kw">leap_year</span>(<span class="dv">2012</span>) <span class="co">## leap year</span></span> <span id="cb11-9"><a href="#cb11-9" aria-hidden="true"></a><span class="co">#> [1] TRUE</span></span> <span id="cb11-10"><a href="#cb11-10" aria-hidden="true"></a><span class="kw">ymd</span>(<span class="dv">20120101</span>) <span class="op">+</span><span class="st"> </span><span class="kw">dyears</span>(<span class="dv">1</span>)</span> <span id="cb11-11"><a href="#cb11-11" aria-hidden="true"></a><span class="co">#> [1] "2012-12-31 06:00:00 UTC"</span></span> <span id="cb11-12"><a href="#cb11-12" aria-hidden="true"></a><span class="kw">ymd</span>(<span class="dv">20120101</span>) <span class="op">+</span><span class="st"> </span><span class="kw">years</span>(<span class="dv">1</span>)</span> <span id="cb11-13"><a href="#cb11-13" aria-hidden="true"></a><span class="co">#> [1] "2013-01-01"</span></span></code></pre></div> <p>You can use periods and durations to do basic arithmetic with date times. For example, if I wanted to set up a reoccuring weekly skype meeting with Hadley, it would occur on:</p> <div class="sourceCode" id="cb12"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true"></a>meetings <-<span class="st"> </span>meeting <span class="op">+</span><span class="st"> </span><span class="kw">weeks</span>(<span class="dv">0</span><span class="op">:</span><span class="dv">5</span>)</span></code></pre></div> <p>Hadley travelled to conferences at the same time as Chris. Which of these meetings would be affected? The last two.</p> <div class="sourceCode" id="cb13"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true"></a>meetings <span class="op">%within%</span><span class="st"> </span>jsm</span> <span id="cb13-2"><a href="#cb13-2" aria-hidden="true"></a><span class="co">#> [1] FALSE FALSE FALSE TRUE TRUE TRUE</span></span></code></pre></div> <p>How long was my stay in Auckland?</p> <div class="sourceCode" id="cb14"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true"></a>auckland <span class="op">/</span><span class="st"> </span><span class="kw">ddays</span>(<span class="dv">1</span>)</span> <span id="cb14-2"><a href="#cb14-2" aria-hidden="true"></a><span class="co">#> [1] 67.08333</span></span> <span id="cb14-3"><a href="#cb14-3" aria-hidden="true"></a>auckland <span class="op">/</span><span class="st"> </span><span class="kw">ddays</span>(<span class="dv">2</span>)</span> <span id="cb14-4"><a href="#cb14-4" aria-hidden="true"></a><span class="co">#> [1] 33.54167</span></span> <span id="cb14-5"><a href="#cb14-5" aria-hidden="true"></a>auckland <span class="op">/</span><span class="st"> </span><span class="kw">dminutes</span>(<span class="dv">1</span>)</span> <span id="cb14-6"><a href="#cb14-6" aria-hidden="true"></a><span class="co">#> [1] 96600</span></span></code></pre></div> <p>And so on. Alternatively, we can do modulo and integer division. Sometimes this is more sensible than division - it is not obvious how to express a remainder as a fraction of a month because the length of a month constantly changes.</p> <div class="sourceCode" id="cb15"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true"></a>auckland <span class="op">%/%</span><span class="st"> </span><span class="kw">months</span>(<span class="dv">1</span>)</span> <span id="cb15-2"><a href="#cb15-2" aria-hidden="true"></a><span class="co">#> [1] 2</span></span> <span id="cb15-3"><a href="#cb15-3" aria-hidden="true"></a>auckland <span class="op">%%</span><span class="st"> </span><span class="kw">months</span>(<span class="dv">1</span>)</span> <span id="cb15-4"><a href="#cb15-4" aria-hidden="true"></a><span class="co">#> [1] 2011-08-04 12:00:00 NZST--2011-08-10 14:00:00 NZST</span></span></code></pre></div> <p>Modulo with an timespan returns the remainder as a new (smaller) interval. You can turn this or any interval into a generalized time span with <code>as.period</code>.</p> <div class="sourceCode" id="cb16"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true"></a><span class="kw">as.period</span>(auckland <span class="op">%%</span><span class="st"> </span><span class="kw">months</span>(<span class="dv">1</span>))</span> <span id="cb16-2"><a href="#cb16-2" aria-hidden="true"></a><span class="co">#> [1] "6d 2H 0M 0S"</span></span> <span id="cb16-3"><a href="#cb16-3" aria-hidden="true"></a><span class="kw">as.period</span>(auckland)</span> <span id="cb16-4"><a href="#cb16-4" aria-hidden="true"></a><span class="co">#> [1] "2m 6d 2H 0M 0S"</span></span></code></pre></div> <div id="if-anyone-drove-a-time-machine-they-would-crash" class="section level3"> <h3>If anyone drove a time machine, they would crash</h3> <p>The length of months and years change so often that doing arithmetic with them can be unintuitive. Consider a simple operation, <code>January 31st + one month</code>. Should the answer be</p> <ol style="list-style-type: decimal"> <li><code>February 31st</code> (which doesn’t exist)</li> <li><code>March 4th</code> (31 days after January 31), or</li> <li><code>February 28th</code> (assuming its not a leap year)</li> </ol> <p>A basic property of arithmetic is that <code>a + b - b = a</code>. Only solution 1 obeys this property, but it is an invalid date. I’ve tried to make lubridate as consistent as possible by invoking the following rule <em>if adding or subtracting a month or a year creates an invalid date, lubridate will return an NA</em>. This is new with version 1.3.0, so if you’re an old hand with lubridate be sure to remember this!</p> <p>If you thought solution 2 or 3 was more useful, no problem. You can still get those results with clever arithmetic, or by using the special <code>%m+%</code> and <code>%m-%</code> operators. <code>%m+%</code> and <code>%m-%</code> automatically roll dates back to the last day of the month, should that be necessary.</p> <div class="sourceCode" id="cb17"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true"></a>jan31 <-<span class="st"> </span><span class="kw">ymd</span>(<span class="st">"2013-01-31"</span>)</span> <span id="cb17-2"><a href="#cb17-2" aria-hidden="true"></a>jan31 <span class="op">+</span><span class="st"> </span><span class="kw">months</span>(<span class="dv">0</span><span class="op">:</span><span class="dv">11</span>)</span> <span id="cb17-3"><a href="#cb17-3" aria-hidden="true"></a><span class="co">#> [1] "2013-01-31" NA "2013-03-31" NA "2013-05-31"</span></span> <span id="cb17-4"><a href="#cb17-4" aria-hidden="true"></a><span class="co">#> [6] NA "2013-07-31" "2013-08-31" NA "2013-10-31"</span></span> <span id="cb17-5"><a href="#cb17-5" aria-hidden="true"></a><span class="co">#> [11] NA "2013-12-31"</span></span> <span id="cb17-6"><a href="#cb17-6" aria-hidden="true"></a><span class="kw">floor_date</span>(jan31, <span class="st">"month"</span>) <span class="op">+</span><span class="st"> </span><span class="kw">months</span>(<span class="dv">0</span><span class="op">:</span><span class="dv">11</span>) <span class="op">+</span><span class="st"> </span><span class="kw">days</span>(<span class="dv">31</span>)</span> <span id="cb17-7"><a href="#cb17-7" aria-hidden="true"></a><span class="co">#> [1] "2013-02-01" "2013-03-04" "2013-04-01" "2013-05-02" "2013-06-01"</span></span> <span id="cb17-8"><a href="#cb17-8" aria-hidden="true"></a><span class="co">#> [6] "2013-07-02" "2013-08-01" "2013-09-01" "2013-10-02" "2013-11-01"</span></span> <span id="cb17-9"><a href="#cb17-9" aria-hidden="true"></a><span class="co">#> [11] "2013-12-02" "2014-01-01"</span></span> <span id="cb17-10"><a href="#cb17-10" aria-hidden="true"></a>jan31 <span class="op">%m+%</span><span class="st"> </span><span class="kw">months</span>(<span class="dv">0</span><span class="op">:</span><span class="dv">11</span>)</span> <span id="cb17-11"><a href="#cb17-11" aria-hidden="true"></a><span class="co">#> [1] "2013-01-31" "2013-02-28" "2013-03-31" "2013-04-30" "2013-05-31"</span></span> <span id="cb17-12"><a href="#cb17-12" aria-hidden="true"></a><span class="co">#> [6] "2013-06-30" "2013-07-31" "2013-08-31" "2013-09-30" "2013-10-31"</span></span> <span id="cb17-13"><a href="#cb17-13" aria-hidden="true"></a><span class="co">#> [11] "2013-11-30" "2013-12-31"</span></span></code></pre></div> <p>Notice that this will only affect arithmetic with months (and arithmetic with years if your start date it Feb 29).</p> </div> </div> <div id="vectorization" class="section level2"> <h2>Vectorization</h2> <p>The code in lubridate is vectorized and ready to be used in both interactive settings and within functions. As an example, I offer a function for advancing a date to the last day of the month</p> <div class="sourceCode" id="cb18"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true"></a>last_day <-<span class="st"> </span><span class="cf">function</span>(date) {</span> <span id="cb18-2"><a href="#cb18-2" aria-hidden="true"></a> <span class="kw">ceiling_date</span>(date, <span class="st">"month"</span>) <span class="op">-</span><span class="st"> </span><span class="kw">days</span>(<span class="dv">1</span>)</span> <span id="cb18-3"><a href="#cb18-3" aria-hidden="true"></a>}</span></code></pre></div> </div> <div id="further-resources" class="section level2"> <h2>Further Resources</h2> <p>To learn more about lubridate, including the specifics of periods and durations, please read the <a href="https://www.jstatsoft.org/v40/i03/">original lubridate paper</a>. Questions about lubridate can be addressed to the lubridate google group. Bugs and feature requests should be submitted to the <a href="https://github.com/tidyverse/lubridate">lubridate development page</a> on github.</p> </div> <!-- code folding --> <!-- dynamically load mathjax for compatibility with self-contained --> <script> (function () { var script = document.createElement("script"); script.type = "text/javascript"; script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"; document.getElementsByTagName("head")[0].appendChild(script); })(); </script> </body> </html>