Python API

Data Model

The Python API client is primarily a GraphQL client that interacts with our GraphQL API endpoint. The data model for the python API client and the GraphQL API are identical.

If you prefer to query our API endpoint directly, it’s available at https://graphql.cryoetdataportal.cziscience.com/v1/graphql.

A simplified diagram of the graph data model is below:

Simplified data model

API documentation

An API client library to facilitate use of the Cryo-Electron Tomography portal API. The Portal is a collection of high quality tomograms and metadata.

For more information on the API, visit the cryoet-data-portal repo: https://github.com/chanzuckerberg/cryoet-data-portal/

class cryoet_data_portal.Annotation

Metadata for an annotation

annotation_method

Describe how the annotation is made (e.g. Manual, crYoLO, Positive Unlabeled Learning, template matching)

Type:

str

annotation_publication

DOIs for publications that describe the dataset. Use a comma to separate multiple DOIs.

Type:

str

annotation_software

Software used for generating this annotation

Type:

str

authors

The annotation authors of this annotation

Type:

List[AnnotationAuthor]

confidence_precision

Describe the confidence level of the annotation. Precision is defined as the % of annotation objects being true positive

Type:

float

confidence_recall

Describe the confidence level of the annotation. Recall is defined as the % of true positives being annotated correctly

Type:

float

deposition

The deposition this annotation is a part of

Type:

Deposition

deposition_date

Date when an annotation set is initially received by the Data Portal.

Type:

date

deposition_id

If the annotation is part of a deposition, the related deposition’s id

Type:

int

files

The annotation files of this annotation

Type:

List[AnnotationFile]

ground_truth_status

Whether an annotation is considered ground truth, as determined by the annotator.

Type:

bool

ground_truth_used

Annotation filename used as ground truth for precision and recall

Type:

str

https_metadata_path

HTTPS path for the metadata json file for this annotation

Type:

str

id

Numeric identifier (May change!)

Type:

int

Data curator’s subjective choice as the best annotation of the same annotation object ID

Type:

bool

last_modified_date

Date when an annotation was last modified in the Data Portal

Type:

date

method_type

The method type for generating the annotation (e.g. manual, hybrid, automated)

Type:

str

object_count

Number of objects identified

Type:

int

object_description

A textual description of the annotation object, can be a longer description to include additional information not covered by the Annotation object name and state.

Type:

str

object_id

Gene Ontology Cellular Component identifier for the annotation object

Type:

str

object_name

Name of the object being annotated (e.g. ribosome, nuclear pore complex, actin filament, membrane)

Type:

str

object_state

Molecule state annotated (e.g. open, closed)

Type:

str

release_date

Date when annotation data is made public by the Data Portal.

Type:

date

s3_metadata_path

S3 path for the metadata json file for this annotation

Type:

str

tomogram_voxel_spacing

The tomogram voxel spacing this annotation is a part of

Type:

TomogramVoxelSpacing

tomogram_voxel_spacing_id

The ID of the tomogram voxel spacing this annotation is part of

Type:

int

download(dest_path=None, format=None, shape=None)

Download annotation files for a given format and/or shape

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

shape : Optional[str], optional

Choose a specific shape type to download (e.g.: OrientedPoint, SegmentationMask)

format : Optional[str], optional

Choose a specific file format to download (e.g.: mrc, ndjson)

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.AnnotationAuthor

Metadata for an annotation’s authors

affiliation_address

Address of the institution an annotator is affiliated with.

Type:

str

affiliation_identifier

A unique identifier assigned to the affiliated institution by The Research Organization Registry (ROR).

Type:

str

affiliation_name

Name of the institution an annotator is affiliated with. Sometimes, one annotator may have multiple affiliations.

Type:

str

annotation

The annotation this annotation author is a part of

Type:

Annotation

annotation_id

Reference to the annotation this author contributed to

Type:

int

author_list_order

The order in which the author appears in the publication

Type:

int

corresponding_author_status

Indicating whether an annotator is the corresponding author (YES or NO)

