The Cicada Settings Files

Each time Cicada starts, it loads the settings file in ./settings/CicadaSettings.json, which specifies default values. It is stored in JavaScript Object Notation (JSON), which may sound quite something, but is actually quite easy read and write for both humans and computers. Basically, is is a collection of ‘name’ and ‘value’ pairs.

Default Import Settings

Some Raw Data that can be imported into Cicada require some guidance on how Cicada should read the file that contains the Raw Data. For instance, a sleep diary can have many different formats, and Cicada is not smart enough to know all of them by heart. The individual import settings are stored in separate JSON settings files (see below). The location of the file that should be used by default is stored in the main Cicada Settings file in an ‘object’ called ‘importSettings’.

"importSettings": {}

The location of the default import settings files are stored as ‘name’ and ‘value’ pairs. In the example below, Cicada will use the import settings in mySleepDiary.json to import a sleep diary.

"importSettings": {
    "sleepDiary": "./settings/mySleepDiary.json"
}

Note

Currently, Cicada can only import Raw Data from ActivInsights GeneActiv .bin files, custom-build spectrometer output in .csv files, and sleep diaries in any tabular text file (.txt, .csv) or spreadsheet (.xls, .xlsx). From this list, Cicada only needs guidance for importing sleep diaries. The list of import settings files will grow as we develop more import functions.

Default Display Settings

The way Cicada displays the accelerometry Metrics can be changed within the Settings Panel, but instead of changing these settings each time, you can specify their default values in the ‘object’ called ‘display’.

In the example below,

  • the actogram start and end clock are set to 15:00,

  • the actogram with is a single day,

  • the number of panels shown in one view without scrolling is 7,

  • the relative height (row-span) of the acceleration Metric axes is 2,

  • the Accleration data is not shown on a logarithmic scale,

  • the range is 0 to 1,

  • the default view is euclNorm.

  • In case you select Counts as the metric to display,

    • its range is 0 to 1000 and is not shown on a logarithmic scale.

  • In case you select euclNorm as the metric to display,

    • its range is 0 to 1 g and is not shown on a logarithmic scale.

  • In case you select angle as the metric to display,

    • its range is -120 to 120 degrees and is not shown on a logarithmic scale.

"display": {
        "actogramStartClock": "15:00",
        "actogramEndClock": "15:00",
        "actogramWidth": "single",
        "actogramLength": 7,
        "acceleration": {
            "rowspan": 2,
            "log": 0,
            "range": [0, 1],
            "view": "euclNorm",
            "counts": {
                "log": 0,
                "range": [0, 1000]
            },
            "euclNorm": {
                "log": 0,
                "range": [0, 1]
            },
            "angle": {
                "log": 0,
                "range": [-120, 120]
            }
        }
    }

Default Epoch Length

The only default value that is currently specified in the Cicada Settings file is the Epoch length. In this example Cicada will use a 5 second Epoch length.

"analysis": {
        "epochLength": 5
}

But here is more you say?

Don’t worry about the default XTickSize. It’s just one of those quirks.

Sleep Diary Import Settings Files

Note

This section outlines in detail how the sleep diary import settings are defined. However, when you import a sleep diary in Cicada, you can load, edit and save the import settings to .json files automatically.

Cicada can import 7 predefined variables from a sleep diary,

  1. date [datestring]

  2. lightsOut [datestring]

  3. sleepLatency in minutes [integer]

  4. awakenings [integer]

  5. waso in minutes [integer]

  6. finAwake [datestring]

  7. lightsOn [datestring]

Note

  • The Sleep Window Events are defined as lightsOut to lightsOn.

  • The Sleep Period Events are defined as lightsOut + sleepLatency to finAwake.

  • The WASO Events are defined by the combination of awakenings (N) and waso, such that there are N WASO events, each with a duration of waso / awakenings minutes.

As described above, the different import settings that guide Cicada in the way Raw Data files should be imported are stored in separate JSON files. The import settings file that Cicada should use by default is stored in the Cicada Settings file. This way, the user can define multiple import settings files, for instance for the various types of sleep diaries the research group may use.

Let’s assume we have a tabular Raw Data file that contains the following column headers and data formatting,

  1. Date, specified as ‘dd/mm/yy’, e.g. 16/05/20

  2. Notes, specified as ‘text’, e.g. Watched TV in bed

  3. Bed time, specified as ‘HH:MM’ 24h clock time, e.g. 22:30

  4. Eyes closed, specified as ‘HH:MM’ 24h clock time, e.g. 22:45

  5. Sleep onset latency, specified in minutes, e.g. 15

  6. Final awakening, specified as ‘HH:MM’ 24h clock time, e.g. 7:30

  7. Eyes open, specified as ‘HH:MM’ 24h clock time, e.g. 7:45

  8. Rise time, specified as ‘HH:MM’ 24h clock time, e.g. 8:00

  9. Sleep quality, specified as ordinal values between 1-5, e.g. 3

The sleep diary import settings file must specify how the Raw Data maps to the expected 7 predefined variables. In the example below, you can see how the format in which the Raw Data is stored is specified in "format": {}, and how the available columns in the Raw Data is mapped to the 7 variables in "idx": {}. Here you can see that the researcher decided to use ‘bed time’ and ‘rise time’ to define the Sleep Windows (lightsOut and lightsOn are column 3 and 8 respectively). Also, you can see that the Raw Data did not contain any information about the number of awakenings or WASO (their value is null).

{
    "format": {
        "date": "dd/mm/yy",
        "lightsOut": "HH:MM",
        "finAwake": "HH:MM",
        "lightsOn": "HH:MM"
    },
    "idx": {
        "date": 1,
        "lightsOut": 3,
        "sleepLatency": 5,
        "awakenings": null,
        "waso": null,
        "finAwake": 6,
        "lightsOn": 8
    }
}

Warning

The date, lightsOut, and lightsOn variables are required, i.e. you cannot import a sleep diary if this information is not available.