willisapi-client 2.0

WillisAPI Client

WillisAPI Client is the Python interface for Brooklyn Health’s WillisAPI.

Official documentation for WillisAPI Client can be found in the Github Wiki.

To learn more about Brooklyn Health or WillisAPI, visit brooklyn.health or getintouch@brooklyn.health.

Installation

pip install willisapi_client

Getting a Personal Access Token (PAT)

1. Log in to the Brooklyn Health web application.
2. Go to your profile section.
3. Navigate to Personal Access Token (PAT) and copy it for use in the client.

Usage

Upload To upload a CSV file:

summary = willisapi.upload(key, '/path/to/data.csv')

How to Call the Function

• key: Your PAT token.
• data.csv: Path to your CSV file.

How to Reupload

If you need to reupload the same or updated file, simply call the upload function again:

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

Understanding Returned DataFrame and Errors

• The upload function returns a summary DataFrame containing the results of your upload.
• Columns typically include status, error messages, and metadata for each row in your CSV.
• If there are errors, they will be listed in the DataFrame under an error or message column.
• Review the DataFrame to identify and resolve any issues before reuploading.

CSV Validation Details

Before uploading, the client validates your CSV for:

• Required Columns: Must include study_id, site_id, participant_id, visit_name, visit_order, coa_name, coa_item_number, coa_item_value, file_path, time_collected.
• Optional Columns: rater_id, age, sex, race, language.
• Valid COA Name: Only these values are allowed: MADRS, YMRS, PHQ-9, GAD-7.
• Valid Audio File: The file path in each row must exist and be accessible.
• Valid Data Types: visit_order, age, coa_item_number, and coa_item_value must be numeric.
• Language: If present, must be in the allowed language choices.

If any validation fails, errors are collected and returned for review before upload proceeds.

Processed Data Upload

To upload a processed data CSV file:

summary = willisapi.processed_upload(key, '/path/to/processed-data.csv')

How to Call the Function

• key: Your PAT token.
• processed-data.csv: Path to your processed data CSV file.

For more information on how to organize the data.csv, visit the Github Wiki.

If you run into trouble while using the client, please raise it in the Issues tab.

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.