Type:

bool

email

Email address for this author

Type:

str

id

Numeric identifier for this annotation author (this may change!)

Type:

int

name

Full name of an annotation author (e.g. Jane Doe).

Type:

str

orcid

A unique, persistent identifier for researchers, provided by ORCID.

Type:

str

primary_annotator_status

Indicating whether an annotator is the main person executing the annotation, especially on manual annotation (YES or NO)

Type:

bool

primary_author_status

Indicating whether an author is the main person executing the annotation, especially on manual annotation (YES or NO)

Type:

bool

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.AnnotationFile

Metadata for an annotation file

annotation

The annotation this annotation file is a part of

Type:

Annotation

annotation_id

The ID of the annotation this file applies to

Type:

int

format

File format for this file

Type:

str

https_path

HTTPS path for this annotation file

Type:

str

id

Numeric identifier (May change!)

Type:

int

is_visualization_default

Data curator’s subjective choice of default annotation to display in visualization for an object

Type:

bool

s3_path

s3 path of the annotation file

Type:

str

shape_type

The type of the annotation

Type:

str

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.Client

A GraphQL Client library that can traverse all the metadata in the CryoET Data Portal

Parameters:
url : Optional[str]

The API URL to connect to, defaults to the latest portal endpoint.

Returns:

A GraphQL API Client library

Examples

Generate a client that connects to the default GraphQL API:

>>> client = cryoet_data_portal.Client()
class cryoet_data_portal.Dataset

Metadata for a dataset

authors

The dataset authors of this dataset

Type:

List[DatasetAuthor]

cell_component_id

If the dataset focuses on a specific part of a cell, the subset is included here

Type:

str

cell_component_name

Name of the cellular component

Type:

str

cell_name

Name of the cell from which a biological sample used in a CryoET study is derived from.

Type:

str

cell_strain_id

Link to more information about the cell strain

Type:

str

cell_strain_name

Cell line or strain for the sample.

Type:

str

cell_type_id

Cell Ontology identifier for the cell type

Type:

str

dataset_citations

DOIs for publications that cite the dataset. Use a comma to separate multiple DOIs.

Type:

str

dataset_publications

DOIs for publications that describe the dataset. Use a comma to separate multiple DOIs.

Type:

str

deposition

The deposition this dataset is a part of

Type:

Deposition

deposition_date

Date when a dataset is initially received by the Data Portal.

Type:

date

deposition_id

Reference to the deposition this dataset is associated with

Type:

int

description

A short description of a CryoET dataset, similar to an abstract for a journal article or dataset.

Type:

str

funding_sources

The dataset fundings of this dataset

Type:

List[DatasetFunding]

grid_preparation

Describe Cryo-ET grid preparation.

Type:

str

https_prefix

The https directory path where this dataset is contained

Type:

str

id

An identifier for a CryoET dataset, assigned by the Data Portal. Used to identify the dataset as the directory name in data tree

Type:

int

key_photo_thumbnail_url

URL for the thumbnail of preview image.

Type:

str

key_photo_url

URL for the dataset preview image.

Type:

str

last_modified_date

Date when a released dataset is last modified.

Type:

date

organism_name

Name of the organism from which a biological sample used in a CryoET study is derived from, e.g. homo sapiens

Type:

str

organism_taxid

NCBI taxonomy identifier for the organism, e.g. 9606

Type:

str

other_setup

Describe other setup not covered by sample preparation or grid preparation that may make this dataset unique in the same publication

Type:

str

related_database_entries

If a CryoET dataset is also deposited into another database, enter the database identifier here (e.g. EMPIAR-11445). Use a comma to separate multiple identifiers.

Type:

str

