materials_commons.api.client module

Raises

add_dataset_to_community(dataset_id, community_id)[source]

Add a dataset to a community. The dataset must have been published.

Parameters

dataset_id (int) –
community_id (int) –

Return type

Returns

The community with the dataset

Raises

add_user_to_project(project_id, user_id)[source]

Adds user to project.

Parameters

project_id (int) – Id of project to add user to
user_id (int) – Id of user to add to project

Returns

The updated project

Return type

Raises

assign_doi_to_dataset(project_id, dataset_id)[source]

Assign DOI to existing dataset.

Parameters

project_id (int) – The project to create the dataset in
dataset_id (int) – The id of the dataset

Returns

The updated dataset with DOI

Return type

Raises

change_dataset_file_selection(project_id, dataset_id, file_selection)[source]

Change the file selection for a dataset to match the passed in dataset.

Parameters

project_id (int) – Project id containing dataset
dataset_id (int) – Id of dataset
file_selection –
{ “include_files”: array, “exclude_files”: array, “include_dirs”: array, “exclude_dirs”: array}

Returns

The updated dataset

Return type

Raises

Returns

The updated Dataset

check_file_by_path_in_dataset(project_id, dataset_id, file_path)[source]

Check if file path is in the dataset selection. Throws an error if the file_path isn’t in the project.

Parameters

project_id (int) – project dataset and file_path are in
dataset_id (int) – data to check file_selection against
file_path (str) – file_path to check against dataset file_selection

Returns

{‘in_dataset’: True} or {‘in_dataset’: False}

Raises

check_file_in_dataset(project_id, dataset_id, file_id)[source]

Check if file is in the dataset selection.

Parameters

project_id (int) – project dataset and file are in
dataset_id (int) – dataset to check file_selection against
file_id (int) – file to check

Returns

{‘in_dataset’: True} or {‘in_dataset’: False}

Raises

close_globus_transfer(project_id)[source]

Closes an existing globus transfer. If there isn’t an open transfer for the user in project then does nothing and returns success.

Parameters: project_id (int) – The id of the project to close globus transfer for the current user
Returns: None
Raises: MCAPIError –

create_activity(project_id, name, request=None, attrs=None)[source]

Create a new activity in the project.

Parameters

project_id – The project to create the activity int
name (str) – Name of activity
request (CreateActivityRequest) – Attributes on the activity
attrs – Array of dicts of the form {“name”: “name-of-attr”, “unit”: “optional-unit”, “value”: dict | bool | int | float | str}

Returns

The activity to create

Return type

Activity

Raises

create_community(name, attrs={})[source]

Creates a new community owned by the user.

Parameters

name (str) – Name of community
attrs (CreateCommunityRequest) – (optional) Additional attributes for the create request

Returns

The created community

Return type

Raises

create_dataset(project_id, name, attrs=None)[source]

Create a new dataset in a project.

Parameters

project_id (int) – The project to create the dataset in
name (string) – The name of the dataset
attrs (CreateDatasetRequest) – Attributes of the dataset

Returns

The created dataset

Return type

Raises

create_directory(project_id, name, parent_id, attrs=None)[source]

Create a new directory in project in the given directory.

Parameters

project_id (int) – The id of the project the directory will be created in
name (str) – Name of directory
parent_id (int) – Parent directory id - The directory that this directory will be in
attrs (CreateDirectoryRequest) – Additional attributes on the directory

Returns

The created directory

Return type

Raises

create_entity(project_id, name, activity_id, request=None, attrs=None)[source]

Creates a new entity in the project.

Parameters

project_id – The id of the project to create entity in
name (str) – The entity name
activity_id – The activity to associated the samples as initially coming from
request (CreateEntityRequest) – Attributes of the entity
attrs – Array of dicts of the form {“name”: “name-of-attr”, “unit”: “optional-unit”, “value”: dict | bool | int | float | str}

Returns

The created entity

Return type

Entity

Raises

create_entity_state(project_id, entity_id, activity_id, current=True, attrs=None)[source]

Adds a new state to an existing entity.

Parameters

project_id (int) – The id of the project containing the entity
entity_id (int) – The id of the entity to associate the state with
activity_id (in) – The id of the activity that created the state
current (bool) – Whether to mark the state as the current state
attrs – Array of dicts of the form {“name”: “name-of-attr”, “unit”: “optional-unit”, “value”: dict | bool | int | float | str}

Returns

Entity

Raises

create_experiment(project_id, name, attrs=None)[source]

Create a new experiment in a project.

