Type:	Package
Title:	Time-Series Management Made Easy
Version:	0.1.0
Description:	Manage time-series data frames across time zones, resolutions, and date ranges, while filling gaps using weekday/hour patterns or simple fill helpers or plotting them interactively. It is designed to work seamlessly with the tidyverse and dygraphs environments.
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
Suggests:	testthat (≥ 3.0.0), rmarkdown
Config/testthat/edition:	3
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1.0)
Imports:	dplyr, lubridate, rlang, purrr, dygraphs
URL:	https://github.com/resourcefully-dev/timefully/, https://resourcefully-dev.github.io/timefully/
BugReports:	https://github.com/resourcefully-dev/timefully/issues
Language:	en-US
NeedsCompilation:	no
Packaged:	2025-12-04 09:24:54 UTC; marc
Author:	Marc Cañigueral [aut, cre]
Maintainer:	Marc Cañigueral <marccanyigueral@gmail.com>
Repository:	CRAN
Date/Publication:	2025-12-10 20:40:02 UTC

Adapt time-series dataframe to timezone, date range and fill gaps

Description

This function adapts the date range of a time series by reusing historical patterns based on the same weekday occurrence within the year and decimal hour of the day. It also can fill gaps in the data based on past data, so it is recommended to use it for time series with weekly or yearly patterns (so for example energy demand but not solar generation). It can also adapt the timezone of the time series, for example if the data was stored in UTC but corresponds to a different timezone.

Usage

adapt_timeseries(dtf, start_date, end_date, tzone = NULL, fill_gaps = FALSE)

Arguments

Value

tibble

Examples

# Example data set
print(dtf)

# Original date range
range(dtf$datetime)

dtf2 <- adapt_timeseries(
  dtf,
  start_date = as.Date("2021-01-01"),
  end_date = as.Date("2021-01-31"),
  tzone = "America/New_York",
  fill_gaps = FALSE
)

# New date range
range(dtf2$datetime)

Add an extra day at the beginning and the end of datetime sequence using the last and first day of the data

Description

Add an extra day at the beginning and the end of datetime sequence using the last and first day of the data

Usage

add_extra_days(dtf)

Arguments

Value

tibble

Aggregate multiple timeseries columns to a single one

Description

The first column datetime will be kept.

Usage

aggregate_timeseries(dtf, varname, omit = NULL)

Arguments

Value

tibble

Examples

building_flows <- data.frame(
  datetime = as.POSIXct("2024-01-01 00:00:00", tz = "UTC") + 0:3 * 3600,
  building1 = c(2.1, 2.5, 2.3, 2.0),
  building2 = c(1.0, 1.1, 0.9, 1.2)
)
aggregate_timeseries(building_flows, varname = "total_building")

Change time resolution of a time-series data frame

Description

Change time resolution of a time-series data frame

Usage

change_timeseries_resolution(dtf, resolution, method)

Arguments

Value

tibble

Examples

fifteen_min <- data.frame(
  datetime = as.POSIXct("2024-01-01 00:00:00", tz = "UTC") + 0:7 * 900,
  load = c(10, 12, 14, 16, 14, 12, 10, 8)
)
change_timeseries_resolution(
  fifteen_min,
  resolution = 60,
  method = "average"
)

Adapt the timezone of a time series dataframe

Description

The timezone of the datetime column is changed while keeping the same date time sequence. This is useful when the time series data is known to be in a different timezone. If you just want the same time series in a different timezone, use lubridate::force_tz function instead.

Usage

change_timeseries_tzone(dtf, tzone = "Europe/Amsterdam")

Arguments

Value

tibble

Examples

# Example data set
get_timeseries_tzone(dtf)
range(dtf$datetime)

#  Change timezone
new_dtf <- change_timeseries_tzone(dtf, tzone = "Europe/Paris")
get_timeseries_tzone(new_dtf)
range(new_dtf$datetime)

Check if there are any gaps in the datetime sequence

Description

This means all rows a part from "datetime" will be NA. Note that timefully considers a full datetime sequence when days are complete.

Usage

check_timeseries_gaps(dtf)

Arguments

Value

tibble

Examples

# Sample just some hours
dtf_gaps <- dtf[c(1:3, 7:10), ]

