Acquisition Formats

Add a tilt series from a stack file and its acquisition metadata.

Parameters:

• root (CopickRoot) –

  The copick project.

• run_name (str) –

  The run.

• ts_type (str) –

  Type of the tilt series (e.g. raw).

• path (PathLike) –

  The stack (MRC .mrc/.st/.mrcs/.ali, TIFF, or Zarr).

• file_type (Optional[str], default: None ) –

  Format of the stack (mrc, tiff, zarr). Default: from the extension.

• pixel_size (Optional[float], default: None ) –

  Pixel size in Angstrom. Default: from the stack's header or the mdoc.

• angles (Optional[PathLike], default: None ) –

  Tilt-angle file in stack order (.rawtlt, .tlt, AreTomo3 _TLT.txt).

• angles_format (Optional[str], default: None ) –

  Its format. Default: from its name.

• mdoc (Union[PathLike, str, None], default: 'auto' ) –

  SerialEM mdoc; "auto" uses one next to the stack, None none.

• ctf (Optional[PathLike], default: None ) –

  CTF fits (AreTomo3 _CTF.txt, CTFFIND4, Warp XML, RELION tomograms.star).

• ctf_format (Optional[str], default: None ) –

  Their format. Default: from the file name.

• dose_per_tilt (Optional[float], default: None ) –

  Dose of every image in e/Ų, overriding the files.

• voltage (Optional[float], default: None ) –

  Acceleration voltage in kV.

• spherical_aberration (Optional[float], default: None ) –

  Spherical aberration in mm.

• amplitude_contrast (Optional[float], default: None ) –

  Amplitude contrast.

• tilt_axis_angle (Optional[float], default: None ) –

  Tilt-axis angle in degrees, overriding the mdoc.

• handedness (Optional[str], default: None ) –

  right_handed or left_handed, if known.

• section_map (str, default: 'auto' ) –

  How the mdoc's and CTF file's rows map to sections (see copick.util.acquisition_formats).

• angle_tolerance (float, default: DEFAULT_ANGLE_TOLERANCE ) –

  Largest difference in degrees between a row's angle and its section's nominal angle.

• sort_by_angle (bool, default: False ) –

  Store the sections in ascending nominal tilt angle.

• is_aligned (bool, default: False ) –

  Whether the images are already aligned.

• levels (int, default: TILT_SERIES_LEVELS ) –

  Number of pyramid levels.

• chunks (Tuple[int, int, int], default: TILT_SERIES_CHUNKS ) –

  Chunk shape.

• dtype (Optional[str], default: 'float32' ) –

  Data type of the stored images (None: that of the stack).

• create (bool, default: True ) –

  Create the run if it does not exist.

• overwrite (bool, default: False ) –

  Replace the images of an existing tilt series.

Returns:

• CopickTiltSeries ( CopickTiltSeries ) –

  The tilt series.

Add an alignment of a tilt series from a tool's files.

Parameters:

• root (CopickRoot) –

  The copick project.

• run_name (str) –

  The run.

• path (PathLike) –

  The alignment: AreTomo3 .aln, Warp tilt-series XML, RELION tomograms.star or IMOD basename.

• fmt (str) –

  aretomo3, warp, relion or imod.

• ts_type (str) –

  The tilt series it aligns.

• name (Optional[str], default: None ) –

  Name of the alignment. Default: the format.

• tomo_name (Optional[str], default: None ) –

  The tomogram of a RELION file listing several. Default: the run name, if the file lists several.

• native_pixel_size (Optional[float], default: None ) –

  Pixel size of the stack the tool aligned, if not that of the tilt series.

• volume_size (Optional[Sequence[int]], default: None ) –

  Size (x, y, z) of the tool's reconstruction in pixels, overriding the files.

• thickness (Optional[int], default: None ) –

  Thickness of the tool's reconstruction in pixels, overriding the files.

• reference_tomogram (Optional[str], default: None ) –

  URI (tomo_type@voxel_size) of the tomogram the tool reconstructed with this alignment; it becomes the reference volume and is linked.

• link_tomograms (Sequence[str], default: () ) –

  URIs of further tomograms reconstructed with this alignment.

• preferred (bool, default: False ) –

  Prefer this alignment over the tilt series' others.

• ctf (Optional[PathLike], default: None ) –

  CTF fits to store on the tilt series (AreTomo3 _CTF.txt, ...).

• ctf_format (Optional[str], default: None ) –

  Their format. Default: from the file name.

• tlt (Optional[PathLike], default: None ) –

  AreTomo3 _TLT.txt whose acquisition order and dose to store on the tilt series.

• update_tilt_series (bool, default: True ) –

  Whether ctf and tlt are stored on the tilt series.

• section_map (str, default: 'auto' ) –

  How the tool's rows map to sections.

• angle_tolerance (float, default: DEFAULT_ANGLE_TOLERANCE ) –

  Largest difference in degrees between a row's angle and its section's nominal angle.

