Visit The University of Sydney, Faculty Of Science Web-Site
Visit Physics of Circadian Rhythms and Sleep Web-Site

User Guide: Alertness Models Interface

This is the User Guide for accessing the sleep-wake and alertness models provided at https://www.alertnessapi.com. These mathematical models of human sleep-wake and alertness dynamics can be used to generate predictions of sleep and alertness as well as sleep recommendations. The models are evaluated in the context of a schedule (time-periods of forced-wake) and environmental conditions (such as lighting). As the user, you provide that context in the form of json formatted text. This json file also contains fields for setting other properties of the model’s evaluation and for specifying what you would like returned from the interface.

There are two interfaces available for accessing the predictions and recommendations:

  1. a web-browser interface for manually uploading files and retrieving results; and
  2. an application programming interface (API, RESTish) for automated access.

This User Guide describes the background information necessary to make use of either of these interfaces.

For specific information on using the interfaces, see either the:

Background

To effectively use https://www.alertnessapi.com it is necessary to have an, at least, general understanding of the mathematical models behind the interface. So, if you are not already familiar with these models, you should start with an overview of the components, concepts and functionality of our model for sleep-wake and alertness dynamics.

Getting Started

  1. Get an Account: currently a request must be emailed to the people listed in the Contacts section at the bottom of this document.
  2. Write an Input File: the input file specifies the context in which the model is evaluated and the output that should be returned, see the Input section below for details.
  3. Submit Your Input File: You can use either the REST or Browser interface.
    • REST: the contents of your input file should be POSTed, as the request body, to the /v3/query endpoint.
    • Browser: Upload your file using the form at /v3/jsonupload.
  4. Retrieve Results:

Authentication

All access requires two request parameters for authentication: userName and password. For upload via the web form, and download by following emailed links, fields are provided on the web page for you to enter these values. For every other request (eg REST) they must be included as query parameters, the equivalent of:

?userName=<yourAPIusername>&password=<yourAPIpassword>

in addition to any other required request parameters. Where <yourAPIusername> and <yourAPIpassword> should be substituted with your actual credentials.

If you do not already have an account, send a request to the people listed in the Contacts section at the bottom of this document.

Input

Whether uploading a file using your web browser or submitting to the REST interface the context for which you want to evaluate a sleep and alertness model is described using json formatted text.

The input for a single query is a json object, with braces {} used to mark the start and end of an object:

{
  ...
}

where, in the above, ... indicates content goes here.

You can also provide multiple queries within a single json file by using a json array, with brackets [] used to mark the start and end of an array. That is, a file containing multiple queries must have the format:

[
  {...},
  {...},
  {...}
]

where each {...} is an individual query. Note that there is an effective limit on the number of queries per file/batch as the uploaded file is limited to a few MB in size.

To learn about the content/fields of individual queries, see the:

If you are familiar, and comfortable, with json then the definitive description of the structure of an input json object is provided by json-schema definitions that can be retrieved from the /v3/schema endpoint.

Validation

When submitting a query to https://www.alertnessapi.com, whether uploading a file via a web-browser or POSTing to the REST endpoint, the query undergoes three stages of validation:

  1. Must be either a json object or json array;
  2. Each json object must conform to the json-schema definition of the inputs;
  3. Values provided as input must be self-consistent, for example: two periods of forced-wake can not overlap in time; date-times in a single array must be provided in ascending order; date-times for the start_time of a period of forced_wake must be earlier than their associated end_time.

Models

Sydney Group’s

postnova_2016 – Sydney-CRC model of alertness validated for sleep deprivation, forced desynchrony, shiftwork (laboratory and real world), Alertness output – visual PVT lapses (per 10 min) (Postnova et al. 2016; Postnova et al. 2018).

sydney_crc_2017 – Sydney-CRC model of alertness incorporating chronic sleep restriction (unpublished). Alertness output – visual PVT lapses (per 10 min). Differences in alertness measures will be observed during chronic sleep restriction protocols and during recovery from sleep deprivation.

Other available models

phillips_2010 – Pre-CRC version of the arousal dynamics (Fulcher et al. 2010 ). Alertness output – wake effort.

abeysuriya_2018 – Abeysuriya RG, etal, 2018

Default ambient lighting for all of the Sydney group’s models is 250 photopic lux 08:00-20:00, 40 lux 20:00-08:00, and 0 lux during sleep. Commute light is equal to ambient lighting during commute hours.

Published models from other groups

