Python API

Warning

This is under developement

The functionality of the command line programs can be called from python as shown below.

Image IO functions

parakeet.io.new(filename, shape=None, pixel_size=1, dtype='float32', vmin=None, vmax=None)

Create a new file for writing

Parameters:

  • filename (str) – The output filename

  • shape (tuple) – The output shape

  • pixel_size (tuple) – The pixel size

  • dtype (object) – The data type (only used with NexusWriter)

  • vmin (int) – The minimum value (only used in ImageWriter)

  • vmax (int) – The maximum value (only used in ImageWriter)

Returns:

The file writer

Return type:

object

parakeet.io.open(filename)

Read the simulated data from file

Parameters:

filename (str) – The output filename

PDB file functions

parakeet.data.get_pdb(name)

Return the path to the data file

Parameters:

name (str) – The pdb id

Returns:

The absolute filename

Return type:

str

Configuration functions

parakeet.config.new(filename: str = 'config.yaml', full: bool = False) → Config

Generate a new config file

Parameters:

  • filename – The config filename

  • full – Full or basic configuration

Sample functions

parakeet.sample.new(config_file, sample_file: str) → Sample
parakeet.sample.new(config: Config, filename: str) → Sample
parakeet.sample.new(config: Sample, filename: str) → Sample

Create an ice sample and save it

Parameters:

  • config_file – The input config filename

  • sample_file – The sample filename

parakeet.sample.add_molecules(config_file, sample_file: str) → Sample
parakeet.sample.add_molecules(config: Config, sample_file: str) → Sample
parakeet.sample.add_molecules(config: Sample, sample: Sample) → Sample

Add molecules to the sample

Parameters:

  • config_file – The input config filename

  • sample_file – The input sample filename

parakeet.sample.mill(config_file, sample_file: str) → Sample
parakeet.sample.mill(config: Config, sample_file: str) → Sample
parakeet.sample.mill(config: Sample, sample: Sample) → Sample

Mill to the shape of the sample

Parameters:

  • config_file – The input config filename

  • sample_file – The sample filename

Returns:

The sample object

parakeet.sample.sputter(config_file, sample_file: str) → Sample
parakeet.sample.sputter(config: Config, sample_file: str) → Sample
parakeet.sample.sputter(config: Sputter, sample: Sample) → Sample

Sputter the sample

Parameters:

  • config_file – The input config filename

  • sample_file – The sample filename

Image simulation functions

parakeet.simulate.potential(config_file, sample_file: str, potential_prefix: str, device: Device = None, nproc: int = None, gpu_id: list = None)
parakeet.simulate.potential(config: Config, sample_file: str, potential_prefix: str)

Simulate the projected potential from the sample

Parameters:

  • config_file – The input config filename

  • sample_file – The input sample filename

  • potential_prefix – The input potential filename

  • device – The device to run on (cpu or gpu)

  • nproc – The number of processes

  • gpu_id – The list of gpu ids

parakeet.simulate.exit_wave(config_file, sample_file: str, exit_wave_file: str, device: Device = None, nproc: int = None, gpu_id: list = None)
parakeet.simulate.exit_wave(config: Config, sample: Sample, exit_wave_file: str)

Simulate the exit wave from the sample

Parameters:

  • config_file – The config filename

  • sample_file – The sample filename

  • exit_wave_file – The exit wave filename

  • device – The device to run on (cpu or gpu)

  • nproc – The number of processes

  • gpu_id – The list of gpu ids

parakeet.simulate.optics(config_file, exit_wave_file: str, optics_file: str, device: Device = None, nproc: int = None, gpu_id: list = None)
parakeet.simulate.optics(config: Config, exit_wave_file: str, optics_file: str)

Simulate the optics

Parameters:

  • config_file – The input config filename

  • exit_wave_file – The input exit wave filename

  • optics_file – The output optics filename

  • device – The device to run on (cpu or gpu)

  • nproc – The number of processes

  • gpu_id – The list of gpu ids

parakeet.simulate.image(config_file, optics_file: str, image_file: str)
parakeet.simulate.image(config: Config, optics_file: str, image_file: str)

