ohapi and submodules

The open-humans-api package will be available in Python as ohapi.

In turn ohapi contains multiple sub modules to interact with different things like the project & member-based APIs, the public data API and methods for working with files on the local filesystem.

ohapi.api module

Utility functions to use the OAuth2 project API to e.g. message users, download their files, upload new ones and delete existing files.

exception ohapi.api.SettingsError

Bases: exceptions.Exception

ohapi.api.delete_file(access_token, project_member_id=None, base_url='https://www.openhumans.org/', file_basename=None, file_id=None, all_files=False)
Delete project member files by file_basename, file_id, or all_files. To
learn more about Open Humans OAuth2 projects, go to: https://www.openhumans.org/direct-sharing/oauth2-features/.
Parameters:
  • access_token – This field is user specific access_token.
  • project_member_id – This field is the project member id of user. It’s default value is None.
  • base_url – It is this URL https://www.openhumans.org.
  • file_basename – This field is the name of the file to delete for the particular user for the particular project.
  • file_id – This field is the id of the file to delete for the particular user for the particular project.
  • all_files – This is a boolean field to delete all files for the particular user for the particular project.
ohapi.api.delete_files(*args, **kwargs)

Alternate name for the delete_file.

ohapi.api.exchange_oauth2_member(access_token, base_url='https://www.openhumans.org/', all_files=True)

Returns data for a specific user, including shared data files.

Parameters:
  • access_token – This field is the user specific access_token.
  • base_url – It is this URL https://www.openhumans.org.
ohapi.api.get_all_results(starting_page)

Given starting API query for Open Humans, iterate to get all results.

Parameters:page (starting) – This field is the first page, starting from which results will be obtained.
ohapi.api.get_page(url)

Get a single page of results.

Parameters:url – This field is the url from which data will be requested.
ohapi.api.handle_error(r, expected_code)

Helper function to match reponse of a request to the expected status code

Parameters:
  • r – This field is the response of request.
  • expected_code – This field is the expected status code for the function.
ohapi.api.message(subject, message, access_token, all_members=False, project_member_ids=None, base_url='https://www.openhumans.org/')

Send an email to individual users or in bulk. To learn more about Open Humans OAuth2 projects, go to: https://www.openhumans.org/direct-sharing/oauth2-features/

Parameters:
  • subject – This field is the subject of the email.
  • message – This field is the body of the email.
  • access_token – This is user specific access token/master token.
  • all_members – This is a boolean field to send email to all members of the project.
  • project_member_ids – This field is the list of project_member_id.
  • base_url – It is this URL https://www.openhumans.org.
ohapi.api.oauth2_auth_url(redirect_uri=None, client_id=None, base_url='https://www.openhumans.org/')

Returns an OAuth2 authorization URL for a project, given Client ID. This function constructs an authorization URL for a user to follow. The user will be redirected to Authorize Open Humans data for our external application. An OAuth2 project on Open Humans is required for this to properly work. To learn more about Open Humans OAuth2 projects, go to: https://www.openhumans.org/direct-sharing/oauth2-features/

Parameters:
  • redirect_uri – This field is set to None by default. However, if provided, it appends it in the URL returned.
  • client_id – This field is also set to None by default however, is a mandatory field for the final URL to work. It uniquely identifies a given OAuth2 project.
  • base_url – It is this URL https://www.openhumans.org.
ohapi.api.oauth2_token_exchange(client_id, client_secret, redirect_uri, base_url='https://www.openhumans.org/', code=None, refresh_token=None)

Exchange code or refresh token for a new token and refresh token. For the first time when a project is created, code is required to generate refresh token. Once the refresh token is obtained, it can be used later on for obtaining new access token and refresh token. The user must store the refresh token to obtain the new access token. For more details visit: https://www.openhumans.org/direct-sharing/oauth2-setup/#setup-oauth2-authorization

Parameters:
  • client_id – This field is the client id of user.
  • client_secret – This field is the client secret of user.
  • redirect_uri – This is the user redirect uri.
  • base_url – It is this URL https://www.openhumans.org
  • code – This field is used to obtain access_token for the first time. It’s default value is none.
  • refresh_token – This field is used to obtain a new access_token when the token expires.
