Detector events

A detector that counts electrons records events, not images, as an EER file does. Its events are read as they are, or become a movie by cutting time into fractions and rendering each.

Reading

vitrio.read_events(key, begin=None, end=None, events=None)

Read the events a detector counted over a stretch of time.

Time is counted in the quanta of the file, which are frames for EER. The events come in groups of one timestamp each:

timeline = read_events('movie.eer', 0, 10)
frames = np.asarray(timeline.timestamps)
positions = np.asarray(timeline.get_positions(0))

Positions are counted on the grid of subpixels the file places them on, slowest axis first. The views share the memory of the timeline, which refuses to change while one of them is alive.

Parameters:

  • key – The file to read, as its key in events.

  • begin – The first time quantum to read. Defaults to the first.

  • end – One past the last time quantum to read. Defaults to the end of the acquisition.

  • events – Where the file becomes a reader of its events. Defaults to a provider that opens the file at the path key is.

Returns:

The events of the stretch of time.

Return type:

DetectorEventTimeline

vitrio.detector_event_timeline_reader_provider(formats=None)

Assemble a provider of the events of the files of a detector, such as EER files.

Parameters:

formats – The formats to recognize files with. Defaults to the bundled ones.

Returns:

The assembled provider. Its

keys are paths.

Return type:

DetectorEventTimelineReaderProvider

vitrio.detector_event_image_reader_provider(fractions, binning=1, cache=None, formats=None)

Assemble a reader provider that reads the files of a detector that counts events, such as EER files, as movies.

The time of a file is cut into as many fractions as asked for, as evenly as its frames allow, and the events of each fraction are counted per pixel into one image of the movie. A single fraction reads as one image of every event.

readers = detector_event_image_reader_provider(40, binning=2) movie = read(‘movie.eer’, readers, data_type=’float32’)

Parameters:

  • fractions – How many fractions to cut a file into.

  • binning – How many pixels of the detector a pixel of the movie gathers along each axis. Defaults to the resolution of the detector. It must divide the pixels of every file read.

  • cache – How many open readers to keep between reads. Defaults to opening a file every time it is asked for.

  • formats – The formats to recognize files with. Defaults to the bundled ones.

Returns:

The assembled provider. Its keys are paths.

Return type:

ImageReaderProvider

Events

class vitrio.DetectorEventTimeline(rank: int)

The events a detector counted over a stretch of time.

The events come in groups of one timestamp each, such as the frames of an EER file. timestamps and get_positions return read-only views of the memory of the timeline, which keep it alive. The timeline refuses to change with BufferError while one of them is alive, as a bytearray refuses to resize while a memoryview of it is.

Make an empty timeline.

Parameters:

rank – How many axes the positions of its events have.

add_group(self, timestamp: int, positions: ndarray[dtype=uint32, shape=(*, *), order='C', device='cpu', writable=False]) → None

Add a group of events to the end.

Parameters:

  • timestamp – The time quantum its events happened in.

  • positions – A two-dimensional array of unsigned 32-bit integers with a row for each event.

Raises:

  • ValueError – If a row does not have the rank of the timeline.

  • BufferError – If a view of the timeline is alive.

clear(self) → None

Remove every group.

Raises:

BufferError – If a view of the timeline is alive.

property event_count

How many events in all the groups.

get_positions(self, group: int | None = None) → ArrayLike[dtype=uint32, shape=(*, *), writable=False]

View the positions of the events.

Parameters:

group – The group to view. Defaults to every group, one after the other.

Returns: A read-only view with a row of coordinates for each event, on the grid of position quanta, slowest axis first.

Raises:

IndexError – If the group is not there.

property group_count

How many groups of events, one for each timestamp.

property rank

How many coordinates the position of an event has.

reserve(self, group_count: int, event_count: int) → None

Make room for that many groups and events, to allocate once.

property timestamps

A view of the timestamps, one for each group, in time quanta.

property view_count

How many views of its memory are alive.

class vitrio.DetectorEventTimelineDescriptor(extents: collections.abc.Sequence[int], subdivisions: collections.abc.Sequence[int], time_extent: int, time_quantum: float)

What is fixed for one acquisition of a detector that counts events.

The positions of its events lie on a grid of position quanta: a pixel of the detector may be divided into several of them along each axis. The time of the acquisition is counted in time quanta, which are the frames of an EER file.

Describe an acquisition.

Parameters:

  • extents – The extents of the grid of positions, slowest axis first.

  • subdivisions – How many position quanta a pixel of the detector spans along each axis.

  • time_extent – How many time quanta the acquisition spans.

  • time_quantum – The length of a time quantum in seconds, or zero when it is not known.

property extents

The extents of the grid of positions, as a tuple.

property rank

How many axes events are placed along.

property subdivisions

How many position quanta a pixel spans along each axis.

property time_extent

How many time quanta the acquisition spans.

property time_quantum

The length of a time quantum in seconds, or zero if unknown.

