Package 'when'

Precalculated date set

Description

Precalculated date set

Usage

date_days

Format

A vector.

See Also

Other time definition: time_seconds

---

Define dimension characteristics

Description

With this function we can define the characteristics of the dimension that do not depend on the levels it includes, such as the name, type, location or the day the week begins. It also allows us to define whether the table includes a surrogate key.

Usage

define_characteristics(
  td,
  name,
  surrogate_key,
  type,
  locale,
  week_starts_monday
)

## S3 method for class 'when'
define_characteristics(
  td,
  name = NULL,
  surrogate_key = NULL,
  type = NULL,
  locale = NULL,
  week_starts_monday = NULL
)

Arguments

td	A when object.
name	A string, table name.
surrogate_key	A boolean, include a surrogate key in the dimension table.
type	A string, type of calendar (NULL, 'iso', 'epi' or 'time').
locale	A locale, to use for day and month names.
week_starts_monday	A boolean.

Details

The week_starts_monday parameter only affects the numbering of days, not weeks.

The week number associated with each date depends on the type of date dimension selected: standard ('date'), ISO 8601 ('iso') or epidemiological ('epi').

The standard week numbers blocks of 7 days beginning on January 1. The last week of the year can be less than 7 days long.

The ISO 8601 week numbers blocks of 7 days from Monday to Sunday. The first and last week of the year can contain days from the previous or next year.

The epidemiological week is like ISO 8601 only that it considers that the week begins on Sunday.

Value

A when object.

See Also

Other dimension definition: define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td <- when() |>
  define_characteristics(name = 'time', type = 'time')

---

Define instances

Description

Using this function we can define the instances from which the dimension will be generated according to the rest of its defined characteristics.

Usage

define_instances(td, start, end, values)

## S3 method for class 'when'
define_instances(td, start = NULL, end = NULL, values = NULL)

Arguments

td	A when object.
start	A string, start of the period to be included in the dimension.
end	A string, end of the period to be included in the dimension.
values	A vector of string.

Details

We must indicate dates or date components in ISO 8601 format (yyyy-mm-dd). The times in hh:mm:ss format.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td_1 <- when() |>
  define_instances(start = "2020", end = "2030")

td_1 <- when() |>
  define_instances(start = "2020-01-01", end = "2030-01-01")

td_2 <- when(type = 'time') |>
  define_instances(values = 1:5)

---

Generate table

Description

Once all the characteristics of the dimension have been defined, we can generate its table according to them using this function.

Usage

generate_table(td)

## S3 method for class 'when'
generate_table(td)

Arguments

td	A when object.

Value

A when object.

See Also

when, get_table

Other obtaining results: get_level_attribute_names(), get_level_names(), get_table_attribute_names(), set_table_attribute_names()

Examples

td <- when() |>
  generate_table()

---

Get attribute definition function

Description

Each attribute is defined by a function that adds a column to a table based on the parameter that contains the date or time. This function returns the definition function for the attribute whose name is given.

Usage

get_attribute_definition_function(td, name)

## S3 method for class 'when'
get_attribute_definition_function(td, name = NULL)

Arguments

td	A when object.
name	A string, attribute name.

Value

A function.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

f <- when() |>
  get_attribute_definition_function(name = "year")

---

Get day part

Description

Get day part.

Usage

get_day_part(td)

## S3 method for class 'when'
get_day_part(td)

Arguments

td	A when object.

Value

A named vector.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

dp <- when() |>
  get_day_part()

---

Get level attribute names

Description

Returns the names of the level attributes. We can obtain all the available ones or only the selected ones.

Usage

get_level_attribute_names(td, name, selected)

## S3 method for class 'when'
get_level_attribute_names(td, name = NULL, selected = FALSE)

Arguments

td	A when object.
name	A string.
selected	A boolean.

Value

A string vector.

See Also

Other obtaining results: generate_table(), get_level_names(), get_table_attribute_names(), set_table_attribute_names()

Examples

names <- when() |>
  get_level_attribute_names()

---

Get level names

Description

