Help for package cepiweek

Title:

Continuous Epidemiological Week Indexing for Time-Series Analysis

Version:

0.2.0

Description:

Provides a simple algorithm to generate a continuous epidemiological week index from date variables in a data frame. Weeks are computed as sequential 7-day intervals aligned to Mondays, starting from the earliest observed date or from a user-supplied start date. They do not reset at calendar year boundaries and are not ISO 8601 nor MMWR calendar weeks. Missing or non-convertible dates are returned as NA instead of stopping the computation. The approach is intended for epidemiological modeling and time-series analysis where temporal continuity is required.

License:

MIT + file LICENSE

Encoding:

UTF-8

Imports:

lubridate

Suggests:

testthat (≥ 3.1.5)

Config/testthat/edition:

URL:

https://github.com/DanielDegina/cepiweek

BugReports:

https://github.com/DanielDegina/cepiweek/issues

Config/roxygen2/version:

8.1.1

NeedsCompilation:

Packaged:

2026-10-13 09:50:00 UTC; Daniel_Degina_MY

Author:

Daniel Degina [aut, cre], Joel Mbuyi [ctb]

Maintainer:

Daniel Degina <deginadan@gmail.com>

Repository:

CRAN

Date/Publication:

2026-10-13 10:10:02 UTC

Generate Continuous Epidemiological Week Index for a Date Column

Description

This function adds a continuous epidemiological week index to a data frame by assigning each date to a sequential week number starting from a reference date.

Usage

cepiweek(data, col_date, start = NULL, format = "dmy", quiet = FALSE)

Arguments

data

A data frame containing the date column.

col_date

Name of the date column (string). The column can be of class Date, POSIXct or character.

start

Optional start date for counting weeks (Date or string, read with the same format as the column). Defaults to the minimum date in the column col_date.

format

Optional date format flag. Use "mdy" if all dates are in month-day-year format (common in US). Defaults to "dmy"/"ymd" which handles day-month-year or year-month-day formats.

quiet

Logical. If FALSE (default), a warning reports the number of values that could not be converted to a date. Set to TRUE to silence it.

Details

The generated weeks are continuous and do not reset at calendar year boundaries. They are not ISO 8601 or MMWR weeks. This function is intended for epidemiological modeling, time-series analysis, and nowcasting applications.

You can specify a start date for counting weeks; if none is provided, the minimum date in the column is used. The function also allows specifying the format of the dates to handle different conventions (day-month-year vs month-day-year).

The function automatically replaces / with - for consistency.
Missing values, empty strings, "NA" and "N/A" are treated as missing dates.
Dates that cannot be converted do not stop the function: they are set to NA and reported in a warning (unless quiet = TRUE).
Date-times (for example "2024-01-15 10:30:00") are accepted; the time is ignored.
A warning is issued if the start date is after the earliest date in the column.
Continuous weeks are aligned to Mondays.

Value

A data frame with an added cepiweek column containing continuous week indices. The date column is returned as class Date. Missing or non-convertible dates are returned as NA (NA_Date_ in the date column and NA_integer_ in cepiweek).

Examples

# Standard dmy/ymd dates
k = data.frame(
  num = c(1, 2, 3),
  date = c("15-01-2024", "12/02/2025", "2026-08-01")
)
cepiweek(k, col_date = "date")

# American format mm-dd-yyyy
k2 = data.frame(
  num = c(1, 2, 3),
  date = c("01/15/2024", "02-12-2025", "08/01/2026")
)
cepiweek(k2, col_date = "date", format = "mdy")

# Missing and non-convertible dates give NA instead of an error
k3 = data.frame(
  num = 1:4,
  date = c("15-01-2024", NA, "not a date", "2024-02-05")
)
cepiweek(k3, col_date = "date", quiet = TRUE)

Package {cepiweek}