class vitrio.DetectorEventTimelineReader

An open file of the events of an acquisition.

property descriptor

The DetectorEventTimelineDescriptor of the acquisition.

read(self, time_begin: int, time_end: int, destination: vitrio._binding.DetectorEventTimeline) → None

Read the events of a stretch of time.

The GIL is released meanwhile.

Parameters:

  • time_begin – The first time quantum to read.

  • time_end – One past the last.

  • destination – The DetectorEventTimeline they are read into.

class vitrio.DetectorEventTimelineReaderProvider

Turns a key into an open reader of the events of an acquisition.

acquire(self, key: str | os.PathLike) → vitrio._binding.DetectorEventTimelineReader

Get the reader of a key.

Parameters:

key – The key, a path for the provider of files.

Returns:

The reader.

Return type:

DetectorEventTimelineReader

class vitrio.FileDetectorEventTimelineReaderProvider(formats: vitrio._binding.DetectorEventTimelineFileReadFormatSelector)

Opens the file at a path with the format that suits it.

Make a provider.

Parameters:

formats – The DetectorEventTimelineFileReadFormatSelector that opens the files.

class vitrio.DetectorEventTimelineFileReadFormatSelector

Holds the formats the events of a detector may be read from.

get_shared() → vitrio._binding.DetectorEventTimelineFileReadFormatSelector

Get the selector that holds the formats that come with vitrio.

Returns:

Holds EER, when built with TIFF.

Return type:

DetectorEventTimelineFileReadFormatSelector

Movies

class vitrio.DetectorEventFractionation(fraction_count: int)

How the time of an acquisition is cut into the fractions of a movie.

The time quanta are shared as evenly as they allow: none is dropped, and a fraction has at most one more than another.

Cut time into a number of fractions.

Parameters:

fraction_count – How many fractions, at least one.

Raises:

ValueError – If it is zero or more than max_fraction_count.

property fraction_count

How many fractions the time is cut into.

get_fraction_begin(self, fraction: int, time_extent: int) → int

Get the first time quantum of a fraction.

Parameters:

  • fraction – The fraction. fraction_count gives where the last one ends, which is time_extent.

  • time_extent – How many time quanta the acquisition spans.

Returns:

The time quantum the fraction begins at.

Return type:

int

Raises:

IndexError – If fraction is past fraction_count.

class vitrio.DetectorEventBinning(factor: int)

How many pixels of the detector a pixel of an image gathers.

It is stated in pixels of the detector, not in position quanta, so it means the same for a detector that places its events finer.

Gather pixels along each axis.

Parameters:

factor – How many pixels along each axis, at least one.

property factor

How many pixels of the detector along each axis.

resolve(self, events: vitrio._binding.DetectorEventTimelineDescriptor) → tuple[int, ...]

Get how many position quanta a pixel of an image gathers.

Parameters:

events – The DetectorEventTimelineDescriptor of the acquisition.

Returns:

The extents of the block of quanta, slowest axis first.

Return type:

tuple

Raises:

ValueError – If the factor does not divide the pixels of the detector along an axis.

class vitrio.DetectorEventRenderer

Turns the events of a stretch of time into an image.

property data_type

The NumericalType of the images it renders.

get_image_extents(self, events: vitrio._binding.DetectorEventTimelineDescriptor) → tuple[int, ...]

Get the extents of the image it renders.

Parameters:

events – The DetectorEventTimelineDescriptor of the acquisition.

Returns:

The extents, slowest axis first.

Return type:

tuple

render(self, descriptor: vitrio._binding.DetectorEventTimelineDescriptor, events: vitrio._binding.DetectorEventTimeline, destination: ndarray[device='cpu']) → None

Render events into an image.

Parameters:

  • descriptor – The DetectorEventTimelineDescriptor of the acquisition.

  • events – The DetectorEventTimeline to render.

  • destination – Where the image lands, as any host array of the extents get_image_extents gives.

class vitrio.CountingDetectorEventRenderer(binning: vitrio._binding.DetectorEventBinning)

Renders an image whose pixels count the events that fall on them.

Make a renderer.

Parameters:

binning – The DetectorEventBinning that says how many pixels of the detector a pixel of the image gathers.

property binning

The DetectorEventBinning it renders with.

class vitrio.DetectorEventImageReaderProvider(events: vitrio._binding.DetectorEventTimelineReaderProvider, fractionation: vitrio._binding.DetectorEventFractionation, renderer: vitrio._binding.DetectorEventRenderer)

Reads the files of a detector that counts events as movies.

The time of a file is cut into fractions, and the events of each are rendered into one image. What it opens is shown as a stack with an image for each fraction, so it reads wherever an image provider does. vitrio.detector_event_image_reader_provider assembles one.

Make a provider.

Parameters:

  • events – The DetectorEventTimelineReaderProvider that opens the files.

  • fractionation – The DetectorEventFractionation that cuts time.

  • renderer – The DetectorEventRenderer that renders a fraction.