Intro to timeperiodsR (RUS)
Alexey Seleznev
2019-12-09
Цель пакета timeperiodsR
Зачастую при создании скриптов которые в последствии будут запускаться по расписанию нам необходимо определить некий отчётный период. Как правило, таким периодом может быть прошлая неделя, прошлый месяц, либо какое-то количество прошлых дней. Пакет timeperiodsR предоставляет вам набор функций которые автоматически будут вычислять такой период от заданной даты. Все функции пакета возвращают период в объекте класса tpr, в этой виньетке мы подробно разберём все функции пакета timeperiodsR, а также компоненты и методы класса tpr.
Содержание
- Функции пакета
- Компоненты класса tpr
- Аргументы
- Методы
- Операторы
- Конвертация других объектов в класс tpr
Помимо данной виньетки к пакету timeperiodsR есть видео инструкция, ознакомится с которой можно по этой ссылке.
Функции пакета timeperiodsR
Текущая версия пакета состоит из 24 функций, по названию каждой из функций можно определить какой временной интервал она возвращает. Название состоит из префикса last / previous / this / next и временной единицы day / week / month / quarter / year. Нижнее подчёркивание _ является разделителем слов в названиях функций.
Список функций
last_n_days()last_n_weeks()last_n_months()last_n_quarters()last_n_years()previous_week()previous_month()previous_quarter()previous_year()this_week()this_month()this_quarter()this_year()next_week()next_month()next_quarter()next_year()next_n_days()next_n_weeks()next_n_months()next_n_quarters()next_n_years()custom_period()
Компоненты получаемых объектов
Любая из функций пакета возвращает объект класса tpr состоящий из следующих компонентов:
- start - начальную дату;
- end - конечную дату;
- sequence - последовательность дат;
- length - количество дней входящих в период;
Аргументы
В функциях пакета timeperiodsR присутствуют следующие аргументы:
- x - Объект даты, от которой будет вычисляться интервал, по умолчанию это текущий день;
- n - Количество временных интервалов на которое необходимо сместится от даты указанной в аргументе x;
- part - Какую часть объекта вам необходимо получить:
- “all” - объект со всеми доступными компонентами;
- “start” - начальную дату;
- “end” - конечную дату;
- “sequence” - последовательность дат;
- “length” - количество дней входящих в период;
- week_start - Какой день будет являться началом недели: 1 - понедельник, 7 - воскресенье;
- include_current - Включать ли в период текущий временной объект, TRUE или FALSE.
Методы
Пакет timeperiodsR имеет несколько методов, позволяющих вам извлекать некоторые элементы объектов класса tpr.
seq - получить последовательность дат из объекта класса tpr;length - получить длительность объекта класса tpr в днях;start - получить первую дату из объекта класса tpr;end - получить последнюю дату из объекта класса tpr;print - вывести в консоль информацию о периоде содержащемся в объекте класса tpr.
last_n_*
Функции блока last_n_*() позволяют вам получить прошлый период с заданным количеством временных единиц.
Вместо * подставьте один из нужных вам временных интервалов: days, weeks, months, quarters, years
Например, допустим, что сегодня 26 сентября 2019 года и вам необходимо получить 2 прошлые недели то используйте функцию last_n_weeks():
##
## ---------------------
## Welcome to timeperiodsR version 0.3.0
##
## Author: Alexey Seleznev (Head of analytics dept at Netpeak).
## Telegram channel: https://t.me/R4marketing
## Email: selesnow@gmail.com
## Blog: https://alexeyseleznev.wordpress.com
## Facebook: https://facebook.com/selesnown
## Linkedin: https://www.linkedin.com/in/selesnow
##
## Type ?timeperiodsR for the main documentation.
## The github page is: https://github.com/selesnow/timeperiodsR/
##
## Suggestions and bug-reports can be submitted at: https://github.com/selesnow/timeperiodsR/issues
## Or contact: <selesnow@gmail.com>
##
## To suppress this message use: suppressPackageStartupMessages(library(timeperiodsR))
## ---------------------
Код захватит даты с 9 по 22 сентября включительно.
После чего у вас появится объект last2weeks класса tpr. Из него вы легко можете получить начальную или конечную дату периода, а так же всю последовательность дат которая вошла в этот период, или количество дней вошедших в период.
## [1] "2019-11-25"
## [1] "2019-11-25"
## [1] "2019-12-08"
## [1] "2019-12-08"
## [1] "2019-11-25" "2019-11-26" "2019-11-27" "2019-11-28" "2019-11-29"
## [6] "2019-11-30" "2019-12-01" "2019-12-02" "2019-12-03" "2019-12-04"
## [11] "2019-12-05" "2019-12-06" "2019-12-07" "2019-12-08"
## [1] "2019-11-25" "2019-11-26" "2019-11-27" "2019-11-28" "2019-11-29"
## [6] "2019-11-30" "2019-12-01" "2019-12-02" "2019-12-03" "2019-12-04"
## [11] "2019-12-05" "2019-12-06" "2019-12-07" "2019-12-08"
## [1] 14
## [1] 14
Во всех функциях предназначенных для работы с неделями т.е. last_n_weeks(), previous_week(), this_week(), next_week(), next_n_weeks() присутствует аргумент week_start, с его помощью можно указать день недели который будет являться её началом. По умолчанию неделя начинается с понедельника, т.е. week_start = 1, но вы можете задать и любой другой день:
- Понедельник
- Вторник
- Среда
- Четверг
- Пятница
- Суббота
- Воскресенье
Т.е. если вы хотите получить 2 предыдущие недели отталкиваясь от 26 сентября, и при этом необходимо считать началом недели воскресенье то используйте следующий код:
previous_*
Функции блока previous_*() позволяют вам получить прошлый период со смещением на заданное количеством временных единиц. Т.е. например получить позапрошлую неделю.
Вместо * подставьте один из нужных вам временных интервалов: week, month, quarter, year
Допустим нам необходимо получить позапрошлую неделю отталкиваясь от 26 сентября 2019 года, началом недели должен быть понедельник
this_*
Функции блока this_*() позволяют вам получить текущий период.
Вместо * подставьте один из нужных вам временных интервалов: week, month, quarter, year
Если вам необходимо получить первую и последнюю дату текущего месяца, и всю последовательность дат которые в него входят, то используйте следующий код:
##
## Time period: 2019-12-01 (воскресенье) - 2019-12-31 (вторник)
Т.е. если сегодня 26 сентября 2019 года функция this_month() захватит весь сентябрь 2019 года.
next_*
Функции блока next_*() противоположный функциям блока previous_*(). Т.е. позволяют вам получить будущий период со смещением на заданное количеством временных единиц. Т.е. например получить следующую неделю от 12 сентября.
Вместо * подставьте один из нужных вам временных интервалов: week, month, quarter, year
next_n_*
Блок next_n_* позволяет создать период обратный от того, что создают функции блока last_n_*, т.е. получить будущий период с заданным количеством временных единиц.
Вместо * подставьте один из нужных вам временных интервалов: days, weeks, months, quarters, years
Например если вам необходимо получить 5 следующих дней воспользуйтесь следующим кодом.
custom_period
Данная функция позволяет создавать объект класса tpr с любым произвольным периодом.
Операторы
В timeperiodsR есть несколько операторов.
- %.in% - проверяет вхождение одного вектора дат, или объекта класса tpr в другой, и возвращает логический вектор.
- %left_out% - сравнивает два объекта класса tpr, и возвращает значение из левого, которые отсутствуют в правом.
- %left_in% - сравнивает два объекта класса tpr, и возвращает даты из левого объекта которые входят в правый
- %right_out% - сравнивает два объекта класса tpr, и возвращает значение из правого, которые отсутствуют в левом.
- %right_in% - сравнивает два объекта класса tpr, и возвращает даты из правого объекта которые присутствуют в левом.
Из представленного описания возможно сложно понять зачем эти операторы нужны, и как именно они работают. Поэтому рассмотрим несколько примеров.
Сначала создадим два объекта tpr класса, относительно 7 ноября 2019 года. Один будет соответствовать текущему месяцу, а второй предыдущей неделе.
##
## Time period: 2019-11-01 (пятница) - 2019-11-30 (суббота)
##
## Time period: 2019-10-28 (понедельник) - 2019-11-03 (воскресенье)
В таком случае первый период содержит даты с 1 по 30 ноября, а второй с 28 октября по 3 ноября. Т.е. частично эти два периода пересекаются и мы можем фильтровать один из используя значения другого.
## [1] "2019-11-01" "2019-11-02" "2019-11-03"
## [1] "2019-11-04" "2019-11-05" "2019-11-06" "2019-11-07" "2019-11-08"
## [6] "2019-11-09" "2019-11-10" "2019-11-11" "2019-11-12" "2019-11-13"
## [11] "2019-11-14" "2019-11-15" "2019-11-16" "2019-11-17" "2019-11-18"
## [16] "2019-11-19" "2019-11-20" "2019-11-21" "2019-11-22" "2019-11-23"
## [21] "2019-11-24" "2019-11-25" "2019-11-26" "2019-11-27" "2019-11-28"
## [26] "2019-11-29" "2019-11-30"
## [1] "2019-11-01" "2019-11-02" "2019-11-03"
## [1] "2019-10-28" "2019-10-29" "2019-10-30" "2019-10-31"
Такие операторы фильтрации удобно использовать например при проверке наличия данных в базе за какой-то период, в тех случаях когда вы наполняете базу данными из внешних источников на ежедневной основе.
К примеру вы каждый день запрашиваете данные из API Google Analytics, и записываете их в базу. При этом API периодически может давать сбой, и за какой-то день в вашей базе будут отсутствовать данные, тогда вы можете определить проверочный период, например предыдущие 30 дней, с помощью команды last_n_days(n = 30). Далее запрашивать данные за этот из вашей СУБД. После, с помощью приведённых выше операторов фильтрации убрать из общего 30 дневного периода даты которые присутствуют в базе, и по оставшимся датам подгрузить данные.
Конвертация различных объектов в класс tpr
Вы можете преобразоватьвектор из дат, или строковый вектор состоящий из дат в формате YYYY-MM-DD в объект класса tpr с помощью функции as_timeperiod().
##
## Time period: 2019-08-30 (пятница) - 2019-10-11 (пятница)
В приведённом выше примере конвертации строкового вектора в объект класса tpr, исходный вектор содержит 4 даты, они идут в произвольном порядке, и в целом между ними много пропущенных дней, т.е. данный вектор не является непрерывной последовательностью дат. В таком случае функция as_timeperiod() находит в исходном векторе минимальную и максимальную дату, и создаёт объект класса tpr равный временному интервалу между этими двумя датами.
