Skip to content

Home

Jump to bottom
zwihawks edited this page Jan 14, 2026 · 25 revisions

Welcome to the Github Wiki for the WillisAPI Client, the official python interface for interacting with Brooklyn Health’s WillisAPI. Here, you will find setup and user instructions for the audio recording upload and processed data upload functions.

Gaining access

Before you can get started with WillisAPI, you will need to have a personal access token (key) from Brooklyn Health. If you don’t have one just yet and are interested in using WillisAPI, be sure to getintouch@brooklyn.health.

Getting started

Before you begin, we recommend you create a virtual environment for the WillisAPI Client.

pip install virtualenv
virtualenv willisapi_client --python=3.10
source willisapi_client/bin/activate

Note: For stable behavior, it's recommended to use any Python version above 3.10.

To install the client, simply run:

pip install willisapi_client

Then, enter a python environment. From there, you’ll want to run:

import willisapi_client as willisapi

Upload audio recordings

Use the audio recording upload function to submit raw audio files for processing on Brooklyn Health’s servers.

To upload audio recordings, use the following function:

summary = willisapi.upload(key,'recording_data.csv')

Enter the key that was saved during login.

recording_data.csv is where information on the data to be uploaded will be given.

It is a CSV organized in the following format:

study_id site_id rater_id participant_id age sex race language visit_name visit_order coa_name coa_item_number coa_item_value time_collected file_path recording_order
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...

In this CSV:

  • study_id: This is the study identifier, specified by the user as a string.

  • site_id: This is the site identifier, specified by the user as a string.

  • rater_id: (optional) This is the rater identifier, specified by the user as a string.

  • participant_id: This is the participant identifier, specified by the user as a string.

  • age (optional): This is the participant's age, specified by the user as a number.

  • sex (optional): This is the participant's sex, specified by the user as a string.

  • race (optional): This is the participant's race, specified by the user as a string.

  • language (optional): This is the participant's language country code (e.g., "en-US").

  • visit_name: This is the name of the study visit, specified by the user as a string (e.g., "screening").

  • visit_order: This is the order of the study visit, specified by the user as a number. For example, if the first study visit is screening and the second study visit is baseline, visit_order would be "0" for screening and "1" for baseline.

  • coa_name: This is the name of the coa, specified by the user as a string (e.g., MADRS).

  • coa_item_number: This is the coa item number, specified by the user as a number.

  • coa_item_value: This is the coa item score, specified by the user as a number. Note: When multiple recordings exist for a single COA, enter item level scores for the first COA (minimum recording order) only.

  • time_collected: This is the timepoint the coa was collected, formatted as MM/DD/YYYY HH:MM:SS.

  • file_path: This is the local path for the file that you are trying to upload. Please enter the full file path, including the file extension.

  • recording_order: This is the order of the recording if a single COA is split across multiple files. It is 0-indexed (0 for the first part, 1 for the second, etc.). The system will concatenate recordings uniquely identified by study, site, participant, visit, and COA prior to processing.

A sample CSV file is included in the repo. We recommend you use this as a starting point when creating your own recording_data.csv. It will ensure all column headings and subsequent entries are formatted correctly.

After triggering the function, it verifies the provided information before securely uploading data to Brooklyn Health’s servers. Upload speed relies on your internet connection. Where possible, an upload progress bar is displayed.

After uploading, the summary will show successful and failed uploads. If there are failures (some failures are expected in large uploads), you can re-run the command after isolating failed records in a new metadata CSV.

If, for any reason, you want to replace files that have previously been uploaded, you can use the force_upload command in the manner shown below. This command will fail if the metadata CSV contains records that have not been uploaded.

summary = willisapi.upload(key,'data.csv', force_upload=True)

Upload processed data

After WillisPipeline has generated output, use the processed data upload function to submit the data to Brooklyn Health’s servers for visualization on Willis.

Calling the WillisAPI processed_upload() function initiates secure data upload to Brooklyn Health’s servers. Upload speed relies on your internet connection. Where possible, an upload progress bar is displayed.

To upload processed data (WillisPipeline output), use the following function:

summary = willisapi.processed_upload(api_key = key, csv_path = input.csv, output_path = '/user/ssm-user/willisoutput')

Enter your key, the input file that was provided to WillisPipeline (e.g., input.csv), and the output_path where WillisPipeline output is saved.

––

Brooklyn Health is a small team of clinicians, scientists, and engineers based in Brooklyn, NY.

We develop and maintain OpenWillis, an open source python library for digital health measurement.

Clone this wiki locally