copick add picks

core

Add picks from external formats (EM, STAR, Dynamo, CSV).

Usage

copick add picks [OPTIONS] PATH

Description

Imports particle picks from a single file, or many at once via a glob pattern, into one or more runs. The format is inferred from the extension unless --file-type is given. Supported formats are TOM toolbox EM motivelists (.em), RELION particle STAR files (.star), Dynamo tables (.tbl), and copick CSV files (.csv). A voxel size is required for the EM, STAR, and Dynamo formats so coordinates can be converted; CSV files carry a run_name column and are grouped automatically.

STAR files are read as RELION does: centred coordinates (rlnCenteredCoordinate*Angst) relative to the tomogram centre when it is known (from --tomograms-star or the run's copick tomogram), otherwise rlnCoordinateX/Y/Z in tilt-series pixels (--tilt-series-pixel-size, or the file's optics table), otherwise in pixels of --voxel-size. Subtomogram orientations (rlnTomoSubtomogram*) and shifts (rlnOrigin*Angst) are applied.

For batch imports from a single file that spans many tomograms, use the dedicated commands copick add picks-em, copick add picks-dynamo, or copick add picks-relion instead. For format-specific conventions (coordinate systems, Euler angle conventions), see the docstrings in copick.util.formats.

Arguments

Argument	Description
`PATH`	Path to the picks file (EM, STAR, Dynamo .tbl, or CSV) or a glob pattern.

Options

Option	Type	Default	Description
`-c, --config`	path	—	Path to the configuration file.
`--run-name-prefix`	text	`""`	Prefix to prepend to run names after regex extraction.
`--run-regex`	text	`(.*)`	Regular expression to extract the run name from the filename. If not provided, will use the file name without extension. The regex should capture the run name in the first group.
`--run`	text	`""`	The name of the run. If not specified, will use the name of the file (stripping extension), ignored if PATH is glob pattern.
`--object-name`	text	required	Name of the pickable object (must exist in config).
`--session-id`	text	`1`	Session ID for the annotation.
`--user-id`	text	`copick`	User ID for the annotation.
`--voxel-size`	float	—	Voxel size in Angstrom (required for EM and Dynamo formats for coordinate conversion; for STAR, required only when the file's coordinates are tomogram pixels, i.e. no tilt-series pixel size is known).
`--tilt-series-pixel-size`	float	—	STAR only: tilt-series pixel size in Angstrom, the unit RELION 4/5 use for rlnCoordinateX/Y/Z. Read from the file's optics table (rlnTomoTiltSeriesPixelSize) when omitted.
`--tomograms-star`	file	—	STAR only: RELION tomograms.star giving each tomogram's centre (for rlnCenteredCoordinate*Angst) and tilt-series pixel size.
`--file-type`	choice (em \| star \| dynamo \| csv)	—	File type ('em', 'star', 'dynamo', 'csv'). Will guess type based on extension if omitted.
`--max-workers`	integer	`4`	Maximum number of worker threads.
`--overwrite / --no-overwrite`	boolean flag	`False`	Overwrite the object if it exists.
`--create / --no-create`	boolean flag	`True`	Create the object if it does not exist.
`--debug / --no-debug`	boolean flag	`False`	Enable debug logging.

Examples

# Import picks from a TOM toolbox EM motivelist
copick add picks particles.em -c config.json --object-name ribosome \
    --voxel-size 10.0 --run TS_001

# Import picks from a RELION STAR file
copick add picks particles.star -c config.json --object-name ribosome \
    --voxel-size 10.0 --run TS_001

# Import picks from a CSV (run names come from the file)
copick add picks particles.csv -c config.json --object-name ribosome

# Import from multiple files via a glob (run names from filenames)
copick add picks "*.star" -c config.json --object-name ribosome \
    --voxel-size 10.0