Simulate the image with noise

Parameters:

  • config_file – The config filename

  • optics_file – The optics image filename

  • image_file – The output image filename

parakeet.simulate.ctf(config_file, output_file: str)
parakeet.simulate.ctf(config: Config, output_file: str)

Simulate the ctf

Parameters:

  • config_file – The config filename

  • output_file – The output ctf filename

Analysis functions

parakeet.analyse.correct(config_file, image_file: str, corrected_file: str, num_defocus: int = 1, device: Device = None)
parakeet.analyse.correct(config: Config, image_filename: str, corrected_filename: str, num_defocus: int | None = None)

Correct the images using 3D CTF correction

Parameters:

  • config_file – The input config filename

  • image_file – The input image filename

  • corrected_file – The output CTF corrected filename

  • num_defocus – The number of defoci

  • device – The device to use (CPU or GPU)

parakeet.analyse.reconstruct(config_file, image_file: str, rec_file: str, device: Device = None)
parakeet.analyse.reconstruct(config: Config, image_filename: str, rec_filename: str)

Reconstruct the volume

Parameters:

  • config_file – The input config filename

  • image_file – The input image filename

  • rec_file – The output CTF corrected reconstruction filename

  • device – The device to use (CPU or GPU)

parakeet.analyse.average_particles(config_file, sample_file: str, rec_file: str, half1_file: str, half2_file: str, particle_size: int, num_particles: int)
parakeet.analyse.average_particles(config: Scan, sample: Sample, rec_filename: str, half_1_filename: str, half_2_filename: str, particle_size: int = 0, num_particles: int = 0)

Perform sub tomogram averaging

Parameters:

  • config_file – The input config filename

  • sample_file – The sample filename

  • rec_file – The reconstruction filename

  • half1_file – The particle average filename for half 1

  • half2_file – The particle average filename for half 2

  • particle_size – The particle size (px)

  • num_particles – The number of particles to average

parakeet.analyse.average_all_particles(config_file, sample_file: str, rec_file: str, average_file: str, particle_size: int, num_particles: int)
parakeet.analyse.average_all_particles(config: Scan, sample: Sample, rec_filename: str, average_filename: str, particle_size: int = 0, num_particles: int = 0)

Perform sub tomogram averaging

Parameters:

  • config_file – The input config filename

  • sample_file – The sample filename

  • rec_file – The reconstruction filename

  • average_file – The particle average filename

  • particle_size – The particle size (px)

parakeet.analyse.extract(config_file, sample_file: str, rec_file: str, particles_file: str, particle_size: int, particle_sampling: int)
parakeet.analyse.extract(config: Config, sample: Sample, rec_filename: str, extract_file: str, particle_size: int = 0, particle_sampling: int = 1)

Perform sub tomogram extraction

Parameters:

  • config_file – The input config filename

  • sample_file – The sample filename

  • rec_file – The reconstruction filename

  • particles_file – The file to extract the particles to

  • particle_size – The particle size (px)

  • particle_sampling – The particle sampling (factor of 2)

parakeet.analyse.refine(sample_filename: str, rec_filename: str)

Refine the molecule against the map

parakeet.run(config_file, sample_file: str, exit_wave_file: str, optics_file: str, image_file: str, device: Device = None, nproc: int = None, gpu_id: list = None, steps: list = None)
parakeet.run(config: Config, sample_file: str, exit_wave_file: str, optics_file: str, image_file: str, steps: list | None = None)

Simulate the TEM image from the sample

If steps is None then all steps are run, otherwise steps is a list which contains one or more of the following: all, sample, simulate, sample.new, sample.add_molecules, simulate.exit_wave, simulate.optics and simulate.image

Parameters:

  • config_file – The config filename

  • sample_file – The sample filename

  • exit_wave_file – The exit wave filename

  • optics_file – The optics filename

  • image_file – The image filename

  • device – The device to run on (cpu or gpu)

  • nproc – The number of processes

  • gpu_id – The list of gpu ids

  • steps – Choose the steps to run

