Skip to content

export

export converts a file to an open format. To write one embedded attachment as it is stored, see extract. Pictures are saved by plot and preview with -o; over MCP, openreadout_export saves them too (saving figures).

openreadout export [OPTIONS] <FILE>...

Each export is written under a temporary name, read back and compared with the source, then given its final name. The source file is not modified.

Flags

Target and output

  • --format FORMAT: target format: ome-tiff, ome-zarr, nifti, mzml, csv, asm, parquet, arrow, nwb, jcamp, rdml, fastq or mrc. Without it, the extension of -o sets the format, or the file’s kind when there is no -o; see Export formats.
  • -o, --output PATH: output path. Default: the input name with the target’s extension. With several inputs, or with --per-image, a directory.
  • --overwrite: replace an existing output file or OME-Zarr store.
  • --group-frames N: MRC only: sum every N time points into one section (the dose fractions of an electron-event movie).
  • --compression MODE: images none, deflate (default) or lzw; Parquet none, snappy (default) or lz4; Arrow none (default) or lz4.
  • --json: print the export report as JSON.

What to export

  • --image N: only this image. Default: all images.
  • --select SEL: plane selection such as c=0, z=2-5, t=0,3. Repeatable. Axes not mentioned are exported in full.
  • --table N: CSV, Parquet, Arrow: this table. Default 0.
  • --trace N: trace exports: this trace. Default 0 (NWB: every trace).
  • --sweep N: trace exports: this sweep. CSV default 0; Parquet, Arrow, NWB and JCAMP-DX default every sweep.
  • --rows A-B: zero-based inclusive row range (A-B, A- or A). For traces, samples of each sweep.
  • --spectra: Parquet and Arrow: export the mass spectra of --run (one row per point, plus a per-scan summary file).
  • --run N: mzML, Parquet, Arrow: run index. Default 0.
  • --labels: CSV: add a second header line with column labels (FCS $PnS).

Images: pyramids, levels and regions

  • --pyramid auto|source|mean|none: lower resolutions to write. auto copies the source’s own pyramid when it has one and the whole image is exported from level 0; otherwise it writes 2×2 mean levels for OME-Zarr and none for OME-TIFF.
  • --levels N: resolution levels including full resolution. Exact for mean pyramids, a maximum for the source’s own.
  • --level N: export this source pyramid level as the full resolution. Default 0.
  • --region X,Y,W,H: export only this rectangle of every plane, in the pixels of --level, read tile by tile.
  • --chunk-size N: OME-Zarr chunk edge, or OME-TIFF tile edge (a multiple of 16). Default 512.
  • --embed-vendor: embed the vendor metadata tree as an OME StructuredAnnotation.

Plates

  • --well WELL: export only the fields of this well (C05). Repeatable. OME-Zarr and --per-image OME-TIFF.
  • --skip-incomplete: leave out fields whose plane files are missing instead of failing.
  • --no-plate: OME-Zarr: write a bioformats2raw.layout collection instead of an OME-NGFF HCS plate.
  • --per-image: OME-TIFF: one file per field of view, into the directory given by -o.

Mass spectrometry and NMR

  • --centroid: mzML: write the instrument’s centroid lists instead of profiles where a scan has both.
  • --process: NMR: export FIDs as spectra processed by OpenReadout. Stored spectra are unchanged.
  • --process-phase MODE, --process-lb HZ, --process-size N, --process-baseline MODE: processing settings. See analyze nmr-peaks.

export takes the flags in Several inputs.

Examples

Terminal window
$ openreadout export doctor.tif -o doctor.ome.tiff
wrote doctor.ome.tiff (1 images, 2 planes, 2207 bytes, verified=true)
Terminal window
openreadout export slide.czi --format ome-zarr # pyramid kept
openreadout export slide.svs --region 20000,15000,4096,4096 -o roi.ome.tiff
openreadout export sample.fcs --format parquet
openreadout export run.raw --format mzml --centroid
openreadout export -r --skip-unknown raw/ -o ome/ # keeps the folder layout

Export formats

