Getting started - chronopsychiatry/AmbientViewer GitHub Wiki

Loading data

Data can be loaded into AmbientViewer using the "Data Input" section:

Ambient Viewer GUI with Data Input section highlighted

To load the data, select the Sessions and Epochs csv files.

Note: some tables and graphs can be generated by loading only the Session data (compliance table, sleep clock,...) but it is necessary to load both Session and Epoch data to show the Epoch-based graphs such as the sleep spiral.

Data produced by the GGIR package can also be loaded; see instructions on the Using GGIR data page.

Loading data on the command line

Sessions

sessions <- load_sessions(sessions_file)

Inputs:

  • sessions_file: the path to the sessions .csv file

Outputs:

  • A data.frame containing the session data

Details:

load_sessions reads the sessions csv file to a dataframe, and adds a night column to group the data. 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"

Epochs

epochs <- load_epochs(epochs_file)

Inputs:

  • epochs_file: the path to the epochs .csv file

Outputs:

  • A data.frame containing the epoch data

A night column is added to the dataframe, similar to Sessions.

Summary tables

Once data has been loaded, a summary table will be displayed at the top of the app, showing the subject and device IDs, number of sessions recorded, average times at sleep onset and wakeup, and average duration of the sessions (in hours).

Screen capture of the summary table in Ambient Viewer GUI

Displaying the summary tables on the command line 
sessions_summary <- get_sessions_summary(sessions)
epochs_summary <- get_epochs_summary(epochs)

Example data

The Ambient Viewer package includes example session and epoch data. Once the library is loaded, they can be accessed via the example_sessions and example_epochs variables.

sessions_summary <- get_sessions_summary(example_sessions)
epochs_summary <- get_epochs_summary(example_epochs)

If you want to use the example data in the Ambient Viewer app, you will need to save them as csv first. This can be done in R:

write.csv(example_sessions, "path/to/save/sessions.csv", row.names = FALSE)
write.csv(example_epochs, "path/to/save/epochs.csv", row.names = FALSE)
⚠️ **GitHub.com Fallback** ⚠️