Data models

class parakeet.beam.Beam(energy: float = 300, energy_spread: float = 0, acceleration_voltage_spread: float = 0, illumination_semiangle: float = 0.1, electrons_per_angstrom: float = 40, theta: float = 0, phi: float = 0, incident_wave: str | None = None)

A class to encapsulate a beam

__init__(energy: float = 300, energy_spread: float = 0, acceleration_voltage_spread: float = 0, illumination_semiangle: float = 0.1, electrons_per_angstrom: float = 40, theta: float = 0, phi: float = 0, incident_wave: str | None = None)

Initialise the beam

Parameters:

  • energy – The beam energy (keV)

  • energy_spread – dE / E where dE is the 1/e half width

  • acceleration_voltage_spread – dV / V where dV is the 1 / e half width

  • illumination_semiangle – The illumination semiangle spread (mrad)

  • electrons_per_angstrom – The number of electrons per angstrom

  • theta – The beam tilt theta

  • phi – The beam tilt phi

  • incident_wave – The wave function

property acceleration_voltage_spread: float

dV / V where dV is the 1 / e half width

property electrons_per_angstrom: float

The number of electrons per angstrom

property energy: float

The beam energy (keV)

property energy_spread: float

dE / E where dE is the 1/e half width

property illumination_semiangle: float

The illumination semiangle (mrad)

property phi: float

The beam tilt phi

property theta: float

The beam tilt theta

class parakeet.detector.Detector(nx: int = 0, ny: int = 0, pixel_size: float = 1, origin: Tuple[float, float, float] = (0, 0, 0), dqe: bool = True)

A class to encapsulate a detector

__init__(nx: int = 0, ny: int = 0, pixel_size: float = 1, origin: Tuple[float, float, float] = (0, 0, 0), dqe: bool = True)

Initialise the detector

Parameters:

  • nx – The size of the detector in X

  • ny – The size of the detector in Y

  • pixel_size – The effective size of the pixels in A

  • origin – The detector origin (A, A)

  • dqe – Use the detector DQE

class parakeet.lens.Lens(m: int = 0, c_10: float = 20, c_12: float = 0.0, phi_12: float = 0.0, c_21: float = 0.0, phi_21: float = 0.0, c_23: float = 0.0, phi_23: float = 0.0, c_30: float = 0.04, c_32: float = 0.0, phi_32: float = 0.0, c_34: float = 0.0, phi_34: float = 0.0, c_41: float = 0.0, phi_41: float = 0.0, c_43: float = 0.0, phi_43: float = 0.0, c_45: float = 0.0, phi_45: float = 0.0, c_50: float = 0.0, c_52: float = 0.0, phi_52: float = 0.0, c_54: float = 0.0, phi_54: float = 0.0, c_56: float = 0.0, phi_56: float = 0.0, inner_aper_ang: float = 0.0, outer_aper_ang: float = 0.0, c_c: float = 0.0, current_spread: float = 0.0)

A class to encapsulate a lens

__init__(m: int = 0, c_10: float = 20, c_12: float = 0.0, phi_12: float = 0.0, c_21: float = 0.0, phi_21: float = 0.0, c_23: float = 0.0, phi_23: float = 0.0, c_30: float = 0.04, c_32: float = 0.0, phi_32: float = 0.0, c_34: float = 0.0, phi_34: float = 0.0, c_41: float = 0.0, phi_41: float = 0.0, c_43: float = 0.0, phi_43: float = 0.0, c_45: float = 0.0, phi_45: float = 0.0, c_50: float = 0.0, c_52: float = 0.0, phi_52: float = 0.0, c_54: float = 0.0, phi_54: float = 0.0, c_56: float = 0.0, phi_56: float = 0.0, inner_aper_ang: float = 0.0, outer_aper_ang: float = 0.0, c_c: float = 0.0, current_spread: float = 0.0)

Initialise the lens