Parameters

project_id (int) – The id of the project the experiment is in
name (str) – Name of experiment
attrs (CreateExperimentRequest) – Additional attributes on the experiment

Returns

The created experiment

Return type

Experiment

Raises

create_globus_download_request(project_id, name)[source]

Create a globus download request for a project.

Parameters

project_id (int) –
name (str) – The name of the download request

Returns

The globus download

Return type

GlobusDownload

Raises

create_globus_upload_request(project_id, name)[source]

Create a new globus request in the given project.

Parameters

project_id (int) – The project id for the upload
name – The name of the request

Returns

The globus request

Return type

GlobusUpload

Raises

create_link_in_community(community_id, name, url, attrs=None)[source]

Adds a link to a community.

Parameters

community_id (int) – The community to add the link to
name (str) – name to show for url
url (str) – url to add
attrs (CreateLinkRequest) – additional attrs

Returns

The community

Return type

Raises

create_project(name, attrs=None)[source]

Creates a new project for the authenticated user. Project name must be unique.

Parameters

name (str) – Name of project
attrs (CreateProjectRequest) – (optional) Additional attributes for the create request

Returns

The created project

Return type

Raises

MCAPIError – On error

delete_activity(project_id, activity_id)[source]

Deletes an activity.

Parameters

project_id – The id of the project containing the activity
activity_id – The id of the activity to delete

Raises

delete_dataset(project_id, dataset_id)[source]

Delete an unpublished dataset.

Parameters

project_id (int) – The project id containing the dataset
dataset_id (int) – The id of the dataset

Raises

delete_directory(project_id, directory_id)[source]

Should not be used yet: Delete a directory only if the directory is empty.

Parameters

project_id (int) – The project id containing the directory to delete
directory_id (int) – The id of the directory to delete

Raises

delete_entity(project_id, entity_id)[source]

Delete an entity.

Parameters

project_id (int) – The id of the project containing the entity
entity_id (int) – The entity id

Raises

delete_experiment(project_id, experiment_id)[source]

Delete experiment in project.

Parameters

project_id (int) – The id of the project the experiment is in
experiment_id – The experiment id

Raises

delete_file(project_id, file_id, force=False)[source]

Delete a file in a project.

Parameters

project_id (int) – The id of the project containing the file
file_id (int) – The id of the file to delete

Raises

delete_file_from_community(file_id, community_id)[source]

Deletes file from the community and deletes the file on the system.

Parameters

file_id (int) – The file to delete
community_id (int) – The community to delete it from

Raises

delete_globus_download_request(project_id, globus_download_id)[source]

Delete an existing globus download request.

Parameters

project_id (int) – The id of the project containing the download request
globus_download_id (int) – The id of the globus download to delete

Raises

delete_globus_upload_request(project_id, globus_upload_id)[source]

Delete an existing globus upload request.

Parameters

project_id (int) –
globus_upload_id (int) –

Raises

delete_link_from_community(link_id, community_id)[source]

Delete a link from a community and remove it from the system.

Parameters

link_id (int) – The link to remove
community_id (int) – The community to delete the link from

Raises

delete_project(project_id)[source]

Deletes a project.

Parameters: project_id (int) – id of project to delete
Raises: MCAPIError –

download_file(project_id, file_id, to)[source]

Download a file.

Parameters

project_id (int) – The project id containing the file to download
file_id (int) – The id of the file to download
to (str) – path including file name to download file to

Raises

download_file_by_path(project_id, path, to)[source]

Download a file by path.

Parameters

project_id (int) – The project id containing the file to download
path (str) – The path in the project of the file
to (str) – path including file name to download file to

Raises

download_published_dataset_file(dataset_id, file_id, to)[source]

Download file from a published dataset.

Parameters

dataset_id (int) – The id of the published dataset
file_id (int) – The id of the file in the dataset
to (str) – The path including the file name to write the download to

Raises

download_published_dataset_zipfile(dataset_id, to)[source]

Download the zipfile for a published dataset.

Parameters

dataset_id (int) – The id of the published dataset
to (str) – The path including the file name to write the download to

Raises

finish_globus_upload_request(project_id, globus_upload_id)[source]

Mark a globus upload request as finished.

Parameters

project_id (int) – The project id for the upload
globus_upload_id (int) – The id of the globus upload

Returns

The globus upload

Return type

GlobusUpload

Raises

get_activity(project_id, activity_id, params=None)[source]

Get an activity.

Parameters

project_id (int) – The id of the project containing the activity
activity_id (int) – The id of the activity
params –

