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

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

Parameters:
  • x – The x-index (pims expects this)
  • y – The y-index (pims expects this)
  • c – The color channel number
  • t – The frame number
  • z – The z stack number
  • v – The field of view index
Returns:

The requested frame

Return type:

numpy.ndarray

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_name, 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_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

Contains information about the defined ROIs – shape, position and type (reference/background/stimulation).

Returns:ROI metadata dictionary
Return type:dict
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_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.

exception nd2reader.exceptions.NoImageError[source]

Bases: Exception

No image found.

Some apparent images in ND2s are just completely blank placeholders. These are used when the number of images per cycle are unequal (e.g. if you take fluorescent images every 2 minutes, and bright field images every minute).

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