diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index b2ca25e8d..21ebc49a5 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -20,6 +20,7 @@ html, body { --md-primary-fg-color: #A2C9FF; --md-code-bg-color: #494949; --md-code-fg-color: #FFFFFF; + --sd-color-card-border: var(--md-default-fg-color--light); } /* Header */ @@ -263,7 +264,7 @@ dl.py.attribute.objdesc > dd > p { margin-bottom: 0; } -.md-typeset blockquote, .md-typeset dl, .md-typeset figure, .md-typeset ol, .md-typeset pre, .md-typeset ul { +.md-typeset blockquote, .md-typeset dl, .md-typeset ol, .md-typeset pre, .md-typeset ul { margin-top: 0; margin-bottom: 0; } @@ -325,3 +326,34 @@ dl.class > dd > dl:nth-child(27) { box-shadow: none; border-bottom: 0.01px solid var(--md-default-fg-color--lightest); } + +/* Figure/video captions */ +.md-typeset figcaption { + min-width: 75%; + max-width: fit-content; + text-align: justify; + font-size: small; + margin-top: 0px; +} + +/* Better spacing around figure elements */ +.md-typeset figure { + margin-top: 30px; +} + +.md-typeset figure img { + margin: auto; +} + +/* Landing page button */ +.sd-btn { + font-size: 0.75rem; +} + +/* Centered quote */ +div .centered-quote { + text-align: center; + font-style: italic; + max-width: 24rem; + margin: auto; +} diff --git a/docs/_static/img/intro_movie.mp4 b/docs/_static/img/intro_movie.mp4 new file mode 100644 index 000000000..742ff9288 Binary files /dev/null and b/docs/_static/img/intro_movie.mp4 differ diff --git a/docs/_static/img/intro_movie.png b/docs/_static/img/intro_movie.png new file mode 100644 index 000000000..eb038f6fc Binary files /dev/null and b/docs/_static/img/intro_movie.png differ diff --git a/docs/_static/img/resolution_ranges.png b/docs/_static/img/resolution_ranges.png new file mode 100644 index 000000000..7222b0547 Binary files /dev/null and b/docs/_static/img/resolution_ranges.png differ diff --git a/docs/_static/img/schematics_subtomogram.png b/docs/_static/img/schematics_subtomogram.png new file mode 100644 index 000000000..aa5d21ec2 Binary files /dev/null and b/docs/_static/img/schematics_subtomogram.png differ diff --git a/docs/_static/img/schematics_transmission.png b/docs/_static/img/schematics_transmission.png new file mode 100644 index 000000000..058a67990 Binary files /dev/null and b/docs/_static/img/schematics_transmission.png differ diff --git a/docs/_static/img/schematics_vitrification.png b/docs/_static/img/schematics_vitrification.png new file mode 100644 index 000000000..3208e7e22 Binary files /dev/null and b/docs/_static/img/schematics_vitrification.png differ diff --git a/docs/_static/img/schematics_workflow.png b/docs/_static/img/schematics_workflow.png new file mode 100644 index 000000000..80f8723a6 Binary files /dev/null and b/docs/_static/img/schematics_workflow.png differ diff --git a/docs/_toc.yml b/docs/_toc.yml index 4c74077c8..d8fa64ef5 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -5,13 +5,17 @@ subtrees: title: "Home" - file: cryoet_data_portal_docsite_quick_start.md - file: python-api.md - - file: cryoet_data_portal_docsite_data.md - file: tutorials.md subtrees: - entries: + - file: cryoet_data_portal_docsite_aws.md - file: cryoet_data_portal_docsite_examples.md + - file: cryoet_data_portal_docsite_napari.md - file: tutorial_sample_boundaries.md + - file: about.md + subtrees: + - entries: + - file: intro_cryoet.md + - file: cryoet_data_portal_docsite_data.md - file: cryoet_data_portal_docsite_faq.md title: "FAQ" - - file: cryoet_data_portal_docsite_aws.md - - file: cryoet_data_portal_docsite_napari.md diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 000000000..3bad4a859 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,25 @@ +--- +hide-navigation: true +--- + +# About CryoET + +Learn about CryoET data and how to navigate the CryoET Data Portal. + +::::{grid} 1 1 2 2 +:gutter: 2 + +:::{grid-item-card} Introduction to CryoET +:link: cryoet-intro +:link-type: ref + +Learn about the capabilities and acquisition of CryoET data +::: + +:::{grid-item-card} Data Organization +:link: data-organization +:link-type: ref + +Guide on how the CryoET Data Portal is organized +::: +:::: diff --git a/docs/conf.py b/docs/conf.py index 7d022ff96..06964ddab 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,6 +26,7 @@ "myst_nb", "sphinx_immaterial", "sphinx_external_toc", + "sphinx_design", ] napoleon_custom_sections = ["Lifecycle"] diff --git a/docs/cryoet_data_portal_docsite_aws.md b/docs/cryoet_data_portal_docsite_aws.md index d2939140a..1ca63c725 100644 --- a/docs/cryoet_data_portal_docsite_aws.md +++ b/docs/cryoet_data_portal_docsite_aws.md @@ -1,7 +1,4 @@ ---- -hide-navigation: true ---- - +(download-data)= # Download Data ## Download data using AWS CLI diff --git a/docs/cryoet_data_portal_docsite_data.md b/docs/cryoet_data_portal_docsite_data.md index 305a49e6c..a9aafc141 100644 --- a/docs/cryoet_data_portal_docsite_data.md +++ b/docs/cryoet_data_portal_docsite_data.md @@ -2,7 +2,7 @@ tocdepth: 2 hide-navigation: true --- - +(data-organization)= # Data Organization The Data Portal is organized in a hierarchical structure. We welcome contributions to the Portal. [Use this form](https://airtable.com/apppmytRJXoXYTO9w/shr5UxgeQcUTSGyiY?prefill_Event=Portal\&hide_Event=true) to express interest in adding your data to the Portal. diff --git a/docs/cryoet_data_portal_docsite_examples.md b/docs/cryoet_data_portal_docsite_examples.md index 0c5a5635b..253301f86 100644 --- a/docs/cryoet_data_portal_docsite_examples.md +++ b/docs/cryoet_data_portal_docsite_examples.md @@ -1,3 +1,4 @@ +(examples)= # Examples Below are code snippets for completing various tasks using the Python Client API. Have an example you'd like to share with the community? Submit a [GitHub issue](https://github.com/chanzuckerberg/cryoet-data-portal/issues) and include "Example:" in your title. diff --git a/docs/cryoet_data_portal_docsite_landing.md b/docs/cryoet_data_portal_docsite_landing.md index 5220f5524..b9cb14635 100644 --- a/docs/cryoet_data_portal_docsite_landing.md +++ b/docs/cryoet_data_portal_docsite_landing.md @@ -6,6 +6,13 @@ hide-navigation: true The [Chan Zuckerberg Institute for Advanced Biological Imaging (CZ Imaging Institute)](https://www.czimaginginstitute.org/) has made a beta release of the [CryoET Data Portal](https://cryoetdataportal.czscience.com) providing queryable and organized data from CryoET experiments. Each of the over 15,000 tomograms on the Portal have at least one structure annotated. +```{button-ref} data-organization +:color: primary +:align: center + +Learn about the Data Schema +``` + This site provides additional documentation for using our [Python API](python-api) to query and download data and for navigating the [CryoET Data Portal](https://cryoetdataportal.czscience.com) and its visualization tools. We hope this site will assist segmentation algorithm developers to produce annotations for diverse macromolecules in the tomograms that may be used for high-resolution subtomogram averaging. We welcome feedback from the community on the data structure, design and functionality. @@ -15,10 +22,37 @@ We welcome feedback from the community on the data structure, design and functio ## Getting Started -- [Installation](cryoet_data_portal_docsite_quick_start) -- [Python Client API Reference](python-api) -- [Tutorials](tutorials) -- [napari Plugin Documentation](cryoet_data_portal_docsite_napari) +::::{grid} 1 1 2 2 +:gutter: 2 + +:::{grid-item-card} Get Started +:link: quick-start +:link-type: ref + +Install and start using the Python Client API +::: + +:::{grid-item-card} API Reference +:link: api-documentation +:link-type: ref + +Information on the Python Client API Classes +::: + +:::{grid-item-card} Tutorials +:link: tutorials +:link-type: doc + +Examples of selecting, downloading, and visualizing data from the Portal +::: + +:::{grid-item-card} About CryoET +:link: about +:link-type: doc + +Learn about CryoET data and how to navigate the CryoET Data Portal +::: +:::: ## Amazon Web Services S3 Bucket Info @@ -34,23 +68,7 @@ To list the bucket contents with the S3 CLI without credentials, please use the aws s3 ls --no-sign-request s3://cryoet-data-portal-public ``` -## CryoET Workflow Overview - - -```{image} https://github.com/chanzuckerberg/cryoet-data-portal/assets/100323416/dc425098-d949-479f-b2f2-325f1c944784 -:alt: CZII Graphic Github -:align: center -``` - -Electron Tomography workflow and the data we provide. - -**A.** Sample is rotated to different tilt angles and electrons pass through to produce projection images of the 3D volume - -**B.** We provide raw movie frames collected by a direct detector and may also provide these stacked into a tilt series of images - -**C.** A 3D tomographic reconstructed volume is produced by back projecting projections which are first corrected in a variety of ways (motion correction, CTF estimation, etc.) - -**D.** We provide the 3D volume together with any available point annotations or semantic segmentations of macromolecular complexes for each volume +Refer to [this how-to guide](download-data) for information on downloading data from our AWS S3 bucket. ## Citing the CryoET Data Portal diff --git a/docs/cryoet_data_portal_docsite_napari.md b/docs/cryoet_data_portal_docsite_napari.md index 6d3ce508e..083c8de2a 100644 --- a/docs/cryoet_data_portal_docsite_napari.md +++ b/docs/cryoet_data_portal_docsite_napari.md @@ -1,7 +1,4 @@ ---- -hide-navigation: true ---- - +(using-napari)= # Using napari [napari](https://napari.org) is a general purpose interactive image viewer for Python diff --git a/docs/cryoet_data_portal_docsite_quick_start.md b/docs/cryoet_data_portal_docsite_quick_start.md index 3fb5397a4..66e1734dd 100644 --- a/docs/cryoet_data_portal_docsite_quick_start.md +++ b/docs/cryoet_data_portal_docsite_quick_start.md @@ -2,6 +2,7 @@ hide-navigation: true --- +(quick-start)= # Quick start This page provides details to help you get started using the CryoET Data Portal Client API. diff --git a/docs/intro_cryoet.md b/docs/intro_cryoet.md new file mode 100644 index 000000000..a9a61bc16 --- /dev/null +++ b/docs/intro_cryoet.md @@ -0,0 +1,186 @@ +--- +hide-navigation: true +--- + +(cryoet-intro)= +# Introduction to CryoET + +
+"You can observe a lot by watching..." When it comes to biological machinery +you can't see, CryoET promises to let researchers view the whole picture. +
+ +## What is CryoET? + +Cryo-electron tomography (CryoET) is a technique that provides researchers with +a 3D view of cells, subcellular components (e.g., organelles), viruses, and +proteins. Detailed 3D image reconstructions generated through CryoET enable +researchers to answer questions that are critical for understanding cellular +function and response, such as: + +- How are subcellular components and proteins spatially organized within a cell? +- How do subcellular components and proteins interact with each other? +- How do cells change in response to stress, injury, or disease? +- How do infectious agents interact with host cells? + +
+ +
Cryo-electron tomogram of a sectioned spore from the intracellular + parasite Encephalitozoon intestinalis. The video shows tomographic slices along + the depth dimension of the volume (left) and voxel segmentations of various parts + of the infection machinery (right). Encephalitozoon intestinalis is an + opportunistic human pathogen that uses a harpoon-like apparatus called the polar + tube to invade host cells. CryoET helped investigate the infection mechanism + through the polar tube. When activated, the specialized polaroplast organelle + swells and causes the polar tube to be expelled and catapulted through the host + cell membrane, allowing injection of infectious material. This + run is available + on the CryoET data portal as part of + dataset 10437 + and was generously contributed by Usmani et. al as supporting material for + their E. intestinalis study. +
+
+ +## What makes CryoET special? + +Thanks to CryoET, researchers can now bridge the gap between techniques that +enable them to study cells at the micron scale (e.g., light microscopy) and +molecular structures at the atomic-level (e.g., X-ray crystallography). Although +there are other techniques that generate 3D models of subcellular components, +viruses, and proteins, these techniques require isolation of single particles. +CryoET is the only technique that enables researchers to study biological +samples in their native environment at near atomic resolution while providing +context about their location, conformation, and interactions within a cell or +medium. It is a powerful technique that can provide structural information at a +range of resolutions, from whole cells to molecules, including the atomic +structure of particles with resolutions near 3 angstrom (Å; 1 Å = 0.1 nm). + +
+ Schematic of resolution ranges achieved by different microscopy and structural determination methods. +
Schematic of resolution ranges achieved by different microscopy + and structural determination methods. Icons highlight cells and biological + components that can be captured at various resolution ranges. The scale bar + depicts millimeter (mm) to angstrom (Å) level resolutions. +
+
+ +## What is the technology behind CryoET? + +The main technologies that make CryoET possible are highlighted in its name, +including: **cryo**genic techniques, **electron** microscopy and **tomography**. + +### Cryo + +Cryo refers to cryogenic freezing techniques that are used to fix samples +without the use of chemical fixatives or stains. Cryo-fixation happens so +quickly that biological material and processes are frozen in their hydrated, +near native state before ice crystals start to form. This flash-freezing +process that preserves the natural structure of the sample in a glass-like +state is known as vitrification because it embeds the sample in amorphous +(vitreous) ice. One of the first steps during CryoET sample preparation is to +"vitrify" samples. Cryo-fixation also protects the sample when exposed to the +high-vacuum environment of the electron microscope. + +
+ Schematic and electron microscopy images showing how vitrification preserves specimens in their native state and fine structural details. +
Schematic showcasing how vitrification keeps cells in their + hydrated, near-native state (top panel) and electron microscope (EM) images of + the Golgi apparatus (bottom panel) from a chemically fixed cell (A) versus a + CryoET reconstruction (B). Note that crystalline ice formation damages cell + membranes and excludes solutes (e.g., salts and sugars) from the ice lattice, + increasing solute concentrations to lethal levels and causing dehydration. + When cells are vitrified, cell membranes and solutes remain in their original + position as water transitions into a glass-like state that prevents molecular + movement. When looking at the EM images, note the molecular cross bridges + preserved in the cryoET reconstruction (yellow box) that can’t be observed in + the chemically preserved sample. Chemically preserved samples lose fine + biological details due to the staining process. The EM images were originally + published in a review by Hylton and Swulius 2021 + and portrayed in CryoET 101. +
+
+ +### Electron + +Electron specifies that CryoET is an electron microscopy technique where an +electron beam interacts with the sample to project an image. Electron microscopy +is used to view and gain structural information about subcellular and viral +components. Electron wavelengths are small enough to interact with these +components and produce images based on those interactions. CryoET falls under +the transmission electron microscopy category, where electrons pass through the +sample and illuminate film or a digital camera. High electron density components +cast stronger shadows than lighter density ones, thus producing a 2D projection +of the material in the sample. Click [here](https://youtu.be/pQc-GrilCiU) for a +video explaining how electron microscopes work. + +
+ Schematic of a transmission electron microscope. +
Transmission electron microscope schematic highlighting components + of the illumination and imaging systems and the electron detection chamber. +
+
+ +### Tomography + +Tomography refers to an imaging technique that provides 3D information of an +object by capturing projection images from multiple angles. CryoET collects 2D +images representing rotational views or tilted projections from a sample. The +collected 2D images, known as a _tilt series_, are then transformed into volume +providing spatial information. Reconstructed 3D images are known as _tomograms_. + +
+ Schematic of the CryoET imaging workflow. +
Schematic of the CryoET imaging workflow. (A) First, a vitrified + specimen, depicted here as a cell (gray oval) embedded in an ice slab is + tilted at a range of angles while an electron beam passes through the sample + producing projection images. The cell includes three distinct molecular + components (red, blue, and green objects) (B) Projected images from rotational + views around a common axis produce a tilt series. (C) Finally, the tilt series + is computationally aligned and used to reconstruct a 3D map of the imaged + specimen through back-projection. Image adapted from + Galaz-Montoya and Ludtke 2017. +
+
+ +Computational efforts are continuously optimizing tomogram reconstruction (e.g., +automation of image pre-processing steps, such as image alignments, and +improving signal-to-noise ratios). High quality tomograms can then be used to +computationally improve the resolution of smaller, repetitive particles within +tomograms to reconstruct their structure. This single particle reconstruction +from tomograms is known as subtomogram averaging. Through subtomogram averaging, +CryoET data can lead to molecular structures with resolutions near 3 Å. + +
+ Schematic of the subtomogram averaging workflow. +
Subtomogram averaging workflow schematic. During subtomogram + selection, the volumes of repetitive particles representing the same cellular + component are selected from reconstructed tomograms. In this example, + repetitive particles are represented by the blue structures and red arrows + indicate their orientations. Selected subtomograms are then aligned in a way + that 3D structures can be overlaid for averaging. Averaged subtomograms result + in high resolution 3D structures. Image adapted from + Jonker 2020. +
+
diff --git a/docs/python-api.md b/docs/python-api.md index 3db5582d9..618ed3558 100644 --- a/docs/python-api.md +++ b/docs/python-api.md @@ -18,6 +18,7 @@ A simplified diagram of the graph data model is below: :align: center ``` +(api-documentation)= ## API documentation ```{eval-rst} diff --git a/docs/requirements.txt b/docs/requirements.txt index 4bebf8cd6..3825fe7eb 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ sphinx-immaterial myst_nb sphinx-external-toc +sphinx-design diff --git a/docs/tutorial_sample_boundaries.md b/docs/tutorial_sample_boundaries.md index 4fd856156..d16217020 100644 --- a/docs/tutorial_sample_boundaries.md +++ b/docs/tutorial_sample_boundaries.md @@ -1,7 +1,7 @@ --- tocdepth: 2 --- - +(tutorial-sample-boundaries)= # Predicting sample boundaries ```{figure} ./figures/tomo_side_light.png diff --git a/docs/tutorials.md b/docs/tutorials.md index e2a5ed8d7..b65231888 100644 --- a/docs/tutorials.md +++ b/docs/tutorials.md @@ -1,8 +1,40 @@ +--- +hide-navigation: true +--- + # Tutorials These tutorials will help you learn about using the Portal API. -- [Example code snippets](cryoet_data_portal_docsite_examples) are short examples of using the API. -- [Predicting sample boundaries](tutorial_sample_boundaries) in tomograms is an end to end example of using AWS and the Portal API. +::::{grid} 1 1 2 2 +:gutter: 2 + +:::{grid-item-card} Download data +:link: download-data +:link-type: ref + +Guide on downloading data from the AWS S3 bucket +::: + +:::{grid-item-card} Examples +:link: examples +:link-type: ref + +Short code snippets using the API +::: + +:::{grid-item-card} napari Plugin +:link: using-napari +:link-type: ref + +Quick start guide on using napari for visualizing data +::: + +:::{grid-item-card} Predicting sample boundaries +:link: tutorial-sample-boundaries +:link-type: ref + +End to end tutorial from downloading data to analyzing tomograms +:::: Please start a [discussion on Github](https://github.com/chanzuckerberg/cryoet-data-portal/discussions/new/choose) if you'd like to request a tutorial.