--- title: "Intro to timeperiodsR" author: "Alexey Seleznev" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Intro to timeperiodsR} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( eval=TRUE, collapse = TRUE, comment = "#>" ) ``` # Цель пакета timeperiodsR Зачастую при создании скриптов которые в последствии будут запускаться по расписанию нам необходимо определить некий отчётный период. Как правило, таким периодом может быть прошлая неделя, прошлый месяц, либо какое-то количество прошлых дней. Пакет timeperiodsR предоставляет вам набор функций которые автоматически будут вычислять такой период от заданной даты. Все функции пакета возвращают период в виде объекта класса *tpr*. В этой виньетке мы подробно разберём все функции пакета `timeperiodsR`, а также компоненты и методы класса *tpr*. # Содержание * Простой пример использования * Функции пакета * Компоненты класса tpr * Аргументы * Методы * Операторы * Конвертация других объектов в класс tpr * Пользовательские выходные дни Помимо данной виньетки к пакету `timeperiodsR` есть видео инструкция, ознакомится с которой можно по этой [ссылке](https://youtu.be/NgfWELbM6Fk). # Простой пример использования Как я уже писал выше, основная цель `timeperiodsR` упростить процесс определения относительного периода. Если у вас есть скрипт который запускается по рассписанию, и собирает данные за прошлый месяц, то вы можете получить прошлый месяц следующим образом: ```{r, echo=TRUE, eval=TRUE} library(timeperiodsR) # получаем прошлый месяц period <- previous_month() # получаем начальную и конечную дату прошлого месяца start <- period$start # первый день прошлого месяца end <- period$end # последний день прошлого месяца ``` Код определения временно периода с помощью `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()` * `as_timeperiod()` * `check_dayoffs()` ## Компоненты получаемых объектов Любая из функций пакета возвращает объект класса `tpr` состоящий из следующих компонентов: **Обязательные компоненты** * start - начальная дата; * end - конечная дата; * first_workday - первый рабочий день; * last_workday - последний рабочий день; * first_weekend - первый выходной день; * last_weekend - последний выходной день; * sequence - последовательность дат; * workdays - последовательность будних дней; * weekends - последовательность выходных дней; * length - количество дней входящих в период; * workdays_length - количество будних дней входящих в период; * weekends_length - количество выходных дней входящих в период; **Дополнительные компоненты** * official_workdays - Официальные рабочие дни; * official_first_workday - Первый официальный рабочий день; * official_last_workday - Последний официальный рабочий день; * official_day_offs - официальные выходные дни в выбранной стране, по умолчанию России; * custom_day_offs - пользовательские выходные дни; * dayoffs_marks - пометки о том, какой статус имеет день в официальном календаре страны; * custom_day_offs - пользовательские выходные. Начиная с версии `timeperiodsR 0.5.0` в пакет была интегрирована поддержка API производственного календаря [isDayOff](https://www.isdayoff.ru/). Этот API позволяет получить официальные праздничные дни в следующих странах: Россия, Украина, Казахстан и Белоруссия. Для активации дополнительных компонентов вам необходимо установить пакет `httr`. ```{r eval=FALSE} install.packages("httr") ``` По умолчанию дополнительные компоненты приведённые выше выключены, т.к. они нужны не всем пользователям пакета, а пакет с использованием API работает значительно медленнее. Для расширения класса `tpr` дополнительными компонентами вы можете воспользоваться опциями или переменными среды. #### Опции для включения дополнительных компонентов * timeperiodsR.official_day_offs - включение дополнительных компонентов, по умолчанию имеет значение `FALSE`; * timeperiodsR.official_day_offs_country - установить страну для которой будет запрашиваться список официальных выходных дней: * ru - Россия, значение по умолчанию; * ua - Украина * by - Белоруссия * kz - Казахстан * timeperiodsR.official_day_offs_pre - распознавать, что день предпраздничный, т.е. сокращённым: * 0 - без вывода сокращённых дней (по умолчанию) * 1 - распознавать, что день предпраздничный (сокращённый) Пример установки опций: ```{r eval=TRUE} options("timeperiodsR.official_day_offs" = TRUE, "timeperiodsR.official_day_offs_country" = "ua", "timeperiodsR.official_day_offs_pre" = 1) ``` #### Переменные среды для включения дополнительных компонентов Опции удобны для работы, но их необходимо задавать при каждом новом сеансе работы с R, если все указанные в опциях параметры в большинстве случаев у вас статичны, то лучше задать их на уровне операционной системы. О том как создавать переменные среды можно узнать из этого [видео](https://www.youtube.com/watch?v=zoNvu2T6IFc&list=PLD2LDq8edf4pItOb-vZTG5AXZK2niJ8_R&index=5&t). Задайте следующие переменные среды для того, что бы не указывать опции в каждом сеансе: * TPR_DAY_OFFS - TRUE, для активации дополнительных компонентов; * TPR_COUNTRY - Страна: ru, ua, by или kz; * TPR_PRE - Включать в компонент *official_day_offs* сокращённые рабочие дни, в компоненте *dayoffs_marks* они будут помечены числом 2. После того как вы установите значения для переменных среды пакет автоматически будет считывать их при подключении. ## Аргументы В функциях пакета timeperiodsR присутствуют следующие аргументы: * *x* - Объект даты, от которой будет вычисляться интервал, по умолчанию это текущий день; * *n* - Количество временных интервалов на которое необходимо сместится от даты указанной в аргументе *x*; * *part* - Какую часть объекта вам необходимо получить: * "all" - объект со всеми доступными компонентами; * "start" - начальную дату; * "end" - конечную дату; * "first_workday" - первый рабочий день периода; * "last_workday" - последний рабочий день периода; * "first_weekend" - первый выходной день периода; * "last_weekend" - последний выходной день периода; * "sequence" - последовательность дат; * "workdays" - последовательность будних дней в периоде; * "weekends" - последовательность выходных дней в периоде; * "length" - количество дней входящих в период; * "workdays_length" - количество будних дней входящих в период; * "weekends_length" - количество выходных дней входящих в период; * "official_workdays" - официальные рабочие дни для указанной страны; * "official_first_workday" - первый официальный рабочий день для указанной страны; * "official_last_workday" - последний официальный рабочий день для указанной страны; * "official_day_offs" - официальные выходные дни для указанной страны; * "dayoffs_marks" - пометки для каждого дня; * *week_start* - Какой день будет являться началом недели: 1 - понедельник, 7 - воскресенье; * *include_current* - Включать ли в период текущий временной объект, TRUE или FALSE. ## Методы Пакет `timeperiodsR` имеет несколько методов, позволяющих вам извлекать некоторые элементы объектов класса *tpr*. * `seq` - получить последовательность дат из объекта класса *tpr*; * `length` - получить длительность объекта класса *tpr* в днях; * `start` - получить первую дату из объекта класса *tpr*; * `end` - получить последнюю дату из объекта класса *tpr*; * `first_workday` - получить первый рабочий день из объекта класса *tpr*; * `last_workday` - получить последний рабочий день из объекта класса *tpr*; * `first_weekend` - получить первый выходной день из объекта класса *tpr*; * `last_weekend` - получить последний выходной из объекта класса *tpr*; * `workdays` - получить последовательность рабочих дней из объекта класса *tpr*; * `weekends` - получить последовательность выходных из объекта класса *tpr*; * `workdays_length` - получить из объекта класса *tpr*; * `weekends_length` - получить из объекта класса *tpr*; * `print` - вывести в консоль информацию о периоде содержащемся в объекте класса *tpr*. # last\_n\_\* Функции блока `last_n_*()` позволяют вам получить прошлый период с заданным количеством временных единиц. Вместо `*` подставьте один из нужных вам временных интервалов: *days, weeks, months, quarters, years* Например, допустим, что сегодня 26 сентября 2019 года и вам необходимо получить 2 прошлые недели то используйте функцию `last_n_weeks()`: ```{r, echo=TRUE, eval=TRUE} last2weeks <- last_n_weeks(n = 2) ``` ![2 прошлые недели](http://img.netpeak.ua/alsey/156864246904_kiss_75kb.png) Код захватит даты с 9 по 22 сентября включительно. После чего у вас появится объект **last2weeks** класса `tpr`. Из него вы легко можете получить начальную или конечную дату периода, а так же всю последовательность дат которая вошла в этот период, или количество дней вошедших в период. ```{r, echo=TRUE, eval=TRUE} # начальная дата last2weeks$start ## или start(last2weeks) # конечная дата last2weeks$end ## или end(last2weeks) # первый рабочий день last2weeks$first_workday ## или first_workday(last2weeks) # последний рабочий день last2weeks$last_workday ## или last_workday(last2weeks) # первый выходной день last2weeks$first_weekend ## или first_weekend(last2weeks) # последний выходной день last2weeks$last_weekend ## или last_weekend(last2weeks) # последовательность дат last2weeks$sequence ## или seq(last2weeks) # последовательность будних дней last2weeks$workdays ## или workdays(last2weeks) # последовательность выходных дней last2weeks$weekends # или weekends(last2weeks) # количество дней вошедших в период last2weeks$length ## или length(last2weeks) # количество будних дней в периоде last2weeks$workdays_length ## или workdays_length(last2weeks) # количество выходных дней в периоде last2weeks$weekends_length ## или weekends_length(last2weeks) ``` Во всех функциях предназначенных для работы с неделями т.е. `last_n_weeks()`, `previous_week()`, `this_week()`, `next_week()`, `next_n_weeks()` присутствует аргумент *week_start*, с его помощью можно указать день недели который будет являться её началом. По умолчанию неделя начинается с понедельника, т.е. `week_start = 1`, но вы можете задать и любой другой день: 1. Понедельник 2. Вторник 3. Среда 4. Четверг 5. Пятница 6. Суббота 7. Воскресенье Т.е. если вы хотите получить 2 предыдущие недели отталкиваясь от 26 сентября, и при этом необходимо считать началом недели воскресенье то используйте следующий код: ```{r, echo=TRUE} library(timeperiodsR) last2weeks <- last_n_weeks(x = "2019-09-26", n = 2, week_start = 7) ``` ![Две предыдущие недели, начало недели воскресенье](http://img.netpeak.ua/alsey/156864661236_kiss_74kb.png) # previous\_\* Функции блока `previous_*()` позволяют вам получить прошлый период со смещением на заданное количеством временных единиц. Т.е. например получить позапрошлую неделю. Вместо `*` подставьте один из нужных вам временных интервалов: *week, month, quarter, year* Допустим нам необходимо получить позапрошлую неделю отталкиваясь от 26 сентября 2019 года, началом недели должен быть понедельник ```{r, echo=TRUE} previous2weeks <- previous_week(x = "2019-09-26", n = 2) ``` ![Позапрошлая неделя](http://img.netpeak.ua/alsey/156863814902_kiss_70kb.png) # this\_\* Функции блока `this_*()` позволяют вам получить текущий период. Вместо `*` подставьте один из нужных вам временных интервалов: *week, month, quarter, year* Если вам необходимо получить первую и последнюю дату текущего месяца, и всю последовательность дат которые в него входят, то используйте следующий код: ```{r, echo=TRUE} this_month() ``` ![Текущий месяц](http://img.netpeak.ua/alsey/156880445292_kiss_73kb.png) Т.е. если сегодня 26 сентября 2019 года функция `this_month()` захватит весь сентябрь 2019 года. # next\_\* Функции блока `next_*()` противоположный функциям блока `previous_*()`. Т.е. позволяют вам получить будущий период со смещением на заданное количеством временных единиц. Т.е. например получить следующую неделю от 12 сентября. Вместо `*` подставьте один из нужных вам временных интервалов: *week, month, quarter, year* ```{r, echo=TRUE} nextweek_from_12sep <- next_week("2019-09-12") nextweek_from_today <- next_week() ``` ![Следующая неделя](http://img.netpeak.ua/alsey/156881039998_kiss_72kb.png) # next\_n\_\* Блок `next_n_*` позволяет создать период обратный от того, что создают функции блока `last_n_*`, т.е. получить будущий период с заданным количеством временных единиц. Вместо `*` подставьте один из нужных вам временных интервалов: *days, weeks, months, quarters, years* Например если вам необходимо получить 5 следующих дней воспользуйтесь следующим кодом. ```{r, echo=TRUE} # получить 5 следующих дней не включая текущую дату next5days <- next_n_days(n = 5) # получить 5 следующих дней включая текущую дату next5days_wt <- next_n_days(n = 5, include_current = T) ``` # custom_period Данная функция позволяет создавать объект класса *tpr* с любым произвольным периодом. ```{r, echo=TRUE} period1 <- custom_period("2019-09-03", "2019-09-11") ``` # Операторы В `timeperiodsR` есть несколько операторов. * %.in% - проверяет вхождение одного вектора дат, или объекта класса tpr в другой, и возвращает логический вектор. * %left_out% - сравнивает два объекта класса tpr, и возвращает значение из левого, которые отсутствуют в правом. * %left_in% - сравнивает два объекта класса tpr, и возвращает даты из левого объекта которые входят в правый * %right_out% - сравнивает два объекта класса tpr, и возвращает значение из правого, которые отсутствуют в левом. * %right_in% - сравнивает два объекта класса tpr, и возвращает даты из правого объекта которые присутствуют в левом. Из представленного описания возможно сложно понять зачем эти операторы нужны, и как именно они работают. Поэтому рассмотрим несколько примеров. Сначала создадим два объекта tpr класса, относительно 7 ноября 2019 года. Один будет соответствовать текущему месяцу, а второй предыдущей неделе. ```{r, echo=TRUE} period1 <- this_month("2019-11-07") period2 <- previous_week("2019-11-07") print(period1) print(period2) ``` В таком случае первый период содержит даты с 1 по 30 ноября, а второй с 28 октября по 3 ноября. Т.е. частично эти два периода пересекаются и мы можем фильтровать один из используя значения другого. ```{r, echo=TRUE} period1 %left_in% period2 # получить даты из period1 которые входят в period2 period1 %left_out% period2 # получить даты из period1 которые не входят в period2 period1 %right_in% period2 # получить даты из period2 которые входят в period1 period1 %right_out% period2 # получить даты из period2 которые не входят в period2 ``` Такие операторы фильтрации удобно использовать например при проверке наличия данных в базе за какой-то период, в тех случаях когда вы наполняете базу данными из внешних источников на ежедневной основе. К примеру вы каждый день запрашиваете данные из API Google Analytics, и записываете их в базу. При этом API периодически может давать сбой, и за какой-то день в вашей базе будут отсутствовать данные, тогда вы можете определить проверочный период, например предыдущие 30 дней, с помощью команды `last_n_days(n = 30)`. Далее запрашивать данные за этот из вашей СУБД. После, с помощью приведённых выше операторов фильтрации убрать из общего 30 дневного периода даты которые присутствуют в базе, и по оставшимся датам подгрузить данные. # Конвертация различных объектов в класс tpr Вы можете преобразоватьвектор из дат, или строковый вектор состоящий из дат в формате *YYYY-MM-DD* в объект класса *tpr* с помощью функции `as_timeperiod()`. ```{r, echo=TRUE} dates <- c("2019-09-11", "2019-09-02", "2019-10-11", "2019-08-30") dates_tpr <- as_timeperiod(dates) dates_tpr ``` В приведённом выше примере конвертации строкового вектора в объект класса *tpr*, исходный вектор содержит 4 даты, они идут в произвольном порядке, и в целом между ними много пропущенных дней, т.е. данный вектор не является непрерывной последовательностью дат. В таком случае функция `as_timeperiod()` находит в исходном векторе минимальную и максимальную дату, и создаёт объект класса *tpr* равный временному интервалу между этими двумя датами. # Пользовательские выходные дни Иногда помимо официальных выходных дней вам может понадобиться выделить собственные дополнительные выходные дни, например ваш отпуск. Пакет `timeperiodsR` даёт вам такую возможность с помощью опции или переменной среды. В опцию `timeperiodsR.custom_day_offs` вы можете передать вектор с датами которые будут помечены как дополнительные выходные дни, такие дни в компоненте *dayoffs_marks* будут помечены значением 3. Также вы можете задать переменную среды `TPR_CUSTOM_DAY_OFFS`, в которой укажите даты в формате ГГГГ-ММ-ДД разделённые запятыми или точками с запятой. Таким образом вы можете помечать дополнительные выходные дни. ```{r, echo=TRUE} options("timeperiodsR.custom_day_offs" = c("2020-01-14", "2020-01-15", "2020-01-16", "2020-01-17", "2020-02-12")) tm <- this_month("2020-01-01") # получить ваши пользовательские выходные которые входят в текущий период tm$custom_day_offs # пользовательские выходные будут помечены 3 tm$dayoffs_marks ```