cylindra_builtins.relion

This built-in plugin submodule provides functions to work with RELION file formats.

load_molecules(ui, path)

Read monomer coordinates and angles from RELION .star file.

Parameters:

Name	Type	Description	Default
path	path - like	The path to the star file.	required

Source code in cylindra_builtins/relion/io.py

@register_function(name="Load molecules")
def load_molecules(ui: CylindraMainWidget, path: Path.Read[FileFilter.STAR]):
    """Read monomer coordinates and angles from RELION .star file.

    Parameters
    ----------
    path : path-like
        The path to the star file.
    """
    path = Path(path)
    moles = _read_star(path, ui.tomogram)
    for i, mole in enumerate(moles.values()):
        add_molecules(ui.parent_viewer, mole, f"{path.name}-{i}", source=None)

load_splines(ui, path)

Read a star file and register all the tubes as splines.

The "rlnHelicalTubeID" column will be used to group the points into splines.

Parameters:

Name	Type	Description	Default
path	path - like	The path to the star file.	required

Source code in cylindra_builtins/relion/io.py

@register_function(name="Load splines")
def load_splines(ui: CylindraMainWidget, path: Path.Read[FileFilter.STAR]):
    """Read a star file and register all the tubes as splines.

    The "rlnHelicalTubeID" column will be used to group the points into splines.

    Parameters
    ----------
    path : path-like
        The path to the star file.
    """
    mole = Molecules.concat(_read_star(path, ui.tomogram).values())
    if RELION_TUBE_ID not in mole.features.columns:
        warnings.warn(
            f"{RELION_TUBE_ID!r} not found in star file. Use all points as a "
            "single spline.",
            UserWarning,
            stacklevel=2,
        )
        ui.register_path(mole.pos, err_max=1e-8)
    else:
        for _, each in mole.group_by(RELION_TUBE_ID):
            ui.register_path(each.pos, err_max=1e-8)

open_relion_job(ui, path, project_root=None, invert=True, bin_size=[1], scale_override=None, join_molecules_by_id=False, use_tilt_series=False, reference_scale=2.0, tomo_height=300.0, path_sets=None)

Open a RELION tomogram reconstruction/refinement job as a cylindra batch project.

Tomogram reconstruction, denoising, particle picking, initial model, 3D classification and 3D refinement jobs are supported. Tilt series alignment jobs are also supported, which always create projects from the tilt series.

Parameters:

Name	Type	Description	Default
path	path - like	The path to the RELION job.star file.	required
project_root	path - like	The root directory to save the projects for each tomogram. If not provided, it will be automatically created in the RELION job directory.	None
invert	bool	Set to True if the tomograms are light backgroud.	True
bin_size	list[int]	The multiscale binning size for the tomograms. If the projects are created from the tilt series, the bin sizes available for analysis.	[1]
scale_override	float	If provided, the pixel size in the tomogram.star file will be ignored and this value will be used in cylindra. If the projects are created from the tilt series, this is the pixel size of the tilt series.	None
join_molecules_by_id	bool	If True, particle will be joined to the cylindra particles assuming that the current Batch Analysis widget state is the same as the state when you exported cylindra particles for RELION. This option is useful when you want to import particles back to cylindra and fill the missing geometrical features (e.g. nth and pf-id used for lattice structure analysis).	False
use_tilt_series	bool	If True, the projects are created from the tilt series (the "rlnTomoTiltSeriesStarFile" column) instead of the reconstructed tomograms. Subtomograms are reconstructed directly from the tilt series, and the image regions needed for analysis are reconstructed on demand. Always True for tilt series alignment jobs, which have no tomograms.	False
reference_scale	nm	Pixel size of the coarse tomograms for visualization in nm, if the projects are created from the tilt series. It does not need to be an integer multiple of the pixel size of the tilt series. The coarse tomogram is reconstructed from the tilt series when the project is opened, and saved when the project is saved. If None, the RELION tomograms are used as the coarse tomograms. If the RELION tomograms are not available, the coarse tomograms are reconstructed with the pixel size of the RELION tomograms, or 2.0 nm for jobs without tomograms.	2.0
tomo_height	nm	Height (thickness along z) of the coarse tomograms reconstructed from the tilt series in nm, used only for jobs without the tomogram size (such as tilt series alignment jobs).	300.0

Source code in cylindra_builtins/relion/io.py

