Skip to content

See the Python API overview for an introduction to the midas python package, and data analysis for how to analyse midas data. This page contains the full API reference of the midas.event module, which provides a python interface to the midas data format.

midas.event

Represents data from a MIDAS-format event as python objects, and provides tools for packing and unpacking from raw bytes.

Note that using a numpy array for bank contents (rather than a regular python list/tuple) will result in much faster encoding of the event when sending to midas buffers etc.

midas.event.Bank

Represents a midas BANK, BANK32, or BANK32A struct.

Attributes:

  • name (str) –

    4 characters

  • type (int) –

    See TID_xxx members in midas module

  • size_bytes (int) –
  • data (tuple of int/float/byte etc, or a numpy array if use_numpy is specified when unpacking) –

    The actual data array

dump(data_idx_start=None, data_idx_end=None)

Dump the content of this bank to screen. Format closely matches that of the mdump utility.

Some banks contain thousands of elements / entries. If you only want to see a few entries, you can specify a range to display. By default we show all of them.

Parameters:

  • data_idx_start (int, default: None ) –

    See above

  • data_idx_end (int, default: None ) –

    See above

fill_header_from_bytes(bank_header_data, is_bank_32, is_64bit_aligned)

Fill this EventHeader object from a set of bytes.

Parameters:

  • bank_header_data (byte array of length 8/12) –

    8 bytes if is_bank_32 is False; 12 bytes if is_bank_32 is True.

  • is_bank_32 (bool) –

    Whether the bank size is given by a 32-bit number of a 16-bit number.

  • is_64bit_aligned (bool) –

    Whether bank data starts at 64-bit alignment

Returns:

  • None –

    Attributes of this object just get filled

get_expected_padding()

Midas aligns banks to the nearest 8 bytes. This function tells you how much extra padding to put at the end of this bank's content.

get_pack_fmt(is_bank_32, is_64bit_aligned)

The format string to pass to struct.unpack to extract the bank header data.

Parameters:

  • is_bank_32 (bool) –

    Whether the bank size is given by a 32-bit number of a 16-bit number.

  • is_64bit_aligned (bool) –

    Whether bank data starts at 64-bit alignment

midas.event.Event

Represents a full midas event.

Attributes:

  • header (EventHeader) –

    Metadata about the event

  • all_bank_size_bytes (int) –
  • flags (int) –
  • banks (dict of {str) –

    Bank}): Keyed by bank name

  • non_bank_data (bytes or None) –

    Content of some special events that don't use banks (e.g. begin-of-run ODB dump)

__init__(bank32=True, align64=False)

Parameters: bank32 (bool): 32-bit banks align64 (bool): Make bank data start at 64-bit alignment

add_bank(bank)

Add a bank that was manually created to this event. Most people will use create_bank instead of add_bank.

Parameters:

bank_exists(bank_name)

Whether this event contains a bank of the given name.

Parameters:

  • bank_name (str) –

    Bank to search for

Returns:

  • bool –

    Whether this event contains a bank of the given name.

calculate_bank_sizes()

Calculate and fill the size of the banks in this event, and the overall event size.

This function must be called before we send events into a buffer.

create_bank(bank_name, data_type, data)

Take python data, create a bank from it, and add it to the this event.

  • For most data types you should pass in a list/tuple/numpy.ndarray of numbers.
  • For TID_BYTE and TID_CHAR you should pass in bytes (created with bytes() or bytearray()).
  • For TID_BOOL you can pass in a list/tuple of bools (True/False) or a numpy.ndarray of bools.
Note about numpy

If performance is a strong factor (and you have large bank sizes), you should use a numpy array instead of raw python lists. The correct (most efficient) numpy data type for each midas TID_xxx type is shown in the midas.tid_np_formats dict. E.g.

  • midas.tid_np_formats[midas.TID_DWORD] is numpy.uint32
  • midas.tid_np_formats[midas.TID_DOUBLE] is numpy.float64 etc.

Using a numpy array of the correct data type will result in significantly faster encoding when sending this event to midas buffers.

Parameters:

  • bank_name (str) –

    Name of this bank (must be 4 characters long).

  • data_type (int) –

    See midas.TID_xxx (e.g. midas.TID_INT for storing integers).

  • data (list / tuple / ndarray / bytearray) –

    The data for this bank. See above for more details.