• assume_frame (Optional[str], default: None ) –

  Centre convention (half or floor) of an IMOD alignment of odd-sized images.

• rigid_only (bool, default: False ) –

  Import the rigid part of a local AreTomo3 alignment.

• allow_varying_grids (bool, default: False ) –

  Drop the spatially varying deformation of a Warp alignment.

• overwrite (bool, default: False ) –

  Replace an existing alignment of this name (its tomogram links are kept).

Returns:

• CopickAlignment ( CopickAlignment ) –

  The alignment.

Set the CTF fits of a tilt series from a file.

Raises:

• PermissionError –

  If the tilt series is read-only (changing static metadata is not supported yet).

Export a tilt series as a stack, with its tilt angles and CTF fits.

Parameters:

• tilt_series (CopickTiltSeries) –

  The tilt series.

• output_dir (PathLike) –

  Directory to write to.

• output_format (str, default: 'mrc' ) –

  mrc, tiff or zarr.

• level (int, default: 0 ) –

  Pyramid level of the stack (mrc, tiff).

• angles (Optional[str], default: 'rawtlt' ) –

  Angle file to write: rawtlt, tlt, aretomo3-tlt or None.

• ctf_format (Optional[str], default: None ) –

  CTF file to write: aretomo3, ctffind4 or None.

• basename (Optional[str], default: None ) –

  Base name of the files. Default: the run name.

Returns:

• List[Path] –

  The written paths.

Export an alignment in a tool's format.

Parameters:

• alignment (CopickAlignment) –

  The alignment.

• output_dir (PathLike) –

  Directory to write to.

• output_format (str) –

  aretomo3 (.aln + _TLT.txt), warp (tilt-series XML), relion, imod (.xf, .tlt, .xtilt, tilt.com, newst.com in <output_dir>/<basename>/) or cdp (CryoET Data Portal alignment JSON).

• reference_tomogram (Optional[CopickTomogram], default: None ) –

  Tomogram the tool should reconstruct; default: the alignment's reference volume.

• include_ctf (bool, default: False ) –

  Also write the CTF fits (AreTomo3 _CTF.txt, Warp grids, RELION columns).

• drop_x_tilt (bool, default: False ) –

  Drop the tilt about x, which AreTomo3 cannot represent.

• hand (float, default: -1.0 ) –

  RELION rlnTomoHand.

• relion_tomo_name (Optional[str], default: None ) –

  RELION rlnTomoName. Default: the run name.

• assume_frame (Optional[str], default: None ) –

  Centre convention for IMOD with odd sizes.

• basename (Optional[str], default: None ) –

  Base name of the files. Default: the run name.

• amplitude_contrast (Optional[float], default: None ) –

  RELION amplitude contrast if the tilt series has none (default 0.07).

Returns:

• Union[List[Path], Any] –

  The written paths, or for relion the RelionAlignment to write (see write_relion_alignments).

Export the alignments a URI selects, from all or some runs.

RELION alignments are written to one tomograms.star in output_dir, each run's under its own name.

Parameters:

• root (CopickRoot) –

  The copick project.

• alignment_uri (str) –

  Alignments to export (e.g. aretomo3 or *@raw?default=true).

• output_dir (PathLike) –

  Directory to write to.

• output_format (str) –

  aretomo3, warp, relion, imod or cdp.

• run_names (Optional[Sequence[str]], default: None ) –

  Runs to export. Default: all.

• reference_tomogram (Optional[str], default: None ) –

  URI of each run's tomogram the tool should reconstruct.

• **kwargs –

  Passed to export_alignment.

Returns:

• List[Path] –

  The written paths.

Export the CTF fits of a tilt series as an AreTomo3 _CTF.txt or a CTFFIND4 file.

Write RELION alignments of several tomograms as one tomograms.star and tilt_series/<name>.star each.

Open a stack of tilt images for reading.

MRC files (.mrc, .st, .mrcs, .ali) are memory-mapped, so sections are read as they are used. TIFF files are read whole. A Zarr store is read at its first OME-Zarr level, or as a plain array.

Yields:

• Stack ( Stack ) –

  The images (section, y, x) and the header pixel size in Angstrom (None if unknown).

Read a tilt-angle file: IMOD .rawtlt/.tlt or AreTomo3 _TLT.txt (with acquisition order and dose).

Read a SerialEM tilt-series mdoc.

Parameters:

• path (str) –

  The mdoc.

• dose_per_tilt (Optional[float], default: None ) –

  Dose of every image in e/Ų, overriding the file's.

Returns:

• AcquisitionTable ( AcquisitionTable ) –

  One row per [ZValue] section, keyed by ZValue.

Read per-image CTF fits.

Parameters:

• path (str) –

  The file: an AreTomo3 _CTF.txt, a CTFFIND4 output .txt, a Warp tilt-series XML or a RELION tomograms.star.

• fmt (str) –

  aretomo3, ctffind4, warp or relion.