ohapi.api.upload_aws(target_filepath, metadata, access_token, base_url='https://www.openhumans.org/', remote_file_info=None, project_member_id=None, max_bytes=128000000)

Upload a file from a local filepath using the “direct upload” API. Equivalent to upload_file. To learn more about this API endpoint see: * https://www.openhumans.org/direct-sharing/on-site-data-upload/ * https://www.openhumans.org/direct-sharing/oauth2-data-upload/

Parameters:
  • target_filepath – This field is the filepath of the file to be uploaded
  • metadata – This field is the metadata associated with the file. Description and tags are compulsory fields of metadata.
  • access_token – This is user specific access token/master token.
  • base_url – It is this URL https://www.openhumans.org.
  • remote_file_info – This field is for for checking if a file with matching name and file size already exists. Its default value is none.
  • project_member_id – This field is the list of project member id of all members of a project. Its default value is None.
  • max_bytes – This field is the maximum file size a user can upload. It’s default value is 128m.
ohapi.api.upload_file(target_filepath, metadata, access_token, datatypes=None, base_url='https://www.openhumans.org/', remote_file_info=None, project_member_id=None, max_bytes=128000000)

Upload a file from a local filepath using the “direct upload” API. To learn more about this API endpoint see: * https://www.openhumans.org/direct-sharing/on-site-data-upload/ * https://www.openhumans.org/direct-sharing/oauth2-data-upload/

Parameters:
  • target_filepath – This field is the filepath of the file to be uploaded
  • metadata – This field is a python dictionary with keys filename, description and tags for single user upload and filename, project member id, description and tags for multiple user upload.
  • access_token – This is user specific access token/master token.
  • base_url – It is this URL https://www.openhumans.org.
  • remote_file_info – This field is for for checking if a file with matching name and file size already exists. Its default value is none.
  • project_member_id – This field is the list of project member id of all members of a project. Its default value is None.
  • max_bytes – This field is the maximum file size a user can upload. It’s default value is 128m.
ohapi.api.upload_stream(stream, filename, metadata, access_token, datatypes=None, base_url='https://www.openhumans.org/', remote_file_info=None, project_member_id=None, max_bytes=128000000, file_identifier=None)

Upload a file object using the “direct upload” feature, which uploads to an S3 bucket URL provided by the Open Humans API. To learn more about this API endpoint see: * https://www.openhumans.org/direct-sharing/on-site-data-upload/ * https://www.openhumans.org/direct-sharing/oauth2-data-upload/

Parameters:
  • stream – This field is the stream (or file object) to be uploaded.
  • metadata – This field is the metadata associated with the file. Description and tags are compulsory fields of metadata.
  • access_token – This is user specific access token/master token.
  • base_url – It is this URL https://www.openhumans.org.
  • remote_file_info – This field is for for checking if a file with matching name and file size already exists. Its default value is none.
  • project_member_id – This field is the list of project member id of all members of a project. Its default value is None.
  • max_bytes – This field is the maximum file size a user can upload. Its default value is 128m.
  • max_bytes – If provided, this is used in logging output. Its default value is None (in which case, filename is used).

ohapi.public module

Utility functions to download public data files.

ohapi.public.download(source=None, username=None, directory='.', max_size='128m', quiet=None, debug=None)

Download public data from Open Humans.

Parameters:
  • source – This field is the data source from which to download. It’s default value is None.
  • username – This fiels is username of user. It’s default value is None.
  • directory – This field is the target directory to which data is downloaded.
  • max_size – This field is the maximum file size. It’s default value is 128m.
  • quiet – This field is the logging level. It’s default value is None.
  • debug – This field is the logging level. It’s default value is None.
ohapi.public.download_url(result, directory, max_bytes)

Download a file.

Parameters:
  • result – This field contains a url from which data will be downloaded.
  • directory – This field is the target directory to which data will be downloaded.
  • max_bytes – This field is the maximum file size in bytes.
ohapi.public.get_members_by_source(base_url='https://www.openhumans.org/api/public-data/')

