CSV file documentation - Sleep as Android

Documentation
1

The sleep-export.csv file is a backup file that contains data from sleep records. Each record is saved onto two lines (manually inserted sleep records) or three lines (sleep records recorded by sleep tracking).

This is a companion discussion topic for the original entry at https://docs.sleep.urbandroid.org//devs/csv.html
1 Like
2

This should really mention the ‘Event’ fields, which seem to match the storage API Event Labels, with the exception that there are both ‘DHA’ and ‘DEVICE’ events which are not mentioned under EVENT Labels at all.

Also, it would be useful to have a better explanation of some of the fields, like how exactly the ‘Geo’ field is generated.

1 Like
3

I am also facing the same problem as zeph.
Could you please provide the meaning of the events? I’m seeing DHA, DEVICE, LUX which are not there in the storage API. Further, there is a floating point after the timestamp for some of these events. What are those?
And there is a list of floating points with the frame rate. Are those actigraphy values?

1 Like
4

Questions on values present in the sleep-export.csv file:

  1. Movement: accelerometric (actigraphic) - what is the range of values? Is each actigraphic value directly based (simply proportional to) on the raw sensor data, or is it the result of SaA algorithms calculating based on the raw sensor data?
  2. What inputs influences the calculated values of Deep sleep, Light sleep, ~REM, Awake? From the urbandroid.org Blog posts it appears to be magnitude and concentration of movement.
  3. How are the value of Cycles and DeepSleep calculated?
    I assume it is (at least) influenced by movement data I ask about above.
  4. If heart rate and O2 are recorded do those affect the sleep levels, DeepSleep and Cycles values?
  5. What sleep-export.csv values trigger the presence of the “watch” (wearables) symbol? Found it by re-inspecting the file: #watch in the “Comment” field.

I’m continuing work on importing Wellue O2Ring sensor data as a modified sleep-export.csv file.

I want to:

  1. Translate the series of accelerometric (actigraphic) sensor readings recorded every 4 seconds by the O2Ring (magnitude seems to be around 150 full scale) in O2Ring export to the same range and interval expected by SaA during import of sleep-export.csv file.
    If I understand correctly the SaA Wearables API expects the data to be in m/s2 and be sent in batches every 120 seconds containing samples spaced 10 seconds apart). Of course the sleep-export.csv file is not laden with actigraphic samples every 10 seconds, so aggregation must be happening internally to SaA.

  2. Calculate using same method as SaA uses internally with live sensor data:
    a. Cycles value (a count I assume)
    b. DeepSleep value (percentage as a decimal I assume)

Instead of calculating and injecting the Cycles and DeepSleep values myself, can a special cycles value (perhaps a value of -2?) be introduced as a new feature that tells SaA to use its algorithms to generate the Cycles and DeepSleep values based on the actigraph readings included in the modified sleep-export.csv file?

1 Like
5

Hi!

I notice that the page for converting the CSV file to JSON format has been out of commission for a while, so it might help to note that I have a webpage for people to do this if they wish to use it: Reference Desk Projects.

Alternatively, the code I wrote to do this is also publicly available under the GPL-3.0 licence, so feel free to use and expand upon that if it suits: Sleep Parser. :slight_smile:

3 Likes
6

Also looking to understand “DHA”. I’m assuming “LUX” is light level.

DHA, on the other hand, appears often with values in the realm of 1x10 to -40…so super small. Seems like an error more than anything.

Hints?

How often? Here are the percentages from years of data:
Event Type Frequencies as Percentage of All Events:
DHA 43.218392
LIGHT_END 9.773859
LIGHT_START 9.773859
DEEP_START 7.545747
DEEP_END 7.545747
REM_START 2.957324
REM_END 2.957324
BROKEN_END 2.760822
BROKEN_START 2.760822
TRACKING_PAUSED 2.075676
TRACKING_RESUMED 2.070454
LUX 1.183909
TRACKING_STOPPED_BY_USER 0.855209
ALARM_LATEST 0.793842
ALARM_EARLIEST 0.793842
ALARM_STARTED 0.741942
AWAKE_START 0.569595
AWAKE_END 0.567963
ALARM_SNOOZE 0.552948
DEVICE 0.309442
ALARM_DISMISS 0.186057
LOW_BATTERY 0.004896
NO_AWAKE 0.000326