• pixel_size (Optional[float], default: None ) –

  Pixel size of a Warp tilt series, if its XML does not record one.

• tomo_name (Optional[str], default: None ) –

  The tomogram of a RELION file listing several.

Returns:

• CtfTable ( CtfTable ) –

  The fits in canonical form (u >= v in Angstrom, angle in [0, 180) degrees, phase in degrees).

Read an alignment in a tool's format.

Parameters:

• path (str) –

  The .aln (AreTomo3), tilt-series XML (Warp), tomograms.star (RELION) or basename / .xf (IMOD, with .tlt, optional .xtilt and tilt.com next to it).

• fmt (str) –

  aretomo3, warp, relion or imod.

• pixel_size (Optional[float], default: None ) –

  Pixel size of the stack the tool aligned, if not that of the tilt series (Warp: overrides its XML).

• tomo_name (Optional[str], default: None ) –

  The tomogram of a RELION file listing several.

• image_size (Optional[Tuple[int, int]], default: None ) –

  Image size (width, height), needed for RELION files with projection matrices.

• rigid_only (bool, default: False ) –

  Keep the rigid part of a local (patch) AreTomo3 alignment.

• allow_varying_grids (bool, default: False ) –

  Drop the spatially varying deformation of a Warp alignment.

Raises:

• ValueError –

  If the alignment is local and its loss is not allowed, or the files are inconsistent.

The tilt-series section of each row of a file.

Parameters:

• n_sections (int) –

  Number of sections of the tilt series.

• angles (Optional[Sequence[float]]) –

  Tilt angle of each row, if the file has them; rows without are taken to be in ascending angle.

• mode (str) –

  index, sorted or angle (see the module documentation).

• nominal (Optional[Sequence[Optional[float]]], default: None ) –

  Nominal tilt angle of each section, if known.

• tolerance (float, default: DEFAULT_ANGLE_TOLERANCE ) –

  Largest difference in degrees between a row's angle and the nominal tilt angle of its section.

• keys (Optional[Sequence[int]], default: None ) –

  Section each row names (index mode).

• what (str, default: 'rows' ) –

  Name of the rows in messages.

• refined (bool, default: False ) –

  Whether the rows' angles may be refined; a mismatch is then only reported.

• n_rows (Optional[int], default: None ) –

  Number of rows, for files with neither angles nor keys.

Returns:

• List[int] –

  The section of each row.

Raises:

• ValueError –

  If the rows cannot be mapped, or the mapping contradicts the nominal tilt angles.

Map an alignment to the sections of a tilt series and convert it to copick's CETS frame.

Parameters:

• native (NativeAlignment) –

  The alignment.

• metadata (CopickTiltSeriesMetadata) –

  Metadata of the tilt series.

• reference (CopickReferenceVolume) –

  Its reference volume (see native_reference).

• section_map (str, default: 'auto' ) –

  How the tool's rows map to sections (see the module documentation).

• tolerance (float, default: DEFAULT_ANGLE_TOLERANCE ) –

  Largest difference in degrees between a row's angle and the nominal angle of its section.

• assume_frame (Optional[CenterKind], default: None ) –

  Centre convention of an IMOD alignment of odd-sized images or volumes.

• n_sections (Optional[int], default: None ) –

  Number of sections of the tilt series (default: that of the metadata).

Convert a copick alignment to a tool's frame and row order.

Parameters:

• file (CopickAlignmentFile) –

  The alignment.

• metadata (CopickTiltSeriesMetadata) –

  Metadata of its tilt series.

• source_format (str) –

  The tool: ARETOMO3, WARP, RELION, IMOD or PORTAL.

• n_sections (int) –

  Number of sections of the tilt series.

• reference (Optional[CopickReferenceVolume], default: None ) –

  The volume the tool should reconstruct (default: the alignment's reference volume).

• reference_offset (Optional[Sequence[float]], default: None ) –

  Offset of reference from the alignment's reference volume (see rebase_sections).

• sort_by_angle (bool, default: True ) –

  Order the rows by ascending nominal tilt angle (else by section).

• drop_x_tilt (bool, default: False ) –

  Set the tilt about x to zero, for tools that cannot represent it.

• assume_frame (Optional[CenterKind], default: None ) –

  Centre convention for IMOD with odd sizes.

Raises:

• ValueError –

  If the alignment has no reference volume or its tilt series no images.

The sections of an alignment with another reference volume.

Positions p of the new reference relate to those of the old one as p_old = p + o, so the shifts become t + (R @ o)[:2]. Without reference_offset, the two volumes share their centre in the alignment's native convention, as copick assumes for tomograms reconstructed with an alignment (see CopickAlignment.project).

Parameters:

• file (CopickAlignmentFile) –

  The alignment.

• reference (CopickReferenceVolume) –

  The new reference volume.

• reference_offset (Optional[Sequence[float]], default: None ) –

  o in Angstrom, from the new reference's CETS centre to the old one's.