Adjusting column names - chronopsychiatry/AmbientViewer GitHub Wiki

Ambient Viewer has pre-set column names for Somnofy data. This includes data generated on v1 of the VitalThings API (~2024) and on v2 of the API (from 2025 onwards). In the event that your data has column names that don't match the pre-sets, you can either:

• Rename columns in the original .csv file
• Manually set column names, in the app or when calling Ambient Viewer functions

See below for detailed instructions.

Ambient Viewer app

Column names can be changed in the app after loading a csv file, using the "Set Session Columns" or "Set Epochs Columns" buttons.

This will open a menu with drop-down menus for each column name. If a column name wasn't found in the data, it will show as "-".

Once you have made changes, scroll down and click on "Save". Alternatively, click on "Cancel" to discard changes, or "Reset" to come back to the original values.

Follow the same protocol to change the Epochs column names.

Ambient Viewer functions

All Ambient Viewer functions that process Session or Epoch data accept a col_names argument (optional). col_names must be a list of column names that will be used by the function. To know which column names to define, you can look at the package documentation, or the function tooltip (by hovering on the function name in VScode or RStudio).

For example, the function set_min_time_in_bed uses the time_in_bed column. If in the data, this column is called time_in_bed_hours, you can call the function like so:

sessions <- set_min_time_in_bed(sessions, col_names = list(time_in_bed = "time_in_bed_hours"))

For larger scripts, and if several column names differ from the default values, a unique list can be defined at the beginning of the script and used for all functions:

# Change the strings on the right-side to your actual column names
col_names = list(
  id = "id",
  subject_id = "subject_id",
  device_id = "device_serial_number",
  session_start = "session_start",
  session_end = "session_end",
  time_at_sleep_onset = "time_at_sleep_onset",
  time_at_wakeup = "time_at_wakeup",
  sleep_period = "sleep_period",
  time_in_bed = "time_in_bed",
  is_workday = "is_workday",
  night = "night"
)

sessions <- load_sessions("path/to/sessions.csv") |>
    remove_sessions_no_sleep(col_names = col_names) |>
    set_min_time_in_bed(col_names = col_names) |>
    plot_sleep_clock(col_names = col_names)

If your data always has the same column names, please open an issue to request it being added to Ambient Viewer's pre-sets.