Parameter setup: Image Descriptor

The Image Descriptor object contains the parameters required to interpret a set of 2D images (Images stack or Templates). An ImageDescriptor is a required input to the functions for making Templates or converting experimentally-captured Images.

For full details, see cryolike.metadata.image_descriptor.ImageDescriptor

Available fields

The following fields are present on the ImageDescriptor object. In general, users will set them through a simpler interface (see the Interface section below and the Parameter-setting example).

Shared fields

The ImageDescriptor object has three fields that must be present, whether it is being used for Images or for Templates.

These are:

• A CartesianGrid2D instance

• A PolarGrid instance

• A precision (single or double), as a string or a Precision

The CartesianGrid2D describes a two-dimensional grid. While the class supports rectangular grids and pixel shapes, by default this is a square grid defined by the number of pixels per side (n_pixels) and the pixel size (pixel_size, in Angstroms).

The PolarGrid describes a polar-coordinate grid used to discretize the Fourier-space representation of the image. The underlying class supports non-uniform grids, but CryoLike as a whole does not yet support them. Uniform grids can be completely described by a number of shells (radii), the radial distances of the shells, and the number of in-plane points per shell.

Template-specific fields

The following ImageDescriptor fields are only used in the process of converting 3D volume data to sets of Templates. Their values have no effect on captured Images, and they are not used for Templates after the initial conversion process. They are saved as part of the metadata file for future reference. These are the specific fields potentially used for Templates creation:

• A set of (ViewingAngles) that determines the number of viewing angles, and thus the number of templates generated

• A viewing distance (in Angstroms) used to generate the ViewingAngles, if they are not specified explicitly

• The resolution_factor in [0,1]

• The radii (in Angstroms) of the atoms or beads in the model

• A string identifying the selected atoms to take from the structure if PDB format is used

• Whether to use the default protein residue model atomic sizes

• The shape of the atoms (i.e. whether to interpret them as hard spheres or Gaussian probability clouds with a given width defined by radii)

These values are all potentially used for Templates creation.

The ViewingAngles are the different orientations of the device lens which will be considered in projecting the 3D model onto a 2D plane. These could be set manually, but in current usage they are computed automatically from the viewing distance. A smaller viewing distance implies a finer angular search grid, and therefore creates more templates and increases the computational costs.

Once the viewing distance is defined, the grid for the \(\alpha\) and \(\beta\) Euler angles is computed, and the rotation as exemplified in the figure below is applied to generate each template.

[TODO: INCLUDE ADI’s figure]

The resolution_factor determines the maximum frequency in the Fourier polar grid up to which the cross-correlation and likelihood computations will be performed. If the resolution_factor=1, the template will be represented in full resolution up to the Nyquist frequency (set at 1/4 the number of voxels per dimension in the input 3D volume). Setting the resolution factor to 0.5 will result in half resolution, but represent the templates up to double the Nyquist frequency.

The maximum frequency radius is the resolution_factor/Nyqst, and therefore a lower resolution_factor implies a lower frequency up to which to perform the calculation.

Note that, since each Template is the 2D projection of a 3D form from a specific angle, the number of viewing angles should match the number of Templates in a Templates file.

The remaining fields are required only for interpreting PDB models (not maps) and will be ignored otherwise. Note that to create a map from a PDB file there are two options. The user must either specify a value for the atom radii that determines the radius of the shape object (Gaussian or sphere) to be centered on the position of the atom selection or set the default protein residue model flag for proteins, which models a single bead per amino acid with a specific Vaan der Waals radii centered on the \(C_\alpha\) as in Cossio and Hummer, 2013.

Compatibility

Image Descriptors can describe the images in Images stacks or in Templates. Two Image Descriptors are considered compatible if they use the same 2D Cartesian grid and Fourier-space polar grid.

All other fields are ignored for the purposes of compatibility. So there is no issue with running a comparison between the Images converted using one ImageDescriptor and Templates constructed with another ImageDescriptor–as long as the descriptors describe the same grid, they are interoperable.

Interface

The main way for a user to create an ImageDescriptor instance is by the ImageDescriptor.from_individual_values() function.

See also the API documentation at cryolike.metadata and cryolike.metadata.ImageDescriptor

The following parameters are accepted:

• Precision (as a string (single or double), or CryoLike enum representation)

• For setting the Cartesian grid:

  • Number of pixels per side of the grid (n_pixels), and

  • size, in Angstroms, of each pixel (pixel_size)

  • Grids and pixels are assumed to be square

  • These are the only required fields–the rest will be set to defaults if not provided

• For setting the polar grid:

  • number of points per shell (n_inplanes)

  • resolution_factor for determining the maximum radius (corresponding to the maximum observable frequency).

    • Because we use a fixed distance of 0.25 between radii, higher values mean higher resolution

    • Maximum radius is set to \(\frac{F}{4p}\), where F is the resolution factor and p is the number of pixels per side of the grid

  • If not specified, a resolution_factor of 1 will be used, which takes the maximum frequency radius up to Nyquist

• For Template generation:

  • A viewing distance, to compute the viewing angles to use for 3D-to-2D projection. In rough terms, this determines how far apart the different viewing angles are on the surface of a unit sphere centered on the template, so a smaller value means a larger number of angles will be considered.

    • If not specified, the default is \(\frac{1}{4 \pi F}\), where F is the same resolution factor used to determine the max radius of the polar grid

  • atomic radii (a scalar value, in Angstrom)

  • atom selection (string)

  • atom shape (hard-shell or Gaussian)

  • whether to use the default protein residue model