Package 'nocturn'

Description

Checks whether all the packages in Suggests are installed and prompts for install if not.

Usage

check_suggests()

Value

No return value, called for side effects

See Also

Other internal: get_col(), get_colnames(), get_epoch_colnames(), get_session_colnames(), get_time_per_day(), is_iso8601_datetime(), set_colnames(), set_data_type()

Description

This function calculates the Chronotype metric based on the mid-sleep time If sleep duration on free days is greater than on workdays, it applies a correction as described in Roenneberg et al. (2019).

Usage

chronotype(sessions)

Arguments

Details

This function uses columns:

• time_at_midsleep

• sleep_period

• is_workday

Value

The Chronotype value in hours

See Also

Other sleep metrics: composite_phase_deviation(), interdaily_stability(), sleep_regularity_index(), social_jet_lag()

Examples

chronotype(example_sessions)

Description

Clean epoch data

Usage

clean_epochs(epochs)

Arguments

Value

The cleaned-up epochs dataframe

Examples

epochs <- clean_epochs(nocturn::example_epochs)
clean_epochs(example_epochs)

Description

Clean session data

Usage

clean_sessions(sessions)

Arguments

Value

The cleaned-up sessions dataframe

Examples

sessions <- clean_sessions(nocturn::example_sessions)
clean_sessions(example_sessions)

Description

This function calculates the Composite Phase Deviation (CPD) metric, used to measure the regularity of the sleep patterns.

Usage

composite_phase_deviation(sessions)

Arguments

Details

This function uses columns:

• time_at_midsleep

• is_workday

• night

Value

The Composite Phase Deviation (CPD) value

See Also

Other sleep metrics: chronotype(), interdaily_stability(), sleep_regularity_index(), social_jet_lag()

Examples

composite_phase_deviation(example_sessions)

Description

A data frame containing epoch data recorded by a Somnofy device.

Usage

example_epochs

Format

example_epochs

A data frame with 18,755 rows and 15 columns. Each row represents a time-point (or epoch) in a session. Epochs are 30 seconds long. The columns are as follows:

• timestamp: The time at which the epoch was recorded in UTC.

• subject_id: The ID of the subject.

• signal_quality_mean: The mean signal quality of the epoch.

• movement_fast_mean: The mean movement detected during the epoch.

• movement_fast_nonzero_pct

• distance_mean: the distance of the subject from the device in meters.

• motion_data_count: The number of data points in the epoch (30).

• light_ambient_mean: The ambient light level during the epoch.

• sound_amplitude_mean: The sound amplitude during the epoch.

• temperature_ambient_mean: The ambient temperature during the epoch.

• humidity_mean: The ambient humidity during the epoch.

• pressure_mean: The ambient pressure during the epoch.

• indoor_air_quality_mean: The indoor air quality during the epoch.

• epoch_duration: The precise duration of the epoch (seconds).

• sleep_stage: The sleep stage as established with the VT algorithm. They are encoded as numbers 0-5

Source

data-raw/example_epochs.csv

Description

A data frame containing epoch data recorded by a Somnofy device.

Usage

example_epochs_v1

Format

example_epochs_v1

A data frame with 1,373 rows and 16 columns. The corresponding session ID is contained in the file name. Each row represents a time-point (or epoch) in a session. Epochs are 30 seconds long. The columns are as follows:

• timestamp: The time at which the epoch was recorded in UTC.

• signal_quality_mean: The mean signal quality of the epoch.

• movement_fast_mean: The mean movement detected during the epoch.

• movement_fast_nonzero_pct

• distance_mean: the distance of the subject from the device in meters.

• motion_data_count: The number of data points in the epoch (30).

• light_ambient_mean: The ambient light level during the epoch.

• sound_amplitude_mean: The sound amplitude during the epoch.

• temperature_ambient_mean: The ambient temperature during the epoch.

• humidity_mean: The ambient humidity during the epoch.

• pressure_mean: The ambient pressure during the epoch.

• indoor_air_quality_mean: The indoor air quality during the epoch.

• epoch_duration: The precise duration of the epoch (seconds).

• sleep_stage: The sleep stage as established with the VT algorithm. They are encoded as numbers 0-5

Source

data-raw/SEtXSxcMEhYXKQAA.example_epochs_v1.csv

Description

A data frame containing sessions recorded by a Somnofy device.

Usage

example_sessions

Format

example_sessions

A data frame with 124 rows and 60 columns. Each row represents a session. Columns contain metadata about the session, including:

• session_start: The start time of the session in UTC.

• session_end: The end time of the session in UTC.

