Skip to content

Your entry point¤

cryojax.simulator.make_image_model ¤

make_image_model(
    volume: cryojax.simulator.AbstractVolumeParametrization,
    image_config: cryojax.simulator.AbstractImageConfig,
    pose: cryojax.simulator.AbstractPose,
    transfer_theory: cryojax.simulator.ContrastTransferTheory | None = None,
    volume_integrator: cryojax.simulator.AbstractVolumeIntegrator = cryojax.simulator.AutoVolumeProjection(),
    detector: cryojax.simulator.AbstractDetector | None = None,
    *,
    image_transform: cryojax.ndimage.AbstractImageTransform | None = None,
    normalizes_signal: bool = False,
    signal_region: Bool[NDArrayLike, "_ _"] | None = None,
    signal_centering: Literal["bg", "mean"] = "mean",
    translate_mode: Literal["fft", "atom", "none"] = "fft",
    quantity_mode: Literal["contrast", "intensity", "counts", "none"] = "none",
    rotation_convention: Literal["object", "frame"] = "object",
) -> cryojax.simulator.AbstractImageModel

Construct an cryojax.simulator.AbstractImageModel for most common use-cases.

Simulate an image

import cryojax.simulator as cxs

# Load modeling components
volume, image_config, pose, transfer_theory = ...
# Build image formation model
image_model = cxs.make_image_model(volume, image_config, pose, transfer_theory)
# Simulate!
image = image_model.simulate()

Main arguments:

Options:

  • image_transform: A cryojax.ndimage.AbstractImageTransform applied to the the output of image_model.simulate() as a postprocessing step.
  • normalizes_signal: Whether or not to normalize the output of image_model.simulate(). If True, see signal_centering for options.
  • signal_region: A boolean array that is 1 where there is signal, and 0 otherwise used to normalize the image. Must have shape equal to image_config.shape.
  • signal_centering: How to calculate the offset for normalization when normalizes_signal = True (and ignored if normalizes_signal = False). Options are
    • 'mean': Normalize the image to be mean 0 within signal_region. This normalizes the image to be a z-score.
    • 'bg': Subtract mean value at the image edges. This makes the image fade to a background with values equal to zero. Requires that image_config.padded_shape is large enough so that the signal sufficiently decays.
  • translate_mode: How to apply in-plane translation to the volume. Options are
    • 'fft': Apply phase shifts in the Fourier domain. This option is best for most use cases and is usually faster than the 'atom' option.
    • 'atom': Apply translation to atom positions before projection. This method is more numerically accurate than the 'fft' option, but it is only supported if the volume argument yields a cryojax.simulator.AbstractAtomVolume.
    • 'none': Do not apply the translation.
  • quantity_mode: The physical observable to simulate. Options are:
  • rotation_convention: If 'object', the rotation given by pose is of the object. If 'frame', the rotation given by pose is of the frame. These are related by transpose.

Info

The make_image_model function enforces agreement between rotation conventions of different volumes via the rotation_convention argument. Lower level cryojax APIs will not enforce this agreement, such as if the user instantiates an cryojax.simulator.AbstractImageModel directly.

In these cases, agreement can be acheived with a manual transpose via pose.to_inverse_rotation().

Returns:

An cryojax.simulator.AbstractImageModel. This has type:

cryojax.simulator.load_tabulated_volume ¤

load_tabulated_volume(
    path_or_mmdf: str | pathlib.Path | pandas.DataFrame,
    *,
    output_type: type[
        cryojax.simulator.IndependentAtomVolume
        | cryojax.simulator.GaussianMixtureVolume
    ] = cryojax.simulator.IndependentAtomVolume,
    tabulation: Literal["peng", "lobato"] = "peng",
    include_b_factors: bool = False,
    b_factor_fn: Callable[
        [cryojax.jax_util.NDArrayLike, cryojax.jax_util.NDArrayLike],
        cryojax.jax_util.NDArrayLike,
    ] = identity_fn,
    selection_string: str = "all",
    pdb_options: dict[str, Any] = {},
) -> (
    cryojax.simulator.IndependentAtomVolume | cryojax.simulator.GaussianMixtureVolume
)

Load an atomistic representation of a volume from tabulated electron scattering factors.

Warning

This function cannot be used with JIT compilation. Rather, its output should be passed to JIT-compiled functions. For example:

import cryojax.simulator as cxs
import equinox as eqx

path_to_pdb = ...
volume = cxs.load_tabulated_volume(path_to_pdb)

@eqx.filter_jit
def simulate_fn(volume, ...):
    image_model = cxs.make_image_model(volume, ...)
    return image_model.simulate()

image = simulate_fn(volume, ...)

Arguments:

Returns:

A cryojax.simulator.AbstractVoxelVolume with exact type equal to output_type.

cryojax.simulator.render_voxel_volume ¤

render_voxel_volume(
    atom_volume: cryojax.simulator.AbstractAtomVolume,
    render_fn: cryojax.simulator.AbstractVolumeRenderFn,
    *,
    output_type: type[
        cryojax.simulator.FourierVoxelGridVolume
        | cryojax.simulator.FourierVoxelSplineVolume
        | cryojax.simulator.RealVoxelGridVolume
    ] = cryojax.simulator.FourierVoxelGridVolume,
) -> (
    cryojax.simulator.FourierVoxelGridVolume
    | cryojax.simulator.FourierVoxelSplineVolume
    | cryojax.simulator.RealVoxelGridVolume
)

Render a voxel volume representation from an atomistic one.

Simulate an image with Fourier slice extraction

import cryojax.simulator as cxs

# Simulate an image with Fourier slice extraction
voxel_volume = cxs.render_voxel_volume(
    atom_volume=cxs.load_tabulated_volume("example.pdb"),
    render_fn=cxs.AutoVolumeRenderFn(shape=(100, 100, 100), voxel_size=1.0),
    output_type=cxs.FourierVoxelGridVolume,
)
image_model = cxs.make_image_model(voxel_volume, ...)
image = image_model.simulate()

Arguments:

Returns:

A cryojax.simulator.AbstractVoxelVolume with exact type equal to output_type.