Функции пакета 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():

library(timeperiodsR)

## 
## ---------------------
## Welcome to timeperiodsR version 0.2.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))
## ---------------------

last2weeks <- last_n_weeks(n = 2)

2 прошлые недели

Код захватит даты с 9 по 22 сентября включительно.

После чего у вас появится объект last2weeks класса tpr. Из него вы легко можете получить начальную или конечную дату периода, а так же всю последовательность дат которая вошла в этот период, или количество дней вошедших в период.

# начальная дата
last2weeks$start

## [1] "2019-10-28"

## или
start(last2weeks)

## [1] "2019-10-28"

# конечная дата
last2weeks$end

## [1] "2019-11-10"

## или
end(last2weeks)

## [1] "2019-11-10"

# последовательность дат
last2weeks$sequence

##  [1] "2019-10-28" "2019-10-29" "2019-10-30" "2019-10-31" "2019-11-01"
##  [6] "2019-11-02" "2019-11-03" "2019-11-04" "2019-11-05" "2019-11-06"
## [11] "2019-11-07" "2019-11-08" "2019-11-09" "2019-11-10"

## или
seq(last2weeks)

##  [1] "2019-10-28" "2019-10-29" "2019-10-30" "2019-10-31" "2019-11-01"
##  [6] "2019-11-02" "2019-11-03" "2019-11-04" "2019-11-05" "2019-11-06"
## [11] "2019-11-07" "2019-11-08" "2019-11-09" "2019-11-10"

# количество дней вошедших в период
last2weeks$length

## [1] 14

## или
length(last2weeks)

## [1] 14

Во всех функциях предназначенных для работы с неделями т.е. last_n_weeks(), previous_week(), this_week(), next_week(), next_n_weeks() присутвует аргумент week_start, с помощью которого можно указать день недели который будет являться её началом. По умолчанию неделя начинается с понедельника, т.е. week_start = 1, но вы можете задать и любой другой день:

Понедельник
Вторник
Среда
Четверг
Пятница
Суббота
Воскресенье

Т.е. если вы хотите получить 2 предыдущие недели отталкиваясь от 26 сентября, и при этом необходимо считать началом неделеи воскресенье то используйте следующий код:

library(timeperiodsR)

last2weeks <- last_n_weeks(x = "2019-09-26", n = 2, week_start = 7)

Две предыдущие недели, начало недели воскресенье

previous_*

Функции блока previous_*() позволяют вам получить прошлый период со смещением на заданное количеством временных единиц. Т.е. например получить позапрошлую неделю.

Вместо * подставьте один из нужных вам временных интервалов: week, month, quarter, year

Допустим нам необходимо получить позапрошлую неделю отталкиваясь от 26 сентября 2019 года, началом недели должен быть понедельник

previous2weeks <- previous_week(x = "2019-09-26", n = 2)

Позапрошлая неделя

this_*

Функции блока this_*() позволяют вам получить текущий период.

Вместо * подставьте один из нужных вам временных интервалов: week, month, quarter, year

Если вам необходимо получить первую и последнюю дату текущего месяца, и всю последовательность дат которые в него входят то используйте следующий код:

this_month()

## 
##  Time period: from  1 Ноябрь of 2019, пятница to 30 Ноябрь of 2019, суббота

Текущий месяц

Т.е. если сегодня 26 сентября 2019 года функция this_month() захватит весь сентябрь 2019 года.

next_*

Функции блока next_*() противоположный функциям блока previous_*(). Т.е. позволяют вам получить будущий период со смещением на заданное количеством временных единиц. Т.е. например получить следующую неделю от 12 сентября.

Вместо * подставьте один из нужных вам временных интервалов: week, month, quarter, year

nextweek_from_12sep <- next_week("2019-09-12")

nextweek_from_today <- next_week()

Следующая неделя

next_n_*

Блок next_n_* позволяет создать период обратный от того, что создают функции блока last_n_*, т.е. получить будущий период с заданным количеством временных единиц.

Вместо * подставьте один из нужных вам временных интервалов: days, weeks, months, quarters, years

Например если вам необходимо получить 5 следующих дней воспользуйтесь следующим кодом.

# получить 5 следующих дней не включая текущую дату
next5days <- next_n_days(n = 5)

# получить 5 следующих дней включая текущую дату
next5days_wt <- next_n_days(n = 5, include_current = T)

custom_period

Данная функция позволяет создавать объект класса tpr с любым произвольным периодом.

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 года. Один будет соответвовать текущему месяцу, а второй предыдущей неделе.

period1 <- this_month("2019-11-07")
period2 <- previous_week("2019-11-07")

print(period1)

## 
##  Time period: from  1 Ноябрь of 2019, пятница to 30 Ноябрь of 2019, суббота

print(period2)

## 
##  Time period: from 28 Октябрь of 2019, понедельник to  3 Ноябрь of 2019, воскресенье

В таком случае первый период содержит даты с 1 по 30 ноября, а второй с 28 октября по 3 ноября. Т.е. частично эти два периода пересекаются и мы можем фильтровать один из используя значения другого.

period1 %left_in% period2   # получить даты из period1 которые входят в period2

## [1] "2019-11-01" "2019-11-02" "2019-11-03"

period1 %left_out% period2  # получить даты из period1 которые не входят в period2

##  [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"

period1 %right_in% period2  # получить даты из period2 которые входят в period1

## [1] "2019-11-01" "2019-11-02" "2019-11-03"

period1 %right_out% period2 # получить даты из period2 которые не входят в period2

## [1] "2019-10-28" "2019-10-29" "2019-10-30" "2019-10-31"

Такие операторы фильтрации удобно использовать например при проверке данных в базе за какой то период, в тех случаях когда вы наполняете базу данными из внешних источников на еждневной основе.

К примеру вы каждый день запраиваете данные из API Google Analytics, и записываете их в базу. При этом API периодически может давать сбой, и за какой то день в вашей базе будут отсутвовать данные, тогда вы можете определить проверочный период, например предыдущие 30 дней, с помощью команды last_n_days(n = 30). Далее запрашивать данные за этот из вашей СУБД. После, с помощью приведённых выше операторов фильтрации убрать из общего 30 дневного периода даты которые пристувуют в базе, и по оставшимся датам подгрузить данные.

Intro to timeperiodsR (RUS)

Alexey Seleznev

2019-11-14

Цель пакета timeperiodsR

Функции пакета timeperiodsR

Список функций

Компоненты получаемых объектов

Аргументы

Методы

last_n_*

previous_*

this_*

next_*

next_n_*

custom_period

Операторы