• subject_id: The ID of the subject.

• device_serial_number: The serial number of the device used.

• time_at_sleep_onset: The time at which the subject fell asleep.

• time_at_wakeup: The time at which the subject woke up. Columns also include various metrics averaged over the session, such as:

• mean heart rate

• mean respiration rate Finally, some columns contain environmental parameters, such as:

• Temperature

• Humidity

• Light intensity

• Noise level

• Atmospheric pressure

Source

data-raw/example_sessions.csv

Description

A data frame containing sessions recorded by a Somnofy device.

Usage

example_sessions_v1

Format

example_sessions_v1

A data frame with 87 rows and 70 columns. Each row represents a session. Columns contain metadata about the session, including:

• user_id: The ID of the recorded subject.

• sex: The sex of the recorded subject.

• birth_year: The year of birth of the recorded subject.

• session_start: The start time of the session in UTC.

• session_end: The end time of the session in UTC.

• time_at_sleep_onset: The time at which the subject fell asleep.

• time_at_wakeup: The time at which the subject woke up. Columns also include various metrics averaged over the session, such as:

• mean heart rate

• mean respiration rate Finally, some columns contain environmental parameters, such as:

• Temperature

• Humidity

• Light intensity

• Noise level

• Atmospheric pressure

Source

data-raw/example_sessions_v1.csv

Description

Filter sessions by age range

Usage

filter_by_age_range(
  sessions,
  min_age = NULL,
  max_age = NULL,
  return_mask = FALSE
)

Arguments

Details

This function uses columns:

• birth_year

• night

Value

The sessions dataframe with only the sessions that belong to subjects within the specified age range, or a logical vector if return_mask is TRUE

See Also

Other filtering: filter_by_night_range(), filter_by_sex(), filter_epochs_from_sessions(), remove_sessions_no_sleep(), select_devices(), select_subjects(), set_min_sleep_period(), set_min_time_in_bed(), set_session_sleep_onset_range(), set_session_start_time_range()

Examples

filtered_sessions <- filter_by_age_range(example_sessions_v1, min_age = 11, max_age = 18)

Description

Filter sessions for nights within a night range

Usage

filter_by_night_range(sessions, from_night, to_night, return_mask = FALSE)

Arguments

Details

This function uses columns:

• night

Value

The sessions dataframe with only the sessions that fall within the specified night range, or a logical vector if return_mask is TRUE

See Also

Other filtering: filter_by_age_range(), filter_by_sex(), filter_epochs_from_sessions(), remove_sessions_no_sleep(), select_devices(), select_subjects(), set_min_sleep_period(), set_min_time_in_bed(), set_session_sleep_onset_range(), set_session_start_time_range()

Examples

filtered_sessions <- filter_by_night_range(example_sessions, "2025-04-07", "2025-04-10")

Description

Filter by sex

Usage

filter_by_sex(sessions, sex, return_mask = FALSE)

Arguments

Details

This function uses columns:

• sex

Value

The sessions dataframe with only the sessions that belong to the specified sex, or a logical vector if return_mask is TRUE

See Also

Other filtering: filter_by_age_range(), filter_by_night_range(), filter_epochs_from_sessions(), remove_sessions_no_sleep(), select_devices(), select_subjects(), set_min_sleep_period(), set_min_time_in_bed(), set_session_sleep_onset_range(), set_session_start_time_range()

Examples

filtered_sessions <- filter_by_sex(example_sessions_v1, "M")

Description

Filter epochs based on session IDs

Usage

filter_epochs_from_sessions(epochs, sessions, return_mask = FALSE)

Arguments

Details

This function uses sessions columns:

• id And epoch columns:

• session_id

Value

The epochs dataframe with only the epochs that belong to the specified sessions, or a logical vector if return_mask is TRUE

See Also

filter_by_night_range() to filter sessions by night range.

Other filtering: filter_by_age_range(), filter_by_night_range(), filter_by_sex(), remove_sessions_no_sleep(), select_devices(), select_subjects(), set_min_sleep_period(), set_min_time_in_bed(), set_session_sleep_onset_range(), set_session_start_time_range()

Examples

# Apply filtering to sessions to keep specific nights, and filter epochs accordingly
filtered_sessions <- filter_by_night_range(example_sessions, "2025-04-07", "2025-04-10")
filtered_epochs <- filter_epochs_from_sessions(example_epochs, filtered_sessions)

Description

Retrieve a column from a dataframe. If the column does not exist or is NULL, it returns a vector of NULLs of the same length as the number of rows in the dataframe.