Function returns which members have joined each activity.

Parameters:base_url – It is URL: https://www.openhumans.org/api/public-data.
ohapi.public.get_sources_by_member(base_url='https://www.openhumans.org/api/public-data/', limit=100)

Function returns which activities each member has joined.

Parameters:
  • base_url – It is URL: https://www.openhumans.org/api/public-data.
  • limit – It is the limit of data send by one request.
ohapi.public.signal_handler_cb(signal_name, frame)

Exit on Ctrl-C.

ohapi.projects module

Utility functions to use master_access_tokens to interact with a project

class ohapi.projects.OHProject(master_access_token)

Work with an Open Humans Project.

download_all(target_dir, source=None, project_data=False, memberlist=None, excludelist=None, max_size='128m', id_filename=False)

Download data for all users including shared data files.

Parameters:
  • target_dir – This field is the target directory to download data.
  • source – This field is the data source. It’s default value is None.
  • project_data – This field is data related to particular project. It’s default value is False.
  • memberlist – This field is list of members whose data will be downloaded. It’s default value is None.
  • excludelist – This field is list of members whose data will be skipped. It’s default value is None.
  • max_size – This field is the maximum file size. It’s default value is 128m.
classmethod download_member_project_data(member_data, target_member_dir, max_size='128m', id_filename=False)

Download files to sync a local dir to match OH member project data.

Parameters:
  • member_data – This field is data related to member in a project.
  • target_member_dir – This field is the target directory where data will be downloaded.
  • max_size – This field is the maximum file size. It’s default value is 128m.
classmethod download_member_shared(member_data, target_member_dir, source=None, max_size='128m', id_filename=False)

Download files to sync a local dir to match OH member shared data.

Files are downloaded to match their “basename” on Open Humans. If there are multiple files with the same name, the most recent is downloaded.

Parameters:
  • member_data – This field is data related to member in a project.
  • target_member_dir – This field is the target directory where data will be downloaded.
  • source – This field is the source from which to download data.
  • max_size – This field is the maximum file size. It’s default value is 128m.
update_data()

Returns data for all users including shared data files.

static upload_member_from_dir(member_data, target_member_dir, metadata, access_token, mode='default', max_size='128m')

Upload files in target directory to an Open Humans member’s account.

The default behavior is to overwrite files with matching filenames on Open Humans, but not otherwise delete files.

If the ‘mode’ parameter is ‘safe’: matching filenames will not be overwritten.

If the ‘mode’ parameter is ‘sync’: files on Open Humans that are not in the local directory will be deleted.

Parameters:
  • member_data – This field is data related to member in a project.
  • target_member_dir – This field is the target directory from where data will be uploaded.
  • metadata – This field is metadata for files to be uploaded.
  • access_token – This field is user specific access token.
  • mode – This field takes three value default, sync, safe. It’s default value is ‘default’.
  • max_size – This field is the maximum file size. It’s default value is 128m.

ohapi.utils_fs module

Utility functions to sync and work with Open Humans data in a local filesystem.

ohapi.utils_fs.characterize_local_files(filedir, max_bytes=128000000)

Collate local file info as preperation for Open Humans upload.

Note: Files with filesize > max_bytes are not included in returned info.

Parameters:
  • filedir – This field is target directory to get files from.
  • max_bytes – This field is the maximum file size to consider. Its default value is 128m.
ohapi.utils_fs.download_file(download_url, target_filepath, max_bytes=128000000)

Download a file.

Parameters:
  • download_url – This field is the url from which data will be downloaded.
  • target_filepath – This field is the path of the file where data will be downloaded.
  • max_bytes – This field is the maximum file size to download. Its default value is 128m.
ohapi.utils_fs.guess_tags(filename)

Function to get potential tags for files using the file names.

Parameters:filename – This field is the name of file.
ohapi.utils_fs.is_single_file_metadata_valid(file_metadata, project_member_id, filename)

Check if metadata fields like project member id, description, tags, md5 and creation date are valid for a single file.