Returns the names of the levels. We can obtain all the available ones or only the selected ones.

Usage

get_level_names(td, selected)

## S3 method for class 'when'
get_level_names(td, selected = FALSE)

Arguments

td	A when object.
selected	A boolean.

Value

A string vector.

See Also

Other obtaining results: generate_table(), get_level_attribute_names(), get_table_attribute_names(), set_table_attribute_names()

Examples

names <- when() |>
  get_level_names()

---

Get the table of the dimension

Description

Once all the configuration elements have been defined and the dimension table has been generated, using this function we can obtain it in tibble format.

Usage

get_table(td)

## S3 method for class 'when'
get_table(td)

Arguments

td	A when object.

Value

A tibble, the table.

See Also

when, generate_table

Other getting results: get_table_csv(), get_table_rdb(), get_table_xlsx()

Examples

table <- when() |>
  generate_table() |>
  get_table()

---

Get table attribute names

Description

Returns the names of the dimension table attributes as a string vector or in string form, so we can easily use it to rename them if deemed necessary.

Usage

get_table_attribute_names(td, as_string)

## S3 method for class 'when'
get_table_attribute_names(td, as_string = TRUE)

Arguments

td	A when object.
as_string	A boolean.

Details

If the table has not been generated yet, returns the attributes it will contain when it is generated.

Value

A string.

See Also

Other obtaining results: generate_table(), get_level_attribute_names(), get_level_names(), set_table_attribute_names()

Examples

names <- when() |>
  get_table_attribute_names()

---

Store the table in a csv files

Description

Once all the configuration elements have been defined and the dimension table has been generated, using this function we can obtain it in csv format.

Usage

get_table_csv(td, dir, type)

## S3 method for class 'when'
get_table_csv(td, dir = NULL, type = 1)

Arguments

td	A when object.
dir	A string, name of a dir.
type	An integer, 1: uses "." for the decimal point and a comma for the separator; 2: uses a comma for the decimal point and a semicolon for the separator.

Details

If no dir name is given, stores the table in a temporary one.

Value

A string, name of a file.

See Also

Other getting results: get_table_rdb(), get_table_xlsx(), get_table()

Examples

file <- when() |>
  generate_table() |>
  get_table_csv()

---

Store the table in a relational database

Description

Once all the configuration elements have been defined and the dimension table has been generated, using this function we can obtain it in table format in a Relational DBMS.

Usage

get_table_rdb(td, con, overwrite)

## S3 method for class 'when'
get_table_rdb(td, con, overwrite = FALSE)

Arguments

td	A when object.
con	A DBI::DBIConnection object.
overwrite	A boolean, allow overwriting tables in the database.

Value

Invisible NULL.

See Also

Other getting results: get_table_csv(), get_table_xlsx(), get_table()

Examples

my_db <- DBI::dbConnect(RSQLite::SQLite())

when() |>
  generate_table() |>
  get_table_rdb(my_db)

DBI::dbDisconnect(my_db)

---

Store the table in a xlsx file

Description

Once all the configuration elements have been defined and the dimension table has been generated, using this function we can obtain it in xlsx format.

Usage

get_table_xlsx(td, dir)

## S3 method for class 'when'
get_table_xlsx(td, dir = NULL)

Arguments

td	A when object.
dir	A string, name of a dir.

Details

If no dir name is given, stores the table in a temporary one.

Value

A string, name of a file.

See Also

Other getting results: get_table_csv(), get_table_rdb(), get_table()

Examples

file <- when() |>
  generate_table() |>
  get_table_xlsx()

---

Get week date range

Description

For weeks between the given dates, gets the date of the first and last day of each week.

Usage

get_week_date_range(start = NULL, end = NULL, type = NULL)

Arguments

start	A string, start of the period to be included in the dimension.
end	A string, end of the period to be included in the dimension.
type	A string, type of calendar (NULL, 'iso', 'epi' or 'time').

Value

A tibble.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

t <- get_week_date_range(start = "2024-01-01", end = "2029-12-31")

---