Usage

get_col(df, col)

Arguments

Value

A vector containing the values of the specified column, or a vector of NULLs if the column does not exist

See Also

Other internal: check_suggests(), get_colnames(), get_epoch_colnames(), get_session_colnames(), get_time_per_day(), is_iso8601_datetime(), set_colnames(), set_data_type()

Examples

get_col(example_sessions, "session_start")

Description

Dispatch to the appropriate function based on the dataframe type attribute (expecting "sessions" or "epochs").

Usage

get_colnames(df)

Arguments

Value

A named list of column names

See Also

Other internal: check_suggests(), get_col(), get_epoch_colnames(), get_session_colnames(), get_time_per_day(), is_iso8601_datetime(), set_colnames(), set_data_type()

Examples

get_colnames(example_sessions)

Description

This function retrieves the standard column names for epochs data. If the column names are not set as an attribute, it attempts to infer them from a list of common column names.

Usage

get_epoch_colnames(epochs)

Arguments

Value

A named list of column names

See Also

Other internal: check_suggests(), get_col(), get_colnames(), get_session_colnames(), get_time_per_day(), is_iso8601_datetime(), set_colnames(), set_data_type()

Examples

get_epoch_colnames(example_epochs)

Description

Display the number of sessions in the epoch data, as well as the start and end dates of the epoch data

Usage

get_epochs_summary(epochs)

Arguments

Details

This function uses columns:

• timestamp

• session_id

Value

A single-row dataframe summarising epoch information

See Also

get_sessions_summary() to summarise session information.

Other data tables: get_non_complying_sessions(), get_removed_sessions(), get_sessions_summary()

Examples

get_epochs_summary(example_epochs)

Description

Get non-complying sessions (i.e. where there is more than one session on the same day)

Usage

get_non_complying_sessions(sessions)

Arguments

Details

This function uses columns:

• night

Value

The sessions dataframe with only the sessions that are non-complying

See Also

Other data tables: get_epochs_summary(), get_removed_sessions(), get_sessions_summary()

Examples

duplicate_sessions <- get_non_complying_sessions(example_sessions)

Description

Get a table of sessions that were removed during filtering

Usage

get_removed_sessions(sessions, filtered_sessions)

Arguments

Details

This function uses columns:

• id

• sleep_period

Value

The sessions dataframe with only the sessions that were removed during filtering

See Also

Other data tables: get_epochs_summary(), get_non_complying_sessions(), get_sessions_summary()

Examples

filtered_sessions <- set_session_start_time_range(example_sessions, "22:00", "06:00")
removed_sessions <- get_removed_sessions(example_sessions, filtered_sessions)

Description

This function retrieves the standard column names for sessions data. If the column names are not set as an attribute, it attempts to infer them from a list of common column names.

Usage

get_session_colnames(sessions)

Arguments

Value

A named list of column names

See Also

Other internal: check_suggests(), get_col(), get_colnames(), get_epoch_colnames(), get_time_per_day(), is_iso8601_datetime(), set_colnames(), set_data_type()

Examples

get_session_colnames(example_sessions)

Description

Summarise session information, including the number of sessions, mean session length, mean time at sleep onset and wakeup, subject and device ID.

Usage

get_sessions_summary(sessions)

Arguments

Details

This function uses columns:

• time_at_sleep_onset

• time_at_wakeup

• time_in_bed

• sleep_period

Value

A single-row dataframe summarizing session information.

See Also

get_epochs_summary() to summarise epoch information.

Other data tables: get_epochs_summary(), get_non_complying_sessions(), get_removed_sessions()

Examples

get_sessions_summary(example_sessions)

Description

This function returns the number of specified time units (seconds, minutes or hours) in a day.

Usage

get_time_per_day(unit = "second")

Arguments

Value

The number of time units in a day (numeric)

See Also

Other internal: check_suggests(), get_col(), get_colnames(), get_epoch_colnames(), get_session_colnames(), is_iso8601_datetime(), set_colnames(), set_data_type()

Examples

get_time_per_day("hour")

Description

The function creates a new column night that groups the epochs by night. Timepoints before 12 PM are considered part of the previous night.

Usage

group_epochs_by_night(epochs)

Arguments

Details

This function uses columns:

• timestamp

Value

The epochs dataframe with the night column added

See Also

group_sessions_by_night() to group session data by night.

Other time processing: group_sessions_by_night(), max_time(), mean_time(), min_time(), parse_date(), parse_time(), sd_time(), shift_times_by_12h(), time_diff(), time_to_hours(), update_date()

Examples