Parameters:
  • file_metadata – This field is metadata of file.
  • project_member_id – This field is the project member id corresponding to the file metadata provided.
  • filename – This field is the filename corresponding to the file metadata provided.
ohapi.utils_fs.load_metadata_csv(input_filepath)

Return dict of metadata.

Format is either dict (filenames are keys) or dict-of-dicts (project member IDs as top level keys, then filenames as keys).

Parameters:input_filepath – This field is the filepath of the csv file.
ohapi.utils_fs.load_metadata_csv_multi_user(csv_in, header, tags_idx)

Return the metadata as requested for multiple users.

Parameters:
  • csv_in – This field is the csv file to return metadata from.
  • header – This field contains the headers in the csv file
  • tags_idx – This field contains the index of the tags in the csv file.
ohapi.utils_fs.load_metadata_csv_single_user(csv_in, header, tags_idx)

Return the metadata as requested for a single user.

Parameters:
  • csv_in – This field is the csv file to return metadata from.
  • header – This field contains the headers in the csv file
  • tags_idx – This field contains the index of the tags in the csv file.
ohapi.utils_fs.mk_metadata_csv(filedir, outputfilepath, max_bytes=128000000)

Make metadata file for all files in a directory.

Parameters:
  • filedir – This field is the filepath of the directory whose csv has to be made.
  • outputfilepath – This field is the file path of the output csv.
  • max_bytes – This field is the maximum file size to consider. Its default value is 128m.
ohapi.utils_fs.print_error(e)

Helper function to print error.

Parameters:e – This field is the error to be printed.
ohapi.utils_fs.read_id_list(filepath)

Get project member id from a file.

Parameters:filepath – This field is the path of file to read.
ohapi.utils_fs.review_metadata_csv(filedir, input_filepath)

Check validity of metadata fields.

Parameters:
  • filedir – This field is the filepath of the directory whose csv has to be made.
  • outputfilepath – This field is the file path of the output csv.
  • max_bytes – This field is the maximum file size to consider. Its default value is 128m.
ohapi.utils_fs.review_metadata_csv_multi_user(filedir, metadata, csv_in, n_headers)

Check validity of metadata for multi user.

Parameters:
  • filedir – This field is the filepath of the directory whose csv has to be made.
  • metadata – This field is the metadata generated from the load_metadata_csv function.
  • csv_in – This field returns a reader object which iterates over the csv.
  • n_headers – This field is the number of headers in the csv.
ohapi.utils_fs.review_metadata_csv_single_user(filedir, metadata, csv_in, n_headers)

Check validity of metadata for single user.

Parameters:
  • filedir – This field is the filepath of the directory whose csv has to be made.
  • metadata – This field is the metadata generated from the load_metadata_csv function.
  • csv_in – This field returns a reader object which iterates over the csv.
  • n_headers – This field is the number of headers in the csv.
ohapi.utils_fs.strip_zip_suffix(filename)

Helper function to strip suffix from filename.

Parameters:filename – This field is the name of file.
ohapi.utils_fs.validate_date(date, project_member_id, filename)

Check if date is in ISO 8601 format.

Parameters:
  • date – This field is the date to be checked.
  • project_member_id – This field is the project_member_id corresponding to the date provided.
  • filename – This field is the filename corresponding to the date provided.
ohapi.utils_fs.validate_metadata(target_dir, metadata)

Check that the files listed in metadata exactly match files in target dir.

Parameters:
  • target_dir – This field is the target directory from which to match metadata
  • metadata – This field contains the metadata to be matched.
ohapi.utils_fs.validate_subfolders(filedir, metadata)

Check that all folders in the given directory have a corresponding entry in the metadata file, and vice versa.

Parameters:
  • filedir – This field is the target directory from which to match metadata
  • metadata – This field contains the metadata to be matched.
ohapi.utils_fs.write_metadata_to_filestream(filedir, filestream, max_bytes=128000000)

Make metadata file for all files in a directory(helper function)

Parameters:
  • filedir – This field is the filepath of the directory whose csv has to be made.
  • filestream – This field is a stream for writing to the csv.
  • max_bytes – This field is the maximum file size to consider. Its default value is 128m.