Filtering and Compliance - chronopsychiatry/AmbientViewer GitHub Wiki

Data filtering

The filtering panel allows to set the following filters:

  • Restricting the date range covered by the data (defaults to all available data)
  • Removing sessions where the sleep onset is outside of a certain time window
    • e.g. adjust the slider to [20, 6] to only keep sessions where sleep onset is between 8pm and 6am
  • Removing sessions where the subject has spent less than a certain time in bed
    • e.g. adjust the slider to 2h to remove sessions where the subject spent less than 2 hours in bed

Whenever a filter is changed, all data tables and figures will be automatically updated. Moreover, filtering sessions will automatically remove epoch data associated with these sessions.

The filtered data can be downloaded in .csv format by clicking the "Download Sessions" and "Download Epochs" buttons in the Data Export section.

Ambient Viewer GUI with Data Export section highlighted

Filtering on the command line

Remove sessions with no sleep

remove_sessions_no_sleep removes all sessions where sleep_period is 0 (note that in the GUI, this is always applied).

sessions <- remove_sessions_no_sleep(sessions)

Filter sessions according to time spent in bed

sessions <- set_min_time_in_bed(sessions, min_time_in_bed = 2)

Inputs:

  • sessions: the sessions dataframe
  • min_time_in_bed: the minimum time in bed (in hours) for the session to be kept

Filter sessions according to their start time

sessions <- set_session_start_time_range(sessions, from_time = "20:00", to_time = "06:00")

Inputs:

  • sessions: the sessions dataframe
  • from_time: lower bound for the time range (format HH:MM)
  • to_time: higher bound for the time range (format HH:MM)

Filter sessions according to the time at sleep onset

sessions <- set_session_sleep_onset_range(sessions, from_time = "20:00", to_time = "06:00")

Inputs:

  • sessions: the sessions dataframe
  • from_time: lower bound for the time range (format HH:MM)
  • to_time: higher bound for the time range (format HH:MM)

Select specific subjects

sessions <- select_subjects(sessions, subject_ids = c("sub_01JNDH3Z5NP0PSV82NFBGPV31X", "sub_04TGSD8Q5NP0PSV82BHDSOO65Q"))

Inputs:

  • sessions: the sessions dataframe
  • subject_ids: either a single subject ID (e.g. "sub_01JNDH3Z5NP0PSV82NFBGPV31X") or a list of subject IDs

Select specific devices

sessions <- select_devices(sessions, device_ids = c("VTGVSRTHCA", "VTUDPMSJFT"))

Inputs:

  • sessions: the sessions dataframe
  • device_ids: either a single device ID (e.g. "VTGVSRTHCA") or a list of device IDs

Filter Epoch data

Epoch data can be filtered to remove all sessions that are not present in the Sessions dataframe, using the filter_epochs_from_sessions function.

epochs <- filter_epochs_from_sessions(epochs, sessions)

Compliance tab

The goal of the compliance section is to check if there are "duplicate sessions" in the data, i.e. multiple sessions on the same night. If there are duplicate sessions with the current filtering parameters, the "Compliance" tab will be displayed in red. Clicking on the tab displays all duplicated sessions.

Compliance table with no filters applied on the data

The Compliance table contains the following columns:

  • id: the session ID
  • night: the night of the session. Nights are defined as ranging from 12pm to 12pm on the next day
    • The 4th March 2025 at 12:30 will be classed as "night of the 2025-03-04"
    • The 5th March 2025 at 11:50 will be classed as "night of the 2025-03-04"
  • start_time: the starting time of the sessions
  • sleep_onset: the time at sleep onset
  • wakeup_time: the time at wakeup
  • end_time: the end time of the session
  • session_duration_h: the duration of the session, in hours
  • time_in_bed_h: the time spent in bed during the session, in hours

Non-complying sessions can be downloaded in .csv format by clicking on the "Download" button under the table (this will download the complete session information for non-complying sessions with all columns included).

The Compliance table will be automatically updated when filters are applied. Once all duplicates have been removed, the tab title will no longer be red, and the table will be replaced by the mention "There are no duplicate sessions on the same night".

Compliance tab with no duplicate sessions

Note that the compliance table is for information only. The presence of duplicate sessions will not prevent figure generation or data export.

Displaying the compliance table on the command line
compliance_table <- get_non_complying_sessions(sessions)

Filtering tab

The filtering tab lets users keep track of the sessions removed by the filtering process.

Filtering tab with 3 sessions removed

Note: removed sessions do not include sessions outside the set "date range".

All removed sessions can be downloaded in .csv format using the "Download" button under the table (this will download the complete sessions information for removed sessions with all columns included).

Displaying the filtering table on the command line
filtering_table <- get_removed_sessions(sessions, filtered_sessions)
⚠️ **GitHub.com Fallback** ⚠️