Skip to contents

Convert data.table to csfmt_rts_data_v1 (deprecated)

Source: R/csfmt_rts_v1.R
set_csfmt_rts_data_v1.Rd

set_csfmt_rts_data_v1 converts a data.table to csfmt_rts_data_v1 by reference. csfmt_rts_data_v1 creates a new csfmt_rts_data_v1 (not by reference) from a data.table. Both stop with an error when x is not a data.table; call data.table::setDT() first.

Usage

set_csfmt_rts_data_v1(x, create_unified_columns = TRUE, heal = TRUE)

csfmt_rts_data_v1(x, create_unified_columns = TRUE, heal = TRUE)

Arguments

x

The data.table to be converted to csfmt_rts_data_v1

create_unified_columns

Do you want it to create unified columns?

heal

Derive the missing time and geography columns on creation? These are deterministically looked up from the time and location columns you supply (see cstime and csdata). Nothing is statistically imputed and no count is invented. Time healing reads granularity_time to decide which time column the others are derived from, so supply it.

Value

An extended data.table, which has been modified by reference and returned (invisibly).

Returns a duplicated csfmt_rts_data_v1.

Smart assignment

csfmt_rts_data_v1 contains the smart assignment feature for time and geography.

When the variables in bold are assigned using :=, the listed variables are automatically re-derived from it. This is deterministic derivation from a calendar and a geography lookup, not statistical imputation.

location_code:

  • granularity_geo

  • country_iso3

isoyear:

  • granularity_time

  • isoweek

  • isoyearweek

  • season

  • seasonweek

  • calyear

  • calmonth

  • calyearmonth

  • date

isoyearweek:

  • granularity_time

  • isoyear

  • isoweek

  • season

  • seasonweek

  • calyear

  • calmonth

  • calyearmonth

  • date

date:

  • granularity_time

  • isoyear

  • isoweek

  • isoyearweek

  • season

  • seasonweek

  • calyear

  • calmonth

  • calyearmonth

Unified columns

csfmt_rts_data_v1 contains 16 unified columns:

  • granularity_time

  • granularity_geo

  • country_iso3

  • location_code

  • border

  • age

  • sex

  • isoyear

  • isoweek

  • isoyearweek

  • season

  • seasonweek

  • calyear

  • calmonth

  • calyearmonth

  • date

Deprecated

csfmt_rts_data_v1 is deprecated. The format still works and nothing warns at run time; the mark is a signpost for new work, not a removal notice. set_csfmt_rts_data_v2() is the replacement. Two properties of that move were measured, and both come out clean. All 16 of v1's unified columns are among v2's 18, the two extra ones being isoquarter and isoyearquarter. v2 heals from every granularity_time v1 heals from ("date", "isoyearweek", "isoyear") and from "season" as well. csdb exports a field-type validator for both formats, so either can be written to the database.

v2 is itself deprecated, in favour of set_csfmt_rts_data_v3(). That further step is not lossless. Read the Deprecated section of set_csfmt_rts_data_v2() before going past v2.

See also

No vignette runs this function. The benchmarks vignette reports its run time, but that vignette is precompiled and carries no runnable code: vignette("benchmarks", package = "cstidy").

Other csfmt_rts_data: expand_time_to(), identify_data_structure(), remove_class_csfmt_rts_data(), set_csfmt_rts_data_v2(), set_csfmt_rts_data_v3(), unique_time_series()

Other csfmt format converters: set_csfmt_rts_data_v2(), set_csfmt_rts_data_v3()

Examples

# granularity_time names the time column that the others are derived from.
d <- data.table::data.table(
  granularity_time = "isoyearweek",
  isoyearweek = c("2022-01", "2022-02"),
  location_code = "county_nor03",
  deaths_n = c(3L, 5L)
)

# set_csfmt_rts_data_v1() converts d in place and returns it invisibly.
cstidy::set_csfmt_rts_data_v1(d)
d[]
#>    granularity_time granularity_geo country_iso3 location_code border    age
#>              <char>          <char>       <char>        <char>  <int> <char>
#> 1:      isoyearweek          county          nor  county_nor03     NA   <NA>
#> 2:      isoyearweek          county          nor  county_nor03     NA   <NA>
#>       sex isoyear isoweek isoyearweek    season seasonweek calyear calmonth
#>    <char>   <int>   <int>      <char>    <char>      <num>   <int>    <int>
#> 1:   <NA>    2022       1     2022-01 2021/2022         24      NA       NA
#> 2:   <NA>    2022       2     2022-02 2021/2022         25      NA       NA
#>    calyearmonth       date deaths_n
#>          <char>     <Date>    <int>
#> 1:         <NA> 2022-01-09        3
#> 2:         <NA> 2022-01-16        5
class(d)
#> [1] "csfmt_rts_data_v1" "data.table"        "data.frame"       

# csfmt_rts_data_v1() copies instead, so e is left as it was.
e <- data.table::data.table(
  granularity_time = "isoyearweek",
  isoyearweek = c("2022-01", "2022-02"),
  location_code = "county_nor03",
  deaths_n = c(3L, 5L)
)
y <- cstidy::csfmt_rts_data_v1(e)
class(y)
#> [1] "csfmt_rts_data_v1" "data.table"        "data.frame"       
class(e)
#> [1] "data.table" "data.frame"
names(e)
#> [1] "granularity_time" "isoyearweek"      "location_code"    "deaths_n"