Updating Docs for commit 2d52f2c made on 2023-11-08T20:20:40+00:00 fr…

…om refs/heads/main by garrettwrong

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 810c33ecf2cd9060b5dc71d9e19cd3eb
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_downloads/004f7a0d822d7ab7e2417aa5e870b8ce/apple_picker.py

@@ -0,0 +1,70 @@
+"""
+Apple Picker
+============
+
+We demonstrate ASPIRE's particle picking methods using the ``Apple`` class.
+"""
+import logging
+import os
+
+import matplotlib.pyplot as plt
+import mrcfile
+
+from aspire.apple.apple import Apple
+
+logger = logging.getLogger(__name__)
+
+# %%
+# Read and Plot Micrograph
+# ------------------------
+#
+# Here we demonstrate reading in and plotting a raw micrograph.
+
+file_path = os.path.join(
+    os.path.dirname(os.getcwd()), "data", "falcon_2012_06_12-14_33_35_0.mrc"
+)
+
+with mrcfile.open(file_path, mode="r") as mrc:
+    micro_img = mrc.data
+
+plt.title("Sample Micrograph")
+plt.imshow(micro_img, cmap="gray")
+plt.show()
+
+# %%
+# Initialize Apple
+# ----------------
+#
+# Initiate ASPIRE's ``Apple`` class.
+# ``Apple`` admits many options relating to particle sizing and mrc processing.
+
+apple_picker = Apple(
+    particle_size=78, min_particle_size=19, max_particle_size=156, tau1=710, tau2=7100
+)
+
+
+# %%
+# Pick Particles and Find Centers
+# -------------------------------
+#
+# Here we use the ``process_micrograph`` method from the ``Apple`` class to find particles in the micrograph.
+# It will also return an image suitable for display, and optionally save a jpg.
+
+centers, particles_img = apple_picker.process_micrograph(file_path, create_jpg=True)
+
+# Note that if you only desire ``centers`` you may call ``process_micrograph_centers(file_path,...)``.
+
+# %%
+# Plot the Picked Particles
+# -------------------------
+#
+# Observe the number of particles picked and plot the result from ``Apple``.
+
+img_dim = micro_img.shape
+particles = centers.shape[0]
+logger.info(f"Dimensions of the micrograph are {img_dim}")
+logger.info(f"{particles} particles were picked")
+
+# sphinx_gallery_thumbnail_number = 2
+plt.imshow(particles_img, cmap="gray")
+plt.show()

_downloads/295b04456c31e136eefc8b736de1e0a4/pipeline_demo.py

