Assessments

This is a v2 science API. These APIs are not yet complete or ready for production.

Introduction

Any activity a user performs in your app that collects data for scientific research is called an assessment in Bridge.

Answering a survey, filling out a medication tracker, or doing a test with device sensors are all assessments of your participant. Assessments with good scientific validity are a team effort involving scientists and software engineers. Bridge provides features to share validated assessments between apps, and within the studies that are conducted in an app. These assessments can then be scheduled for participants who have been allocated to one or more arms of your study. The system allows for controlled customization of these assessments as a software component in your app.

Bridge Assessment Model

The Assessments API has two main components. First, an Assessment and its associated ExternalResource links provide documentation for the assessment (both technical and scientific). We expect most documentation will live outside of our shared assessment tools, hosted in places like Sage Bionetworks’ Synapse wikis or on Github. Second, each assessment has an associated AssessmentConfig that Bridge’s client app SDK uses to present the user interface in an app. This configuration drives the implementation of an assessment’s UI, and will be authored by client app developers. A customization API allows study designers to customize an assessment in a controlled manner, without breaking client apps or the scientific validity of the assessment.

Assessments are conceptually organized into an ordered set of revisions that share a common identifier. The higher the revision number, the more recently that revision should have been created (although this isn’t strictly enforced, and the createdOn timestamp can be used to determine the actual temporal order of revisions). Each assessment revision can also be retrieved by a unique GUID, which is easier to work with than an identifier and revision value. You will need the guid to retrieve the assessment’s configuration, as each revision has its own configuration. Revisions logically replace one another and form a history of changes to an assessment.

Bridge has a shared assessment library of validated, high-quality assessments that researchers can include in their apps. Once copied for use in an app, they can be scheduled as part of a study design.

Using assessments

Curated assessments are available through our Shared Assessments APIs. In addition to some basic information about the assessment, there will be a set of ExternalResource objects that provide links to many kinds of documentation. Those links will be assigned to one of the following categories:

