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])

Open a RELION tomogram reconstruction job folder.

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.	[1]

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: Optional[Path.Save] = None,
    invert: bool = True,
    bin_size: list[int] = [1],
):
    """Open a RELION tomogram reconstruction job folder.

    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.
    """
    path = Path(path)
    if path.name != "job.star" or not path.is_file() or not path.exists():
        raise ValueError(f"Path must be an existing RELION job.star file, got {path}")
    job_dir_path = Path(path).parent
    rln_project_path = _relion_project_path(job_dir_path)
    jobtype = _get_job_type(job_dir_path)
    if project_root is None:
        project_root = job_dir_path / "cylindra"
    if jobtype in ("relion.reconstructtomograms", "relion.denoisetomo"):
        # Reconstruct Tomogram job
        tomogram_star_path = job_dir_path / "tomograms.star"
        if not tomogram_star_path.exists():
            raise FileNotFoundError(
                f"tomogram.star file {tomogram_star_path} does not exist. Make sure "
                "the input job has an tomogram output."
            )
        col = (
            REC_TOMO_DENOISED_PATH if jobtype == "relion.denoisetomo" else REC_TOMO_PATH
        )
        _, tomo_paths, scales = _parse_tomo_star(tomogram_star_path, col)
        paths = [rln_project_path / p for p in tomo_paths]
        moles = None
    elif jobtype in ("relion.picktomo", "relion.pseudosubtomo"):
        if not (opt_star_path := job_dir_path / "optimisation_set.star").exists():
            raise ValueError(
                f"Optimisation set star file not found in {job_dir_path}. "
                "Please ensure the job is a RELION 5.0 pick-particles job."
            )
        paths, scales, moles = _parse_optimisation_star(opt_star_path, rln_project_path)
    elif jobtype in ("relion.initialmodel.tomo", "relion.refine3d.tomo"):
        opt_set_path_list = sorted(
            job_dir_path.glob("run_it*_optimisation_set.star"),
            key=lambda p: p.stem,
        )
        if len(opt_set_path_list) == 0:
            raise ValueError(
                f"No optimisation set star files found in {job_dir_path}. "
                "Please ensure at least one iteration has finished."
            )
        opt_star_path = opt_set_path_list[-1]
        paths, scales, moles = _parse_optimisation_star(opt_star_path, rln_project_path)
    else:
        raise ValueError(f"Job {job_dir_path.name} is not a supported RELION job.")
    # TODO: parse tilt angles
    ui.batch._new_projects_from_table(
        paths,
        save_root=project_root,
        scale=scales,
        invert=[invert] * len(paths),
        molecules=moles,
        bin_size=[bin_size] * len(paths),
    )

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 _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.write(df, save_path)

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

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

Source code in cylindra_builtins/relion/io.py

@register_function(name="Save molecules for extract", record=False)
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 = True,
    centered: bool = True,
):
    """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.
    """
    particles_dfs = list[pd.DataFrame]()
    for _, df in _iter_dataframe_from_path_sets(
        path_sets,
        save_features=save_features,
        shift_by_origin=shift_by_origin,
        centered=centered,
    ):
        particles_dfs.append(df)
    particles_df = pd.concat(particles_dfs)
    starfile.write({"particles": particles_df}, coordinates_path)

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

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

Source code in cylindra_builtins/relion/io.py

@register_function(name="Save molecules for import", record=False)
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,
):
    """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.
    """
    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[pd.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,
    ):
        particles_path = save_dir / f"{tomo_name}_particles.star"
        particles_dfs.append(df)
        particles_paths.append(particles_path)
        tomo_names.append(tomo_name)
        starfile.write(df, particles_path)

    df_opt = pd.DataFrame(
        {
            TOMO_NAME: tomo_names,
            IMPORT_PARTICLE_FILE: particles_paths,
        }
    )
    starfile.write(df_opt, 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")
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
    scale = ui.tomogram.scale
    centerz, centery, centerx = (np.array(ui.tomogram.image.shape) / 2 - 1) * scale
    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").to_pandas()
    starfile.write(df, save_path)