Returns

The activity

Return type

Activity

Raises

get_all_activities(project_id, params=None)[source]

Get all activities in a project.

Parameters

project_id (int) – The id of the project
params –

Returns

List of activities

Return type

Activity[]

Raises

get_all_datasets(project_id, params=None)[source]

Get all datasets in a project.

Parameters

project_id (int) – The project id
params –

Returns

The list of datasets

Return type

Dataset[]

Raises

get_all_entities(project_id, params=None)[source]

Get all entities in a project.

Parameters

project_id (int) – The id of the project
params –

Returns

The list of entities

Return type

Entity[]

Raises

get_all_experiments(project_id, params=None)[source]

Get all experiments for a given project.

Parameters

project_id (int) – The project id
params –

Returns

A list of experiments

Return type

Experiment[]

Raises

get_all_globus_download_requests(project_id, params=None)[source]

Get all globus download requests for a project.

Parameters: project_id (int) – The project
Returns: List of all globus downloads
Return type: GlobusDownload[]
Raises: MCAPIError –

get_all_globus_upload_requests(project_id, params=None)[source]

Get all globus uploads in a project.

Parameters: project_id (int) – The project id
Returns: List of globus uploads
Return type: GlobusUpload[]
Raises: MCAPIError –

get_all_my_communities(params=None)[source]

Get all communities owned by user.

Return type: Community[]
Returns: List of communities
Raises: MCAPIError –

get_all_projects(params=None)[source]

Returns a list of all the projects a user has access to.

Parameters: params –
Returns: List of projects
Return type: Project[]
Raises: MCAPIError –

get_all_public_communities(params=None)[source]

Get all public communities.

Return type: Community[]
Returns: List of public communities
Raises: MCAPIError –

get_all_published_datasets(params=None)[source]

Get all published datasets.

Parameters: params –
Returns: The list of published datasets
Return type: Dataset[]
Raises: MCAPIError –

static get_apikey(email, password, base_url='https://materialscommons.org/api')[source]

Retrieve the API Key for the given user.

Parameters

email (str) – The users email address
password (str) – The password for the user
base_url (str) – Optional, defaults to https://materialscommns.org/api. Used to connect to a different server.

Returns

The users apikey

Return type

str

Raises

get_community(community_id, params=None)[source]

Get a commmunity.

Parameters

community_id (int) – The id of the community to get
params – Query specific parameters

Return type

Returns

The Community

Raises

get_dataset(project_id, dataset_id, params=None)[source]

Get dataset in a project.

Parameters

project_id (int) – The project id containing the dataset
dataset_id (int) – The dataset id
params –

Returns

The dataset

Return type

Raises

get_dataset_activities(project_id, dataset_id, params=None)[source]

Get activities for a dataset.

Parameters

project_id (int) – The project id containing the dataset
dataset_id (int) – The dataset id
params –

Return type

Activity[]

Returns

The activities

Raises

get_dataset_entities(project_id, dataset_id, params=None)[source]

Get entities for a dataset.

Parameters

project_id (int) – The project id containing the dataset
dataset_id (int) – The dataset id
params –

Return type

Entity[]

Returns

The entities

Raises

get_dataset_files(project_id, dataset_id, params=None)[source]

Get files for a dataset.

Parameters

project_id (int) – The project id containing the dataset
dataset_id (int) – The dataset id
params –

Return type

File[]

Returns

The files

Raises

get_directory(project_id, directory_id, params=None)[source]

Get a directory in the project.

Parameters

project_id (int) – The id of the project the directory is in
directory_id (int) – The directory id
params –

Returns

The directory

Return type

Raises

get_entity(project_id, entity_id, params=None)[source]

Get an entity.

Parameters

project_id (int) – The id of the project containing the entity
entity_id (int) – The id of the entity
params –

Returns

The entity

Return type

Entity

Raises

get_experiment(experiment_id, params=None)[source]

Get an experiment.

Parameters

experiment_id (int) – The experiment id
params –

Returns

The experiment

Return type

Experiment

Raises

get_file(project_id, file_id, params=None)[source]

Get file in project.

Parameters

project_id (int) – The id of the project containing the file
file_id (int) – The id of the file
params –

Returns

The file

Return type

Raises

get_file_by_path(project_id, file_path)[source]

Get file by path in project.

Parameters

project_id (int) – The id of the project containing the file
file_path – The path to the file

Returns

The file

Return type

Raises

get_file_versions(project_id, file_id, params=None)[source]

