Python bindings to RELION
Free software: GPLv2 and BSD, see the license file for details
Documentation: https://python-relion.readthedocs.io.
This package provides a python interface to the information contained in a Relion project folder. It does not run Relion itself.
Currently it caters for specific fields from the Motion Correction, CTF Find, 2D Classification and 3D Classification stages of the Relion pipeline, but this could readily be expanded to more stages and fields.
Usage
To access a Relion project folder you first need to create a relion.Project
object (c.f. API for more information):
import relion
proj = relion.Project("/path/to/relion/project/directory")
proj = relion.Project(pathlib.Path("/project/directory")) # path objects are supported
The directory structure inside a Relion directory is built up of stages and jobs.
Each stage folder will contain one or more job folders.
The job folder(s) contain files related to the stage, including the *.star
files from which values can be read:
project_root
│
├── MotionCorr
│ └── job002
│ └── corrected_micrographs.star
│ └── ...
├── CTFFind
│ └── job003
│ └── micrographs_ctf.star
│ └── ...
├── Class2D
│ ├── job008
│ │ └── run_it025_data.star
│ │ └── run_it025_model.star
│ │ └── ...
│ └── job013
│ └── run_it_025_data.star
│ └── run_it_025_model.star
│ └── ...
└── Class3D
└── job016
└── run_it_025_data.star
└── run_it_025_model.star
└── ...
The desired EM values are extracted from *.star files.
For example, a snippet from MotionCorr/job002/corrected_micrographs.star
is shown below:
...
loop_
_rlnCtfPowerSpectrum #1
_rlnMicrographName #2
_rlnMicrographMetadata #3
_rlnOpticsGroup #4
_rlnAccumMotionTotal #5
_rlnAccumMotionEarly #6
_rlnAccumMotionLate #7
MotionCorr/job002/Movies/20170629_00021_frameImage_PS.mrc MotionCorr/job002/Movies/20170629_00021_frameImage.mrc MotionCorr/job002/Movies/20170629_00021_frameImage.star 1 16.420495 2.506308 13.914187
MotionCorr/job002/Movies/20170629_00022_frameImage_PS.mrc MotionCorr/job002/Movies/20170629_00022_frameImage.mrc MotionCorr/job002/Movies/20170629_00022_frameImage.star 1 19.551677 2.478968 17.072709
MotionCorr/job002/Movies/20170629_00023_frameImage_PS.mrc MotionCorr/job002/Movies/20170629_00023_frameImage.mrc MotionCorr/job002/Movies/20170629_00023_frameImage.star 1 17.547827 1.941103 15.606724
MotionCorr/job002/Movies/20170629_00024_frameImage_PS.mrc MotionCorr/job002/Movies/20170629_00024_frameImage.mrc MotionCorr/job002/Movies/20170629_00024_frameImage.star 1 18.100817 1.722567 16.378250
...
To access the _rlnAccumMotionTotal
column in this file you can use:
>>> [micrograph.total_motion for micrograph in proj.motioncorrection["job002"]]
['16.420495', '19.551677', '17.547827', '18.100817', ...]
Stages are dictionary-like objects, so can discover the list of all known jobs by:
>>> list(proj.class2D)
['job008', 'job013']
and use the other standard dictionary accessors (.values()
, .keys()
, .items()
), too.
You can also convert the stages into normal dictionaries:
>>> dict(p.ctffind)
{'job003': [CTFMicrograph(...), ...]}
For a list of supported stages and a list of supported values per stage please have a look at the API page.
API
Project object
- class relion.Project(path, database='ISPyB', run_options=None, message_constructors=None)[source]
Reads information from a Relion project directory and makes it available in a structured, object-oriented, and pythonic fashion.
- property class2D
access the 2D classification stage of the project. Returns a dictionary-like object with job names as keys, and lists of Class2DParticleClass namedtuples as values.
- property class3D
access the 3D classification stage of the project. Returns a dictionary-like object with job names as keys, and lists of Class3DParticleClass namedtuples as values.
- property ctffind
access the CTFFind stage of the project. Returns a dictionary-like object with job names as keys, and lists of CTFMicrograph namedtuples as values.
- property motioncorrection
access the motion correction stage of the project. Returns a dictionary-like object with job names as keys, and lists of MCMicrograph namedtuples as values.
The individual stage accessors .ctffind
, .class2D
, etc. return a dictionary-like object that allows you to access individual Relion jobs within that particular stage.
The dictionary key names are the relion job names (usually jobXXX
), the dictionary value is a list of stage-specific named tuples, listed below.
Stage-specific information
- class relion._parser.ctffind.CTFMicrograph(micrograph_name, astigmatism, defocus_u, defocus_v, defocus_angle, max_resolution, fig_of_merit, amp_contrast, diagnostic_plot_path)
Contrast Transfer Function stage.
- property amp_contrast
Amplitude contrast.
- property astigmatism
Estimated astigmatism. Units angstrom (A).
- property defocus_angle
Estimated angle of astigmatism.
- property defocus_u
Averaged with Defocus V to give estimated defocus. Units angstrom (A).
- property defocus_v
Averaged with Defocus U to give estimated defocus. Units angstrom (A).
- property diagnostic_plot_path
Path to the CTF diagnostic (fit/data comparison) plot (jpeg).
- property fig_of_merit
Figure of merit/CC/correlation value. Confidence of the defocus estimation.
- property max_resolution
Maximum resolution that the software can detect. Units angstrom (A).
- property micrograph_name
Micrograph name. Useful for reference.
- class relion._parser.motioncorrection.MCMicrograph(micrograph_name, micrograph_snapshot_full_path, micrograph_number, total_motion, early_motion, late_motion, micrograph_timestamp, drift_data)
Motion Correction stage.
- property drift_data
Alias for field number 7
- property early_motion
Early motion.
- property late_motion
Late motion.
- property micrograph_name
Micrograph name. Useful for reference.
- property micrograph_number
Micrograph number: sequential in time.
- property micrograph_snapshot_full_path
Path to jpeg of the motion corrected micrograph.
- property micrograph_timestamp
Time stamp at which the micrograph was created.
- property total_motion
Total motion. The amount the sample moved during exposure. Units angstrom (A).
- class relion._parser.class2D.Class2DParticleClass(particle_sum, reference_image, class_distribution, accuracy_rotations, accuracy_translations_angst, estimated_resolution, overall_fourier_completeness, job)
2D Classification stage.
- property accuracy_rotations
Accuracy rotations.
- property accuracy_translations_angst
Accuracy translations angst.
- property class_distribution
Class Distribution. Proportional to the number of particles per class.
- property estimated_resolution
Estimated resolution.
- property job
Job number of the Class2D job.
- property overall_fourier_completeness
Overall Fourier completeness.
- property particle_sum
Sum of all particles in the class. Gives a tuple with the class number first, then the particle sum.
- property reference_image
Reference image.
- class relion._parser.class3D.Class3DParticleClass(particle_sum, reference_image, class_distribution, accuracy_rotations, accuracy_translations_angst, estimated_resolution, overall_fourier_completeness, initial_model_num_particles, job)
3D Classification stage.
- property accuracy_rotations
Accuracy rotations.
- property accuracy_translations_angst
Accuracy translations angst.
- property class_distribution
Class Distribution. Proportional to the number of particles per class.
- property estimated_resolution
Estimated resolution.
- property initial_model_num_particles
The number of particles used to generate the initial model.
- property job
Job number of the Class3D job.
- property overall_fourier_completeness
Overall Fourier completeness.
- property particle_sum
Sum of all particles in the class. Gives a tuple with the class number first, then the particle sum.
- property reference_image
Reference image.
Credits
Anna Horstmann
Colin M. Palmer
Daniel Hatton
Donovan Webb
Markus Gerstel
Sjors H.W. Scheres
Takanori Nakane