mccauley_2013 – model of chronic sleep restriction by Mccauley etal. Reproduces PVT lapses dynamics during sleep restriction protocols but does not account for the effects of light on the circadian phase (McCauley et al. 2013). Alertness output – number of visual PVT lapses (per 10 min).

rajdev_2013 – unified model of sleep deprivation and chronic sleep restriction by Rajdev et al. Reproduces the dynamics of PVT reaction time during sleep restriction protocols but does not account for the effects of light on the circadian phase (Rajdev et al. 2013). Alertness output – number of visual PVT lapses (per 10 min).

ingre_2014 – model of chronic sleep restriction based on the 3-process model. Reproduces the dynamics of subjective sleepiness measures on sleep restriction protocols but does not account for the effects of light on the circadian phase (Ingre et al. 2014). Alertness output – KSS.

phillips_2017 – adenosine-based model of chronic sleep restriction by Phillips et al. reproduces the dynamics of visual PVT lapses on a variety of protocols. Can be connected to a dynamics circadian oscillator but in the current version uses fixed sinusoid circadian as in published papers (Phillips et al. 2017). Alertness output – visual PVT lapses (per 10 min).

johnson_2004 – model of chronic sleep restriction which reproduces the effects of the homeostatic component on performance but not the circadian one. Alertness output – percentage of performance. Its use is not recommended as the model does not have essential features (circadian drive) and uses a measure that is not validated experimentally (Johnson et al. 2004).

NOTES:

  1. All published models from other groups (ie, not the Sydney group) require sleep times as an input and cannot be processed without them. The model by Phillips et al., has an update to predict sleep times and be connected with the dynamics circadian oscillator but this has not been incorporated in the current version. All models are added as published.
  2. When sleep times are provided as an input to the Sydney group’s models they are treated as an “allowed sleep time” so sleep is not forced during these hours but will appear if there is a sufficient physiological need for sleep. Sleep would not be allowed outside of these hours.

Endpoints

Endpoints are the specific addresses for accessing features/resources of the website. The web address is https://www.alertnessapi.com, so, combined with the need to authenticate, the endpoints listed below become:

https://www.alertnessapi.com/END-POINT/?userName=<yourAPIusername>&password=<yourAPIpassword>

for example, a main json-schema definition for inputs can be accessed at:

https://www.alertnessapi.com/v3/status/{query_id}/?userName=<yourAPIusername>&password=<yourAPIpassword>

REST

The REST endpoints constitute our API (application programming interface), these endpoints are intended to be accessed by scripts or programs. They return the resource you have requested, including related links, as json formatted text. For details on using the REST interface see the Alertness API REST Interface Guide.

A complete list of available RESTish endpoints and associated path and request parameters:

  • /v3/schema – GET: a list of the json-schema definitions of the input
  • /v3/schema/{schema_name} – GET: a specific json-schema definition;
  • /v3/query – POST: a new query for the sleep and alertness model;
  • /v3/query/{query_id} – GET: an individual, previously POSTed, query;
  • /v3/query/?upload={upload_id} – GET: all queries from an upload;
  • /v3/query/?status=RECEIVED – GET: all of a user’s queries with status RECIEVED;
  • /v3/query/?status=QUEUED – GET: all of a user’s queries with status QUEUED.
  • /v3/query/?status=RUNNING – GET: all of a user’s queries with status RUNNING.
  • /v3/query/?status=COMPLETE – GET: all of a user’s queries with status COMPLETE.
  • /v3/query/?status=FAILED – GET: all of a user’s queries with status FAILED.
  • /v3/status – GET: a json-array with status information for all of a user’s queries;
  • /v3/status/{query_id} – GET: a json-object with status information for a query;
  • /v3/status/?upload={upload_id} – GET: a json-array with status information for all queries in an upload;
  • /v3/result/{query_id} – GET: an individual result (prediction or recommendation);
  • /v3/result/?upload={upload_id} – GET: all results from an upload group.

Browser

These endpoints are html web-pages, for viewing in a browser. Alertness API Web-Browser Interface Guide.

  • /v3 – Currently, just redirects to /v3/jsonupload
  • /v3/jsonupload – web-form to upload a json formatted input file
  • `/v3/listQueries – a table of your recent queries, with links to view the query or the result
  • `/v3/listDownloads – a table of your recent download files, with the same links you receive by email
  • /v3/viewQuery/{queryId} – view an individual query
  • /v3/viewQueryGroup/{uploadId} – view all queries from an upload
  • /v3/viewResult/{queryId} – view an individual result
  • /v3/results/{fileName:.json} – Links you receive in result emails have this form.

Output

See the Output Fields Description for details of the output fields of the json formatted results, their meaning and potential values.