Website In Development
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:
- a web-browser interface for manually uploading files and retrieving results; and
- 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
- Get an Account: currently a request must be emailed to the people listed in the Contacts section at the bottom of this document.
- 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.
- Submit Your Input File: You can use either the REST or Browser interface.
- REST: the contents of your input file should be
POST
ed, as the request body, to the/v3/query
endpoint. - Browser: Upload your file using the form at
/v3/jsonupload
.
- REST: the contents of your input file should be
- Retrieve Results:
- REST:
GET
thestatus
of your query from the/v3/status
endpoint, and once it isCOMPLETE
retrieve your result from the/v3/result
endpoint. - Browser: you can view a list of your recent queries and their status, and once evaluation of the file you uploaded is
COMPLETE
you can download your result file/s.
- REST:
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:
- Input Examples – to get a basic idea of the range and structure of inputs;
- Input Fields Description for details of the available input fields, their meaning and potential values.
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 POST
ing to the REST endpoint, the query undergoes three stages of validation:
- Must be either a
json
object orjson
array; - Each json object must conform to the json-schema definition of the inputs;
- 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 offorced_wake
must be earlier than their associatedend_time
.
Models
Sydney Group’s
Recommended Models
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:
- 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.
- 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 statusRECIEVED
;/v3/query/?status=QUEUED
– GET: all of a user’s queries with statusQUEUED
./v3/query/?status=RUNNING
– GET: all of a user’s queries with statusRUNNING
./v3/query/?status=COMPLETE
– GET: all of a user’s queries with statusCOMPLETE
./v3/query/?status=FAILED
– GET: all of a user’s queries with statusFAILED
./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 ajson
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.