Mano is a Python library and CLI tool that helps you write applications that interact with the Beiwe Research Platform.
Mano is developed and maintained by Onnela Lab, at the Harvard T.H. Chan School of Public Health, and is part of The Beiwe Platform. It is distributed under the open source BSD-3-Clause license.
Current List of Features:
- Programmatically request lists of the studies you are authorized on from your Beiwe server.
- Request additional information: the list of participants in your study, and the device settings currently enabled on your study.
- Download data generated by the participants in your study.
Table of contents
- Requirements and Compatibility
- Installation
- Initial Setup
- API For Keyring Access
- API For Accessing Study Information
- API For Downloading Data
Requirements and Compatibility
- Mano is compatible with modern versions of Python [at time of writing this means 3.10+]
- Mano's CI runs on macOS (Unix), Ubuntu (Linux), and Windows.
- We have not historically had many Windows users, so Please Report Any Issues You Encounter with Windows compatibility.
- Mano should be fully compatible with the Linux Subsystem for Windows (WSL).
Old SSL Library Compatibility
Beiwe servers require modern, secure connections, so old versions of SSL/TLS libraries provided by your operating system may cause issues. The simplest known solution is to install one of the Miniconda Python distributions, which bundles a more up to date version of OpenSSL.
Installation
The simplest way to install mano is to just use pip
pip install mano
Initial Setup
To interact with Beiwe and download files you will need your Beiwe Platform url, username,
password, access key, and secret key in a JSON file. Don't worry, we're going to eventually
encrypt this file. (Note: we are phasing out the need for the password field, but Beiwe servers
running an older version of the backend software may still require it.)
{
"beiwe.onnela": {
"URL": "...",
"USERNAME": "...",
"PASSWORD": "...",
"ACCESS_KEY": "...",
"SECRET_KEY": "..."
}
}
If you wish to use mano to encrypt certain downloaded data stream files at rest, you should
provide a study-specific passphrase (which you must generate) in an extra SECRETS section.
{
"beiwe.onnela": {
"URL": "...",
"USERNAME": "...",
"PASSWORD": "...",
"ACCESS_KEY": "...",
"SECRET_KEY": "...",
"SECRETS": {
"Beiwe Study Omega": "...",
}
}
}
You don't want this file sitting around as plain text, so Mano requires you encrypt it. Mano uses
the crypt.py utility from the cryptease library which was installed along with the mano
package.
$ crypt.py --encrypt ~/.nrg-keyring.json --output-file ~/.nrg-keyring.enc
It is up to you to decide where to store the encrypted version of this file, but we strongly recommend deleting the unencrypted version.
API For Keyring Access
Before making any API calls Mano must read in your keyring file. The first parameter is the name of the keyring section as shown above
import mano
Keyring = mano.keyring('beiwe.onnela')
Mano still requires that you provide the decryption key for your keyring file. By default it will prompt you to type it in directly, but there are two mechanisms for providing it programmatically.
- Setting the environment variable
NRG_KEYRING_PASSwhere Mano is running. - As the second argument to the
mano.keyringfunction in your code.- We recommend against placing the decryption key as text in your code, or in any file that gets committed to a source control system like Git. This mechanism is provided so that you can programmatically source it from another location.
- It's tough to know where to store a credential securely. If you are on your own computer we recommend using the full drive encryption capability of your operating system to secure it.
API For Accessing Study Information
With your Keyring loaded you can now access information about your studies, users (a.k.a.
participants, subjects), and device settings using simple functions defined within the mano module.
for study in mano.studies(Keyring):
print(study)
_, study_id = study # get the last printed study id
for user_id in mano.users(Keyring, study_id):
print(user_id)
for setting in mano.device_settings(Keyring, study_id):
print(setting)
API For Downloading Data
With your Keyring loaded, you can download collected data from your Beiwe server and extract it to
your filesystem using the mano.sync module. While we're at it, we will turn on more verbose
logging so we can see what's happening.
import logging
from mano import sync as msync
logging.basicConfig(level=logging.INFO)
output_folder = '/tmp/beiwe-data' # set this to a real folder location
zf = msync.download(Keyring, study_id, user_id, data_streams=['identifiers'])
zf.extractall(output_folder)
Encrypt Data Files At Rest
You can pass the ZipFile object to msync.save if you wish to encrypt data stream files.
lock_streams = ['gps', 'audio_recordings']
zf = msync.download(Keyring, study_id, user_id)
data_encryption_key = Keyring['SECRETS']['Beiwe Study Omega'] # not the keyring decryption key!
msync.save(
Keyring,
zf,
user_id,
output_folder,
lock=lock_streams,
passphrase=data_encryption_key,
)
Backfill
By default msync.download attempts to download all of the data for the specified user_id,
which could end up being prohibitively large. For this reason, the msync.download function exposes
parameters for data_streams, time_start, and time_end. By using these parameters you can
limit your download operation to those constraints.
data_streams = ['accel', 'ios_log', 'gps']
time_start = '2015-10-01T00:00:00'
time_end = '2015-12-01T00:00:00'
zf = msync.download(
Keyring,
study_id,
user_id,
data_streams=data_streams,
time_start=time_start,
time_end=time_end,
)
zf.extractall(output_folder)
Eventually you may find yourself day-dreaming about a backfill function that will slide a window
from some arbitrary starting point to the present time in order to download all of your data in more
digestible chunks. You'll be happy to know that the mano.sync module exposes a function for this.
start_date = '2015-01-01T00:00:00'
msync.backfill(
Keyring,
study_id,
user_id,
output_folder,
start_date=start_date,
lock=lock_streams,
passphrase=passphrase,
)
Metadata
Release files for mano 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mano-0.6.0.tar.gz | 21.7 kB | Without provenance | Details for mano-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mano-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for mano-0.6.0-py3-none-any.whl |
Total release size: 37.2 kB
Release files / mano-0.6.0.tar.gz
| Download URL | mano-0.6.0.tar.gz |
|---|---|
| Size | 21.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4c7c68744417627900eb70742054992cb5fcfbb605ee21e2dd62b1f0ef140cf1
|
|
BLAKE2b-256 checksum How to use checksums |
598ba6b7323affc3eb073c3d12e41700053d5909e33f664c8cbd1137b5cf2be0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.4
|
Release files / mano-0.6.0-py3-none-any.whl
| Download URL | mano-0.6.0-py3-none-any.whl |
|---|---|
| Size | 15.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
655a6273b2743ec33a4ecbc94e62250ab1ed561374bfe217bd5863cb166e6155
|
|
BLAKE2b-256 checksum How to use checksums |
5a65474087f1288faebf15d1d96f2d40d2430c043df956a14910851f189bd5ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.4
|
Security for mano 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.