Skip to main content

Easily parse/access a subset of data from a (≤6D) folder of TIFFs

Project description


License: MIT

Lazily read a subset of data from a folder of images using numpy slicing syntax. Includes simplified but robust file pattern matching syntax and multithreaded file reading.

Install with pip

$ pip install tifffolder

Install with conda

$ conda install -c tifffolder


>>> from tifffolder import TiffFolder
>>> tf = TiffFolder('/folder/of/tiffs', patterns={'t': '_stack{d4}', 'c': '_ch{d1}'})

# get dataset shape and order of axes
>>> tf.shape
(10, 2, 65, 184, 157)  # (nt, nc, nz, ny, nx)
>>> tf.axes

# example:
# get the last 10 Z planes from every other timepoint, 
# in the first channel cropping to the middle half in Y
>>> data = tf[::2, 0, -10:, tf.shape[-2] * 1 // 4 : tf.shape[-2] * 3 // 4 ]
>>> data.shape
(5, 10, 92, 157)   # (nt, nz, ny, nx)

# Can also be used as an iterator/generator for lazily reading data
>>> for timepoint in tf:
>>>     do_something(timepoint)
# or just load the whole thing
>>> alldata = tf.asarray()
>>> alldata.shape == tf.shape

# Or just to select filenames along certain axes:
>>> tf.select_filenames(t=range(1,10,2), c=0)

Specifying filename patterns:

tifffolder converts a simplified regex syntax into relatively robust lookahead regex that will match patterns in any order in the filename or fail elegantly.

The TiffFolder class accepts a patterns parameter (dict or list of two-tuples). For each (key, value) in the patterns dict:

  • key = the axes name ('x', 'y', 'z', 'c', 't', 's' are recognized)
  • value = the simplified regex where:
    • things in brackets {} will be captured
    • things outside of brackest will be required to match
    • {d} means match any number of digits
    • {D} means match any number of NON-digits
    • {} means match any alphanumeric character (excluding underscore)
    • {d2} will match exactly two digits

For example:

>>> patterns = {
    'rel': '_{d7}msec',
    'w': '_{d3}nm',
    't': '_stack{d4}',
    'c': '_ch{d1}',
    'cam': 'Cam{D1}'
>>> tf = TiffFolder('/folder/of/tiffs', patterns)
>>> tf._parse_filename('cell1_ch0_stack0009_488nm_0034829msec.tif')
{'rel': 34829, 'w': 488, 't': 9, 'c': 0, 'cam': None}

>>> tf._parse_filename('cell1_CamA_ch2_stack0001_560nm_0034829msec.tif')
{'rel': 34829, 'w': 560, 't': 1, 'c': 2, 'cam': 'A'}

>>> tifffolder.build_regex('cam', 'Cam{}')

>>> tifffolder.build_regex('c', '_ch{d1}')

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tifffolder-0.1.3.tar.gz (7.0 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page