IO#

Unified IO interface for all ClearMap data sources.

This module is the single entry point for reading, writing, and inspecting data in any format that ClearMap understands. It dispatches every call to the appropriate format-specific sub-module based on the type or file extension of the source, so calling code never needs to import TIF, MMP, NPY, etc. directly.

Supported formats#

Extension	Module	Notes
`.npy`	`MMP`	Memory-mapped NumPy arrays (default for large 3-D volumes)
`.tif` / `.tiff`	`TIF`	Single files and file-list expressions
`.nrrd` / `.nrdh`	`NRRD`
`.mhd`	`MHD`	MetaImage header + raw data
`.csv`	`CSV`	Point / coordinate tables
`.gt`	`GT`	graph-tool graphs (optional dependency)
`<tag expression>`	`FileList`	Ordered lists of files matched by a tag expression
`np.ndarray`	`NPY`	In-memory NumPy arrays
`np.memmap`	`MMP`	Memory maps passed directly
shared memory	`SMA`	Shared-memory arrays for parallel processing

Source routing#

source_to_module() maps any source specification to its handler module:

A Source instance → the module that created it.
A str or Expression → location_to_module() (file-list expression, or extension lookup).
A np.ndarray / list / tuple → SMA if in shared memory, else NPY.
A np.memmap → MMP.

Core functions#

Reading and writing

import ClearMap.IO.IO as io

data  = io.read('signal.tif')            # returns np.ndarray
data  = io.read('volume.npy',
                slicing=(slice(0, 100),)) # sub-slice
io.write('output.tif', data)

Source objects — richer than raw arrays; carry shape, dtype, and location:

src = io.as_source('volume.npy')
print(src.shape, src.dtype, src.order)
data = src[10:20, :, :]               # lazy slicing

Initialising a sink before parallel workers write into it:

# Open existing file or create it if absent
sink = io.initialize('counts.npy',
                     shape_=(512, 512, 256),
                     dtype_=np.uint16,
                     order_='F')

File-list expressions — match tiles with tag patterns:

files = io.file_list('raw/tile_<X,2>_<Y,2>.tif')

Bulk conversion between formats (parallelised):

io.convert_files(files, extension='.npy', processes=8)

Property helpers#

shape(), dtype(), order(), location(), element_strides(), memory(), buffer() — each accepts any source specification (path, array, or Source) and returns the corresponding attribute without requiring the caller to construct a Source explicitly.

File-path utilities#

The following functions from FileUtils are re-exported here for convenience: is_file, is_directory, file_extension, join, split, abspath, create_directory, delete_directory, copy_file, link_file, delete_file.