epochs <- group_epochs_by_night(example_epochs)

Description

The function creates a new column night that groups the sessions by night depending on their start time. Sessions that start before 12 PM are considered part of the previous night.

Usage

group_sessions_by_night(sessions)

Arguments

Details

This function uses columns:

• session_start

Value

The sessions dataframe with the night column added

See Also

group_epochs_by_night() to group epoch data by night.

Other time processing: group_epochs_by_night(), max_time(), mean_time(), min_time(), parse_date(), parse_time(), sd_time(), shift_times_by_12h(), time_diff(), time_to_hours(), update_date()

Examples

sessions <- group_sessions_by_night(example_sessions)

Description

This function calculates the Interdaily Stability (IS) metric from a binary awake/asleep variable

Usage

interdaily_stability(epochs)

Arguments

Details

This function uses columns:

• timestamp

• is_asleep

Value

The Interdaily Stability (IS) value

See Also

Other sleep metrics: chronotype(), composite_phase_deviation(), sleep_regularity_index(), social_jet_lag()

Examples

interdaily_stability(example_epochs)

Description

This function checks if all non-missing values in a column are valid ISO 8601 datetime strings.

Usage

is_iso8601_datetime(x)

Arguments

Value

TRUE if all non-missing values are valid ISO 8601 datetime strings, FALSE otherwise

See Also

Other internal: check_suggests(), get_col(), get_colnames(), get_epoch_colnames(), get_session_colnames(), get_time_per_day(), set_colnames(), set_data_type()

Examples

is_iso8601_datetime(c("2026-01-01T14:10"))

Description

Load session or epoch data in batch mode

Usage

load_batch(
  folder_path = NULL,
  file_list = NULL,
  file_names = NULL,
  pattern = NULL,
  type = "sessions"
)

Arguments

Value

A dataframe containing the combined session data from all matching files in the folder

See Also

Other data loading: load_epochs(), load_sessions(), read_edf_epochs(), read_edf_sessions()

Examples

tf1 <- tempfile(fileext = ".csv")
tf2 <- tempfile(fileext = ".csv")
utils::write.csv(data.frame(id = 1), tf1, row.names = FALSE)
utils::write.csv(data.frame(id = 1), tf2, row.names = FALSE)
load_batch(file_list = c(tf1, tf2))

Description

Load epoch data

Usage

load_epochs(epochs_file, file_name = NULL)

Arguments

Details

The function loads the epoch data from a file and groups the epochs by night. Supported formats: CSV, Excel, EDF.

Value

A dataframe containing the epoch data

See Also

Other data loading: load_batch(), load_sessions(), read_edf_epochs(), read_edf_sessions()

Examples

tf <- tempfile(fileext = ".csv")
utils::write.csv(data.frame(id = 1), tf, row.names = FALSE)
load_epochs(tf)

Description

Load session data

Usage

load_sessions(sessions_file)

Arguments

Details

The function loads the session data from a file Supported formats: CSV, Excel, EDF.

Value

A dataframe containing the session data

See Also

Other data loading: load_batch(), load_epochs(), read_edf_epochs(), read_edf_sessions()

Examples

tf <- tempfile(fileext = ".csv")
utils::write.csv(data.frame(id = 1), tf, row.names = FALSE)
load_sessions(tf)

Description

This function calculates the maximum time from a vector of time strings in the format "YYYY-MM-DD HH:MM:SS". It considers a time window from 12pm to 12pm the next day, so 11:00 is considered later than 13:00.

Usage

max_time(time_vector)

Arguments

Value

A string representing the maximum time in the format "HH:MM".

See Also

min_time() to calculate the minimum time in the same format.

Other time processing: group_epochs_by_night(), group_sessions_by_night(), mean_time(), min_time(), parse_date(), parse_time(), sd_time(), shift_times_by_12h(), time_diff(), time_to_hours(), update_date()

Examples

max_time(c("2025-04-08 23:00:00", "2025-04-09 01:00:00", "2025-04-09 02:30:00"))

Description

This function calculates the mean time from a vector of time strings in the format "YYYY-MM-DD HH:MM:SS".

Usage

mean_time(time_vector, unit = "HH:MM")

Arguments

Value

A string representing the mean time in the format "HH:MM".

See Also

Other time processing: group_epochs_by_night(), group_sessions_by_night(), max_time(), min_time(), parse_date(), parse_time(), sd_time(), shift_times_by_12h(), time_diff(), time_to_hours(), update_date()

Examples

