EMC File I/O Module

The EMC file I/O module provides classes for reading and writing EMC photon data files.

Usage Example

Reading EMC files:

from dragonfly import Detector, EMCReader

det = Detector('detector.h5')
emc = EMCReader('photons.emc', det)

aframe = emc.get_frame(0) # Assembled masked array
frame = emc.get_frame(0, raw=True) # Unassembled dense array
# Sparse format (fastest to read)
place_ones, place_multi, count_multi = emc.get_frame(0, sparse=True)

powder = emc.get_powder() # Virtual powder sum (assembled)

Writing EMC files:

import numpy as np
from dragonfly import EMCWriter

# Write a random dataset with a dispersion of 1 ph/pixel on average
num_pix = 10000
with EMCWriter('output.emc', num_pix, hdf5=False) as emc:
    for i in range(100):
        emc.write_frame(np.random.poisson(1.0, num_pix))

Writing subsets of data:

from dragonfly import Detector, EMCReader, EMCWriter

det = Detector('detector.h5')
emc = EMCReader('original.emc', det)

# Write every 10th frame to a new file
with EMCWriter('every10.emc', det.num_pix, hdf5=False) as wemc:
    for i in range(0, emc.num_frames, 10):
        wemc.write_sparse_frame(*emc.get_frame(i, sparse=True))

# Write dataset with 1/10th ph/pixel (randomly chosen)
with EMCWriter('lowsignal.emc', det.num_pix, hdf5=False) as wemc:
    for i in range(emc.num_frames):
        wemc.write_frame(emc.get_frame(i, raw=True), fraction=0.1)

Module containing classes to interface with EMC files

class dragonfly.emcfile.CDataset(fname=None, CDetector det=None, lazy=False)

Bases: object

Low-level interface to EMC photon data files.

Parameters:

fname (str) – Path to EMC file. Default None.
det (CDetector) – Associated detector object. Default None.

append(self, CDataset next_dset)

Append another dataset to the linked list.

Parameters:: next_dset (CDataset) – Dataset to append.

count_multi: Photon counts at multi-photon pixels.

det: Associated detector object.

fname: Path to EMC file.

free(self): Free allocated memory for sparse data arrays.

ftype: Returns the frame type (sparse, dense_integer, or dense_double).

lazy: Whether this dataset uses lazy active-frame loading.

load_active_frames(self, blacklist)

Load sparse binary frames selected by a blacklist.

This is only needed for datasets parsed with lazy=True. The blacklist may either be local to this dataset with length num_data or global with length at least num_offset + num_data. Frames with blacklist value 0 are loaded.

multi: Number of multi-photon pixels per frame.

multi_accum: Cumulative sum of multi-photon counts.

multi_total: Total number of multi-photon events.

next: Next dataset in linked list.

num_data: Number of frames in the file.

num_pix: Number of pixels per frame.

ones: Number of single-photon pixels per frame.

ones_accum: Cumulative sum of single-photon counts.

ones_total: Total number of single-photon events.

parse(self, fname, lazy=False)

Parse EMC file.

Parameters:: fname (str) – Path to EMC file.
Raises:: AttributeError – If detector is not set before parsing.

place_multi: Pixel indices for multi-photon events.

place_ones: Pixel indices for single-photon events.

class dragonfly.emcfile.EMCReader(photons_list, det_list, dset_list=None, det_mapping=None)

Bases: object

EMC file reader.

Provides access to assembled or raw frames given a list of .emc filenames.

Parameters:

photons_list (str or list) – Path or sequence of paths to emc files.
det_list (Detector or list) – Single or list of Detector objects.
dset_list (str or list) – HDF5 dataset names for dense frames. Default None.
det_mapping (list) – Mapping from photons_list to det_list. Default None.

Example

>>> det = Detector('detector.h5')
>>> reader = EMCReader('photons.emc', det)
>>> frame = reader.get_frame(0, zoomed=True)

num_frames

Total number of frames.

Type:: int

blacklist

Blacklist mask for frames.

Type:: numpy.ndarray

num_blacklist

Number of blacklisted frames.

Type:: int

get_frame(self, num, **kwargs)

Get particular frame from file list.

Parameters:

num (int) – Frame number.
raw (bool) – Whether to get unassembled frame. Default False.
sparse (bool) – Whether to return sparse data. Default False.
zoomed (bool) – Whether to zoom assembled frame. Default False.
sym (bool) – Whether to centro-symmetrize frame. Default False.

Returns:

Assembled or unassembled frame as a dense array.

get_powder(self, raw=False, verbose=False, **kwargs)

Get virtual powder sum of all frames.

Parameters:

raw (bool) – Whether to return unassembled powder sum. Default False.
zoomed (bool) – Whether to zoom assembled frame. Default False.
sym (bool) – Whether to centro-symmetrize frame. Default False.

Returns:

Assembled or unassembled powder sum as a dense array.

Raises:

ValueError – If multiple detectors are used.

class dragonfly.emcfile.EMCWriter(out_fname, num_pix, hdf5=True)

Bases: object

EMC file writer.

Provides interface to write photon count data to an emc file.

Parameters:

out_fname (str) – Output filename.
num_pix (int) – Number of pixels in dense frame.
hdf5 (bool) – Use HDF5 format. Default True.

Example

>>> with EMCWriter('photons.emc', num_pix, hdf5=False) as emc:
...     for i in range(num_frames):
...         emc.write_frame(frame[i].ravel())

num_data

Number of frames written.

Type:: int

num_pix

Number of pixels per frame.

Type:: int

mean_count

Mean photon count per frame.

Type:: float

finish_write(self, header_nums=None)

Finalize and close the EMC file.

Writes the header and appends temporary files. Deletes temp files after.

Parameters:: header_nums (list) – Additional header values. Default None.

write_frame(self, frame, fraction=1., partition=1)

Write frame to the file.

Parameters:

frame (numpy.ndarray) – 1D dense array with photon counts per pixel.
fraction (float) – Fraction of photons to write (0-1). Default 1.0.
partition (int) – Partition frame into N sub-frames. Default 1.

Raises:

ValueError – If frame is not a 1D integer array.

write_sparse_frame(self, place_ones, place_multi, count_multi)

Write sparse frame to file.

Parameters:

place_ones (numpy.ndarray) – Pixel indices with single photons.
place_multi (numpy.ndarray) – Pixel indices with multiple photons.
count_multi (numpy.ndarray) – Photon counts at multi-photon pixels.

Raises:

ValueError – If place_multi and count_multi have different lengths.
ValueError – If arrays are not integer type.