@register_function(name="Open RELION job")
def open_relion_job(
    ui: CylindraMainWidget,
    path: Path.Read[FileFilter.STAR_JOB],
    project_root: Annotated[Optional[Path.Save], {"text": "Under the RELION job"}] = None,
    invert: bool = True,
    bin_size: list[int] = [1],
    scale_override: Annotated[
        Optional[float],
        {
            "label": "scale override (nm/pix)",
            "text": "Use same scale",
            "options": {"step": 0.0001, "min": 0.01, "max": 1000.0, "value": 0.5},
        },
    ] = None,
    join_molecules_by_id: Annotated[bool, {"text": "Join RELION particles to the current batch project"}] = False,
    use_tilt_series: Annotated[bool, {"label": "Create projects from tilt series"}] = False,
    reference_scale: Annotated[
        Optional[nm],
        {
            "label": "Coarse tomogram pixel size (nm)",
            "text": "Use RELION tomograms",
            "options": {"min": 0.01, "max": 100.0, "step": 0.001, "value": 2.0},
        },
    ] = 2.0,
    tomo_height: Annotated[nm, {"label": "Coarse tomogram height (nm)", "min": 1.0, "max": 10000.0}] = 300.0,
    path_sets: Annotated[Any, {"bind": _get_loader_paths}] = None,
):  # fmt: skip
    """Open a RELION tomogram reconstruction/refinement job as a cylindra batch project.

    Tomogram reconstruction, denoising, particle picking, initial model, 3D
    classification and 3D refinement jobs are supported. Tilt series alignment jobs
    are also supported, which always create projects from the tilt series.

    Parameters
    ----------
    path : path-like
        The path to the RELION job.star file.
    project_root : path-like, optional
        The root directory to save the projects for each tomogram. If not provided,
        it will be automatically created in the RELION job directory.
    invert : bool, default True
        Set to True if the tomograms are light backgroud.
    bin_size : list[int], default [1]
        The multiscale binning size for the tomograms. If the projects are created
        from the tilt series, the bin sizes available for analysis.
    scale_override : float, optional
        If provided, the pixel size in the tomogram.star file will be ignored and
        this value will be used in cylindra. If the projects are created from the tilt
        series, this is the pixel size of the tilt series.
    join_molecules_by_id : bool, default False
        If True, particle will be joined to the cylindra particles assuming that the
        current Batch Analysis widget state is the same as the state when you exported
        cylindra particles for RELION. This option is useful when you want to import
        particles back to cylindra and fill the missing geometrical features (e.g. `nth`
        and `pf-id` used for lattice structure analysis).
    use_tilt_series : bool, default False
        If True, the projects are created from the tilt series (the
        "rlnTomoTiltSeriesStarFile" column) instead of the reconstructed tomograms.
        Subtomograms are reconstructed directly from the tilt series, and the image
        regions needed for analysis are reconstructed on demand. Always True for tilt
        series alignment jobs, which have no tomograms.
    reference_scale : nm, default 2.0
        Pixel size of the coarse tomograms for visualization in nm, if the projects are
        created from the tilt series. It does not need to be an integer multiple of the
        pixel size of the tilt series. The coarse tomogram is reconstructed from the
        tilt series when the project is opened, and saved when the project is saved. If
        None, the RELION tomograms are used as the coarse tomograms. If the RELION
        tomograms are not available, the coarse tomograms are reconstructed with the
        pixel size of the RELION tomograms, or 2.0 nm for jobs without tomograms.
    tomo_height : nm, default 300.0
        Height (thickness along z) of the coarse tomograms reconstructed from the tilt
        series in nm, used only for jobs without the tomogram size (such as tilt series
        alignment jobs).
    """
    job = _parse_relion_job(path, project_root)
    use_tilt_series = use_tilt_series or not job.has_tomograms
    if use_tilt_series:
        projects = [
            _new_tilt_series_project(
                tomo, scale_override, bin_size, invert, reference_scale, tomo_height
            )
            for tomo in job.tomograms
        ]
    else:
        projects = None
    moles = None
    if job.has_particles:
        moles = list[dict[str, Molecules]]()
        for i, (tomo, particles) in enumerate(
            zip(job.tomograms, job.particles, strict=True)
        ):
            if projects is not None:
                # centered coordinates are in the tomogram space of the tilt series
                prj = projects[i]
                center, scale = prj.tilt_series.tomogram_center, prj.scale
            else:
                scale = tomo.scale
                center = _relion_utils.shape_to_center_zyx(tomo.shape, scale)
            moles.append(_particles_to_molecules(particles, center, scale=scale))
    splines = None
    molecule_sources = None
    if join_molecules_by_id:
        if path_sets is None or len(path_sets) == 0:
            raise ValueError(
                "No molecules to join. Please add projects in the batch analysis "
                "widget first to join RELION particles."
            )
        if moles is None:
            raise ValueError(f"Job {path} has no particles to join.")
        moles, splines, molecule_sources = _match_molecules(moles, path_sets)
    if projects is not None:
        ui.batch._add_new_projects(
            [
                (prj, tomo.name)
                for prj, tomo in zip(projects, job.tomograms, strict=True)
            ],
            save_root=job.project_root,
            splines=splines,
            molecules=moles,
            molecule_sources=molecule_sources,
        )
        return
    paths = [tomo.require_tomo_path() for tomo in job.tomograms]
    if scale_override is not None:
        scales = [scale_override] * len(paths)
    else:
        scales = [tomo.scale for tomo in job.tomograms]
    ui.batch._new_projects_from_table(
        paths,
        save_root=job.project_root,
        splines=splines,
        scale=scales,
        invert=[invert] * len(paths),
        molecules=moles,
        molecule_sources=molecule_sources,
        bin_size=[bin_size] * len(paths),
        tilt_model=[tomo.tilt_model for tomo in job.tomograms],
    )