# Use on a vector of time strings representing full dates
time_vector <- c("2025-04-08 23:00:00", "2025-04-09 01:00:00")
mean_time(time_vector)

# Use on time-only strings
time_vector <- c("22:56", "01:32")
mean_time(time_vector)

# Use on a dataframe column
mean_time(example_sessions$time_at_sleep_onset)

Description

This function calculates the minimum time from a vector of time strings in the format "YYYY-MM-DD HH:MM:SS". It considers a time window from 12pm to 12pm the next day, so 11:00 is considered later than 13:00.

Usage

min_time(time_vector)

Arguments

Value

A string representing the minimum time in the format "HH:MM".

See Also

max_time() to calculate the maximum time in the same format.

Other time processing: group_epochs_by_night(), group_sessions_by_night(), max_time(), mean_time(), parse_date(), parse_time(), sd_time(), shift_times_by_12h(), time_diff(), time_to_hours(), update_date()

Examples

min_time(c("2025-04-08 23:00:00", "2025-04-09 01:00:00", "2025-04-09 02:30:00"))

Description

This function launches the nocturn app, a Shiny application for visualizing and analyzing sleep data.

Usage

nocturn()

Value

No return value, called for side-effects

Examples

if(interactive()){nocturn()}

Description

This function parses a vector of date strings into Date objects. All formats containing year, month, and day information are supported.

Usage

parse_date(date_vector)

Arguments

Value

A vector of Date objects

See Also

Other time processing: group_epochs_by_night(), group_sessions_by_night(), max_time(), mean_time(), min_time(), parse_time(), sd_time(), shift_times_by_12h(), time_diff(), time_to_hours(), update_date()

Examples

parse_date("2026-01-02T14:33:09")

Description

This function parses a vector of time strings into POSIXct objects. Supported formats include "YYYY-MM-DD HH:MM:SS", "YYYY-MM-DD HH:MM", "HH:MM:SS", and "HH:MM". Timezone information is ignored.

Usage

parse_time(time_vector)

Arguments

Value

A vector of POSIXct objects

See Also

Other time processing: group_epochs_by_night(), group_sessions_by_night(), max_time(), mean_time(), min_time(), parse_date(), sd_time(), shift_times_by_12h(), time_diff(), time_to_hours(), update_date()

Examples

parse_time("2026-01-01T14:34:09")

Description

Plot bedtimes and waketimes

Usage

plot_bedtimes_waketimes(sessions, groupby = "night", color_by = "default")

Arguments

Details

This function uses columns:

• night

• time_at_sleep_onset

• time_at_wakeup

• is_workday

Value

A ggplot graph showing the bedtimes and waketimes

Examples

plot_bedtimes_waketimes(example_sessions)

Description

Plot Hypnogram

Usage

plot_hypnogram(epochs)

Arguments

Details

This function uses columns:

• timestamp

• sleep_stage

Value

A ggplot object showing the hypnogram as bars

See Also

Other plot epochs: plot_sleep_spiral(), plot_timeseries()

Examples

plot_hypnogram(example_epochs)

Description

This function creates a bubble plot of sleep sessions, where the size and colour of the bubbles represents the sleep duration.

Usage

plot_sleep_bubbles(sessions, color_by = "default", bubble_size = 10)

Arguments

Details

This function uses columns:

• sleep_period

• night

Value

A ggplot object containing the sleep bubbles graph.

See Also

Other plot sessions: plot_sleep_clock(), plot_timeseries_sessions()

Examples

plot_sleep_bubbles(example_sessions)

Description

Plot Sleep Clock

Usage

plot_sleep_clock(sessions, color_by = "default")

Arguments

Details

This function uses columns:

• time_at_sleep_onset

• time_at_wakeup

• night

Value

A ggplot object showing the sleep clock

See Also

Other plot sessions: plot_sleep_bubbles(), plot_timeseries_sessions()

Examples

plot_sleep_clock(example_sessions)

Description

Plot Sleep Spiral

Usage

plot_sleep_spiral(epochs, color_by = "default")

Arguments

Details

This function uses columns:

• timestamp

• is_asleep

Value

A ggplot object showing the sleep spiral

See Also

Other plot epochs: plot_hypnogram(), plot_timeseries()

Examples

plot_sleep_spiral(example_epochs)

Description

Plot epoch time series data for a given variable

Usage

plot_timeseries(epochs, variable, color_by = "default", exclude_zero = FALSE)

Arguments

Details

This function uses columns:

• timestamp

• night

Value

A ggplot object

See Also

plot_timeseries_sessions() to plot session data.

Other plot epochs: plot_hypnogram(), plot_sleep_spiral()