Configure date levels

Description

When the dimension is defined as date type, using this function we can select the levels to include in it: day, week, month, quarter, semester and year.

Usage

select_date_levels(
  td,
  include_all,
  exclude_all,
  day_level,
  week_level,
  month_level,
  quarter_level,
  semester_level,
  year_level
)

## S3 method for class 'when'
select_date_levels(
  td,
  include_all = FALSE,
  exclude_all = FALSE,
  day_level = NULL,
  week_level = NULL,
  month_level = NULL,
  quarter_level = NULL,
  semester_level = NULL,
  year_level = NULL
)

Arguments

td	A when object.
include_all	A boolean, include all levels.
exclude_all	A boolean, exclude all levels.
day_level	A boolean, include day level.
week_level	A boolean, include week level.
month_level	A boolean, include month level.
quarter_level	A boolean, include quarter level.
semester_level	A boolean, include semester level.
year_level	A boolean, include year level.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td <- when() |>
  select_date_levels(week_level = FALSE)

---

Configure day level

Description

When the dimension is defined as a date type, using this function we can select the day level and its attributes to include in it: date, month_day, week_day, quarter_day and year_day.

Usage

select_day_level(
  td,
  include_all,
  exclude_all,
  date,
  month_day,
  week_day,
  day_name,
  day_num_name,
  day_abbr,
  day_num_abbr,
  quarter_day,
  year_day
)

## S3 method for class 'when'
select_day_level(
  td,
  include_all = FALSE,
  exclude_all = FALSE,
  date = NULL,
  month_day = NULL,
  week_day = NULL,
  day_name = NULL,
  day_num_name = NULL,
  day_abbr = NULL,
  day_num_abbr = NULL,
  quarter_day = NULL,
  year_day = NULL
)

Arguments

td	A when object.
include_all	A boolean, include all fields of the level.
exclude_all	A boolean, exclude all fields of the level.
date	A boolean, include the date.
month_day	A boolean, include the day number in the month.
week_day	A boolean, the day number in the week.
day_name	A boolean, include the name of the day of the week.
day_num_name	A boolean, include the number and name of the day of the week.
day_abbr	A boolean, include the name of the day of the week in abbreviated version.
day_num_abbr	A boolean, include the number and name of the day of the week in abbreviated version.
quarter_day	A boolean, include the number of the day in the quarter.
year_day	A boolean, include the number of the day in the year.

Details

The include_all and exclude_all parameters allow us to include or exclude all attributes, and then specifically exclude or include the ones we need.

For the week_day we have the day number, its name and the name abbreviation. So that the order of the names corresponds to the alphabetical order, the combination of day number and name and/or abbreviation is included.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td <- when() |>
  select_day_level(day_abbr = FALSE,
                    day_num_abbr = FALSE)

---

Configure month level

Description

When the dimension is defined as a date type, using this function we can select the month level and its attributes to include in it. We can also obtain the combination of the year with the month number.

Usage

select_month_level(
  td,
  include_all,
  exclude_all,
  month,
  year_month,
  month_name,
  month_num_name,
  month_abbr,
  month_num_abbr
)

## S3 method for class 'when'
select_month_level(
  td,
  include_all = FALSE,
  exclude_all = FALSE,
  month = NULL,
  year_month = NULL,
  month_name = NULL,
  month_num_name = NULL,
  month_abbr = NULL,
  month_num_abbr = NULL
)

Arguments

td	A when object.
include_all	A boolean, include all fields of the level.
exclude_all	A boolean, exclude all fields of the level.
month	A boolean, include the month number.
year_month	A boolean, include the year-month combination.
month_name	A boolean, include the month name.
month_num_name	A boolean, include the month number and name.
month_abbr	A boolean, include the month name abbreviated version.
month_num_abbr	A boolean, include the month number and name abbreviated version.

Details

For the month we have the month number in the year, its name and the abbreviation of the name. So that the order of the names corresponds to the alphabetical order, the combination of month number and name and/or abbreviation is included.

