nd2reader package

In general, you should only have to use the nd2reader.reader module. The rest of the submodules are for internal use only.

Submodules

nd2reader.reader module

class nd2reader.reader.ND2Reader(filename)[source]

Bases: pims.base_frames.FramesSequenceND

PIMS wrapper for the ND2 parser. This is the main class: use this to process your .nd2 files.

classmethod class_exts()[source]

Let PIMS open function use this reader for opening .nd2 files

class_priority = 12
close()[source]

Correctly close the file handle

events

Get the events of the experiment

Returns

iterator of events as dict

frame_rate

The (average) frame rate

Returns

the (average) frame rate in frames per second

Return type

float

get_frame_2D(c=0, t=0, z=0, x=0, y=0, v=0)[source]

Fallback function for backwards compatibility

get_frame_vczyx(v=None, c=None, t=None, z=None, x=None, y=None)[source]
get_timesteps()[source]

Get the timesteps of the experiment

Returns

an array of times in milliseconds.

Return type

np.ndarray

parser

Returns the parser object. :returns: the parser object :rtype: Parser

pixel_type

Return the pixel data type

Returns

the pixel data type

Return type

dtype

timesteps

Get the timesteps of the experiment

Returns

an array of times in milliseconds.

Return type

np.ndarray

nd2reader.parser module

class nd2reader.parser.Parser(fh)[source]

Bases: object

Parses ND2 files and creates a Metadata and driver object.

CHUNK_HEADER = 180276954
CHUNK_MAP_END = b'ND2 CHUNK MAP SIGNATURE 0000001!'
CHUNK_MAP_START = b'ND2 FILEMAP SIGNATURE NAME 0001!'
calculate_image_properties(index)[source]

Calculate FOV, channels and z_levels

Parameters

index (int) – the index (which is simply the order in which the image was acquired)

Returns

tuple of the field of view, the channel and the z level

Return type

tuple

static get_dtype_from_metadata()[source]

Determine the data type from the metadata.

For now, always use float64 to prevent unexpected overflow errors when manipulating the data (calculating sums/ means/etc.)

get_image(index)[source]