Examples

plot_timeseries(example_epochs, variable="signal_quality_mean")

Description

Plot session time series data for a given variable

Usage

plot_timeseries_sessions(
  sessions,
  variable,
  color_by = "default",
  exclude_zero = FALSE
)

Arguments

Details

This function uses columns:

• night

Value

A ggplot object

See Also

plot_timeseries() to plot epoch data.

Other plot sessions: plot_sleep_bubbles(), plot_sleep_clock()

Examples

plot_timeseries_sessions(example_sessions, variable="time_at_midsleep")

Description

Read EDF Epochs

Usage

read_edf_epochs(file)

Arguments

Details

The function reads the signals of the EDF file to extract epoch information. It must contain a column for timestamps and a column for sleep stage annotations.

Value

A dataframe containing the epoch data extracted from the EDF file signals

See Also

Other data loading: load_batch(), load_epochs(), load_sessions(), read_edf_sessions()

Examples

edf <- system.file("extdata", "mini.edf", package = "nocturn")
read_edf_epochs(edf)

Description

Read EDF Sessions

Usage

read_edf_sessions(file)

Arguments

Details

The function reads the header of the EDF file to extract session information such as start time, duration, and calculates end time and midsleep time.

Value

A dataframe containing the session data extracted from the EDF file header

See Also

Other data loading: load_batch(), load_epochs(), load_sessions(), read_edf_epochs()

Examples

edf <- system.file("extdata", "mini.edf", package = "nocturn")
read_edf_sessions(edf)

Description

Remove sessions with no sleep

Usage

remove_sessions_no_sleep(sessions, return_mask = FALSE)

Arguments

Details

This function uses columns:

• sleep_period

Value

The sessions dataframe with only the sessions that have a sleep period greater than 0, or a logical vector if return_mask is TRUE

See Also

Other filtering: filter_by_age_range(), filter_by_night_range(), filter_by_sex(), filter_epochs_from_sessions(), select_devices(), select_subjects(), set_min_sleep_period(), set_min_time_in_bed(), set_session_sleep_onset_range(), set_session_start_time_range()

Examples

filtered_sessions <- remove_sessions_no_sleep(example_sessions)

Description

This function calculates the standard deviation of a vector of time strings, accounting for the circular nature of time (e.g., 23:59 is close to 00:00).

Usage

sd_time(time_vector, unit = "hour")

Arguments

Value

A numeric value representing the standard deviation in the specified unit.

See Also

Other time processing: group_epochs_by_night(), group_sessions_by_night(), max_time(), mean_time(), min_time(), parse_date(), parse_time(), shift_times_by_12h(), time_diff(), time_to_hours(), update_date()

Examples

sd_time(c("23:59", "00:01"))

Description

Select devices by ID

Usage

select_devices(sessions, device_ids, return_mask = FALSE)

Arguments

Details

This function uses columns:

• device_id

Value

The sessions dataframe with only the sessions recorded by the specified devices, or a logical vector if return_mask is TRUE

See Also

select_subjects() to select sessions by subject ID.

Other filtering: filter_by_age_range(), filter_by_night_range(), filter_by_sex(), filter_epochs_from_sessions(), remove_sessions_no_sleep(), select_subjects(), set_min_sleep_period(), set_min_time_in_bed(), set_session_sleep_onset_range(), set_session_start_time_range()

Examples

filtered_sessions <- select_devices(example_sessions, c("VTGVSRTHCA"))

Description

Select subjects by ID

Usage

select_subjects(sessions, subject_ids, return_mask = FALSE)

Arguments

Details

This function uses columns:

Value

The sessions dataframe with only the sessions that belong to the specified subjects, or a logical vector if return_mask is TRUE

See Also

select_devices() to select sessions by device ID.

Other filtering: filter_by_age_range(), filter_by_night_range(), filter_by_sex(), filter_epochs_from_sessions(), remove_sessions_no_sleep(), select_devices(), set_min_sleep_period(), set_min_time_in_bed(), set_session_sleep_onset_range(), set_session_start_time_range()

Examples

filtered_sessions <- select_subjects(example_sessions, c("sub_01JNDH3Z5NP0PSV82NFBGPV31X"))

Description

This function updates the "col" attribute for a dataframe, overwriting existing column names with the ones provided.

Usage

set_colnames(df, col)

Arguments

Value

The data frame with updated "col" attribute

See Also

Other internal: check_suggests(), get_col(), get_colnames(), get_epoch_colnames(), get_session_colnames(), get_time_per_day(), is_iso8601_datetime(), set_data_type()