Category Purpose of Documentation
customization_options Describes the fields that can be edited, through a special API for this purpose, to customize an assessment in a specific app. These fields are chosen by the assessment authors because they are not believed to effect the validity of the data collected by the assessment.
data_repository Describes an online location where data can be found that has been generated by this assessment, in one or more studies.
science_documentation Documentation of the scientific interpretation of the data collected by the assessment. Schema information, like data dictionaries, falls into this category.
developer_documentation Documentation on the software and the assessment configuration that is specifically for implementing an assessment in app development (information about the interpretation of the data that is generated should be marked as "science_documentation."
license The software or other licenses for this assessment.
publication A publication that was based at least in part on data collected through this assessment.
release_note Documentation of changes in a specific revision of an assessment (we suggest that the minRevision and maxRevision values on this ExternalResource should both be set to the revision being documented).
sample_app A sample app showing the implementation of the assessment in working software. Intended for developers who are implementing a new app.
sample_data Sample data for researchers that is identical to the data generated by the assessment.
screenshot An image file (format field should be an image MIME type) showing an example of the assessment’s UI within Bridge’s app SDKs.
video_preview A video file (with a video MIME type format field) or a web page with a video preview of the assessment.
see_also Link to a related assessment, measure, or methodology (it does not need to be in the Bridge system).
used_in_study A link to a study that has utilized this assessment (this is a link to some public face for the study, not data or publications from that study).
website Any other website.
other Any other kind of resource that might not be linkable (if you can link to it, it may be better to categorize it as a website).

To use a shared assessment, it must be imported into your app. You must be signed in to the app context on Bridge, and you must include the ID of the organization that will own the local copy of the shared assessment (if you only belong to one organization, this will be used as the default if no organization is provided). All persons with access to an app will be able to see and schedule this assessment in any study, but only members of the owning organization will be able to edit or customize the assessment. The imported assessment has a link to the shared assessment so you can retrieve all of the resources that document the assessment.

Developing assessments

Assessments will begin their development lifecycle in a specific app context. At this point the assessment object is sparse as developers will probably be focused on working out an appropriate configuration for the assessment. Once the software for the assessment has been tested and validated, appropriate documentation can be added through the Assessment fields and its associated ExternalResources. It can then be published to the shared assessment library. A shared assessment's configuration will also be published; it cannot be changed or customized once it is shared. The external resources documenting the assessment can then also be published to the shared library.

If the assessment has never been published to the library before (its identifier is unique), it will be published at revision 1. Otherwise it will be published at the next highest revision number.

The local copy of the published assessment will be updated to reflect that it is now a logical “copy” of the newly shared assessment (its originGuid will be set to the GUID of the new shared assessment revision).

While members of the owning organization will be able to edit the metadata of shared assessments (the assessment and resources), they will not be able to edit the shared configuration. To change the configuration, you will need to publish a new revision of your assessment (which should be treated like any other software release).

Why are shared assessment configurations “locked”? The configurations define the code that collects and formats the data produced by the assessment. Changing the configuration could inadvertently change the structure, formatting, or semantic meaning of the data produced. This could invalidate the assessment’s scientific utility.

Alternatively, you may find a shared assessment that you wish to import into your app context. Importing will create a local copy that will have its originGuid set to the GUID of the shared assessment revision, and its configuration will be copied into your local study as well. (If you are only interested in using the assessment, there is no need to import the resources, as these can be referred to via the shared assessment.)

Thus no matter how you create a copy of a shared assessment (publishing or importing), your local copy will be the same:

  • it will have an originGuid pointing to the shared assessment version of the assessment;
  • if the configuration is updated, the assessment will lose this link to its shared assessment.
  • however, the local copy of a shared component can be customized through the customization API while still being considered a valid instance of the assessment.

If you do wish to change a local copy of a shared assessment (e.g. to fix bugs or introduce new behavior), you can do so. If you are a member of the organization that owns the shared assessment, you can publish it as a later revision of the shared assessment. Otherwise you can change the identifier and publish it as a new kind of assessment in the shared library.

If you want to edit the resources that document the assessment, you have these choices (best done as part of publishing a new revision in the shared library):

  • edit the ExternalResource in the shared library (for example, you can change the minRevision and maxRevision fields to reflect whether or not the resource is applicable to a new revision of the assessment);
  • create a new ExternalResource and publish it to the shared library;
  • delete a resource in the shared library (be careful with this option. if it only applies to an older revision of the shared assessment, it is better to set a maxRevision value to indicate that);
  • import an ExternalResource, edit it, and then publish it at the time you publish the rest of the assessment (this last option just lets you coordinate your updates to the shared library).

Assessment configuration

The assessment configuration can be any valid JSON and is not currently constrained by the server beyond the following rules:

  • Each object node should have an identifier property with a value that is unique in your configuration graph;
  • Each object node should have a type property indicating the type of that node (usually the strict type the node would be deserialized to by a server or client).

Note: as Sage Bionetworks refines the assessment configuration model, these rules may change and more type information may be introduced.

Customizing an assessment's configuration

Only local assessments can be customized (shared assessments, being shared, cannot be tailored to use in a specific app). The customizationFields of the Assessment model specifies the nodes of a JSON tree that can be customized. The top-level properties are the identifiers of the nodes that have customizable properties. The value is an array of PropertyInfo objects. Each of these objects describes one property of the object node that can be customized through the customization API, along with some metadata for editing tools.

{
  "Bnm_u6qFhrdmvW82nx2nFRyi": [
    {
      "propName": "label",
      "label": "The screen's label",
      "description": "The text in the title bar at the top of the screen",
      "propType": "string",
      "type": "PropertyInfo"
    }, 
    {
      "propName": "prompt",
      "label": "The screen's prompt",
      "description": "The text above the button to begin the test.",
      "propType": "string",
      "type": "PropertyInfo"
    }
  ],
  "L4gdW7rIttLVuurmBg5P9k5x": [
    {
      "propName": "metadata:show_back_button",
      "label": "Show back button?",
      "description": "Should the UI show a back button on this screen?",
      "propType": "boolean",
      "type": "PropertyInfo"
    },
    {
      "propName": "metadata:show_forward_button",
      "label": "Show forward button?",
      "description": "Should the UI show a forward button on this screen?",
      "propType": "boolean",
      "type": "PropertyInfo"
    }
  ]
}

Any changes that are submitted through the customization API that do not match these allowable fields will be ignored. The assessment will still be linked to a shared assessment (it will still have its originGuid field set) if it has ever been published to or imported from the shared assessments library.