If a CryoET dataset is also deposited into another database, e.g. EMPIAR, enter the database identifier here (e.g.https://www.ebi.ac.uk/empiar/EMPIAR-12345/). Use a comma to separate multiple links.

Type:

str

release_date

Date when a dataset is made available on the Data Portal.

Type:

date

runs

The runs of this dataset

Type:

List[Run]

s3_prefix

The S3 public bucket path where this dataset is contained

Type:

str

sample_preparation

Describe how the sample was prepared.

Type:

str

sample_type

Type of samples used in a CryoET study. (cell, tissue, organism, intact organelle, in-vitro mixture, in-silico synthetic data, other)

Type:

str

tissue_id

UBERON identifier for the tissue

Type:

str

tissue_name

Name of the tissue from which a biological sample used in a CryoET study is derived from.

Type:

str

title

Title of a CryoET dataset

Type:

str

download_everything(dest_path=None)

Download all of the data for this dataset.

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.DatasetAuthor

Metadata for authors of a dataset

affiliation_address

Address of the institution an author is affiliated with.

Type:

str

affiliation_identifier

A unique identifier assigned to the affiliated institution by The Research Organization Registry (ROR).

Type:

str

affiliation_name

Name of the institutions an author is affiliated with. Comma separated

Type:

str

author_list_order

The order in which the author appears in the publication

Type:

int

corresponding_author_status

Indicating whether an author is the corresponding author

Type:

bool

dataset

The dataset this dataset author is a part of

Type:

Dataset

dataset_id

Numeric identifier for the dataset this author corresponds to

Type:

int

email

Email address for each author

Type:

str

id

A numeric identifier for this author (May change!)

Type:

int

name

Full name of a dataset author (e.g. Jane Doe).

Type:

str

orcid

A unique, persistent identifier for researchers, provided by ORCID.

Type:

str

primary_author_status

Indicating whether an author is the main person associated with the corresponding dataset

Type:

bool

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.DatasetFunding

Metadata for a dataset’s funding sources

dataset

The dataset this dataset funding is a part of

Type:

Dataset

dataset_id

Numeric identifier for the dataset this funding source corresponds to

Type:

int

funding_agency_name

Name of the funding agency.

Type:

str

grant_id

Grant identifier provided by the funding agency.

Type:

str

id

A numeric identifier for this funding record (May change!)

Type:

int

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.Deposition

Deposition metadata

annotations

The annotations of this deposition

Type:

List[Annotation]

authors

The deposition authors of this deposition

Type:

List[DepositionAuthor]

dataset

The datasets of this deposition

Type:

List[Dataset]

deposition_date

The date the deposition was deposited

Type:

date

deposition_publications

The publications related to this deposition

Type:

str

deposition_types

The types of data submitted as a part of this deposition

Type:

str

description

Description for the deposition

Type:

str

https_prefix

The https directory path where data about this deposition is contained

Type:

str

id

Numeric identifier for this depositions

Type:

int

key_photo_thumbnail_url

URL for the deposition thumbnail image.

Type:

str

key_photo_url

URL for the deposition preview image.

Type:

str

last_modified_date

The date the deposition was last modified

Type:

date

related_database_entries

The related database entries to this deposition

Type:

str

release_date

The date the deposition was released

Type:

date

s3_prefix

The S3 public bucket path where data about this deposition is contained

Type:

str

tiltseries

The tilt series of this deposition

Type:

List[TiltSeries]

title

Title for the deposition

Type:

str

tomograms

The tomograms of this deposition

Type:

List[Tomogram]

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.DepositionAuthor

Authors for a deposition

affiliation_address

Address of the institution an author is affiliated with.

Type:

str

affiliation_identifier

A unique identifier assigned to the affiliated institution by The Research Organization Registry (ROR).

Type:

str

affiliation_name

Name of the institution an author is affiliated with.

Type:

str

author_list_order

The order in which the author appears in the publication

Type:

int

corresponding_author_status

Indicates whether an author is the corresponding author

Type:

bool

deposition

The deposition this deposition author is a part of

Type:

Deposition

deposition_id

Reference to the deposition this author contributed to

Type:

int

email

Email address for this author

Type:

str

id

Numeric identifier for this deposition author (this may change!)

Type:

int

name

Full name of a deposition author (e.g. Jane Doe).

Type:

str

orcid

A unique, persistent identifier for researchers, provided by ORCID.

Type:

str

primary_author_status

Indicates whether an author is the main person creating the deposition

Type:

bool

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.Run

Metadata for an experiment run

dataset

The dataset this run is a part of

Type:

Dataset

dataset_id

Reference to the dataset this run is a part of

Type:

int

https_prefix

The HTTPS directory path where this dataset is contained

Type:

str

id

Numeric identifier (May change!)

Type:

int

name

Short name for this experiment run

Type:

str

s3_prefix

The S3 public bucket path where this dataset is contained

Type:

str

tiltseries

The tilt series of this run

Type:

List[TiltSeries]

tomogram_voxel_spacings

The tomogram voxel spacings of this run

Type:

List[TomogramVoxelSpacing]

download_everything(dest_path=None)

Download all of the data for this run.

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.TiltSeries

Metadata about how a tilt series was generated, and locations of output files

acceleration_voltage

Electron Microscope Accelerator voltage in volts

Type:

int

aligned_tiltseries_binning

Binning factor of the aligned tilt series

Type:

int

binning_from_frames

Describes the binning factor from frames to tilt series file

Type:

float

camera_manufacturer

Name of the camera manufacturer

Type:

str

camera_model

Camera model name

Type:

str

data_acquisition_software

Software used to collect data

Type:

str

deposition

The deposition this tilt series is a part of

Type:

Deposition

deposition_id

Reference to the deposition this tiltseries is associated with

Type:

int

frames_count

Number of frames associated to the tilt series

Type:

int

https_alignment_file

HTTPS path to the alignment file for this tiltseries

Type:

str

https_angle_list

HTTPS path to the angle list file for this tiltseries

Type:

str

https_collection_metadata

HTTPS path to the collection metadata file for this tiltseries

Type:

str

https_mrc_bin1

HTTPS path to this tiltseries in MRC format (no scaling)

Type:

str

https_omezarr_dir

HTTPS path to this tomogram in multiscale OME-Zarr format

Type:

str

id

Numeric identifier for this tilt series (this may change!)

Type:

int

is_aligned

Tilt series is aligned

Type:

bool

microscope_additional_info

Other microscope optical setup information, in addition to energy filter, phase plate and image corrector

Type:

str

microscope_energy_filter

Energy filter setup used

Type:

str

microscope_image_corrector

Image corrector setup

Type:

str

microscope_manufacturer

Name of the microscope manufacturer

Type:

str

microscope_model

Microscope model name

Type:

str

microscope_phase_plate

Phase plate configuration

Type:

str

pixel_spacing

Pixel spacing equal in both axes in angstroms

Type:

float

related_empiar_entry

If a tilt series is deposited into EMPIAR, the EMPIAR dataset identifier

Type:

str

run

The run this tilt series is a part of

Type:

Run

run_id

The ID of the experimental run this tilt series is part of

Type:

int

s3_alignment_file

S3 path to the alignment file for this tilt series

Type:

str

s3_angle_list

S3 path to the angle list file for this tilt series

Type:

str

s3_collection_metadata

S3 path to the collection metadata file for this tiltseries

Type:

str

s3_mrc_bin1

S3 path to this tiltseries in MRC format (no scaling)

Type:

str

s3_omezarr_dir

S3 path to this tomogram in multiscale OME-Zarr format

Type:

str

spherical_aberration_constant

Spherical Aberration Constant of the objective lens in millimeters

Type:

float

tilt_axis

Rotation angle in degrees

Type:

float

tilt_max

Maximal tilt angle in degrees

Type:

float

tilt_min

Minimal tilt angle in degrees

Type:

float

tilt_range

Total tilt range in degrees

Type:

float

tilt_series_quality

Author assessment of tilt series quality within the dataset (1-5, 5 is best)

Type:

int

tilt_step

Tilt step in degrees

Type:

float

tilting_scheme

The order of stage tilting during acquisition of the data

Type:

str

total_flux

Number of Electrons reaching the specimen in a square Angstrom area for the entire tilt series

Type:

float

download_alignment_file(dest_path=None)

Download the alignment file for this tiltseries

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

download_angle_list(dest_path=None)

Download the angle list for this tiltseries

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

download_collection_metadata(dest_path=None)

Download the collection metadata for this tiltseries

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

download_mrcfile(dest_path=None)

Download an MRC file for this tiltseries

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

download_omezarr(dest_path=None)

Download the omezarr version of this tiltseries

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.Tomogram

Metadata for a tomogram

affine_transformation_matrix

The flip or rotation transformation of this author submitted tomogram is indicated here

Type:

str

authors

The tomogram authors of this tomogram

Type:

List[TomogramAuthor]

ctf_corrected

Whether this tomogram is CTF corrected

Type:

bool

deposition

The deposition this tomogram is a part of

Type:

Deposition

deposition_id

If the tomogram is part of a deposition, the related deposition’s id

Type:

int

fiducial_alignment_status

Fiducial Alignment status: True = aligned with fiducial False = aligned without fiducial

Type:

str

https_mrc_scale0

HTTPS path to this tomogram in MRC format (no scaling)

Type:

str

https_omezarr_dir

HTTPS path to this tomogram in multiscale OME-Zarr format

Type:

str

id

Numeric identifier for this tomogram (this may change!)

Type:

int

is_canonical

Is this tomogram considered the canonical tomogram for the run experiment? True=Yes

Type:

bool

key_photo_thumbnail_url

URL for the thumbnail of key photo

Type:

str

key_photo_url

URL for the key photo

Type:

str

name

Short name for this tomogram

Type:

str

neuroglancer_config

the compact json of neuroglancer config

Type:

str

offset_x

x offset data relative to the canonical tomogram in pixels

Type:

int

offset_y

y offset data relative to the canonical tomogram in pixels

Type:

int

offset_z

z offset data relative to the canonical tomogram in pixels

Type:

int

processing

Describe additional processing used to derive the tomogram

Type:

str

processing_software

Processing software used to derive the tomogram

Type:

str

reconstruction_method

Describe reconstruction method (Weighted back-projection, SART, SIRT)

Type:

str

reconstruction_software

Name of software used for reconstruction

Type:

str

s3_mrc_scale0

S3 path to this tomogram in MRC format (no scaling)

Type:

str

s3_omezarr_dir

S3 path to this tomogram in multiscale OME-Zarr format

Type:

str

scale0_dimensions

comma separated x,y,z dimensions of the unscaled tomogram

Type:

str

scale1_dimensions

comma separated x,y,z dimensions of the scale1 tomogram

Type:

str

scale2_dimensions

comma separated x,y,z dimensions of the scale2 tomogram

Type:

str

size_x

Number of pixels in the 3D data fast axis

Type:

int

size_y

Number of pixels in the 3D data medium axis

Type:

int

size_z

Number of pixels in the 3D data slow axis. This is the image projection direction at zero stage tilt

Type:

int

tomogram_version

Version of tomogram using the same software and post-processing. Version of tomogram using the same software and post-processing. This will be presented as the latest version

Type:

str

tomogram_voxel_spacing

The tomogram voxel spacing this tomogram is a part of

Type:

TomogramVoxelSpacing

tomogram_voxel_spacing_id

The ID of the tomogram voxel spacing this tomogram is part of

Type:

int

type

Tomogram purpose (ex: CANONICAL)

Type:

str

voxel_spacing

Voxel spacing equal in all three axes in angstroms

Type:

float

download_all_annotations(dest_path=None, format=None, shape=None)

Download all annotation files for this tomogram

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

shape : Optional[str], optional

Choose a specific shape type to download (e.g.: OrientedPoint, SegmentationMask)

format : Optional[str], optional

Choose a specific file format to download (e.g.: mrc, ndjson)

download_mrcfile(dest_path=None)

Download an MRC file of this tomogram

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

download_omezarr(dest_path=None)

Download the OME-Zarr version of this tomogram

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.TomogramAuthor

Metadata for a tomogram’s authors

affiliation_address

Address of the institution an author is affiliated with.

Type:

str

affiliation_identifier

A unique identifier assigned to the affiliated institution by The Research Organization Registry (ROR).

Type:

str

affiliation_name

Name of the institution an annotator is affiliated with. Sometimes, one annotator may have multiple affiliations.

Type:

str

author_list_order

The order in which the author appears in the publication

Type:

int

corresponding_author_status

Indicating whether an author is the corresponding author (YES or NO)

Type:

bool

email

Email address for this author

Type:

str

id

Numeric identifier for this tomogram author (this may change!)

Type:

int

name

Full name of an author (e.g. Jane Doe).

Type:

str

orcid

A unique, persistent identifier for researchers, provided by ORCID.

Type:

str

primary_author_status

Indicating whether an author is the main person creating the tomogram (YES or NO)

Type:

bool

tomogram

The tomogram this tomogram author is a part of

Type:

Tomogram

tomogram_id

Reference to the tomogram this author contributed to

Type:

int

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes

class cryoet_data_portal.TomogramVoxelSpacing

Metadata for a given voxel spacing related to tomograms and annotations

annotations

The annotations of this tomogram voxel spacing

Type:

List[Annotation]

https_prefix

The HTTPS directory path where this tomogram voxel spacing is contained

Type:

str

id

Numeric identifier (May change!)

Type:

int

run

The run this tomogram voxel spacing is a part of

Type:

Run

run_id

The ID of the run this tomogram voxel spacing is a part of

Type:

int

s3_prefix

The S3 public bucket path where this tomogram voxel spacing is contained

Type:

str

tomograms

The tomograms of this tomogram voxel spacing

Type:

List[Tomogram]

voxel_spacing

The voxel spacing for the tomograms in this set in angstroms

Type:

float

download_everything(dest_path=None)

Download all of the data for this tomogram voxel spacing.

Parameters:
dest_path : Optional[str], optional

Choose a destination directory. Defaults to $CWD.

classmethod find(client, query_filters=None)

Find objects based on a set of search filters.

Search filters are combined with and so all results will match all filters.

Expressions with python-native operators (==, !=, >, >=, <, <=) must be in the format:

ModelSubclass.field {operator} {value}

Example:

  • Tomogram.voxel_spacing.run.name == "RUN1"

Expressions with method operators (like, ilike, _in) must be in the format:

ModelSubclass.field.{operator}({value})

Examples:

  • Tomogram.voxel_spacing.run.name.like("%RUN1%")

  • Tomogram.voxel_spacing.run.name._in(["RUN1", "RUN2"])

Supported operators are: ==, !=, >, >=, <, <=, like, ilike, _in

  • like is a partial match, with the % character being a wildcard

  • ilike is similar to like but case-insensitive

  • _in accepts a list of values that are acceptable matches.

Values may be strings or numbers depending on the type of the field being matched, and _in supports a list of values of the field’s corresponding type.

ModelSubclass.field may be an arbitrarily nested path to any field on any related model, such as:

ModelSubclass.related_class_field.related_field.second_related_class_field.second_field

Parameters:
client

A CryoET Portal API Client

query_filters=None

A set of expressions that narrow down the search results

Yields:

Matching Model objects.

Examples

Filter runs by attributes, including attributes in related models:

>>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000])
>>> runs = Run.find(client, query_filters=[Run.name._in(['TS_026', 'TS_027']), Run.tomogram_voxel_spacings.annotations.object_name.ilike('%membrane%')])

Get all results for this type:

>>> runs = Run.find(client)
classmethod get_by_id(client, id)

Find objects by primary key

Parameters:
client

A CryoET Portal API Client

id

Unique identifier for the object

Returns:

A matching Model object if found, None otherwise.

Examples

Get a Run by ID:

>>> run = Run.get_by_id(client, 1)
    print(run.name)
to_dict()

Return a dictionary representation of this object’s attributes