The include_all and exclude_all parameters allow us to include or exclude all attributes, and then specifically exclude or include the ones we need.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td <- when() |>
  select_month_level(month_abbr = FALSE,
                      month_num_abbr = FALSE)

---

Configure quarter level

Description

When the dimension is defined as a date type, using this function we can select the quarter level and its attributes to include in it: quarter number and the combination of the year with it.

Usage

select_quarter_level(td, include_all, exclude_all, quarter, year_quarter)

## S3 method for class 'when'
select_quarter_level(
  td,
  include_all = FALSE,
  exclude_all = FALSE,
  quarter = NULL,
  year_quarter = NULL
)

Arguments

td	A when object.
include_all	A boolean, include all fields of the level.
exclude_all	A boolean, exclude all fields of the level.
quarter	A boolean, include the quarter field.
year_quarter	A boolean, include the quarter field.

Details

The include_all and exclude_all parameters allow us to include or exclude all attributes, and then specifically exclude or include the ones we need.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td <- when() |>
  select_quarter_level(quarter = FALSE)

---

Configure semester level

Description

When the dimension is defined as a date type, using this function we can select the semester level and its attributes to include in it: semester number and the combination of the year with it.

Usage

select_semester_level(td, include_all, exclude_all, semester, year_semester)

## S3 method for class 'when'
select_semester_level(
  td,
  include_all = FALSE,
  exclude_all = FALSE,
  semester = NULL,
  year_semester = NULL
)

Arguments

td	A when object.
include_all	A boolean, include all fields of the level.
exclude_all	A boolean, exclude all fields of the level.
semester	A boolean, include the semester field.
year_semester	A boolean, include the semester field.

Details

The include_all and exclude_all parameters allow us to include or exclude all attributes, and then specifically exclude or include the ones we need.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td <- when() |>
  select_semester_level(semester = FALSE)

---

Select time level

Description

When the dimension is defined as a time type, using this function we can select the level and its attributes to include in it: time, minute, second and day_part.

Usage

select_time_level(td, include_all, exclude_all, time, minute, second, day_part)

## S3 method for class 'when'
select_time_level(
  td,
  include_all = FALSE,
  exclude_all = FALSE,
  time = NULL,
  minute = NULL,
  second = NULL,
  day_part = NULL
)

Arguments

td	A when object.
include_all	A boolean, include all fields of the level.
exclude_all	A boolean, exclude all fields of the level.
time	A boolean, include a field for the time.
minute	A boolean, include the minute level of detail.
second	A boolean, include the second level of detail.
day_part	A boolean, include the parts of the day.

Details

The 'hour' attribute will always be included. If the 'minute' attribute is not included the 'second' attribute will not be included either.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td <- when() |>
  select_time_level(day_part = FALSE)

---

Configure week level

Description

When the dimension is defined as a date type, using this function we can select the week level and its attributes to include in it: week and year_week.

Usage

select_week_level(td, include_all, exclude_all, week, year_week)

## S3 method for class 'when'
select_week_level(
  td,
  include_all = FALSE,
  exclude_all = FALSE,
  week = NULL,
  year_week = NULL
)

Arguments

td	A when object.
include_all	A boolean, include all fields of the level.
exclude_all	A boolean, exclude all fields of the level.
week	A boolean, include the week number.
year_week	A boolean, include the year-week combination.

Details

The include_all and exclude_all parameters allow us to include or exclude all attributes, and then specifically exclude or include the ones we need.

For the first and last days of the year, the year associated with the week may be different from the year of the date, depending on the date type selected.

The week number associated with each date depends on the type of date dimension selected: standard ('date'), ISO 8601 ('iso') or epidemiological ('epi').

The standard week numbers blocks of 7 days beginning on January 1. The last week of the year can be less than 7 days long.

The ISO 8601 week numbers blocks of 7 days from Monday to Sunday. The first and last week of the year can contain days from the previous or next year.

The epidemiological week is like ISO 8601 only that it considers that the week begins on Sunday.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_year_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td <- when() |>
  select_week_level(year_week = FALSE)

---