Parameters:

  • m – The vortex momentum

  • c_10 – The defocus (A)

  • c_12 – The 2-fold astigmatism (A)

  • phi_12 – The azimuthal angle of 2-fold astigmatism (degrees)

  • c_21 – The axial coma (A)

  • phi_21 – The azimuthal angle of axial coma (degrees)

  • c_23 – The 3-fold astigmatism (A)

  • phi_23 – The azimuthal angle of 3-fold astigmatism (degrees)

  • c_30 – The 3rd order spherical aberration (mm)

  • c_32 – The axial star aberration (A)

  • phi_32 – The azimuthal angle of axial star aberration (degrees)

  • c_34 – The 4-fold astigmatism (A)

  • phi_34 – The azimuthal angle of 4-fold astigmatism (degrees)

  • c_41 – The 4th order axial coma (A)

  • phi_41 – The azimuthal angle of 4th order axial coma (degrees)

  • c_43 – The 3-lobe aberration (A)

  • phi_43 – The azimuthal angle of 3-lobe aberration (degrees)

  • c_45 – The 5-fold astigmatism (A)

  • phi_45 – The azimuthal angle of 5-fold astigmatism (degrees)

  • c_50 – The 5th order spherical aberration (mm)

  • c_52 – The 5th order axial star aberration (A)

  • phi_52 – The azimuthal angle of 5th order axial star aberration (degrees)

  • c_54 – The 5th order rosette aberration (A)

  • phi_54 – The azimuthal angle of 5th order rosette aberration (degrees)

  • c_56 – The 6-fold astigmatism (A)

  • phi_56 – The azimuthal angle of 6-fold astigmatism (degrees)

  • inner_aper_ang – The inner aperture (mrad)

  • outer_aper_ang – The outer aperture (mrad)

  • c_c – The chromatic abberation (mm)

  • current_spread – dI / I where dI is the 1/e half width

class parakeet.microscope.Microscope(model: ~parakeet.config.MicroscopeModel | None = None, beam: ~parakeet.beam.Beam = <parakeet.beam.Beam object>, lens: ~parakeet.lens.Lens = <parakeet.lens.Lens object>, detector: ~parakeet.detector.Detector = <parakeet.detector.Detector object>, phase_plate: ~parakeet.microscope.PhasePlate = <parakeet.microscope.PhasePlate object>, objective_aperture_cutoff_freq=None)

A class to encapsulate a microscope

__init__(model: ~parakeet.config.MicroscopeModel | None = None, beam: ~parakeet.beam.Beam = <parakeet.beam.Beam object>, lens: ~parakeet.lens.Lens = <parakeet.lens.Lens object>, detector: ~parakeet.detector.Detector = <parakeet.detector.Detector object>, phase_plate: ~parakeet.microscope.PhasePlate = <parakeet.microscope.PhasePlate object>, objective_aperture_cutoff_freq=None)

Initialise the detector

Parameters:

  • model – The microscope model name

  • beam – The beam object

  • lens – The lens object

  • detector – The detector object

  • phase_plate – The phase plate

property beam: Beam

The beam model

property detector: Detector

The detector model

property lens: Lens

The lens model

property model: MicroscopeModel | None

The microscope model type

property phase_plate: PhasePlate

Do we have a phase plate

class parakeet.scan.Scan(image_number: ndarray | None = None, fraction_number: ndarray | None = None, axis: ndarray | None = None, angle: ndarray | None = None, shift: ndarray | None = None, shift_delta: ndarray | None = None, beam_tilt_theta: ndarray | None = None, beam_tilt_phi: ndarray | None = None, electrons_per_angstrom: ndarray | None = None, defocus_offset: ndarray | None = None, exposure_time: float = 1, is_uniform_angular_scan: bool = False)

A scan of angles around a single rotation axis.

__init__(image_number: ndarray | None = None, fraction_number: ndarray | None = None, axis: ndarray | None = None, angle: ndarray | None = None, shift: ndarray | None = None, shift_delta: ndarray | None = None, beam_tilt_theta: ndarray | None = None, beam_tilt_phi: ndarray | None = None, electrons_per_angstrom: ndarray | None = None, defocus_offset: ndarray | None = None, exposure_time: float = 1, is_uniform_angular_scan: bool = False)

