Skip to main content
skill CX Codex

relion — Claude Code skill: cryo-EM refinement in RELION

Validates STAR files, runs gold-standard particle refinement, and postprocesses independent half maps in RELION 5.0.1. Built for single-particle cryo-EM projects.

MIT 463 installs ★ 58,036 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add K-Dense-AI/scientific-agent-skills --skill relion -a claude-code
Open on GitHub

What relion does

The skill handles three stages: validates particle STAR files for correct optics groups, stack indices and CTF parameters (validate-star), launches auto-refinement with gold-standard splitting via relion_refine_mpi (refine), and computes masked FSC between independent half maps (postprocess). Under the hood: Python scripts with numpy, mrcfile and starfile plus native RELION binaries. The refine command requires MPI with odd ranks ≥3 because only relion_refine_mpi can split particles into independent halves; without MPI, gold-standard refinement is impossible.

Refinement starts from CTF-annotated extracted particles and an initial 3D reference. Motion correction, picking, 2D classification and tomography workflows belong elsewhere. Particle coordinates in STAR use one-based indexing ([email protected]), paths resolve from the RELION project root, and _rlnOriginXAngst / _rlnOriginYAngst store shifts in ångströms. Validation opens stacks and checks box sizes, duplicates, finite CTF values; --metadata-only skips reading MRC files when stacks are unavailable.

The postprocess command verifies the mask lies in [0,1], has a smooth edge and matches half-map grids, then calls relion_postprocess with explicit B-factor zero (no automatic estimation). The helper fsc command computes an unmasked diagnostic curve for cubic maps ≤256³; larger maps need native relion_image_handler --fsc.

What it helps with

  • validate particle STAR files for correct optics groups and stack indices
  • run gold-standard auto-refinement with MPI and initial low-pass filtering
  • compute FSC between independent half maps and apply soft-mask postprocessing
  • preserve commands, logs and random seeds for reproducible refinement

Example prompts for the agent

  • Validate the STAR file project/particles.star from directory project
  • Run refinement with initial reference initial.mrc, diameter 180 Å, symmetry C1 and low-pass 40 Å, using 3 MPI ranks and 2 threads
  • Compute FSC between run_half1_class001_unfil.mrc and run_half2_class001_unfil.mrc and save to diagnostic-fsc.tsv

How to install relion

1Skills CLI (Vercel)

npx skills add K-Dense-AI/scientific-agent-skills --skill relion -a claude-code

2Manually: put the files in place

~/.claude/skills/relion/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/relion/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about relion

How to install relion in Claude Code?

Run npx skills add K-Dense-AI/scientific-agent-skills --skill relion -a claude-code, then open ~/.claude/skills/relion/SKILL.md.

What does relion do?

The skill validates particle STAR files, runs gold-standard refinement in RELION via relion_refine_mpi with independent halves, and postprocesses half maps with a mask. Designed for single-particle cryo-EM projects starting from extracted particles.

Why does relion need MPI?

The refine command uses relion_refine_mpi for gold-standard splitting: only the MPI version can divide particles into independent halves and refine them in parallel. The skill requires odd ranks ≥3 (one master plus balanced workers for two half sets).

Source text

SKILL.md · MIT
---
name: relion
description: 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.
license: MIT
compatibility: 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.
metadata:
  version: "1.1"
  skill-author: K-Dense Inc.
  upstream-version: "5.0.1"
  last-reviewed: "2026-10-01"
---

# 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](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:

```bash
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.

```bash
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.

```bash
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.

```bash
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](references/runtime-and-validation.md) for the tested
native utilities and the distinction between pipeline execution and reconstruction validation.

## Primary references

- [RELION 5.0 installation](https://relion.readthedocs.io/en/release-5.0/Installation.html).
- [STAR and map conventions](https://relion.readthedocs.io/en/release-5.0/Reference/Conventions.html).
- [Single-particle tutorial](https://relion.readthedocs.io/en/release-5.0/SPA_tutorial/index.html).
- [Gold-standard refinement](https://relion.readthedocs.io/en/release-5.0/SPA_tutorial/Refine3D.html).
- [Mask creation and postprocessing](https://relion.readthedocs.io/en/release-5.0/SPA_tutorial/Mask.html).

© K-Dense-AI · MIT · K-Dense-AI/scientific-agent-skills

Similar skills

All skills for Science and research →

From the same set176

The whole set →
mageck mageck counts FASTQ reads and guide matrices, validates libraries, runs replicate QC, and ranks genes with FDR for pooled CRISPR screens. CX Codex +1 465installs qiime2-amplicon qiime2-amplicon — a skill that turns paired-end 16S reads into QIIME 2 ASV tables and taxonomy, preserving the full transformation record. Validates manifests, primer orientation, read overlap, and classifier compatibility before execution. CX Codex +1 465installs cellprofiler Runs CellProfiler to count nuclei and measure fluorescence in 2D microscopy images. Use it for repeatable analysis of grayscale TIFF fields. CX Codex +1 464installs pycalphad pycalphad computes thermodynamic CALPHAD phase equilibria and compositions from TDB files. Useful for alloy phase fraction modeling across temperature ranges. CX Codex +1 463installs nwb-conversion nwb-conversion transforms two-photon microscopy frames and behavioral position data into Neurodata Without Borders format with clock alignment verification and schema validation. Requires Python 3.12 and pinned scientific libraries. CX Codex +1 462installs marine-carbonate-chemistry marine-carbonate-chemistry turns two measured carbonate parameters into a speciation table: pH, pCO2, aragonite and calcite saturation, with the assumptions written down. CX Codex +1 ★ 58,036repo stars 13c-metabolic-flux 13c-metabolic-flux estimates intracellular metabolic fluxes from steady-state carbon-13 tracing data using mfapy and SciPy. CX Codex +1 ★ 58,036repo stars fictiv This skill runs Fictiv workflows in a browser, from CAD upload and manufacturing setup to quotes, checkout, and order tracking. CX Codex +1 ★ 58,036repo stars

Project sponsors

Companies that keep this analytics open