save_molecules(ui, save_path, layers, save_features=False, tomo_name_override='', shift_by_origin=True)

Save the selected molecules to a RELION .star file.

If multiple layers are selected, the MoleculeGroupID column will be added to the star file to distinguish the layers. This method is RELION 5 compliant.

Parameters:

Name	Type	Description	Default
save_path	path - like	The path to save the star file.	required
layers	sequence of MoleculesLayer	The layers to save.	required
save_features	bool	Whether to save the features of the molecules.	True
tomo_name_override	str	If provided, this will override the tomogram name identifier (the rlnTomoName column) in the star file.	""
shift_by_origin	bool	If True, the positions will be shifted by the origin of the tomogram. This option is required if you picked molecules in a trimmed tomogram.	True

Source code in cylindra_builtins/relion/io.py

@register_function(name="Save molecules")
def save_molecules(
    ui: CylindraMainWidget,
    save_path: Path.Save[FileFilter.STAR],
    layers: MoleculesLayersType,
    save_features: bool = False,
    tomo_name_override: str = "",
    shift_by_origin: bool = True,
):
    """Save the selected molecules to a RELION .star file.

    If multiple layers are selected, the `MoleculeGroupID` column will be added
    to the star file to distinguish the layers. This method is RELION 5 compliant.

    Parameters
    ----------
    save_path : path-like
        The path to save the star file.
    layers : sequence of MoleculesLayer
        The layers to save.
    save_features : bool, default True
        Whether to save the features of the molecules.
    tomo_name_override : str, default ""
        If provided, this will override the tomogram name identifier (the rlnTomoName
        column) in the star file.
    shift_by_origin : bool, default True
        If True, the positions will be shifted by the origin of the tomogram. This
        option is required if you picked molecules in a trimmed tomogram.
    """
    save_path = Path(save_path)
    layers = assert_list_of_layers(layers, ui.parent_viewer)
    tomo_name = tomo_name_override or _relion_utils.strip_relion5_prefix(
        ui.tomogram.image.name
    )
    df = _mole_to_star_df(
        [layer.molecules for layer in layers],
        ui.tomogram,
        tomo_name,
        save_features,
        shift_by_origin,
    )
    starfile_rs.as_star(df).write(save_path)

save_molecules_for_extract(ui, coordinates_path, path_sets, save_features=False, shift_by_origin=False, centered=True, relion_scale=None)

Save the batch analyzer state as a star file for "Extract subtomo" job.

The output star file should be provided as the "I/O > Input particle set" with "OR: use direct entries" set to "Yes".

Parameters:

Name	Type	Description	Default
coordinates_path	path - like	The path to save the star file containing the particles.	required
path_sets	sequence of PathInfo	The path sets to the tomograms and molecules.	required
save_features	bool	Whether to save the features of the molecules to the star file.	False
shift_by_origin	bool	If True, the positions will be shifted by the origin of the tomogram. This option is required if you picked molecules in a trimmed tomogram.	True
centered	bool	If True, the positions will be centered around the tomogram center, and columns "rlnCenteredCoordinateX/Y/ZAngst" will be used. If False, columns "rlnCoordinateX/Y/Z" will be used.	True
relion_scale	float	Set this value if different pixel size is used in RELION. This happens when you calibrated the pixel size on cylindra side.	None

