Relion

K-DenseCommunityCreated by K-Dense Inc.

Skill
Workflow
Science and research
MIT
Low risk
Has scripts

From the author

Validates and executes RELION single-particle cryo-EM refinement and half-map postprocessing. Supports STAR optics/acquisition checks, particle-stack consistency, gold-standard half sets, soft-mask validation, diagnostic Fourier shell correlation, and restart guidance.

— the description by K-Dense Inc.

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The relion skill provides a structured Python-based workflow for managing single-particle cryo-EM refinement and postprocessing using RELION 5.0.1. It focuses on ensuring data consistency by validating STAR files, optics groups, and particle stacks before executing refinement. The workflow supports gold-standard half-set refinement and provides diagnostic tools for Fourier shell correlation (FSC) and soft-mask validation, helping researchers maintain rigorous standards throughout the reconstruction process.

What it does

Validates STAR file metadata, optics groups, and particle stack consistency.
Executes gold-standard 3D refinement using MPI-parallelized RELION processes.
Performs diagnostic Fourier shell correlation (FSC) analysis on independent half-maps.
Facilitates postprocessing with soft-masking to refine map quality.
Provides guidance for restarting interrupted refinement jobs.
Checks for common data errors like non-finite metadata or mismatched map grids.

When to use it

When performing single-particle cryo-EM refinement on extracted, CTF-annotated particles.
When you need to validate the integrity of your particle stacks and optics groups before processing.
When conducting gold-standard refinement requiring independent half-set splitting.
When performing postprocessing on converged unfiltered half-maps.
When you need to generate diagnostic FSC curves for map resolution assessment.

Advantages

Ensures data consistency through automated pre-refinement validation checks.
Standardizes the execution of complex RELION commands via a unified interface.
Prevents common errors by verifying pixel sizes, box dimensions, and coordinate conventions.
Supports reproducible research by recording command history and process logs.
Provides clear diagnostic outputs for FSC and mask validation.

Usage examples

