course/r4ds
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Don't transform non-crossref links

Browse Source
This commit is contained in:
Hadley Wickham
2022-11-18 10:30:32 -06:00
parent 4caea5281b
commit 78a1c12fe7
32 changed files with 693 additions and 693 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
oreilly/datetimes.html
View File

@@ -38,7 +38,7 @@ Creating date/times</h1>
<li><p>A <strong>date-time</strong> is a date plus a time: it uniquely identifies an instant in time (typically to the nearest second). Tibbles print this as <code>&lt;dttm&gt;</code>. Base R calls these POSIXct, but doesn’t exactly trip off the tongue.</p></li>
</ul><p>In this chapter we are going to focus on dates and date-times as R doesn’t have a native class for storing times. If you need one, you can use the <strong>hms</strong> package.</p>
<p>You should always use the simplest possible data type that works for your needs. That means if you can use a date instead of a date-time, you should. Date-times are substantially more complicated because of the need to handle time zones, which we’ll come back to at the end of the chapter.</p>
<p>To get the current date or date-time you can use <code><a href="#chp-https://lubridate.tidyverse.org/reference/now" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/now</a></code> or <code><a href="#chp-https://lubridate.tidyverse.org/reference/now" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/now</a></code>:</p>
<p>To get the current date or date-time you can use <code><a href="https://lubridate.tidyverse.org/reference/now.html">today()</a></code> or <code><a href="https://lubridate.tidyverse.org/reference/now.html">now()</a></code>:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">today()
#&gt; [1] "2022-11-18"
@@ -67,7 +67,7 @@ read_csv(csv)
#&gt; 1 2022-01-02 2022-01-02 05:12:00</pre>
</div>
<p>If you haven’t heard of <strong>ISO8601</strong> before, it’s an international standard<span data-type="footnote"><a href="https://xkcd.com/1179/" class="uri">https://xkcd.com/1179/</a></span> for writing dates where the components of a date are organised from biggest to smallest separated by <code>-</code>. For example, in ISO8601 March 5 2022 is <code>2022-05-03</code>. ISO8601 dates can also include times, where hour, minute, and second are separated by <code>:</code>, and the date and time components are separated by either a <code>T</code> or a space. For example, you could write 4:26pm on March 5 2022 as either <code>2022-05-03 16:26</code> or <code>2022-05-03T16:26</code>.</p>
<p>For other date-time formats, you’ll need to use <code>col_types</code> plus <code><a href="#chp-https://readr.tidyverse.org/reference/parse_datetime" data-type="xref">#chp-https://readr.tidyverse.org/reference/parse_datetime</a></code> or <code><a href="#chp-https://readr.tidyverse.org/reference/parse_datetime" data-type="xref">#chp-https://readr.tidyverse.org/reference/parse_datetime</a></code> along with a date-time format. The date-time format used by readr is a standard used across many programming languages, describing a date component with a <code>%</code> followed by a single character. For example, <code>%Y-%m-%d</code> specifies a date that’s a year, <code>-</code>, month (as number) <code>-</code>, day. Table <a href="#tbl-date-formats" data-type="xref">#tbl-date-formats</a> lists all the options.</p>
<p>For other date-time formats, you’ll need to use <code>col_types</code> plus <code><a href="https://readr.tidyverse.org/reference/parse_datetime.html">col_date()</a></code> or <code><a href="https://readr.tidyverse.org/reference/parse_datetime.html">col_datetime()</a></code> along with a date-time format. The date-time format used by readr is a standard used across many programming languages, describing a date component with a <code>%</code> followed by a single character. For example, <code>%Y-%m-%d</code> specifies a date that’s a year, <code>-</code>, month (as number) <code>-</code>, day. Table <a href="#tbl-date-formats" data-type="xref">#tbl-date-formats</a> lists all the options.</p>
<div id="tbl-date-formats" class="anchored">
<table class="table"><caption>Table 17.1: All date formats understood by readr</caption>
<thead><tr class="header"><th>Type</th>
@@ -169,7 +169,7 @@ read_csv(csv, col_types = cols(date = col_date("%y/%m/%d")))
#&gt; 1 2001-02-15</pre>
</div>
<p>Note that no matter how you specify the date format, it’s always displayed the same way once you get it into R.</p>
<p>If you’re using <code>%b</code> or <code>%B</code> and working with non-English dates, you’ll also need to provide a <code><a href="#chp-https://readr.tidyverse.org/reference/locale" data-type="xref">#chp-https://readr.tidyverse.org/reference/locale</a></code>. See the list of built-in languages in <code><a href="#chp-https://readr.tidyverse.org/reference/date_names" data-type="xref">#chp-https://readr.tidyverse.org/reference/date_names</a></code>, or create your own with <code><a href="#chp-https://readr.tidyverse.org/reference/date_names" data-type="xref">#chp-https://readr.tidyverse.org/reference/date_names</a></code>,</p>
<p>If you’re using <code>%b</code> or <code>%B</code> and working with non-English dates, you’ll also need to provide a <code><a href="https://readr.tidyverse.org/reference/locale.html">locale()</a></code>. See the list of built-in languages in <code><a href="https://readr.tidyverse.org/reference/date_names.html">date_names_langs()</a></code>, or create your own with <code><a href="https://readr.tidyverse.org/reference/date_names.html">date_names()</a></code>,</p>
</section>
<section id="from-strings" data-type="sect2">
@@ -184,7 +184,7 @@ mdy("January 31st, 2017")
dmy("31-Jan-2017")
#&gt; [1] "2017-01-31"</pre>
</div>
<p><code><a href="#chp-https://lubridate.tidyverse.org/reference/ymd" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/ymd</a></code> and friends create dates. To create a date-time, add an underscore and one or more of “h”, “m”, and “s” to the name of the parsing function:</p>
<p><code><a href="https://lubridate.tidyverse.org/reference/ymd.html">ymd()</a></code> and friends create dates. To create a date-time, add an underscore and one or more of “h”, “m”, and “s” to the name of the parsing function:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">ymd_hms("2017-01-31 20:11:59")
#&gt; [1] "2017-01-31 20:11:59 UTC"
@@ -216,7 +216,7 @@ From individual components</h2>
#&gt; 6 2013 1 1 5 58
#&gt; # … with 336,770 more rows</pre>
</div>
<p>To create a date/time from this sort of input, use <code><a href="#chp-https://lubridate.tidyverse.org/reference/make_datetime" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/make_datetime</a></code> for dates, or <code><a href="#chp-https://lubridate.tidyverse.org/reference/make_datetime" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/make_datetime</a></code> for date-times:</p>
<p>To create a date/time from this sort of input, use <code><a href="https://lubridate.tidyverse.org/reference/make_datetime.html">make_date()</a></code> for dates, or <code><a href="https://lubridate.tidyverse.org/reference/make_datetime.html">make_datetime()</a></code> for date-times:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">flights |&gt;
select(year, month, day, hour, minute) |&gt;
@@ -286,14 +286,14 @@ flights_dt
<section id="from-other-types" data-type="sect2">
<h2>
From other types</h2>
<p>You may want to switch between a date-time and a date. That’s the job of <code><a href="#chp-https://lubridate.tidyverse.org/reference/as_date" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/as_date</a></code> and <code><a href="#chp-https://lubridate.tidyverse.org/reference/as_date" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/as_date</a></code>:</p>
<p>You may want to switch between a date-time and a date. That’s the job of <code><a href="https://lubridate.tidyverse.org/reference/as_date.html">as_datetime()</a></code> and <code><a href="https://lubridate.tidyverse.org/reference/as_date.html">as_date()</a></code>:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">as_datetime(today())
#&gt; [1] "2022-11-18 UTC"
as_date(now())
#&gt; [1] "2022-11-18"</pre>
</div>
<p>Sometimes you’ll get date/times as numeric offsets from the “Unix Epoch”, 1970-01-01. If the offset is in seconds, use <code><a href="#chp-https://lubridate.tidyverse.org/reference/as_date" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/as_date</a></code>; if it’s in days, use <code><a href="#chp-https://lubridate.tidyverse.org/reference/as_date" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/as_date</a></code>.</p>
<p>Sometimes you’ll get date/times as numeric offsets from the “Unix Epoch”, 1970-01-01. If the offset is in seconds, use <code><a href="https://lubridate.tidyverse.org/reference/as_date.html">as_datetime()</a></code>; if it’s in days, use <code><a href="https://lubridate.tidyverse.org/reference/as_date.html">as_date()</a></code>.</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">as_datetime(60 * 60 * 10)
#&gt; [1] "1970-01-01 10:00:00 UTC"
@@ -311,7 +311,7 @@ Exercises</h2>
<pre data-type="programlisting" data-code-language="downlit">ymd(c("2010-10-10", "bananas"))</pre>
</div>
</li>
<li><p>What does the <code>tzone</code> argument to <code><a href="#chp-https://lubridate.tidyverse.org/reference/now" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/now</a></code> do? Why is it important?</p></li>
<li><p>What does the <code>tzone</code> argument to <code><a href="https://lubridate.tidyverse.org/reference/now.html">today()</a></code> do? Why is it important?</p></li>
<li>
<p>For each of the following date-times show how you’d parse it using a readr column-specification and a lubridate function.</p>
<div class="cell">
@@ -335,7 +335,7 @@ Date-time components</h1>
<section id="getting-components" data-type="sect2">
<h2>
Getting components</h2>
<p>You can pull out individual parts of the date with the accessor functions <code><a href="#chp-https://lubridate.tidyverse.org/reference/year" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/year</a></code>, <code><a href="#chp-https://lubridate.tidyverse.org/reference/month" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/month</a></code>, <code><a href="#chp-https://lubridate.tidyverse.org/reference/day" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/day</a></code> (day of the month), <code><a href="#chp-https://lubridate.tidyverse.org/reference/day" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/day</a></code> (day of the year), <code><a href="#chp-https://lubridate.tidyverse.org/reference/day" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/day</a></code> (day of the week), <code><a href="#chp-https://lubridate.tidyverse.org/reference/hour" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/hour</a></code>, <code><a href="#chp-https://lubridate.tidyverse.org/reference/minute" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/minute</a></code>, and <code><a href="#chp-https://lubridate.tidyverse.org/reference/second" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/second</a></code>.</p>
<p>You can pull out individual parts of the date with the accessor functions <code><a href="https://lubridate.tidyverse.org/reference/year.html">year()</a></code>, <code><a href="https://lubridate.tidyverse.org/reference/month.html">month()</a></code>, <code><a href="https://lubridate.tidyverse.org/reference/day.html">mday()</a></code> (day of the month), <code><a href="https://lubridate.tidyverse.org/reference/day.html">yday()</a></code> (day of the year), <code><a href="https://lubridate.tidyverse.org/reference/day.html">wday()</a></code> (day of the week), <code><a href="https://lubridate.tidyverse.org/reference/hour.html">hour()</a></code>, <code><a href="https://lubridate.tidyverse.org/reference/minute.html">minute()</a></code>, and <code><a href="https://lubridate.tidyverse.org/reference/second.html">second()</a></code>.</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">datetime &lt;- ymd_hms("2026-07-08 12:34:56")
@@ -351,7 +351,7 @@ yday(datetime)
wday(datetime)
#&gt; [1] 4</pre>
</div>
<p>For <code><a href="#chp-https://lubridate.tidyverse.org/reference/month" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/month</a></code> and <code><a href="#chp-https://lubridate.tidyverse.org/reference/day" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/day</a></code> you can set <code>label = TRUE</code> to return the abbreviated name of the month or day of the week. Set <code>abbr = FALSE</code> to return the full name.</p>
<p>For <code><a href="https://lubridate.tidyverse.org/reference/month.html">month()</a></code> and <code><a href="https://lubridate.tidyverse.org/reference/day.html">wday()</a></code> you can set <code>label = TRUE</code> to return the abbreviated name of the month or day of the week. Set <code>abbr = FALSE</code> to return the full name.</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">month(datetime, label = TRUE)
#&gt; [1] Jul
@@ -360,7 +360,7 @@ wday(datetime, label = TRUE, abbr = FALSE)
#&gt; [1] Wednesday
#&gt; 7 Levels: Sunday &lt; Monday &lt; Tuesday &lt; Wednesday &lt; Thursday &lt; ... &lt; Saturday</pre>
</div>
<p>We can use <code><a href="#chp-https://lubridate.tidyverse.org/reference/day" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/day</a></code> to see that more flights depart during the week than on the weekend:</p>
<p>We can use <code><a href="https://lubridate.tidyverse.org/reference/day.html">wday()</a></code> to see that more flights depart during the week than on the weekend:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">flights_dt |&gt;
mutate(wday = wday(dep_time, label = TRUE)) |&gt;
@@ -412,7 +412,7 @@ ggplot(sched_dep, aes(minute, avg_delay)) +
<section id="rounding" data-type="sect2">
<h2>
Rounding</h2>
<p>An alternative approach to plotting individual components is to round the date to a nearby unit of time, with <code><a href="#chp-https://lubridate.tidyverse.org/reference/round_date" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/round_date</a></code>, <code><a href="#chp-https://lubridate.tidyverse.org/reference/round_date" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/round_date</a></code>, and <code><a href="#chp-https://lubridate.tidyverse.org/reference/round_date" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/round_date</a></code>. Each function takes a vector of dates to adjust and then the name of the unit round down (floor), round up (ceiling), or round to. This, for example, allows us to plot the number of flights per week:</p>
<p>An alternative approach to plotting individual components is to round the date to a nearby unit of time, with <code><a href="https://lubridate.tidyverse.org/reference/round_date.html">floor_date()</a></code>, <code><a href="https://lubridate.tidyverse.org/reference/round_date.html">round_date()</a></code>, and <code><a href="https://lubridate.tidyverse.org/reference/round_date.html">ceiling_date()</a></code>. Each function takes a vector of dates to adjust and then the name of the unit round down (floor), round up (ceiling), or round to. This, for example, allows us to plot the number of flights per week:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">flights_dt |&gt;
count(week = floor_date(dep_time, "week")) |&gt;
@@ -465,7 +465,7 @@ hour(datetime) &lt;- hour(datetime) + 1
datetime
#&gt; [1] "2030-01-08 13:34:56 UTC"</pre>
</div>
<p>Alternatively, rather than modifying an existing variabke, you can create a new date-time with <code><a href="#chp-https://rdrr.io/r/stats/update" data-type="xref">#chp-https://rdrr.io/r/stats/update</a></code>. This also allows you to set multiple values in one step:</p>
<p>Alternatively, rather than modifying an existing variabke, you can create a new date-time with <code><a href="https://rdrr.io/r/stats/update.html">update()</a></code>. This also allows you to set multiple values in one step:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">update(datetime, year = 2030, month = 2, mday = 2, hour = 2)
#&gt; [1] "2030-02-02 02:34:56 UTC"</pre>
@@ -664,7 +664,7 @@ y2023
y2024
#&gt; [1] 2024-01-01 UTC--2025-01-01 UTC</pre>
</div>
<p>You could then divide it by <code><a href="#chp-https://lubridate.tidyverse.org/reference/period" data-type="xref">#chp-https://lubridate.tidyverse.org/reference/period</a></code> to find out how many days fit in the year:</p>
<p>You could then divide it by <code><a href="https://lubridate.tidyverse.org/reference/period.html">days()</a></code> to find out how many days fit in the year:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">y2023 / days(1)
#&gt; [1] 365
@@ -690,13 +690,13 @@ Time zones</h1>
<!--# https://www.ietf.org/timezones/tzdb-2018a/theory.html -->
<p>The first challenge is that everyday names of time zones tend to be ambiguous. For example, if you’re American you’re probably familiar with EST, or Eastern Standard Time. However, both Australia and Canada also have EST! To avoid confusion, R uses the international standard IANA time zones. These use a consistent naming scheme <code>{area}/{location}</code>, typically in the form <code>{continent}/{city}</code> or <code>{ocean}/{city}</code>. Examples include “America/New_York”, “Europe/Paris”, and “Pacific/Auckland”.</p>
<p>You might wonder why the time zone uses a city, when typically you think of time zones as associated with a country or region within a country. This is because the IANA database has to record decades worth of time zone rules. Over the course of decades, countries change names (or break apart) fairly frequently, but city names tend to stay the same. Another problem is that the name needs to reflect not only the current behavior, but also the complete history. For example, there are time zones for both “America/New_York” and “America/Detroit”. These cities both currently use Eastern Standard Time but in 1969-1972 Michigan (the state in which Detroit is located), did not follow DST, so it needs a different name. It’s worth reading the raw time zone database (available at <a href="https://www.iana.org/time-zones" class="uri">https://www.iana.org/time-zones</a>) just to read some of these stories!</p>
<p>You can find out what R thinks your current time zone is with <code><a href="#chp-https://rdrr.io/r/base/timezones" data-type="xref">#chp-https://rdrr.io/r/base/timezones</a></code>:</p>
<p>You can find out what R thinks your current time zone is with <code><a href="https://rdrr.io/r/base/timezones.html">Sys.timezone()</a></code>:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">Sys.timezone()
#&gt; [1] "America/Chicago"</pre>
</div>
<p>(If R doesn’t know, you’ll get an <code>NA</code>.)</p>
<p>And see the complete list of all time zone names with <code><a href="#chp-https://rdrr.io/r/base/timezones" data-type="xref">#chp-https://rdrr.io/r/base/timezones</a></code>:</p>
<p>And see the complete list of all time zone names with <code><a href="https://rdrr.io/r/base/timezones.html">OlsonNames()</a></code>:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">length(OlsonNames())
#&gt; [1] 595
@@ -725,7 +725,7 @@ x3
x1 - x3
#&gt; Time difference of 0 secs</pre>
</div>
<p>Unless otherwise specified, lubridate always uses UTC. UTC (Coordinated Universal Time) is the standard time zone used by the scientific community and is roughly equivalent to GMT (Greenwich Mean Time). It does not have DST, which makes a convenient representation for computation. Operations that combine date-times, like <code><a href="#chp-https://rdrr.io/r/base/c" data-type="xref">#chp-https://rdrr.io/r/base/c</a></code>, will often drop the time zone. In that case, the date-times will display in your local time zone:</p>
<p>Unless otherwise specified, lubridate always uses UTC. UTC (Coordinated Universal Time) is the standard time zone used by the scientific community and is roughly equivalent to GMT (Greenwich Mean Time). It does not have DST, which makes a convenient representation for computation. Operations that combine date-times, like <code><a href="https://rdrr.io/r/base/c.html">c()</a></code>, will often drop the time zone. In that case, the date-times will display in your local time zone:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="downlit">x4 &lt;- c(x1, x2, x3)
x4