Source code in cylindra_builtins/relion/io.py

@register_function(name="Save molecules for extract", record=False)
@thread_worker.with_progress(
    desc="Saving molecules for extract", total="len(path_sets)"
)
def save_molecules_for_extract(
    ui: CylindraMainWidget,
    coordinates_path: Path.Save[FileFilter.STAR],
    path_sets: Annotated[Any, {"bind": _get_loader_paths}],
    save_features: bool = False,
    shift_by_origin: bool = False,
    centered: bool = True,
    relion_scale: _RELION_SCALE_TYPE = None,
):
    """Save the batch analyzer state as a star file for "Extract subtomo" job.

    The output star file should be provided as the "I/O > Input particle set" with
    "OR: use direct entries" set to "Yes".

    Parameters
    ----------
    coordinates_path : path-like
        The path to save the star file containing the particles.
    path_sets : sequence of PathInfo
        The path sets to the tomograms and molecules.
    save_features : bool, default False
        Whether to save the features of the molecules to the star file.
    shift_by_origin : bool, default True
        If True, the positions will be shifted by the origin of the tomogram. This
        option is required if you picked molecules in a trimmed tomogram.
    centered : bool, default True
        If True, the positions will be centered around the tomogram center, and columns
        "rlnCenteredCoordinateX/Y/ZAngst" will be used. If False, columns
        "rlnCoordinateX/Y/Z" will be used.
    relion_scale : float, optional
        Set this value if different pixel size is used in RELION. This happens when you
        calibrated the pixel size on cylindra side.
    """
    particles_dfs = list[pl.DataFrame]()
    for _, df in _iter_dataframe_from_path_sets(
        path_sets,
        save_features=save_features,
        shift_by_origin=shift_by_origin,
        centered=centered,
        relion_scale=relion_scale,
    ):
        particles_dfs.append(df)
        yield
    particles_df = pl.concat(particles_dfs, how="diagonal_relaxed")
    coordinates_path = Path(coordinates_path)
    if coordinates_path.suffix == "":
        coordinates_path = coordinates_path.with_suffix(".star")
    starfile_rs.as_star(particles=particles_df).write(coordinates_path)

save_molecules_for_import(ui, coordinates_path, path_sets, save_features=False, shift_by_origin=True, centered=True, relion_scale=None)

Save the batch analyzer state as star files for "Import" job.

Parameters:

Name	Type	Description	Default
coordinates_path	path - like	The path to save the star file containing the particles.	required
path_sets	sequence of PathInfo	The path sets to the tomograms and molecules.	required
save_features	bool	Whether to save the features of the molecules to the star file.	False
shift_by_origin	bool	If True, the positions will be shifted by the origin of the tomogram. This option is required if you picked molecules in a trimmed tomogram.	True
centered	bool	If True, the positions will be centered around the tomogram center, and columns "rlnCenteredCoordinateX/Y/ZAngst" will be used. If False, columns "rlnCoordinateX/Y/Z" will be used.	True
relion_scale	float	Set this value if different pixel size is used in RELION. This happens when you calibrated the pixel size on cylindra side.	None

Source code in cylindra_builtins/relion/io.py