Creates an Image object and adds its metadata, based on the index (which is simply the order in which the image was acquired). May return None if the ND2 contains multiple channels and not all were taken in each cycle (for example, if you take bright field images every minute, and GFP images every five minutes, there will be some indexes that do not contain an image. The reason for this is complicated, but suffice it to say that we hope to eliminate this possibility in future releases. For now, you’ll need to check if your image is None if you’re doing anything out of the ordinary.

Parameters

index (int) – the index (which is simply the order in which the image was acquired)

Returns

the image

Return type

Frame

get_image_by_attributes(frame_number, field_of_view, channel, z_level, height, width)[source]

Gets an image based on its attributes alone

Parameters
  • frame_number – the frame number

  • field_of_view – the field of view

  • channel_name – the color channel name

  • z_level – the z level

  • height – the height of the image

  • width – the width of the image

Returns

the requested image

Return type

Frame

supported_file_versions = {(3, None): True}

nd2reader.raw_metadata module

class nd2reader.raw_metadata.RawMetadata(fh, label_map)[source]

Bases: object

RawMetadata class parses and stores the raw metadata that is read from the binary file in dict format.

acquisition_times

Acquisition times

Yields

float – the acquisition time

app_info

NIS elements application info

Returns

(Version) information of the NIS Elements application

Return type

dict

camera_exposure_time

Exposure time information

Returns

Camera exposure time

Return type

dict

camera_temp

Camera temperature

Yields

float – the temperature

custom_data

Custom user data

Returns

custom user data

Return type

dict

get_duration_from_interval_and_loops(duration, interval, loop)[source]

Infers the duration of the loop from the number of measurements and the interval

Parameters
  • duration – loop duration in milliseconds

  • duration – measurement interval in milliseconds

  • loop – loop dictionary

Returns

the loop duration in milliseconds

Return type

float

get_parsed_metadata()[source]

Returns the parsed metadata in dictionary form.

Returns

the parsed metadata

Return type

dict

grabber_settings

Grabber settings

Returns

Acquisition settings

Return type

dict

image_attributes

Image attributes

Returns

containing the image attributes

Return type

dict

image_calibration

The amount of pixels per micron.

Returns

pixels per micron

Return type

dict

image_events

Image events

Returns

Image events

Return type

dict

image_metadata

Image metadata

Returns

Extra image metadata

Return type

dict

image_metadata_sequence

Image metadata of the sequence

Returns

containing the metadata

Return type

dict

image_text_info

Textual image information

Returns

containing the textual image info

Return type

dict

lut_data

LUT information

Returns

LUT information

Return type

dict

pfs_offset

Perfect focus system (PFS) offset

Returns

Perfect focus system (PFS) offset

Return type

dict

pfs_status

Perfect focus system (PFS) status

Returns

Perfect focus system (PFS) status

Return type

dict

roi_metadata

shape, position and type (reference/background/stimulation).

Returns

ROI metadata dictionary

Return type

dict

Type

Contains information about the defined ROIs

x_data

X data

Returns

x_data

Return type

dict

y_data

Y data

Returns

y_data

Return type

dict

z_data

Z data

Returns

z_data

Return type

dict

nd2reader.label_map module

class nd2reader.label_map.LabelMap(raw_binary_data)[source]

Bases: object

Contains pointers to metadata. This might only be valid for V3 files.

acquisition_frames

Get the location of the acquisition frames

Returns

The location of the acquisition frames

Return type

int

acquisition_times

Get the location of the acquisition times, block 1

Returns

The location of the acquisition times, block 1

Return type

int

acquisition_times_2

Get the location of the acquisition times, block 2

Returns

The location of the acquisition times, block 2

Return type

int

app_info

Get the location of the application info metadata

Returns

The location of the application info metadata

Return type

int

camera_exposure_time

Get the location of the camera exposure time

Returns

The location of the camera exposure time

Return type

int

camera_temp

Get the location of the camera temperature

Returns

The location of the camera temperature

Return type

int

custom_data

Get the location of the custom user data

Returns

The location of the custom user data

Return type

int

description

Get the location of the image description

Returns

The location of the image description

Return type

int

get_image_data_location(index)[source]

Get the location of the image data

Returns

The location of the image data

Return type

int

grabber_settings

Get the location of the grabber settings

Returns

The location of the grabber settings

Return type

int

guid

Get the location of the image guid

Returns

The location of the image guid

Return type

int

image_attributes

Get the location of the image attributes

Returns

The location of the image attributes

Return type

int

image_calibration

Get the location of the image calibration

Returns

The location of the image calibration

Return type

int

image_events

Get the location of the image events

Returns

The location of the image events

Return type

int

image_metadata

Get the location of the image metadata

Returns

The location of the image metadata

Return type

int

image_metadata_sequence
Get the location of the image metadata sequence. There is always only one of these, even though it has a pipe

followed by a zero, which is how they do indexes.

Returns

The location of the image metadata sequence

Return type

int

image_text_info

Get the location of the textual image information

Returns

The location of the textual image information

Return type

int

lut_data

Get the location of the LUT data

Returns

The location of the LUT data

Return type

int

pfs_offset

Get the location of the perfect focus system (PFS) offset

Returns

The location of the perfect focus system (PFS) offset

Return type

int

pfs_status

Get the location of the perfect focus system (PFS) status

Returns

The location of the perfect focus system (PFS) status

Return type

int

roi_metadata

Information about any regions of interest (ROIs) defined in the nd2 file

Returns

The location of the regions of interest (ROIs)

Return type

int

x_data

Get the location of the custom x data

Returns

The location of the custom x data

Return type

int

y_data

Get the location of the custom y data

Returns

The location of the custom y data

Return type

int

z_data

Get the location of the custom z data

Returns

The location of the custom z data

Return type

int

nd2reader.common module

nd2reader.common.check_or_make_dir(directory)[source]

Check if a directory exists, if not, create it :param directory: the path to the directory

nd2reader.common.get_from_dict_if_exists(key, dictionary, convert_key_to_binary=True)[source]

Get the entry from the dictionary if it exists :param key: key to lookup :param dictionary: dictionary to look in :param convert_key_to_binary: convert the key from string to binary if true

Returns

the value of dictionary[key] or None

nd2reader.common.get_version(fh)[source]

Determines what version the ND2 is.

Parameters

fh – File handle of the .nd2 file

Returns

Major and minor version

Return type

tuple

nd2reader.common.parse_date(text_info)[source]

The date and time when acquisition began.

Parameters

text_info – the text that contains the date and time information

Returns

the date and time of the acquisition

Return type

datetime

nd2reader.common.parse_version(data)[source]

Parses a string with the version data in it.

Parameters

data (unicode) – the 19th through 54th byte of the ND2, representing the version

Returns

Major and minor version

Return type

tuple

nd2reader.common.read_array(fh, kind, chunk_location)[source]
Parameters
  • fh – File handle of the nd2 file

  • kind – data type, can be one of ‘double’, ‘int’ or ‘float’

  • chunk_location – the location of the array chunk in the binary nd2 file

Returns

an array of the data

Return type

array.array

nd2reader.common.read_chunk(fh, chunk_location)[source]

Reads a piece of data given the location of its pointer.

Parameters
  • fh – an open file handle to the ND2

  • chunk_location (int) – location to read

Returns

the data at the chunk location

Return type

bytes

nd2reader.common.read_metadata(data, count)[source]

Iterates over each element of some section of the metadata and parses it.

Parameters
  • data – the metadata in binary form

  • count – the number of metadata elements

Returns

a dictionary containing the parsed metadata

Return type

dict

nd2reader.exceptions module

exception nd2reader.exceptions.EmptyFileError[source]

Bases: Exception

This .nd2 file seems to be empty.

Raised if no axes are found in the file.

exception nd2reader.exceptions.InvalidVersionError[source]

Bases: Exception

Unknown version.

We don’t know how to parse the version of ND2 that we were given.

nd2reader.artificial module

Functions to create artificial nd2 data for testing purposes

class nd2reader.artificial.ArtificialND2(file, version=(3, 0), skip_blocks=None)[source]

Bases: object

Artificial ND2 class (for testing purposes)

close()[source]

Correctly close the file handle

create_label_map_bytes()[source]

Construct a binary label map

Returns

(binary data, dictionary data)

Return type

tuple

data_types = {'char_array': 9, 'double': 6, 'metadata_item': 11, 'string': 8, 'unsigned_char': 1, 'unsigned_int': 2, 'unsigned_int_2': 3, 'unsigned_long': 5}
file_handle

The file handle to the binary file

Returns

the file handle

Return type

file

header = 180276954
relative_offset = 0
write_file(skip_blocks=None)[source]
write_label_map()[source]
write_label_map_info()[source]

Write the location of the start of the label map at the end of the file

write_version()[source]

Write file header

nd2reader.legacy module

Legacy class for backwards compatibility

class nd2reader.legacy.Nd2(filename)[source]

Bases: object

Warning: this module is deprecated and only maintained for backwards compatibility with the non-PIMS version of nd2reader.

channels

Deprecated. Fetches all color channels.

Returns

the color channels.

Return type

list

close()[source]

Closes the ND2Reader

date

Deprecated. Fetches the acquisition date.

Returns

the date

Return type

string

fields_of_view

Deprecated. Fetches the fields of view.

Returns

fields of view.

Return type

list

frames

Deprecated. Fetches all frames.

Returns

list of frames

Return type

list

get_image(frame_number, field_of_view, channel_name, z_level)[source]

Deprecated. Returns the specified image from the ND2Reader class.

Parameters
  • frame_number – the frame number

  • field_of_view – the field of view number

  • channel_name – the name of the color channel

  • z_level – the z level number

Returns

the specified image

Return type

Frame

height

Deprecated. Fetches the height of the image.

Returns

the pixel height of the image

Return type

int

pixel_microns

Deprecated. Fetches the amount of microns per pixel.

Returns

microns per pixel

Return type

float

select(fields_of_view=None, channels=None, z_levels=None, start=0, stop=None)[source]

Select images based on criteria.

Parameters
  • fields_of_view – the fields of view

  • channels – the color channels

  • z_levels – the z levels

  • start – the starting frame

  • stop – the last frame

Returns

Sliced ND2Reader which contains the frames

Return type

ND2Reader

width

Deprecated. Fetches the width of the image.

Returns

the pixel width of the image

Return type

int

z_levels

Deprecated. Fetches the available z levels.

Returns

z levels.

Return type

list