From 8c6cb984e80b4830136f863cc2501bfb59bd6dec Mon Sep 17 00:00:00 2001 From: Andy Sweet Date: Thu, 14 Dec 2023 14:59:29 -0800 Subject: [PATCH] Update Python API reference docs based on latest GraphQL schema (#282) The main contribution of this PR is to update the Python API reference docs with the new classes added in the recent schema change (`TomogramAuthor` and `AnnotationFile`). In addition, there are few other documentation related changes. 1\. Updated quick start to reflect other API changes (e.g. removing `binning` keyword argument from `download_mrcfile`). 2\. Added the upgrade option to the napari plugin, so that its dependencies (like the Python client in this repo) are upgraded when there is an existing installation. 3\. Fixed the examples in the base model so that they work with the current schema. 4\. Fixed some typos and small mistakes in the model docstrings. 5\. Enforced a version of Sphinx pre v7 to prevent an error when building the HTML docs. The error is `Reason: UndefinedError("'style' is undefined")` and is likely related to the Sphinx RTD theme not supporting Sphinx v7. The [corresponding issue](https://github.com/readthedocs/readthedocs.org/issues/10279) should be fixed for v2 of the theme, but I did not find that to be the case. --- .../src/cryoet_data_portal/_gql_base.py | 12 +++++----- .../src/cryoet_data_portal/_models.py | 22 +++++++++---------- docs/cryoet_data_portal_docsite_napari.md | 2 +- .../cryoet_data_portal_docsite_quick_start.md | 4 ++-- docs/python-api.rst | 12 ++++++++++ docs/requirements.txt | 1 + 6 files changed, 33 insertions(+), 20 deletions(-) diff --git a/client/python/cryoet_data_portal/src/cryoet_data_portal/_gql_base.py b/client/python/cryoet_data_portal/src/cryoet_data_portal/_gql_base.py index 801048976..cc7d17592 100644 --- a/client/python/cryoet_data_portal/src/cryoet_data_portal/_gql_base.py +++ b/client/python/cryoet_data_portal/src/cryoet_data_portal/_gql_base.py @@ -239,18 +239,18 @@ def find( query_filters: A set of expressions that narrow down the search results - Returns: - A list of matching Model objects. + Yields: + Matching Model objects. Examples: Filter runs by attributes, including attributes in related models: - >>> runs_list = Runs.find(client, query_filters=[Runs.camera_model == "K2 Summit", Runs.tomograms.size_x > 900]) + >>> runs = Run.find(client, query_filters=[Run.name == "TS_026", Run.dataset.id == 10000]) Get all results for this type: - >>> runs_object = Runs.find(client) + >>> runs = Run.find(client) """ filters = {} if query_filters: @@ -269,12 +269,12 @@ def get_by_id(cls, client: Client, id: int): Unique identifier for the object Returns: - A matching Model object. + A matching Model object if found, None otherwise. Examples: Get a Run by ID: - >>> run = Runs.get_by_id(client), 1 + >>> run = Run.get_by_id(client, 1) print(run.name) """ results = cls.find(client, [cls.id == id]) diff --git a/client/python/cryoet_data_portal/src/cryoet_data_portal/_models.py b/client/python/cryoet_data_portal/src/cryoet_data_portal/_models.py index 45d8b921f..51c87e575 100644 --- a/client/python/cryoet_data_portal/src/cryoet_data_portal/_models.py +++ b/client/python/cryoet_data_portal/src/cryoet_data_portal/_models.py @@ -29,7 +29,7 @@ class Dataset(Model): cell_type_id (str): Cell Ontology identifier for the cell type dataset_citations (str): DOIs for publications that cite the dataset. Use a comma to separate multiple DOIs. dataset_publications (str): DOIs for publications that describe the dataset. Use a comma to separate multiple DOIs. - deposition_date: date! Date when a dataset is initially received by the Data Portal. + deposition_date: Date when a dataset is initially received by the Data Portal. description (str): A short description of a CryoET dataset, similar to an abstract for a journal article or dataset. funding_sources: List[FundingSource] An array relationship with FundingSource grid_preparation (str): Describe Cryo-ET grid preparation. @@ -41,7 +41,7 @@ class Dataset(Model): organism_taxid (str): NCBI taxonomy identifier for the organism, e.g. 9606 other_setup (str): Describe other setup not covered by sample preparation or grid preparation that may make this dataset unique in the same publication related_database_entries (str): 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. - related_database_links (str): If a CryoET dataset is also deposited into another database, e.g. EMPAIR, enter the database identifier here (e.g.https://www.ebi.ac.uk/empiar/EMPIAR-12345/). Use a comma to separate multiple links. + related_database_links (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. release_date (date): Date when a dataset is made available on the Data Portal. runs: List[Run] An array relationship with Run s3_prefix (str): The S3 public bucket path where this dataset is contained @@ -115,9 +115,9 @@ class DatasetAuthor(Model): affiliation_name (str): Name of the institutions an author is affiliated with. Comma separated author_list_order(int): The order in which the author appears in the publication corresponding_author_status (bool):Indicating whether an author is the corresponding author - dataset (Dataset): An object relationship with the dataset this author correspods to + dataset (Dataset): An object relationship with the dataset this author corresponds to dataset_id (int): Numeric identifier for the dataset this author corresponds to - email (str): Email address for each autho + email (str): Email address for each author name (str): Full name of a dataset author (e.g. Jane Doe). primary_author_status (bool): Indicating whether an annotator is the main person executing the annotation, especially on manual annotation orcid (str): A unique, persistent identifier for researchers, provided by ORCID. @@ -145,7 +145,7 @@ class DatasetFunding(Model): Attributes: id (int): A numeric identifier for this funding record - dataset (Dataset): An object relationship with the dataset this funding source correspods to + dataset (Dataset): An object relationship with the dataset this funding source corresponds to dataset_id (int): Numeric identifier for the dataset this funding source corresponds to funding_agency_name (str): Name of the funding agency. grant_id (str): Grant identifier provided by the funding agency. @@ -263,7 +263,7 @@ class Tomogram(Model): dataset_id (int): Reference to the dataset this tomogram is a part of fiducial_alignment_status (str): Fiducial Alignment status: True = aligned with fiducial False = aligned without fiducial https_mrc_scale0 (str): HTTPS path to this tomogram in MRC format (no scaling) - https_omezarr_dir (str): HTTPS path to the this multiscale omezarr tomogram + https_omezarr_dir (str): HTTPS path to this tomogram in multiscale OME-Zarr format is_canonical (bool): Is this tomogram considered the canonical tomogram for the run experiment? True=Yes key_photo_url (str): URL for the key photo key_photo_thumbnail_url (str): URL for the thumbnail of key photo @@ -274,10 +274,10 @@ class Tomogram(Model): offset_z (int): z offset data relative to the canonical tomogram in pixels processing (str): Describe additional processing used to derive the tomogram processing_software (str): Processing software used to derive the tomogram - reconstruction_method (str):Describe reconstruction method (Weighted backprojection, SART, SIRT) + reconstruction_method (str):Describe reconstruction method (Weighted back-projection, SART, SIRT) reconstruction_software (str):Name of software used for reconstruction s3_mrc_scale0 (str):S3 path to this tomogram in MRC format (no scaling) - s3_omezarr_dir (str):S3 path to the this multiscale omezarr tomogram + s3_omezarr_dir (str):S3 path to this tomogram in multiscale OME-Zarr format scale0_dimensions (str):comma separated x,y,z dimensions of the unscaled tomogram scale1_dimensions (str):comma separated x,y,z dimensions of the scale1 tomogram scale2_dimensions (str):comma separated x,y,z dimensions of the scale2 tomogram @@ -335,7 +335,7 @@ class Tomogram(Model): ) def download_omezarr(self, dest_path: Optional[str] = None): - """Download the omezarr version of this tomogram + """Download the OME-Zarr version of this tomogram Args: dest_path (Optional[str], optional): Choose a destination directory. Defaults to $CWD. @@ -564,7 +564,7 @@ class TiltSeries(Model): https_angle_list (str): HTTPS path to the angle list file for this tiltseries https_collection_metadata (str): HTTPS path to the collection metadata file for this tiltseries https_mrc_bin1 (str): HTTPS path to this tiltseries in MRC format (no scaling) - https_omezarr_dir (str): HTTPS path to the this multiscale omezarr tiltseries + https_omezarr_dir (str): HTTPS path to this tomogram in multiscale OME-Zarr format microscope_additional_info (str): Other microscope optical setup information, in addition to energy filter, phase plate and image corrector microscope_energy_filter: (str): Energy filter setup used microscope_image_corrector (str): Image corrector setup @@ -576,7 +576,7 @@ class TiltSeries(Model): s3_angle_list (str): S3 path to the angle list file for this tiltseries s3_collection_metadata (str): S3 path to the collection metadata file for this tiltseries s3_mrc_bin1 (str): S3 path to this tiltseries in MRC format (no scaling) - s3_omezarr_dir (str): S3 path to the this multiscale omezarr tiltseries + s3_omezarr_dir (str): S3 path to this tomogram in multiscale OME-Zarr format spherical_aberration_constant (float): Spherical Aberration Constant of the objective lens in millimeters tilt_axis (float): Rotation angle in degrees tilt_max (float): Maximal tilt angle in degrees diff --git a/docs/cryoet_data_portal_docsite_napari.md b/docs/cryoet_data_portal_docsite_napari.md index 641d79a4b..405465ea8 100644 --- a/docs/cryoet_data_portal_docsite_napari.md +++ b/docs/cryoet_data_portal_docsite_napari.md @@ -122,7 +122,7 @@ We also built [a plugin that lets you browse the CryoET Data Portal in napari](h This plugin can be installed from PyPI by running ```shell -pip install napari-cryoet-data-portal +pip install -U napari-cryoet-data-portal ``` After installation, navigate to napari's *Plugins* menu and click on the *CryoET Data Portal* item to open the browser. diff --git a/docs/cryoet_data_portal_docsite_quick_start.md b/docs/cryoet_data_portal_docsite_quick_start.md index 52d75e745..7bd087b8f 100644 --- a/docs/cryoet_data_portal_docsite_quick_start.md +++ b/docs/cryoet_data_portal_docsite_quick_start.md @@ -86,8 +86,8 @@ for tomo in tomos: # Print the tomogram metadata as a json string print(json.dumps(tomo.to_dict(), indent=4)) - # Download a 25% size preview image (uncomment to actually download files) - # tomo.download_mrcfile(binning=4) + # Download a tomogram in the MRC format (uncomment to actually download files) + # tomo.download_mrcfile() ``` Downloads display a progress bar by default: diff --git a/docs/python-api.rst b/docs/python-api.rst index 2d073d5d1..ff31a27c2 100644 --- a/docs/python-api.rst +++ b/docs/python-api.rst @@ -55,12 +55,24 @@ Tomogram :members: :inherited-members: +TomogramAuthor +-------------- +.. autoclass:: cryoet_data_portal.TomogramAuthor + :members: + :inherited-members: + Annotation -------------- .. autoclass:: cryoet_data_portal.Annotation :members: :inherited-members: +AnnotationFile +-------------- +.. autoclass:: cryoet_data_portal.AnnotationFile + :members: + :inherited-members: + AnnotationAuthor ---------------- .. autoclass:: cryoet_data_portal.AnnotationAuthor diff --git a/docs/requirements.txt b/docs/requirements.txt index 4ea283f4d..fac16a303 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ +sphinx<7 nbsphinx myst-parser sphinx-rtd-theme