Examples

sessions <- set_colnames(
 example_sessions,
 list(night = "calendar_date", sleep_period = "duration_sleep")
)

Description

This function sets the "type" attribute for a data frame to indicate whether it contains session or epoch data.

Usage

set_data_type(data, type)

Arguments

Value

The data frame with updated "type" attribute

See Also

Other internal: check_suggests(), get_col(), get_colnames(), get_epoch_colnames(), get_session_colnames(), get_time_per_day(), is_iso8601_datetime(), set_colnames()

Examples

set_data_type(example_sessions, "sessions")

Description

Set minimum sleep period

Usage

set_min_sleep_period(sessions, min_sleep_period, return_mask = FALSE)

Arguments

Details

This function uses columns:

• sleep_period

Value

The sessions dataframe with only the sessions that meet the minimum sleep period requirement, or a logical vector if return_mask is TRUE

See Also

Other filtering: filter_by_age_range(), filter_by_night_range(), filter_by_sex(), filter_epochs_from_sessions(), remove_sessions_no_sleep(), select_devices(), select_subjects(), set_min_time_in_bed(), set_session_sleep_onset_range(), set_session_start_time_range()

Examples

filtered_sessions <- set_min_sleep_period(example_sessions, 2)

Description

Set minimum time in bed

Usage

set_min_time_in_bed(sessions, min_time_in_bed, return_mask = FALSE)

Arguments

Details

This function uses columns:

• time_in_bed

Value

The sessions dataframe with only the sessions that meet the minimum time in bed requirement, or a logical vector if return_mask is TRUE

See Also

Other filtering: filter_by_age_range(), filter_by_night_range(), filter_by_sex(), filter_epochs_from_sessions(), remove_sessions_no_sleep(), select_devices(), select_subjects(), set_min_sleep_period(), set_session_sleep_onset_range(), set_session_start_time_range()

Examples

filtered_sessions <- set_min_time_in_bed(example_sessions, 2)

Description

Set sleep onset time range

Usage

set_session_sleep_onset_range(
  sessions,
  from_time,
  to_time,
  return_mask = FALSE
)

Arguments

Details

This function uses columns:

• time_at_sleep_onset

Value

The sessions dataframe with only the sessions where sleep started within the specified time range, or a logical vector if return_mask is TRUE

See Also

set_session_start_time_range() to filter sessions based on start time.

Other filtering: filter_by_age_range(), filter_by_night_range(), filter_by_sex(), filter_epochs_from_sessions(), remove_sessions_no_sleep(), select_devices(), select_subjects(), set_min_sleep_period(), set_min_time_in_bed(), set_session_start_time_range()

Examples

filtered_sessions <- set_session_sleep_onset_range(example_sessions, "22:00", "06:00")

Description

Set session start time range

Usage

set_session_start_time_range(sessions, from_time, to_time, return_mask = FALSE)

Arguments

Details

This function uses columns:

• session_start

Value

The sessions dataframe with only the sessions that started within the specified time range, or a logical vector if return_mask is TRUE

See Also

set_session_sleep_onset_range() to filter sessions based on sleep onset time.

Other filtering: filter_by_age_range(), filter_by_night_range(), filter_by_sex(), filter_epochs_from_sessions(), remove_sessions_no_sleep(), select_devices(), select_subjects(), set_min_sleep_period(), set_min_time_in_bed(), set_session_sleep_onset_range()

Examples

filtered_sessions <- set_session_start_time_range(example_sessions, "22:00", "06:00")

Description

This function shifts times so that the day starts at 12 PM. This is useful for plotting night data

Usage

shift_times_by_12h(times)

Arguments

Value

A vector of times in POSIXct format (or numerical if numerical provided as input) shifted to start at 12 PM

See Also

Other time processing: group_epochs_by_night(), group_sessions_by_night(), max_time(), mean_time(), min_time(), parse_date(), parse_time(), sd_time(), time_diff(), time_to_hours(), update_date()

Examples

# Shift a vector of times in HH:MM format
shift_times_by_12h(c("02:30", "16:00"))
#> "14:30" "04:00"

# Shift times in YYYY-MM-DD HH:MM:SS format
shift_times_by_12h(c("2025-04-08 23:00:00", "2025-04-09 01:00:00"))
#> "2025-04-08 11:00" "2025-04-09 13:00"

# Shift sessions start times to start at 12 PM
shifted_times <- shift_times_by_12h(example_sessions$session_start)