# Note that the full day is provided
check_timeseries_gaps(
   dtf_gaps
)

Convert numeric time value to a datetime period (hour-based)

Description

Convert numeric time value to a datetime period (hour-based)

Usage

convert_time_num_to_period(time_num)

Arguments

Value

lubridate::period vector with hours and minutes corresponding to the numeric input.

Examples

convert_time_num_to_period(1.5)
convert_time_num_to_period(c(0.25, 2))

Convert date or datetime value to timestamp number

Description

Convert date or datetime value to timestamp number

Usage

date_to_timestamp(date, tzone = "Europe/Paris", milliseconds = TRUE)

Arguments

Value

numeric

Examples

date_to_timestamp(as.Date("2024-01-01"))
date_to_timestamp(as.POSIXct("2024-01-01 08:00:00", tz = "UTC"), milliseconds = FALSE)

Decrease time resolution of timeseries data frame

Description

Decrease time resolution of timeseries data frame

Usage

decrease_timeseries_resolution(
  dtf,
  resolution,
  method = c("average", "first", "sum")
)

Arguments

Value

tibble

Decimal hours from datetime

Description

Converts a datetime vector into decimal hours (hour plus minutes / 60). The input must not include seconds because sub-minute resolution would make the decimal representation ambiguous for matching time slots.

Usage

dhours(datetime)

Arguments

Value

Numeric vector with decimal hours.

Time-series profiles of consumption and production energy data

Description

This data set is extracted from flextools::energy_profiles

Usage

dtf

Format

A tibble

solar

Solar PV production (in kW)

building

Consumption profile of a building (in kW)

Fill NA values of a datetime sequence vector

Description

Fill NA values of a datetime sequence vector

Usage

fill_datetime(dttm)

Arguments

Value

filled datetime sequence vector

Examples

incomplete_seq <- as.POSIXct("2024-01-01 00:00:00", tz = "UTC") + 0:4 * 3600
incomplete_seq[c(2, 3)] <- NA
fill_datetime(incomplete_seq)

Fill down tibble columns until a maximum number of time slots

Description

Fill down tibble columns until a maximum number of time slots

Usage

fill_down_until(dtf, varnames, max_timeslots = 1)

Arguments

Value

tibble

Examples

down_data <- data.frame(
  datetime = as.POSIXct("2024-01-01 00:00:00", tz = "UTC") + 0:5 * 3600,
  temperature = c(15, 15, NA, NA, NA, 16)
)
fill_down_until(down_data, "temperature", max_timeslots = 2)

Fill from past values

Description

If back index ( NA index - back) is lower than zero then the it is filled with the first value of the data frame. If the value in the back index is also NA, it iterates backwards until finding a non-NA value.

Usage

fill_from_past(dtf, varnames, back = 24)

Arguments

Value

tibble or data.frame

Examples

past_data <- data.frame(
  datetime = as.POSIXct("2024-01-01 00:00:00", tz = "UTC") + 0:3 * 3600,
  consumption = c(1.2, NA, NA, 2.5)
)
fill_from_past(past_data, "consumption", back = 1)

Fill gaps with a specific value

Description

This is useful when the gaps in a numeric timeseries can be filled with the same number (e.g. zero)

Usage

fill_na(dtf, varnames, with = 0)

Arguments

Value

tibble or data.frame

Examples

past_data <- data.frame(
  datetime = as.POSIXct("2024-01-01 00:00:00", tz = "UTC") + 0:3 * 3600,
  consumption = c(1.2, NA, NA, 2.5)
)
fill_na(past_data, "consumption", with = 0)

Date time sequence with time zone and resolution

Description

Date time sequence with time zone and resolution

Usage

get_datetime_seq(start_date, end_date, tzone, resolution)

Arguments

Value

vector of datetime values

Examples

get_datetime_seq(
  start_date = as.Date("2024-01-01"),
  end_date = as.Date("2024-01-03"),
  tzone = "UTC",
  resolution = 120
)

Return the time resolution of a datetime sequence

Description

Return the time resolution of a datetime sequence

Usage

get_time_resolution(dttm_seq, units = "mins")

Arguments

Value