Get versions for file in project (does not include file given).

Parameters

project_id (int) – The id of the project containing the file
file_id (int) – The id of the file
params –

Returns

File versions

Return type

File[]

Raises

get_globus_download_request(project_id, globus_download_id, params=None)[source]

Get a globus download.

Parameters

project_id (int) – The id of the project containing the globus download
globus_download_id (int) – The globus download id

Returns

The globus download

Return type

GlobusDownload

Raises

get_project(project_id, params=None)[source]

Get a project by its id.

Parameters

project_id (int) – Project id for project
params –

Returns

The project

Return type

Raises

get_published_dataset(dataset_id, params=None)[source]

Get published dataset.

Parameters

dataset_id (int) – The dataset id
params –

Returns

The dataset

Return type

Raises

get_published_dataset_activities(dataset_id, params=None)[source]

Get activities for a published dataset.

Parameters

dataset_id (int) – The dataset id
params –

Return type

Activity[]

Returns

The activities

Raises

get_published_dataset_directory(dataset_id, directory_id, params=None)[source]

Get a directory in a published dataset.

Parameters

dataset_id (int) – The id of the published dataset the directory is in
directory_id (int) – The directory id
params –

Returns

The directory

Return type

Raises

get_published_dataset_entities(dataset_id, params=None)[source]

Get entities for a published dataset.

Parameters

dataset_id (int) – The dataset id
params –

Return type

Entity[]

Returns

The entities

Raises

get_published_dataset_files(dataset_id, params=None)[source]

Get files for a published dataset.

Parameters

dataset_id (int) – The dataset id
params –

Return type

File[]

Returns

The files

Raises

get_published_datasets_for_author(author)[source]

Get all published datasets for an author.

Parameters: author (str) – Author name string
Returns: List of datasets author is on
Return type: Dataset[]
Raises: MCAPIError –

get_published_datasets_for_tag(tag)[source]

Get all published datasets tagged with tag.

Parameters: tag (str) – tag to use
Returns: List of datasets tagged with tag
Return type: Dataset[]
Raises: MCAPIError –

get_server_info()[source]

Gets information about the materials commons server

Returns: server information
Return type: Server

get_user_by_email(email, params=None)[source]

Get a user by their email.

Parameters: email (string) – email address of user to lookup
Returns: The user
Return type: User
Raises: MCAPIError –

import_dataset(dataset_id, project_id, directory_name)[source]

Launches a job to import a dataset into a project. The import will complete at some.

point in the future. There isn’t currently a way to query the import status. :param int dataset_id: The dataset id to import :param int project_id: A project id the user has access to :param string directory_name: The top level directory to import the dataset into (will be created) :raises MCAPIError:

list_authors_in_community(community_id)[source]

List all unique authors across all the published datasets in a community.

Parameters: community_id (int) – The community to list the authors for
Returns: The list of authors
Return type: string[]
Raises: MCAPIError –

list_directory(project_id, directory_id, params=None)[source]

Return a list of all the files and directories in a given directory.

Parameters

project_id (int) – The id of the project the directory is in
directory_id (int) – The directory id
params –

Returns

A list of the files and directories in the given directory

Return type

File[]

Raises

list_directory_by_path(project_id, path, params=None)[source]

Return a list of all the files and directories at given path.

Parameters

project_id (int) – The id of the project the path is in
path (str) –
params –

Returns

A list of the files and directories in the given path

Return type

File[]

Raises

list_published_authors()[source]

List all published authors.

Returns: List of authors
Return type: User[]
Raises: MCAPIError –

list_published_dataset_directory(dataset_id, directory_id, params=None)[source]

Return a list of all the files and directories in a given published dataset directory.

Parameters

dataset_id (int) – The id of the dataset the directory is in
directory_id (int) – The directory id
params –

Returns

A list of the files and directories in the given directory

Return type

File[]

Raises

list_published_dataset_directory_by_path(dataset_id, path, params=None)[source]

Return a list of all the files and directories at given path.

Parameters

dataset_id (int) – The id of the dataset the path is in
path (str) –
params –

Returns

A list of the files and directories in the given path

Return type

File[]

Raises

list_tags_for_published_datasets()[source]

List all tags used in published datasets.

Returns: List of tags
Return type: Tag[]
Raises: MCAPIError –

list_tags_in_community(community_id)[source]

List all the unique tags across all the published datasets in a community.

Parameters: community_id (int) – The community to list the tags for
Returns: The list of tags
Return type: Tag[]
Raises: MCAPIError –