--format for default output
ome-tiff images (default) <stem>.ome.tiff
ome-zarr images, plates <stem>.ome.zarr
nifti volumes (medical images first) <stem>.nii.gz
csv tables, traces, NMR and 1-D spectra (default) <stem>.csv
parquet, arrow tables, traces, mass spectra <stem>.parquet, <stem>.arrow
mzml mass spectrometry (default) <stem>.mzML
nwb electrophysiology traces <stem>.nwb
jcamp NMR, 1-D spectra, chromatograms <stem>.jdx
asm plate-reader exports <stem>.asm.json
rdml qPCR (RDML, .eds, .rex) <stem>.rdml (<stem>.export.rdml for an RDML input)
fastq base calls: a Sanger read (default for .ab1), an Illumina run folder <stem>.fastq; <run folder>_fastq/ for a run
mrc one channel of an image: movies, stacks, diffraction sweeps <stem>.mrcs for frames, <stem>.mrc otherwise
  • OME-TIFF is one BigTIFF file with OME-XML in the first IFD. Pyramids go in SubIFDs. With a pyramid, a level, a region, or a plane above 4 GiB, the file is tiled and written block by block, so a whole-slide image exports in bounded memory.
  • OME-Zarr is an OME-NGFF 0.5 (Zarr v3) store with 5-D t, c, z, y, x arrays. Several images become a bioformats2raw.layout collection; a screening plate becomes an HCS plate. Except for plates, OME/METADATA.ome.xml keeps what OME-NGFF has no place for: objective, instrument, acquisition mode, exposures. With a pyramid copied from the source, a level, a region, or a plane above 256 MiB, the store is written block by block.
  • What differs from the source. OME-NGFF has no samples axis, so the red, green and blue samples of an RGB image become three OME-Zarr channels, named <channel> (R), (G) and (B). OME-Zarr channels whose source records no colour get a display colour. OME-TIFF takes 1-sample int8 to int32, uint8 to uint32, float and double images and 3-sample uint8, uint16 and float images, and leaves out the label images of an OME-Zarr source. Other sample counts go to OME-Zarr. Neither format is written for 64-bit integer or complex images (exit 6). Pixels are copied as OpenReadout decodes them, so the export of a JPEG-compressed slide holds OpenReadout’s decoded values, which can differ from another JPEG decoder’s by a few grey levels.
  • NIfTI is NIfTI-1, gzip-compressed for .nii.gz: one image (--image) with x, y, z, t and channels as the fifth dimension, in the values info reports (rescaled, so CT is in Hounsfield units). The voxel size is always written. The orientation comes from the DICOM geometry or the source NIfTI header and is written as both qform and sform. The report’s affine_from says dicom, nifti, or none when the source records no orientation.
  • CSV of a table writes column names on line 1 and raw stored values. FCS values are not compensated or scaled. CSV of a trace starts with a time_s column (or the trace’s own axis, such as chemical_shift_ppm) followed by one column per channel in physical units.
  • Parquet and Arrow keep each column’s stored type. Units, labels, provenance and the source’s info are stored as field and file metadata.
  • mzML is indexed mzML 1.1.0, one spectrum per scan of the chosen run. An mzML source also keeps its spectrum ids (when it names their nativeID format), its chromatograms (TIC, SRM traces) and its exact instrument, component and software terms. Other sources get a TIC from the written spectra and, for SRM/MRM runs (Thermo, Sciex, Agilent, Shimadzu), one SRM chromatogram per transition, as msconvert writes them. They were checked against ProteoWizard exports of Thermo, Sciex, Agilent and Shimadzu runs. Optical spectra in an mzML source (a PDA detector’s, over wavelength) are left out; the report counts them in spectra_skipped and says why in warnings. A run with chromatograms and no spectra (an MRM-only mzML, a Waters MRM .raw) is written as its chromatograms alone, a Waters MRM table as a TIC and one SRM chromatogram per transition.
  • NWB writes one TimeSeries per trace, sweep and unit, in physical units.
  • JCAMP-DX is version 5.01 or 6.00. Values round-trip exactly when they are integer multiples of one factor; the report says whether they did.
  • ASM is Allotrope Simple Model plate-reader JSON, one document per plate and well.
  • RDML is RDML 1.3 with the plate setup, Cq values, amplification curves and melt data.
  • FASTQ uses Phred+33 qualities. A Sanger read gives one record from the basecaller’s calls. An Illumina run gives a directory with one gzipped file per lane and read, from the BCL or CBCL base calls of clusters that pass the filter; --rows 0-N writes the first N+1 clusters of each lane.
  • MRC is MRC2014: time points become an image stack, z planes a volume, with the pixel size in the cell dimensions. --group-frames N sums every N frames into one section. uint8 and uint16 samples are written as mode 6 (uint16), int16 as mode 1, the rest as float32.

With -o and no --format, the output’s extension picks the format: .ome.tiff, .ome.tif, .tiff and .tif give OME-TIFF, .ome.zarr and .zarr OME-Zarr, .nii and .nii.gz NIfTI, .mzML mzML, .csv CSV, .parquet Parquet, .arrow and .feather Arrow, .nwb NWB, .jdx and .dx JCAMP-DX, .json ASM, .rdml RDML, .fastq and .fq FASTQ (and a name ending in _fastq, the directory an Illumina run’s FASTQ goes to), and .mrc and .mrcs MRC. export x.lif -o x.ome.zarr writes OME-Zarr. An extension that names no format, or one that contradicts --format (-o x.ome.zarr --format ome-tiff), exits 2 and writes nothing. With --format, an output name without one of these extensions is fine.

A combination that does not fit, such as an image file --format csv, exits 6.

JSON

export.

Run openreadout export --help for the full help of your installed version.