numeric

Examples

seq_15m <- as.POSIXct(
  c("2024-01-01 00:00:00", "2024-01-01 00:15:00", "2024-01-01 00:30:00"),
  tz = "UTC"
)
get_time_resolution(seq_15m, units = "mins")

Return the time resolution of a time series dataframe

Description

Return the time resolution of a time series dataframe

Usage

get_timeseries_resolution(dtf, units = "mins")

Arguments

Value

numeric

Examples

get_timeseries_resolution(dtf, units = "mins")

Get the time zone of a time series dataframe

Description

Get the time zone of a time series dataframe

Usage

get_timeseries_tzone(dtf)

Arguments

Value

character

Examples

get_timeseries_tzone(dtf)

Week date from datetime value

Description

Week date from datetime value

Usage

get_week_from_datetime(dttm)

Arguments

Value

date vector

Examples

dttm <- as.POSIXct(
  c("2024-01-01 08:00:00", "2024-01-02 09:00:00", "2024-01-08 10:00:00"),
  tz = "UTC"
)
get_week_from_datetime(dttm)

Summarise dataframe with weekly total column values

Description

Converts the numeric columns of a time-series data frame to total values per week (sum). Note that if the input values are in power units (e.g., kW), the output values will be in energy units (e.g., kWh).

Usage

get_week_total(dtf)

Arguments

Value

tibble

Examples

get_week_total(dtf[1:100, ])

Yearly date time sequence with time zone and resolution

Description

Yearly date time sequence with time zone and resolution

Usage

get_yearly_datetime_seq(year, tzone, resolution)

Arguments

Value

vector of datetime values

Examples

get_yearly_datetime_seq(
  year = 2024,
  tzone = "UTC",
  resolution = 60
)

Increase datetime vector resolution

Description

Increase datetime vector resolution

Usage

increase_datetime_resolution(y, resolution)

Arguments

Value

datetime vector

Increase numeric vector resolution

Description

Increase numeric vector resolution

Usage

increase_numeric_resolution(
  y,
  n,
  method = c("interpolate", "repeat", "divide")
)

Arguments

Details

if we have a vector v = c(1, 2), and we choose the interpolate method, then:

increase_numeric_resolution(v, 4, 'interpolate')

returns c(1, 1.25, 1.5, 1.75, 2)

if we choose the repeat method, then:

increase_numeric_resolution(v, 4, 'repeat')

returns c(1, 1, 1, 1, 2)

Value

numeric vector

Increase time resolution of a timeseries data frame

Description

Increase time resolution of a timeseries data frame

Usage

increase_timeseries_resolution(
  dtf,
  resolution,
  method = c("interpolate", "repeat", "divide")
)

Arguments

Value

tibble

Interpolate n values between two numeric values

Description

Interpolate n values between two numeric values

Usage

interpolation(y1, y2, n)

Arguments

Value

numeric vector

Interactive plot for time-series tibbles

Description

First column of the df tibble must be a datetime or date variable. The rest of columns must be numeric of the same units. This functions makes use of dygraphs package to generate an HTML dygraphs plot.

Usage

plot_ts(
  df,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  legend_show = "auto",
  legend_width = 250,
  group = NULL,
  width = NULL,
  height = NULL,
  ...
)

Arguments

Value

dygraph

Examples

plot_ts(dtf, ylab = "kW", legend_show = "onmouseover")

Time difference start function

Description

Use this function together with toc() to control time spent by functions

Usage

tic()

Value

numeric

Convert a number of minutes in string format "HH:MM"

Description

Convert a number of minutes in string format "HH:MM"

Usage

to_hhmm(mins)

Arguments

Value

character

Examples

to_hhmm(75)

Time difference end function

Description

Use this function together with tic() to control time spent by functions

Usage

toc(units = "secs", digits = 2)

Arguments

Value

numeric

Year-weekday occurrence identifier

Description

Computes a stable index for each datetime by combining the weekday (Monday = 1) with how many times that weekday has already occurred in the year. The result can be used to align data such as "third Monday" across different calendar years without depending on ISO week numbers.

Usage

ywday(datetime)

Arguments

Value

Integer vector; for example, 402 denotes the second Thursday.