Initialise the scan

property angles: ndarray

Get the angles

property axes: ndarray

Get the axes

property beam_tilt_phi: ndarray

Get the beam tilt phi angles

property beam_tilt_theta: ndarray

Get the beam tilt theta angles

property defocus_offset: ndarray

Get the defocus offset

property electrons_per_angstrom: ndarray

Get the dose

property euler_angles: ndarray

Euler angle representation of the orientations.

The Euler angles are intrinsic, right handed rotations around ZYZ. This matches the convention used by XMIPP/RELION.

property exposure_time: ndarray

Get the exposure times

property fraction_number: ndarray

Get the movie fraction number

property image_number: ndarray

Get the image number

property orientation: ndarray

Get the orientations

property position: ndarray

Get the positions

property shift: ndarray

Get the shifts

property shift_delta: ndarray

Get the shift deltas (drift)

class parakeet.sample.Sample(filename=None, mode='r')

A class to hold the sample data

__init__(filename=None, mode='r')

Initialise the class with a filename

Parameters:

  • filename (str) – The filename

  • mode (str) – The open mode

add_atoms(atoms)

Add some atoms

Parameters:

atoms (object) – The atom data to add to the sample

add_molecule(atoms, positions, orientations, name=None)

Add a molecule.

This adds the atoms of each copy of the molecule but also stores the molecule itself with the positions and orientations

Parameters:

  • atoms (object) – The atom data

  • positions (list) – A list of positions

  • orientations (list) – A list of orientations

  • name (str) – The name of the molecule

atoms_dataset_name(x)

Get the atom dataset name

atoms_dataset_range(x0, x1)

Get the atom dataset range

Parameters:

  • x0 (array) – The minimum coord

  • x1 (array) – The maximum coord

Yields:

tuple – The coordinates of the sub ranges

atoms_dataset_range_3d(x0, x1)

Get the atom dataset range

Parameters:

  • x0 (array) – The minimum coord

  • x1 (array) – The maximum coord

Yields:

tuple – The coordinates of the sub ranges

property bounding_box

The bounding box

Returns:

lower, upper - the bounding box coordinates

Return type:

tuple

property centre

The centre of the shape

close()

Close the HDF5 file

property containing_box

The box containing the sample

del_atoms(deleter)

Delete atoms in the given range

Parameters:

deleter (func) – Check atoms and return only those we want to keep

property dimensions

The dimensions of the bounding box

Returns:

The dimensions

Return type:

array

get_atoms()

Get all the atoms

Returns:

The atom data

Return type:

object

get_atoms_in_fov(x0, x1)

Get the subset of atoms within the field of view

Parameters:

  • x0 (float) – The start of the z range

  • x1 (float) – The end of the z range

Returns:

The atom data

Return type:

object

get_atoms_in_group(name)

Get the atoms in the group

get_atoms_in_range(x0, x1, filter=None)

Get the subset of atoms within the field of view

Parameters:

  • x0 (float) – The start of the z range

  • x1 (float) – The end of the z range

  • filter (func) – A function to filter the atoms

Returns:

The atom data

Return type:

object

get_molecule(name)

Get the molcule data

Parameters:

name (str) – The molecule name

Returns:

The molecule data

Return type:

tuple (atoms, positions, orientations)

identifier(name)

Get an identifier for the object

info()

Get some sample info

Returns:

Some sample info

Return type:

str

iter_atom_groups()

Iterate over the atom groups

Yields:

object – The atom group

iter_atoms()

Iterate over the atoms

Yields:

object – The atom data

iter_molecules()

Iterate over the molecules

Yields:

tuple (name, data) – The molecule data

property molecules

The list of molecule names

Returns:

The list of molecule names

Return type:

list

property number_of_atoms

Returns: int: The number of atoms

property number_of_molecular_models

The number of molecular models

Returns:

The number of molecular models

Return type:

int

property number_of_molecules

The number of molecules

Returns:

The number of molcules

Return type:

int

property shape

The ideal shape of the sample

property shape_box

Return the shape box

property shape_radius

Return a radius