# Use dplyr::mutate to dicrectly add the shifted times to a dataframe
epochs <- example_epochs |>
  dplyr::mutate(shifted_time = shift_times_by_12h(timestamp))

Description

The Sleep Regularity Index (SRI) is a measure of the regularity of sleep patterns. It is calculated as the percentage of epochs where the sleep state remains the same after 24 hours.

Usage

sleep_regularity_index(epochs)

Arguments

Details

This function uses columns:

• timestamp

• is_asleep

Value

The Sleep Regularity Index (SRI) value

See Also

Other sleep metrics: chronotype(), composite_phase_deviation(), interdaily_stability(), social_jet_lag()

Examples

sleep_regularity_index(example_epochs)

Description

This function generates a sleep report in PDF format using an SVG template. It is designed to work with Somnofy data. Other data types may be supported in the future.

Usage

sleep_report(sessions, title = "", output_file = "Sleep_report.pdf")

Arguments

Details

This function uses columns:

• night

• time_at_sleep_onset

• time_at_wakeup

• time_at_midsleep

• sleep_onset_latency

• sleep_period

• time_in_bed

Value

No return value. Called for side-effects

Examples

sleep_report(example_sessions)

Description

Plot boxplots for sleep onset, midsleep, and wakeup times

Usage

sleeptimes_boxplot(sessions, circular = FALSE)

Arguments

Details

This function uses columns:

• time_at_sleep_onset

• time_at_wakeup

• time_at_midsleep

Value

A ggplot object with three horizontal boxplots (onset, midsleep, wakeup)

Examples

sleeptimes_boxplot(example_sessions)

Description

Plot density curves for sleep onset, midsleep, and wakeup times with a dashed line showing the median

Usage

sleeptimes_density(sessions, adjust = 1, circular = FALSE)

Arguments

Details

This function uses columns:

• time_at_sleep_onset

• time_at_wakeup

• time_at_midsleep

Value

A ggplot object with three overlaid density curves (sleep onset, midsleep, wakeup)

Examples

sleeptimes_density(example_sessions)

Description

Plot histograms for sleep onset, midsleep, and wakeup times

Usage

sleeptimes_histogram(sessions, binwidth = 0.25, circular = FALSE)

Arguments

Details

This function uses columns:

• time_at_sleep_onset

• time_at_wakeup

• time_at_midsleep

Value

A ggplot object with three overlaid histograms (sleep onset, midsleep, wakeup)

Examples

sleeptimes_histogram(example_sessions)

Description

This function calculates the Social Jet Lag (SJL) metric as the difference in mid-sleep times between workdays and free days.

Usage

social_jet_lag(sessions)

Arguments

Details

This function uses columns:

• time_at_midsleep

• is_workday

Value

The Social Jet Lag (SJL) value in hours

See Also

Other sleep metrics: chronotype(), composite_phase_deviation(), interdaily_stability(), sleep_regularity_index()

Examples

social_jet_lag(example_sessions)

Description

This function returns the time from t1 to t2, always moving forward on the clock. For example, from 07:00 to 22:00 is 15 hours, from 22:00 to 07:00 is 9 hours.

Usage

time_diff(t1, t2, unit = "hour")

Arguments

Value

The forward difference in the specified unit (numeric, always positive, 0 <= x < 24)

See Also

Other time processing: group_epochs_by_night(), group_sessions_by_night(), max_time(), mean_time(), min_time(), parse_date(), parse_time(), sd_time(), shift_times_by_12h(), time_to_hours(), update_date()

Examples

time_diff("07:00", "22:00") # 15
time_diff("22:00", "07:00") # 9
time_diff("07:00", "22:00", unit = "minute") # 540

Description

This function converts a vector of time strings or POSIXct objects to numeric hours.

Usage

time_to_hours(time_vector)

Arguments

Details

See parse_time() for supported time formats.

Value

A numeric vector representing the time in hours

See Also

Other time processing: group_epochs_by_night(), group_sessions_by_night(), max_time(), mean_time(), min_time(), parse_date(), parse_time(), sd_time(), shift_times_by_12h(), time_diff(), update_date()

Examples

time_to_hours(c("2026-10-12T14:20:09"))

Description

This function updates the date component of a POSIXct time object while preserving the time component.

Usage

update_date(time, date)

Arguments

Value

A POSIXct time object with the updated date

See Also

Other time processing: group_epochs_by_night(), group_sessions_by_night(), max_time(), mean_time(), min_time(), parse_date(), parse_time(), sd_time(), shift_times_by_12h(), time_diff(), time_to_hours()

Examples

update_date("2026-01-01T14:09:09", "0000-01-01")