list_users(params=None)[source]

List users of Materials Commons.

Returns: List of users
Return type: User[]
Raises: MCAPIError –

static login(email, password, base_url='https://materialscommons.org/api')[source]

Creates a new instance of the Client by retrieving the given user’s APIKey.

Parameters

email (str) – The users email address
password (str) – The password for the user
base_url (str) – Optional, defaults to https://materialscommns.org/api. Used to connect to a different server.

Returns

The users apikey

Return type

str

Raises

move_directory(project_id, directory_id, to_directory_id)[source]

Moves a directory into another directory.

Parameters

project_id (int) – The project id that target and destination directories are in
directory_id (int) – Id of directory to move
to_directory_id (int) – Id of the destination directory

Returns

The directory that was moved

Return type

Raises

move_file(project_id, file_id, to_directory_id)[source]

Move file into a different directory.

Parameters

project_id (int) – The project id of the file and the destination directory
file_id (int) – The id of the file to move
to_directory_id (int) – The id of the destination directory

Returns

The moved file

Return type

Raises

mql_execute_query(project_id, statement, select_processes=True, select_samples=True)[source]

mql_load_project(project_id)[source]

mql_reload_project(project_id)[source]

open_globus_transfer(project_id, params=None)[source]

Open a globus transfer request for current user in project. If one is already active then it returns the already active request.

Parameters: project_id (int) – The id of the project associated with this globus transfer
Returns: The globus transfer
Return type: GlobusTransfer
Raises: MCAPIError –

publish_dataset(project_id, dataset_id)[source]

Publish a dataset.

Parameters

project_id (int) – The id of the project containing the dataset
dataset_id (int) – The dataset id

Returns

The dataset

Return type

Raises

remove_admin_from_project(project_id, user_id)[source]

Removes admin user from project.

Parameters

project_id (int) – Id of project to add user to
user_id (int) – Id of user to remove from project

Returns

The updated project

Return type

Raises

remove_dataset_from_community(dataset_id, community_id)[source]

Remove a dataset from a community.

Parameters

dataset_id (int) –
community_id (int) –

Raises

remove_user_from_project(project_id, user_id)[source]

Remove user from project.

Parameters

project_id (int) – Id of project to add user to
user_id (int) – Id of user to add to project

Returns

The updated project

Return type

Raises

rename_directory(project_id, directory_id, name)[source]

Rename a given directory.

Parameters

project_id (int) – The project id that the directory is in
directory_id (int) – The id of the directory being renamed
name – The new name of the directory

Returns

The directory that was renamed

Return type

Raises

rename_file(project_id, file_id, name)[source]

Rename a file.

Parameters

project_id (int) – The project id of the file to rename
file_id (int) – The id of the file to rename
name (str) – The files new name

Returns

The rename file

Return type

Raises

search_published_data(search_str)[source]

Search published datasets for matching string.

Parameters: search_str (str) – string to search on
Returns: List of matches
Return type: Searchable[]
Raises: MCAPIError –

set_as_active_file(project_id, file_id)[source]

Set file as active version, changing current active file version to inactive.

Parameters

project_id (int) – The id of the project containing the file
file_id (int) – The id of the file

Returns

File

Return type

Raises

static set_debug_off()[source]: Turns debug logging off for the API.

static set_debug_on()[source]: Turns debug logging on for the API.

unpublish_dataset(project_id, dataset_id)[source]

Unpublish an published dataset.

Parameters

project_id (int) – The id of the project containing the dataset
dataset_id (int) – The dataset id

Returns

The dataset

Return type

Raises

update_dataset(project_id, dataset_id, name, attrs=None)[source]

Update an existing dataset.

Parameters

project_id (int) – The project to create the dataset in
dataset_id (int) – The id of the dataset
name (str) – The name of the dataset (doesn’t need to be different)
attrs (UpdateDatasetRequest) – The attributes to update

Returns

The updated dataset

Return type

Raises

update_dataset_activities(project_id, dataset_id, activity_id)[source]

Toggle whether an activity is in a dataset.

Parameters

project_id (int) – Project id containing dataset and activity
dataset_id (int) – Id of dataset
activity_id (int) – Id of activity

Returns

The updated dataset

Return type

Raises

update_dataset_entities(project_id, dataset_id, entity_id)[source]

Toggle whether an entity is in a dataset.

Parameters

project_id (int) – Project id containing dataset and entity
dataset_id (int) – Id of dataset
entity_id (int) – Id of entity

Returns

The updated dataset

Return type

Raises