Configure year level

Description

When the dimension is defined as a date type, using this function we can select the year level and its attributes to include in it: year and decade.

Usage

select_year_level(td, include_all, exclude_all, year, decade)

## S3 method for class 'when'
select_year_level(
  td,
  include_all = FALSE,
  exclude_all = FALSE,
  year = NULL,
  decade = NULL
)

Arguments

td	A when object.
include_all	A boolean, include all fields of the level.
exclude_all	A boolean, exclude all fields of the level.
year	A boolean, include the year field.
decade	A boolean, include the decade field.

Details

The include_all and exclude_all parameters allow us to include or exclude all attributes, and then specifically exclude or include the ones we need.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), set_attribute_definition_function(), set_day_part(), when()

Examples

td <- when() |>
  select_year_level(decade = FALSE)

---

Set attribute definition function

Description

Each attribute is defined by a function that adds a column to a table based on the parameter that contains the date or time. This function sets the definition function for the attribute whose name is given.

Usage

set_attribute_definition_function(td, name, f)

## S3 method for class 'when'
set_attribute_definition_function(td, name = NULL, f = NULL)

Arguments

td	A when object.
name	A string, attribute name.
f	A function.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_day_part(), when()

Examples

f <- function(table, values, ...) {
  table[['year']] <- 'Not defined'
  table
}

wd <- when() |>
  set_attribute_definition_function(name = "year", f)

---

Set day part

Description

Using this function we can change the name assigned to the hours of the day to designate the parts of the day.

Usage

set_day_part(td, hour, name)

## S3 method for class 'when'
set_day_part(td, hour = NULL, name = NULL)

Arguments

td	A when object.
hour	A number, hour number (between 0 and 23).
name	a string, name of the part of the day.

Value

A when object.

See Also

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), when()

Examples

td <- when() |>
  set_day_part(hour = c(21:23, 0:4), name = "Night")

---

Set table attribute names

Description

Rename the attributes of the dimension table. It is especially useful if we want to export the table, for example, to a database.

Usage

set_table_attribute_names(td, names)

## S3 method for class 'when'
set_table_attribute_names(td, names = NULL)

Arguments

td	A when object.
names	A string vector.

Value

A when object.

See Also

Other obtaining results: generate_table(), get_level_attribute_names(), get_level_names(), get_table_attribute_names()

Examples

wd <- when() |>
  generate_table()
wd |>
  get_table_attribute_names()

wd <- wd |>
  set_table_attribute_names(
    c(
      'id_when',
      'date',
      'month_day',
      'week_day',
      'day_name',
      'day_num_name',
      'year_week',
      'week',
      'year_month',
      'month',
      'month_name',
      'month_num_name',
      'year'
    )
  )

---

Time in seconds of a day

Description

Time in seconds of a day

Usage

time_seconds

Format

A vector.

See Also

Other time definition: date_days

---

when S3 class

Description

Creates a when object.

Usage

when(
  name = NULL,
  type = NULL,
  locale = NULL,
  start = lubridate::today(),
  end = lubridate::today(),
  values = NULL,
  ...
)

Arguments

name	A string, table name.
type	A string, type of calendar (NULL, 'iso', 'epi' or 'time').
locale	A locale, to use for day and month names.
start	A string, start of the period to be included in the dimension.
end	A string, end of the period to be included in the dimension.
values	A vector of string.
...	Rest of boolean configuration parameters.

Details

Using the parameters of this function we can configure practically all the elements of the dimension. Alternatively, we can use the configuration functions to define the available options.

We discuss the parameters in each of the specific configuration functions.

Value

A when object.

See Also

generate_table, get_table

Other dimension definition: define_characteristics(), define_instances(), get_attribute_definition_function(), get_day_part(), get_week_date_range(), select_date_levels(), select_day_level(), select_month_level(), select_quarter_level(), select_semester_level(), select_time_level(), select_week_level(), select_year_level(), set_attribute_definition_function(), set_day_part()

Examples

td_1 <- when()

td_2 <- when(type = 'time')

---