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(fh)[source]¶

Bases: 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

property events¶

Get the events of the experiment

Returns:: iterator of events as dict

property 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]¶

Gets a given frame using the parser :param x: The x-index (pims expects this) :param y: The y-index (pims expects this) :param c: The color channel number :param t: The frame number :param z: The z stack number :param v: The field of view index

Returns:: The requested frame
Return type:: pims.Frame

get_timesteps()[source]¶

Get the timesteps of the experiment

Returns:: an array of times in milliseconds.
Return type:: np.ndarray

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

property pixel_type¶

Return the pixel data type

Returns:: the pixel data type
Return type:: dtype

property 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.

property acquisition_times¶

Acquisition times

Yields:: float – the acquisition time

property app_info¶

NIS elements application info

Returns:: (Version) information of the NIS Elements application
Return type:: dict

property camera_exposure_time¶

Exposure time information

Returns:: Camera exposure time
Return type:: dict

property camera_temp¶

Camera temperature

Yields:: float – the temperature

property 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

property grabber_settings¶

Grabber settings

Returns:: Acquisition settings
Return type:: dict

property image_attributes¶

Image attributes

Returns:: containing the image attributes
Return type:: dict

property image_calibration¶

The amount of pixels per micron.

Returns:: pixels per micron
Return type:: dict

property image_events¶

Image events

Returns:: Image events
Return type:: dict

property image_metadata¶

Image metadata

Returns:: Extra image metadata
Return type:: dict

property image_metadata_sequence¶

Image metadata of the sequence

Returns:: containing the metadata
Return type:: dict

property image_text_info¶

Textual image information

Returns:: containing the textual image info
Return type:: dict

property lut_data¶

LUT information

Returns:: LUT information
Return type:: dict

property pfs_offset¶

Perfect focus system (PFS) offset

Returns:: Perfect focus system (PFS) offset
Return type:: dict

property pfs_status¶

Perfect focus system (PFS) status

Returns:: Perfect focus system (PFS) status
Return type:: dict

property roi_metadata¶

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

Returns:: ROI metadata dictionary
Return type:: dict
Type:: Contains information about the defined ROIs

property x_data¶

X data

Returns:: x_data
Return type:: dict

property y_data¶

Y data

Returns:: y_data
Return type:: dict

property 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.

property acquisition_frames¶

Get the location of the acquisition frames

Returns:: The location of the acquisition frames
Return type:: int

property acquisition_times¶

Get the location of the acquisition times, block 1

Returns:: The location of the acquisition times, block 1
Return type:: int

property acquisition_times_2¶

Get the location of the acquisition times, block 2

Returns:: The location of the acquisition times, block 2
Return type:: int

property app_info¶

Get the location of the application info metadata

Returns:: The location of the application info metadata
Return type:: int

property camera_exposure_time¶

Get the location of the camera exposure time

Returns:: The location of the camera exposure time
Return type:: int

property camera_temp¶

Get the location of the camera temperature

Returns:: The location of the camera temperature
Return type:: int

property custom_data¶

Get the location of the custom user data

Returns:: The location of the custom user data
Return type:: int

property 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

property grabber_settings¶

Get the location of the grabber settings

Returns:: The location of the grabber settings
Return type:: int

property guid¶

Get the location of the image guid

Returns:: The location of the image guid
Return type:: int

property image_attributes¶

Get the location of the image attributes

Returns:: The location of the image attributes
Return type:: int

property image_calibration¶

Get the location of the image calibration

Returns:: The location of the image calibration
Return type:: int

property image_events¶

Get the location of the image events

Returns:: The location of the image events
Return type:: int

property image_metadata¶

Get the location of the image metadata

Returns:: The location of the image metadata
Return type:: int

property 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

property image_text_info¶

Get the location of the textual image information

Returns:: The location of the textual image information
Return type:: int

property lut_data¶

Get the location of the LUT data

Returns:: The location of the LUT data
Return type:: int

property 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

property 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

property 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

property x_data¶

Get the location of the custom x data

Returns:: The location of the custom x data
Return type:: int

property y_data¶

Get the location of the custom y data

Returns:: The location of the custom y data
Return type:: int

property 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.InvalidFileType[source]¶

Bases: Exception

Non .nd2 extension file.

File does not have an extension .nd2.

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}¶

property 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.

property channels¶

Deprecated. Fetches all color channels.

Returns:: the color channels.
Return type:: list

close()[source]¶: Closes the ND2Reader

property date¶

Deprecated. Fetches the acquisition date.

Returns:: the date
Return type:: string

property fields_of_view¶

Deprecated. Fetches the fields of view.

Returns:: fields of view.
Return type:: list

property 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

property height¶

Deprecated. Fetches the height of the image.

Returns:: the pixel height of the image
Return type:: int

property 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

property width¶

Deprecated. Fetches the width of the image.

Returns:: the pixel width of the image
Return type:: int

property z_levels¶

Deprecated. Fetches the available z levels.

Returns:: z levels.
Return type:: list