Tutorial

Simulation of datasets is split into a number of different commands. Each command takes a set of command line options or a configuration file in YAML format.

Generate a new configuration file

parakeet.config.new

This will generate a new file called config.yaml which will contain the following configuration.

microscope:
  beam:
    electrons_per_angstrom: 30
    energy: 300
    source_spread: 0.1
  detector:
    nx: 1000
    ny: 1000
    pixel_size: 1
  lens:
    c_10: -20000
    c_30: 2.7
    c_c: 2.7
sample:
  box:
  - 1000
  - 1000
  - 1000
  centre:
  - 500
  - 500
  - 500
  molecules: null
  shape:
    cube:
      length: 1000.0
    cuboid:
      length_x: 1000.0
      length_y: 1000.0
      length_z: 1000.0
    cylinder:
      length: 1000.0
      radius: 500.0
    margin:
    - 0
    - 0
    - 0
    type: cube
scan:
  mode: still
  num_images: 1
  start_angle: 0
  step_angle: 0
simulation:
  ice: false

Edit the configuration file

The configuration file now needs to be edited to perform the desired simulation. For example, to simulate with a single molecule we modify the sample.molecules field as follows.

microscope:
  beam:
    electrons_per_angstrom: 30
    energy: 300
    source_spread: 0.1
  detector:
    nx: 1000
    ny: 1000
    pixel_size: 1
  lens:
    c_10: -20000
    c_30: 2.7
    c_c: 2.7
sample:
  box:
  - 1000
  - 1000
  - 1000
  centre:
  - 500
  - 500
  - 500
  molecules:
    pdb:
      - id: 4v1w
        instances: 1
  shape:
    cube:
      length: 1000.0
    cuboid:
      length_x: 1000.0
      length_y: 1000.0
      length_z: 1000.0
    cylinder:
      length: 1000.0
      radius: 500.0
    margin:
    - 0
    - 0
    - 0
    type: cube
scan:
  mode: still
  num_images: 1
  start_angle: 0
  step_angle: 0
simulation:
  ice: false

Generate sample model

Once the configuration file has been generated a new sample file can be created with the following command:

parakeet.sample.new -c config.yaml

This will result in a file “sample.h5” being generated. This file contains information about the size and shape of the sample but as yet doesn’t contain any atomic coordinates. The atomic model is added by running the following command which adds molecules to the sample file. If a single molcule is specified then it will be placed in the centre of the sample volume. If multiple molecules are specified then the molecules will be positioned at random locations in the sample volume. This command will update the “sample.h5” file with the atomic coordinates but will not generated any new files.

parakeet.sample.add_molecules -c config.yaml

Simulate EM images

Once the atomic model is ready, the EM images can be simulated with the following commands. Each stage of the simulation is separated because it may be desirable to simulate many different defocused images from the sample exit wave for example or many different doses for the sample defocusses image. Being separate, the output of one stage can be reused for multiple runs of the next stage. The first stage is to simulate the exit wave. This is the propagation of the electron wave through the sample. It is therefore the most computationally intensive part of the processes since the contribution of all atoms within the sample needs to be calculated.

parakeet.simulate.exit_wave -c config.yaml

This command will generate a file “exit_wave.h5” which will contain the exit wave of all tilt angles. The next step is to simulate the micropscope optics which is done with the following command:

parakeet.simulate.optics -c config.yaml

This step is much quicker as it only scales with the size of the detector image and doesn’t require the atomic coordinates again. The command will output a file “optics.h5”. Finally, the response of the detector can be simulated with the following command:

parakeet.simulate.image -c config.yaml

This command will add the detector DQE and the Poisson noise for a given dose and will output a file “image.h5”.

Export functions

Typically we cant to output an MRC file for further processing. The hdf5 files can easily be exported to MRC by the following command:

parakeet.export file.h5 -o file.mrc

The export command can also be used to rebin the image or select a region of interest.

Analysis functions

The reconstruction function can be called in Parakeet in the following way:

parakeet.export image.h5 -o image.mrc
parakeet.analyse.reconstruct -c config.yaml -i image.mrc

Averaging of the particles can then be done with:

parakeet.analyse.average_particles -c config.yaml