“Validate my particle STAR file before starting refinement.”: The skill runs a series of checks on the STAR file, verifying optics membership, particle indices, and stack accessibility, reporting any inconsistencies.
“Run a 3D refinement on my particle subset.”: The skill executes the RELION refinement process with specified symmetry, diameter, and MPI ranks, ensuring gold-standard half-set splitting.
“Calculate the FSC for my refined half-maps.”: The skill performs a diagnostic FSC calculation between the two unfiltered half-maps and outputs the results to a TSV file.
“Postprocess my refined maps with a soft mask.”: The skill validates the mask and map grids before running the RELION postprocessing utility to generate the final sharpened map.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/k-dense-ai/relion/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip relion.zip -d .agents/skills
```

Documentation by K-Dense Inc.

RELION single-particle refinement

Use for a RELION single-particle project, especially extracted particles → homogeneous selected particle subset → gold-standard refinement → half-map validation and postprocessing. The bundled runner starts from CTF-annotated extracted particles and an initial 3D reference. It does not replace motion correction, picking, 2D/3D selection, or a biological interpretation of map quality. For tomography, helical reconstruction, Blush, or heterogeneous-state modeling, use the appropriate upstream workflow rather than forcing those data into this bounded SPA runner.

Preserve acquisition and coordinate conventions

Read references/acquisition-and-restarts.md when starting from movies or resuming jobs. Confirm pixel size in Å/pixel, voltage in kV, spherical aberration in mm, defocus in Å, amplitude contrast as a fraction, and the symmetry justified by the specimen. Do not “correct” a suspicious value by guessing its units.

data_optics describes acquisition/image groups; data_particles references them through _rlnOpticsGroup. Particle filenames use one-based [email protected]; leading zeros such as [email protected] are valid. Relative paths resolve from the RELION project directory, not the STAR file's directory. Keep optics groups when merging or subsetting STAR files. _rlnOriginXAngst/_rlnOriginYAngst are Å translations, not pixels.

Run from this skill directory with paths to the real project:

python scripts/spa_workflow.py validate-star project/particles.star --project project

This opens referenced stacks and checks optics membership, finite acquisition/CTF values, indices, box sizes, duplicate particle references and existing half-set assignments. Use --metadata-only only when stacks are genuinely unavailable; the JSON records stack_checks_performed: false. It does not scan every particle pixel for corruption or establish correct image normalization. Physical-range warnings are review prompts, not proof that unusual microscope settings are wrong.

Refine a selected particle population

Before running, inspect representative particles and class averages, defocus distributions, CTF fits, particle orientation distribution, and the initial reference. Ensure the map and particle boxes/pixel sizes agree after any downsampling. The runner deliberately supports one effective box/pixel size across optics groups; handle heterogeneous sampling with an explicit upstream resampling workflow. Use conventionally extracted, normalized particles that have not already been phase-flipped or Wiener-filtered; this runner does not configure those special input cases.

python scripts/spa_workflow.py refine \
  --star project/particles.star --reference project/initial.mrc \
  --project project --diameter 180 --symmetry C1 \
  --initial-lowpass 40 --mpi-ranks 3 --threads 2 --output project/RefinePilot

The diameter and low-pass filter above are illustrative Å values. Use specimen-appropriate values. Refinement executes mpirun -np 3 relion_refine_mpi with --auto_refine, --split_random_halves, --ctf, and a low-pass starting reference. Gold-standard splitting requires MPI; the plain sequential relion_refine executable cannot perform this split. Use odd ranks ≥3 (master plus balanced half-set workers), with a matching MPI installation. The CPU command is useful for a bounded pilot; choose a documented GPU/MPI launch for full data.

The runner keeps the command, native version and log in a new output directory, records an explicit random seed (default 1), surfaces runtime warnings, stops on process failure, and requires converged unfiltered half maps before reporting success. It does not automatically retry expensive jobs or silently discard failed-job artifacts. Keep _optimiser.star, model/sampling STAR files, and referenced particle paths for restart. Use the original job's optimiser rather than starting a new random split from a partially processed table.

Inspect independent half maps

Use the two independently refined unfiltered half maps, never two copies of the combined, sharpened map. Matching headers cannot establish statistical independence; the independent particle assignments and refinement history provide that evidence. Inspect directional anisotropy, preferred orientation and local resolution as well as a global FSC curve.

python scripts/spa_workflow.py fsc \
  project/RefinePilot/run_half1_class001_unfil.mrc \
  project/RefinePilot/run_half2_class001_unfil.mrc --output diagnostic-fsc.tsv

This checks map dimensions, finite values, pixel size, origin, axis order and duplicate maps, then writes an unmasked diagnostic FSC. The reported 0.143 crossing uses linear interpolation; null means no downward crossing was detected, not infinite resolution. Nyquist resolution is 2 × pixel size. This diagnostic is limited to even cubic maps ≤256³; use RELION's native relion_image_handler --fsc for larger maps. It does not substitute for mask-corrected FSC. The helper requires real-space maps with canonical axes, zero MRC start indices and orthogonal cell angles. Convert other grids explicitly with provenance; merely editing headers can misalign density. Matching headers and FSC cannot determine absolute handedness.

Postprocess with a soft mask

Construct the solvent mask from an appropriately low-pass-filtered density, with an expanded boundary and a smooth edge. Inspect all slices; a tight mask can inflate correlation. Avoid a mask derived from high-frequency noise shared between half maps.

python scripts/spa_workflow.py postprocess \
  --half1 project/RefinePilot/run_half1_class001_unfil.mrc \
  --half2 project/RefinePilot/run_half2_class001_unfil.mrc \
  --mask project/soft_mask.mrc --output project/PostProcessPilot

The helper checks a nonconstant mask in [0,1], soft-edge voxels and matching map grids, then runs relion_postprocess with explicit half maps, mask and pixel size. RELION performs its own mask/randomization correction and writes postprocess.star. The bounded command leaves the B-factor at zero (no automatic B-factor estimation); add automatic/manual sharpening only after choosing a defensible fit range and inspecting map quality. A valid range and some fractional mask voxels do not prove the mask is scientifically appropriate. Inspect the phase-randomized masked FSC near the reported resolution: residual correlation calls for a smoother/wider mask and another postprocessing run.

See references/runtime-and-validation.md for the tested native utilities and the distinction between pipeline execution and reconstruction validation.

Primary references

Files

ATTRIBUTION.mdAdded by AutoGineer904 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md7.9 KiB
references/acquisition-and-restarts.md6.0 KiB
references/runtime-and-validation.md6.9 KiB
scripts/spa_workflow.pyScript16.7 KiB

references/runtime-and-validation.md

Runtime and verification scope

Targeted build

The workflow targets RELION 5.0.1, source tag 5.0.1, commit d476e6f6a4f1f37627c06ace5227fc374c0c2b05 from the official repository. The latest official stable release was still 5.0.1 at the 2026-10-01 review. The Python helper was retested with Python 3.12, numpy 2.5.3, mrcfile 1.5.4 and starfile 0.5.13. NumPy 2.5.3 requires Python 3.12 or newer. These packages validate local formats; they do not install the C++ programs.

The previous native integration record used a CPU-only, GUI-disabled build on Apple Silicon: AppleClang, OpenMPI 5.0.11, FFTW, OpenMP, and CMake 3.26. The build disabled optional model-weight downloads; Blush, DynaMight, ModelAngelo and GPU paths were not installed or exercised. AppleClang required explicit OpenMP include/library flags for the installed libomp. Use the official installation instructions for the platform, and ensure the MPI runtime matches the binary's build. Those native integrations were not rerun during this review because the executables were absent from PATH. The current isolated suite runs the portable tests and skips three opt-in native cases.

The build targets are image_handler, postprocess, and refine_mpi; resulting executable names are relion_image_handler, relion_postprocess, and relion_refine_mpi. MPI remains a dependency of the RELION 5.0.1 source configuration even when acceleration and GUI support are disabled. Keep native build artifacts outside the skill directory. The current installation guide still requires CMake earlier than 3.27 for this tag; check this before building with a modern system CMake. FFTW is the default FFT library, with MKL as an alternative. CUDA, HIP/ROCm and SYCL builds require their corresponding supported toolchains; the native source build should not be confused with installing the Python validation dependencies.

Portable regression checks rerun in this review

Real STAR parsing, optics-group/CTF checks and opening tiny particle stacks.
Failure cases for undefined optics, invalid particle indices, duplicate references after path normalization, nonfinite metadata, reversed defocus signs, and invalid half-set assignments.
Zero-padded native image indices, project-relative stack lookup from a nested STAR location, read-only STAR handling, explicit metadata-only reporting, and float16 particle stacks.
Rejection of scalar STAR blocks, complex data, noncanonical stack/map axes, nonzero map starts, nonorthogonal map cells and mismatched origins; invalid low-pass/seed values fail before launch.
Diagnostic FSC on two independently generated noisy 32³ maps sharing a smooth signal: high low-frequency correlation and a noise floor at high frequencies.
Rejection of duplicated half maps, inconsistent sampling, and hard-edged masks.
Exact version-token gating and retention of previous output directories (mocked process checks).

Earlier native integration record (not rerun in this review)

The native relion_image_handler --i half1.mrc --fsc half2.mrc --angpix 1.5 utility on those maps, with its shell curve compared to the Python diagnostic.
Real relion_postprocess execution through the helper, using a smooth solvent mask, and a finite reported resolution in postprocess.star.
A tiny native MPI auto-refine run with 32 noisy 16×16 synthetic projections, verifying the executable launch, final half maps and preservation of both particle half sets. The rotationally symmetric toy signal is not a physical CTF simulation; native alignment warnings are expected and its nominal resolution is not meaningful.

These small synthetic maps establish executable/format/FSC behavior, not a validated biological reconstruction or mask-selection strategy. Full production-data refinement, external motion correction/CTF programs and GPU acceleration require verification on the actual installation and representative experimental data. Example particle diameters, resolutions and checkpoint names in the entry point are illustrative.

Reproduce native utility regression tests

In a repository checkout, use an isolated Python environment containing the three Python packages above and pytest. Set RELION_IMAGE_HANDLER_TEST_EXECUTABLE and RELION_POSTPROCESS_TEST_EXECUTABLE to the corresponding native binaries. Set RELION_REFINE_TEST_EXECUTABLE to relion_refine_mpi for the additional MPI smoke test with mpirun on PATH, then run python -m pytest tests/relion -q. The suite constructs the synthetic STAR/MRC data in a temporary folder. Without those variables, only the explicit native integration cases are skipped; local scientific validation and CLI tests run normally.

A native diagnostic command writes its FSC STAR table to standard output:

relion_image_handler --i half1.mrc --fsc half2.mrc --angpix 1.5 > unmasked-fsc.star

Use the actual image sampling. Compare the resulting curve with corrected FSC from postprocessing; they answer different questions. The Python diagnostic uses shell-rounded radii and conjugate weights for an rFFT. The native utility's Fourier-grid conventions can produce small shell-wise differences on tiny maps; the regression checks agreement within 0.06 rather than bitwise identity.

Source and interface audit, 2026-10-01

All native arguments emitted by the helper and the restart example were checked in tagged ml_optimiser.cpp, ml_optimiser_mpi.cpp, postprocessing.cpp and image_handler.cpp. --offset_range/--offset_step are pixels, while --particle_diameter and --ini_high are Å. --i2 explicitly selects the second postprocessing half map. --auto_bfac is opt-in; --adhoc_bfac defaults to zero and FSC weighting remains enabled. The native FSC output is a STAR table, while the helper's diagnostic is TSV. No HTTP endpoints are used by this workflow.

FileName::compose/decompose confirms zero-padded stack indices, and rwMRC.h writes canonical axes, zero start indices and 90-degree cells. The helper intentionally rejects other map grids rather than guessing how to reinterpret them. Reading loops with starfile.read(..., always_dict=True) and reading MRC data/headers with mrcfile.mmap were cross-checked against the starfile API and mrcfile guide, then exercised on local synthetic files. Native source review validates option names and defaults, not the result of a new reconstruction. Scheduler, GUI, Schemes, GPU/model workflows, CTFFIND integration and biological map/model validation remain outside the executed portable test scope.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

The author says: Python 3.12+ with numpy, mrcfile and starfile for bundled validation; RELION 5.0.1 CPU/MPI executables for refinement and postprocessing. Native workflows require MPI, OpenMP and an FFT library (FFTW or MKL). GPU builds require their supported accelerator stack. Network is needed for installation only.

Security

What our scanner noticed· Low risk

Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

K-Dense Inc.

Publisher

K-Dense (Community)

Source

K-Dense-AI/scientific-agent-skills · skills/relion · commit a25cf9e

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE.md)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by K-Dense Inc. or K-Dense.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download relion.zip