dump(include_bank_content=True)

Print the content of this event to screen. The output format closely resembles that of the mdump utility.

Parameters:

  • include_bank_content (bool, default: True ) –

    Whether to print the content of the data banks, or just the metadata.

fill_header_from_bytes(bank_header_data)

Fill the attributes of this Event object (excluding the bank data itself) from a set of bytes.

Parameters:

  • bank_header_data (byte array of length 8) –

Returns:

  • None –

    the attributes of this object just get filled

get_bank(bank_name)

Return the data bank in this event with the given name.

Parameters:

  • bank_name (str) –

    Bank to search for

Returns:

  • Bank –

    or None if not found.

get_bank_header_size()

Get the number of bytes needed to store the header of a Bank object.

is_bank_32()

Whether the size of banks are stored as 16-bit or 32-bit integers.

is_bank_data_64bit_aligned()

Whether bank data payload is 64-bit aligned or not.

pack(buf=None, buf_offset=0)

Pack an event into a buffer of bytes (creating the buffer if needed).

Parameters:

  • buf (c_char_p, default: None ) –

    The buffer to write to. Probably best created using ctypes.create_string_buffer(). If None, we'll create a buffer of the appropriate size.

  • buf_offset (int, default: 0 ) –

    Where in the buffer to start writing this event.

Returns:

  • c_char_p –

    The buffer that was written to

unpack(buf, buf_offset=0, use_numpy=False)

Unpack a buffer of bytes into this Event object.

Parameters:

  • buf (c_char_p) –

    The buffer to read from.

  • buf_offset (int, default: 0 ) –

    Location in the buffer where this event starts.

  • use_numpy (bool, default: False ) –

    Whether to use numpy arrays or regular python tuples for bank data.

Returns:

  • None –

    self.header and self.banks just get populated

unpack_body(buf, buf_offset=0, use_numpy=False)

Unpack a buffer of bytes into this Event object. You must already have unpacked the event header into self.header.

Parameters:

  • buf (c_char_p) –

    The buffer to read from.

  • buf_offset (int, default: 0 ) –

    Location in the buffer where the overall bank header data starts.

  • use_numpy (bool, default: False ) –

    Whether to use numpy arrays or regular python tuples for bank data.

Returns:

  • None –

    self.banks just gets populated

midas.event.EventHeader

Represents a midas EVENT_HEADER struct.

Attributes:

  • event_id (int) –

    Identifier of which program produced this event

  • trigger_mask (int) –

    Sub-identifier if you need to distinguish events

  • serial_number (int) –

    Increments during the run

  • timestamp (int) –

    UNIX timestamp of event

  • event_data_size_bytes (int) –

    Size of all banks

dump()

Print the content of this event header to screen.

fill_from_bytes(header_data)

Fill this EventHeader object from a set of bytes.

Parameters:

  • header_data (byte array of length 16) –

Returns:

  • None –

    But the attributes of this object just get filled

fill_from_struct_pointer(event_header_p)

Fill this EventHeader object from a C struct. This is a low-level interface that may be needed to handle some of the midas C library interfaces.

Parameters:

  • event_header_p (POINTER(EventHeader)) –

Returns:

  • None –

    The attributes of this object just get filled

is_bor_event()

Whether this is a special event that contains the begin-of-run ODB dump.

Returns:

  • bool –

    If this is a BOR event.

is_eor_event()

Whether this is a special event that contains the end-of-run ODB dump.

Returns:

  • bool –

    If this is an EOR event.

is_midas_internal_event()

Whether this is a special event that contains the ODB dumps or midas messages.

Returns:

  • bool –

    If this is a special event.

is_msg_event()

Whether this is a special event that contains a midas message.

Returns:

  • bool –

    If this is a message event.

pack(buf=None, buf_offset=0)

Pack this header data into a buffer of bytes (creating the buffer if needed). If self.timestamp has not been set yet, we'll set it the current time. All other attributes must be set.

Parameters:

  • buf (c_char_p, default: None ) –

    The buffer to write to. Probably best created using ctypes.create_string_buffer(). If None, we'll create a buffer of the appropriate size.

  • buf_offset (int, default: 0 ) –

    Where in the buffer to start writing this event.

Returns:

  • c_char_p –

    The buffer that was written to