@@ -0,0 +1,276 @@
+"""
+Ab-initio Pipeline Demonstration
+================================
+
+This tutorial demonstrates some key components of an ab-initio
+reconstruction pipeline using synthetic data generated with ASPIRE's
+``Simulation`` class of objects.
+"""
+
+# %%
+# Download an Example Volume
+# -----------------
+# We begin by downloading a high resolution volume map of the 80S
+# Ribosome, sourced from EMDB: https://www.ebi.ac.uk/emdb/EMD-2660.
+# This is one of several volume maps that can be downloaded with
+# ASPIRE's data downloading utility by using the following import.
+# sphinx_gallery_start_ignore
+# flake8: noqa
+# sphinx_gallery_end_ignore
+from aspire.downloader import emdb_2660
+
+# Load 80s Ribosome as a ``Volume`` object.
+original_vol = emdb_2660()
+
+# Downsample the volume
+res = 41
+vol = original_vol.downsample(res)
+
+# %%
+# .. note::
+#     A ``Volume`` can be saved using the ``Volume.save()`` method as follows::
+#
+#         fn = f"downsampled_80s_ribosome_size{res}.mrc"
+#         vol.save(fn, overwrite=True)
+
+
+# %%
+# Create a Simulation Source
+# --------------------------
+# ASPIRE's ``Simulation`` class can be used to generate a synthetic
+# dataset of projection images.  A ``Simulation`` object produces
+# random projections of a supplied Volume and applies noise and CTF
+# filters. The resulting stack of 2D images is stored in an ``Image``
+# object.
+
+
+# %%
+# CTF Filters
+# ^^^^^^^^^^^^^^^^^^^^^
+# Let's start by creating CTF filters. The ``operators`` package
+# contains a collection of filter classes that can be supplied to a
+# ``Simulation``.  We use ``RadialCTFFilter`` to generate a set of CTF
+# filters with various defocus values.
+
+# Create CTF filters
+import numpy as np
+
+from aspire.operators import RadialCTFFilter
+
+# Radial CTF Filter
+defocus_min = 15000  # unit is angstroms
+defocus_max = 25000
+defocus_ct = 7
+
+ctf_filters = [
+    RadialCTFFilter(pixel_size=5, defocus=d)
+    for d in np.linspace(defocus_min, defocus_max, defocus_ct)
+]
+
+# %%
+# Initialize Simulation Object
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+# We feed our ``Volume`` and filters into ``Simulation`` to generate
+# the dataset of images.  When controlled white Gaussian noise is
+# desired, ``WhiteNoiseAdder.from_snr()`` can be used to generate a
+# simulation data set around a specific SNR.
+#
+# Alternatively, users can bring their own images using an
+# ``ArrayImageSource``, or define their own custom noise functions via
+# ``Simulation(..., noise_adder=CustomNoiseAdder(...))``.  Examples
+# can be found in ``tutorials/class_averaging.py`` and
+# ``experiments/simulated_abinitio_pipeline.py``.
+
+from aspire.noise import WhiteNoiseAdder
+from aspire.source import Simulation
+
+# set parameters
+n_imgs = 2500
+
+# SNR target for white gaussian noise.
+snr = 0.5
+
+# %%
+# .. note::
+#   Note, the SNR value was chosen based on other parameters for this
+#   quick tutorial, and can be changed to adjust the power of the
+#   additive noise.
+
+# For this ``Simulation`` we set all 2D offset vectors to zero,
+# but by default offset vectors will be randomly distributed.
+src = Simulation(
+    n=n_imgs,  # number of projections
+    vols=vol,  # volume source
+    offsets=0,  # Default: images are randomly shifted
+    unique_filters=ctf_filters,
+    noise_adder=WhiteNoiseAdder.from_snr(snr=snr),  # desired SNR
+)
+
+
+# %%
+# Several Views of the Projection Images
+# --------------------------------------
+# We can access several views of the projection images.
+
+# with no corruption applied
+src.projections[0:10].show()
+
+# %%
+
+# with no noise corruption
+src.clean_images[0:10].show()
+
+# %%
+
+# with noise and CTF corruption
+src.images[0:10].show()
+
+
+# %%
+# CTF Correction
+# --------------
+# We apply ``phase_flip()`` to correct for CTF effects.
+
+src = src.phase_flip()
+src.images[0:10].show()
+
+
+# %%
+# Class Averaging
+# ---------------
+# We use ``RIRClass2D`` object to classify the images via the
+# rotationally invariant representation (RIR) algorithm. Class
+# selection is customizable. The classification module also includes a
+# set of protocols for selecting a set of images to be used for
+# classification.  Here we're using ``TopClassSelector``, which
+# selects the first ``n_classes`` images from the source.  In
+# practice, the selection is done by sorting class averages based on
+# some configurable notion of quality.
+
+from aspire.classification import RIRClass2D
+
+# set parameters
+n_classes = 200
+n_nbor = 6
+
+# We will customize our class averaging source. Note that the
+# ``fspca_components`` and ``bispectrum_components`` were selected for
+# this small tutorial.
+rir = RIRClass2D(
+    src,
+    fspca_components=40,
+    bispectrum_components=30,
+    n_nbor=n_nbor,
+)
+
+from aspire.denoising import DebugClassAvgSource
+
+avgs = DebugClassAvgSource(
+    src=src,
+    classifier=rir,
+)
+
+# We'll continue our pipeline with the first ``n_classes`` from ``avgs``.
+avgs = avgs[:n_classes]
+
+
+# %%
+# View the Class Averages
+# -----------------------
+
+# Show class averages
+avgs.images[0:10].show()
+
+# %%
+
+# Show original images corresponding to those classes. This 1:1
+# comparison is only expected to work because we used
+# ``TopClassSelector`` to classify our images.
+src.images[0:10].show()
+
+
+# %%
+# Orientation Estimation
+# ----------------------
+# We create an ``OrientedSource``, which consumes an ``ImageSource`` object, an
+# orientation estimator, and returns a new source which lazily estimates orientations.
+# In this case we supply ``avgs`` for our source and a ``CLSyncVoting``
+# class instance for our orientation estimator. The ``CLSyncVoting`` algorithm employs
+# a common-lines method with synchronization and voting.
+
+from aspire.abinitio import CLSyncVoting
+from aspire.source import OrientedSource
+
+# Stash true rotations for later comparison
+true_rotations = src.rotations[:n_classes]
+
+# For this low resolution example we will customize the ``CLSyncVoting``
+# instance to use fewer theta points ``n_theta`` then the default value of 360.
+orient_est = CLSyncVoting(avgs, n_theta=72)
+
+# Instantiate an ``OrientedSource``.
+oriented_src = OrientedSource(avgs, orient_est)
+
+
+# %%
+# Mean Squared Error
+# ------------------
+# ASPIRE has some built-in utility functions for globally aligning the
+# estimated rotations to the true rotations and computing the mean
+# squared error.
+
+from aspire.utils.coor_trans import (
+    get_aligned_rotations,
+    get_rots_mse,
+    register_rotations,
+)
+
+# Compare with known true rotations
+Q_mat, flag = register_rotations(oriented_src.rotations, true_rotations)
+regrot = get_aligned_rotations(oriented_src.rotations, Q_mat, flag)
+mse_reg = get_rots_mse(regrot, true_rotations)
+mse_reg
+
+
+# %%
+# Volume Reconstruction
+# ---------------------
+# Now that we have our class averages and rotation estimates, we can
+# estimate the mean volume by supplying the class averages and basis
+# for back projection.
+
+from aspire.basis import FFBBasis3D
+from aspire.reconstruction import MeanEstimator
+
+# Create a reasonable Basis for the 3d Volume
+basis = FFBBasis3D(res, dtype=vol.dtype)
+
+# Setup an estimator to perform the back projection.
+estimator = MeanEstimator(oriented_src, basis)
+
+# Perform the estimation and save the volume.
+estimated_volume = estimator.estimate()
+
+
+# %%
+# Comparison of Estimated Volume with Source Volume
+# -------------------------------------------------
+# To get a visual confirmation that our results are sane, we rotate
+# the estimated volume by the estimated rotations and project along
+# the z-axis.  These estimated projections should align with the
+# original projection images.
+
+from aspire.source import ArrayImageSource
+
+# Get projections from the estimated volume using the estimated
+# orientations.  We instantiate the projections as an
+# ``ArrayImageSource`` to access the ``Image.show()`` method.
+projections_est = ArrayImageSource(estimated_volume.project(oriented_src.rotations))
+
+# We view the first 10 projections of the estimated volume.
+projections_est.images[0:10].show()
+
+# %%
+
+# For comparison, we view the first 10 source projections.
+src.projections[0:10].show()