@register_function(name="Save molecules for import", record=False)
@thread_worker.with_progress(desc="Saving molecules for import", total="len(path_sets)")
def save_molecules_for_import(
    ui: CylindraMainWidget,
    coordinates_path: Path.Save[FileFilter.STAR],
    path_sets: Annotated[Any, {"bind": _get_loader_paths}],
    save_features: bool = False,
    shift_by_origin: bool = True,
    centered: bool = True,
    relion_scale: _RELION_SCALE_TYPE = None,
):
    """Save the batch analyzer state as star files for "Import" job.

    Parameters
    ----------
    coordinates_path : path-like
        The path to save the star file containing the particles.
    path_sets : sequence of PathInfo
        The path sets to the tomograms and molecules.
    save_features : bool, default False
        Whether to save the features of the molecules to the star file.
    shift_by_origin : bool, default True
        If True, the positions will be shifted by the origin of the tomogram. This
        option is required if you picked molecules in a trimmed tomogram.
    centered : bool, default True
        If True, the positions will be centered around the tomogram center, and columns
        "rlnCenteredCoordinateX/Y/ZAngst" will be used. If False, columns
        "rlnCoordinateX/Y/Z" will be used.
    relion_scale : float, optional
        Set this value if different pixel size is used in RELION. This happens when you
        calibrated the pixel size on cylindra side.
    """
    coordinates_path = Path(coordinates_path)
    save_dir = coordinates_path.parent / f"{coordinates_path.stem}_particles"
    save_dir.mkdir(exist_ok=True)

    tomo_names = list[str]()
    particles_paths = list[str]()
    particles_dfs = list[pl.DataFrame]()
    for tomo_name, df in _iter_dataframe_from_path_sets(
        path_sets,
        save_features=save_features,
        shift_by_origin=shift_by_origin,
        centered=centered,
        relion_scale=relion_scale,
    ):
        particles_path = save_dir / f"{tomo_name}_particles.star"
        particles_dfs.append(df)
        particles_paths.append(str(particles_path))
        tomo_names.append(tomo_name)
        starfile_rs.as_star(df).write(particles_path)
        yield

    df_opt = pl.DataFrame(
        {
            TOMO_NAME: tomo_names,
            IMPORT_PARTICLE_FILE: particles_paths,
        },
        schema={TOMO_NAME: pl.String, IMPORT_PARTICLE_FILE: pl.String},
    )
    starfile_rs.as_star(df_opt).write(coordinates_path)

save_splines(ui, save_path, interval=10.0, tomo_name_override='', shift_by_origin=True)

Save the current splines to a RELION .star file.

Parameters:

Name	Type	Description	Default
save_path	path - like	The path to save the star file.	required
interval	float	Sampling interval along the splines. For example, if interval=10.0 and the length of a spline is 100.0, 11 points will be sampled.	10.0
tomo_name_override	str	If provided, this will override the tomogram name identifier (the rlnTomoName column) in the star file.	""
shift_by_origin	bool	If True, the positions will be shifted by the origin of the tomogram. This option is required if you picked molecules in a trimmed tomogram.	True

Source code in cylindra_builtins/relion/io.py

@register_function(name="Save splines", record=False)
def save_splines(
    ui: CylindraMainWidget,
    save_path: Path.Save[FileFilter.STAR],
    interval: Annotated[float, {"min": 0.01, "max": 1000.0, "label": "Sampling interval (nm)"}] = 10.0,
    tomo_name_override: str = "",
    shift_by_origin: bool = True,
):  # fmt: skip
    """Save the current splines to a RELION .star file.

    Parameters
    ----------
    save_path : path-like
        The path to save the star file.
    interval : float, default 10.0
        Sampling interval along the splines. For example, if interval=10.0 and the
        length of a spline is 100.0, 11 points will be sampled.
    tomo_name_override : str, default ""
        If provided, this will override the tomogram name identifier (the rlnTomoName
        column) in the star file.
    shift_by_origin : bool, default True
        If True, the positions will be shifted by the origin of the tomogram. This
        option is required if you picked molecules in a trimmed tomogram.
    """

    if interval <= 1e-4:
        raise ValueError("Interval must be larger than 1e-4.")
    save_path = Path(save_path)
    data_list: list[pl.DataFrame] = []
    orig = ui.tomogram.origin
    if not shift_by_origin:
        orig = type(orig)(0.0, 0.0, 0.0)
    tomo_name = tomo_name_override or ui.tomogram.image.name
    centerz, centery, centerx = _relion_center_zyx(ui.tomogram)
    for i, spl in enumerate(ui.splines):
        num = int(spl.length() / interval)
        coords = spl.partition(num)
        mole_count = coords.shape[0]
        df = pl.DataFrame(
            {
                TOMO_NAME: [tomo_name] * mole_count,
                POS_CENTERED[2]: (coords[:, 2] - centerx + orig.x) * 10,  # Angstrom
                POS_CENTERED[1]: (coords[:, 1] - centery + orig.y) * 10,  # Angstrom
                POS_CENTERED[0]: (coords[:, 0] - centerz + orig.z) * 10,  # Angstrom
                ROT_COLUMNS[0]: 0.0,
                ROT_COLUMNS[1]: 0.0,
                ROT_COLUMNS[2]: 0.0,
                RELION_TUBE_ID: i,
            }
        )
        data_list.append(df)
    df = pl.concat(data_list, how="vertical")
    starfile_rs.as_star(df).write(save_path)