Current period year-to-date

Source: R/time_intelligence_classes.R

• For each group, ytd() will create the running annual sum of a value based on the calendar type specified

• The function returns a ti object which prints out the summary of steps and actions that will take to create the calendar table and calculations

• Use calculate to return the results

Usage

ytd(.data, .date, .value, calendar_type = "standard", fiscal_year_start = 1)

Arguments

.data

tibble or dbi object (either grouped or ungrouped)

.date

the date column to group by. Must be a Date or POSIXt type.

.value

the value column to summarize. Must be numeric.

calendar_type

select either ‘standard’, ‘445’, ‘454’, or ‘544’ calendar, see ‘Details’ for additional information

fiscal_year_start

integer 1-12, the month the fiscal year starts nearest to (default 1 = January). Only used with retail calendars (‘445’, ‘454’, ‘544’).

Value

ti object

Details

• This function creates a complete calendar object that fills in any missing days, weeks, months, quarters, or years

• If you provide a grouped object with dplyr::group_by(), it will generate a complete calendar for each group

• The function creates a ti object, which pre-processes the data and arguments for further downstream functions

NA Handling

• NA values in the .value column propagate through cumulative sums (cumsum returns NA once an NA is encountered)

• NA values in the .date column are excluded from the calendar join and will not appear in results

• Missing dates (gaps in your data) are filled with 0 values, not NA

standard calendar

• The standard calendar splits the year into 12 months (with 28–31 days each) and uses a 7-day week

• It automatically accounts for leap years every four years to match the Gregorian calendar

5-5-4 calendar

• The 5-5-4 calendar divides the fiscal year into 52 weeks (occasionally 53), organizing each quarter into two 5-week periods and one 4-week period.

• This system is commonly used in retail and financial reporting

See Also

Other time_intelligence: atd(), dod(), mom(), momtd(), mtd(), mtdopm(), pmtd(), pqtd(), pwtd(), pytd(), qoq(), qoqtd(), qtd(), qtdopq(), wow(), wowtd(), wtd(), wtdopw(), yoy(), yoytd(), ytdopy()

Examples

ytd(contoso::sales,.date=order_date,.value=quantity,calendar_type="standard")
#> 
#> ── Year-to-date ────────────────────────────────────────────────────────────────
#> Function: `ytd` was executed
#> 
#> ── Description: ──
#> 
#> This creates a daily `cumsum()` of the current year quantity from the start of
#> the standard calendar year to the end of the year
#> 
#> ── Calendar: ──
#> 
#> • The calendar aggregated order_date to the day time unit
#> • A standard calendar is created with 0 groups
#> • Calendar ranges from 2021-05-18 to 2024-04-20
#> • 222 days were missing and replaced with 0
#> • New date column date, year was created from order_date
#> ── Actions: ──
#> ✔Aggregate
#> ✖Shift
#> ✖Compare
#> ✖Proportion of Total
#> ✖Count Distinct
#> 
#> ── Next Steps: ──
#> 
#> • Use `calculate()` to return the results
#> ────────────────────────────────────────────────────────────────────────────────
#>