Skip to content

copick export picks

core

Export picks to external formats (EM, STAR, Dynamo, CSV).

Usage

copick export picks [OPTIONS]

Description

Selects picks with the --picks-uri filter (e.g. ribosome:user1/* or *:*/*) and writes them as TOM toolbox EM motivelists, RELION STAR files, Dynamo tables, or copick CSV. The EM, STAR, and Dynamo formats require --voxel-size (in Angstrom) to convert coordinates.

Two output modes are mutually exclusive: per-run mode (--output-dir) writes one file per run, while combined mode (--output-file) writes all runs to a single file. Combined EM/Dynamo export requires --index-map to assign a tomogram index to each run; per-run EM/Dynamo default to index 1 unless an index map is supplied, and STAR/CSV reference runs by name. For coordinate and Euler-angle conventions, see the docstrings in copick.util.formats.

STAR files carry rlnTomoName and coordinates centred on each tomogram (from --tomograms-star, or the copick tomogram at --voxel-size, of type --tomo-type if given). With --tilt-series-pixel-size (or a tomograms.star) they also carry rlnCoordinateX/Y/Z in tilt-series pixels and the optics table RELION requires; --coordinates centered writes the centered coordinates only. With --star-layout import, --output-file is the index that RELION's tomography Import Coordinates job reads (data_coordinate_files: rlnTomoName, rlnTomoImportParticleFile), naming one coordinate file per run in coordinates/ beside it.

Picks of objects declared a filament get RELION's filament columns (--filament-columns): the frame in rlnTomoSubtomogram*, rlnAngleTilt and its prior at 90, rlnHelicalTubeID from the instance ID, and rlnHelicalTrackLengthAngst. Their rlnAnglePsiFlipRatio is 0 for picks of filaments whose polarity is known and 0.5 for the rest; the polarity comes from the Filaments under the picks' own URI, or from those named by --filaments-uri (e.g. when the picks were sampled from Filaments into another session). With --filament-angles pose, the picks' own rotations go into rlnAngleRot/Tilt/Psi instead, with no subtomogram angles and no priors, for poses already registered (e.g. to a lattice). --half-sets filament assigns rlnRandomSubset by whole filament, so that neighboring particles of one filament never land in both half sets.

Options

Option Type Default Description
-c, --config path — Path to the configuration file.
--run-names, -r text · multiple — Specific run names to process (default: all runs). Repeatable; pass -r once per run.
--picks-uri text required URI to filter picks for export (e.g., 'ribosome:user1/' or ':/').
--output-dir directory — Output directory for per-run export (one file per run). Mutually exclusive with --output-file.
--output-file file — Output file for combined export (all runs in one file). Mutually exclusive with --output-dir.
--output-format choice (em | star | dynamo | csv) required Output format for picks.
--voxel-size float — Voxel size in Angstrom (required for EM, STAR, and Dynamo formats).
--index-map path — CSV/TSV file mapping tomogram index to run name. Required for combined EM/Dynamo export, optional for per-run.
--include-optics / --no-include-optics boolean flag True Include optics group in STAR file output.
--tilt-series-pixel-size float — STAR only: tilt-series pixel size in Angstrom. Adds rlnCoordinateX/Y/Z in tilt-series pixels and an optics table with rlnTomoTiltSeriesPixelSize, which RELION requires.
--tomograms-star file — STAR only: RELION tomograms.star giving each tomogram's centre, tilt-series pixel size and CTF parameters (takes precedence over the copick tomograms).
--star-layout choice (particles | import) particles STAR only, with --output-file: 'particles' writes one particle file; 'import' makes --output-file the index RELION's tomography Import Coordinates job reads, naming one coordinate file per run in 'coordinates/' beside it.
--tomo-type text — STAR only: type of the copick tomogram (at --voxel-size) whose shape defines each run's center. Default: the first tomogram at that voxel size.
--coordinates choice (auto | centered) auto STAR only: 'auto' writes centered coordinates and/or rlnCoordinateX/Y/Z in tilt-series pixels, whatever is known; 'centered' writes centered coordinates only and fails for a run without a tomogram center.
--filament-columns choice (auto | on | off) auto STAR only: RELION's filament columns (rlnHelicalTubeID, track length, subtomogram frame, priors) for objects declared a filament ('auto'), always ('on'), or never ('off').
--polarity-from-filaments / --no-polarity-from-filaments boolean flag True STAR only, with filament columns: set rlnAnglePsiFlipRatio from each filament's polarity_known in a Filaments source (0 where the polarity is known, 0.5 elsewhere). Off: 0.5 for every pick.
--filaments-uri text — STAR only: the Filaments (e.g. 'microtubule:tracer/1') that state the polarity, matched to the picks by instance ID in each run; every pick's filament must be in them. Default: the Filaments under the picks' own URI, when they exist.
--filament-angles choice (frame | pose) frame STAR only, with filament columns: 'frame' writes RELION's filament convention (the frame in rlnTomoSubtomogramRot/Tilt/Psi, rlnAngleRot/Tilt/Psi = (0, 90, 0), tilt and psi priors); 'pose' writes each pick's own rotation in rlnAngleRot/Tilt/Psi, with no subtomogram angles and no priors, for registered poses. Without filament columns the angles are always the picks' rotations.
--half-sets choice (none | filament) none STAR only: 'filament' adds rlnRandomSubset (1/2) by whole filament (rlnTomoName, rlnHelicalTubeID), greedily balanced by particle count, so that no filament is in both halves of a refinement; needs filament columns. Per-run export balances each file on its own.
--max-workers integer 4 Maximum number of worker threads.
--debug / --no-debug boolean flag False Enable debug logging.

Examples

# Per-run export: one EM file per run
copick export picks -c config.json --picks-uri "ribosome:user1/*" \
    --output-dir ./output --output-format em --voxel-size 10.0

# Combined export: all runs to a single STAR file
copick export picks -c config.json --picks-uri "*:*/*" \
    --output-file ./particles.star --output-format star --voxel-size 10.0

# Input for RELION's tomography Import Coordinates job
copick export picks -c config.json --picks-uri "ribosome:user1/1" \
    --output-file ./import/particles.star --output-format star \
    --voxel-size 10.0 --star-layout import --coordinates centered

# Filament picks sampled from traced Filaments in another session:
# their polarity comes from those Filaments
copick export picks -c config.json --picks-uri "microtubule:sampler/1" \
    --filaments-uri "microtubule:tracer/1" \
    --output-file ./filaments.star --output-format star --voxel-size 10.0

# Lattice-registered filament subunits: their poses as particle angles,
# and half sets by whole filament
copick export picks -c config.json --picks-uri "microtubule:helix/1" \
    --filament-columns on --filament-angles pose --half-sets filament \
    --output-file ./registered.star --output-format star --voxel-size 10.0

# Combined export to a Dynamo table using an index map
copick export picks -c config.json --picks-uri "ribosome:*/*" \
    --output-file ./particles.tbl --output-format dynamo \
    --voxel-size 10.0 --index-map ./index_map.csv

See also