Misc. Submodules

mce_data module

The mce_data (from the MCE wiki) is a low-level interface for reading the MCE binary files. In our case these are files like saturn_191130_0030 with no file extension.

The library has been modified in two important ways: First, it had a hard limit on file size—it would refuse to open files larger than a certain size—which I have exceeded in the past, so I modified it to accept larger files. I also modified it to run on Python 3. Now it also supports reading in the chop data that is embedded in the MCE data files!

exception zeustools.mce_data.BadRunfile(value): Bases: Exception

class zeustools.mce_data.BitField

Bases: object

Describes the truncation and packing of a signal into a carrier word.

define(name, start, count, scale=1.0, signed=True)

extract(data, do_scale=True): Extracts bit field from a numpy array of 32-bit signed integers. Assumes a two’s complement architecture!

class zeustools.mce_data.DataMode

Bases: dict

A DataMode consists of a set of BitFields describing signal packing into MCE data words.

define(*args, **kargs)

class zeustools.mce_data.HeaderFormat

Bases: object

Contains description of MCE header content and structure.

class zeustools.mce_data.MCEData

Bases: object

Container for MCE data (single channel) and associated header and origin information.

chop: numpy.array: Chop signal for the time series, as a 1-d array.

data: numpy.array: the Data member variable contains the mce data as a 3-d datacube.

zeustools.mce_data.MCEFile: alias of SmallMCEFile

class zeustools.mce_data.MCERunfile(filename=None)

Bases: object

Item(block, key, array=True, type='string')

Item2d(block, key_format, array=True, type='string', first=0, count=None)

Item2dRC(block, key_format, array=True, type='string', first=0, count=None, rc_count=4, rc_start=1)

Read(filename)

class zeustools.mce_data.SmallMCEFile(filename=None, runfile=True, basic_info=True)

Bases: object

Facilitate the loading of (single channels from) raw MCE flat-files. Extraction and rescaling of data content is performed automatically by default.

After instantiation with a data filename, a call to Read() will return the detector data as an MCEData object.

See code for ‘Reset’ method for list of useful attributes.

Read(count=None, start=0, dets=None, do_extract=True, do_scale=True, data_mode=None, field=None, fields=None, row_col=False, raw_frames=False, cc_indices=False, n_frames=None)

Read MCE data, and optionally extract the MCE signals.

Parameters

dets – Pass a list of (row,col) tuples of detectors to extract (None=All)
count – Number of samples to read per channel (default=None, which means all of them). Negative numbers are taken relative to the end of the file.
start – Index of first sample to read (default=0).
do_extract – If True, extract signal bit-fields using data_mode from runfile
do_scale – If True, rescale the extracted bit-fields to match a reference data mode.
data_mode – Overrides data_mode from runfile, or can provide data_mode if no runfile is used.
field – A single field to extract. The output data will contain an array containing the extracted field. (If None, the default field is used.)
fields – A list of fields of interest to extract, or ‘all’ to get all fields. This overrides the value of field, and the output data will contain a dictionary with the extracted field data.
row_col – If True, detector data is returned as a 3-D array with indices (row, column, frame).
raw_frames – If True, return a 2d array containing raw data (including header and checksum), with indices (frame, index_in_frame).
cc_indices – If True, count and start are interpreted as readout frame indices and not sample indices. Default is False.

Return data_out

An instance of MCEData containing all your data needs.

ReadRaw(count=None, start=0, raw_frames=False)

Load data as CC output frames. Most users will prefer the Read() method, which decodes the data into detector channels.

Returns a (frames x dets) array of integers.

Reset()

zeustools.mce_data.runfile_break(s)

leapseconds module

The leapseconds (from this GitHub Gist) module provides helper functions for converting between GPS time and UTC time. This can be important because .ts files are written with GPS timestamps.

Get TAI-UTC difference in seconds for a given time using tzdata.

i.e., find the number of seconds that must be added to UTC to compute TAI for any timestamp at or after the given time[1].

>>> from datetime import datetime
>>> import leapseconds
>>> leapseconds.dTAI_UTC_from_utc(datetime(2005, 1, 1))
datetime.timedelta(0, 32)
>>> leapseconds.utc_to_tai(datetime(2015, 7, 1))
datetime.datetime(2015, 7, 1, 0, 0, 36)
>>> leapseconds.tai_to_utc(datetime(2015, 7, 1, 0, 0, 36))
datetime.datetime(2015, 7, 1, 0, 0)
>>> leapseconds.tai_to_utc(datetime(2015, 7, 1, 0, 0, 35)) # leap second
datetime.datetime(2015, 7, 1, 0, 0)
>>> leapseconds.tai_to_utc(datetime(2015, 7, 1, 0, 0, 34))
datetime.datetime(2015, 6, 30, 23, 59, 59)

Python 2.6+, Python 3, Jython, Pypy support.

[1]: https://github.com/eggert/tz/blob/master/leap-seconds.list [2]: https://github.com/eggert/tz/blob/master/tzfile.h [3]: https://github.com/eggert/tz/blob/master/zic.c [4]: http://datacenter.iers.org/eop/-/somos/5Rgv/latest/16

class zeustools.leapseconds.LeapSecond(utc, dTAI_UTC)

Bases: tuple

dTAI_UTC: Alias for field number 1

utc: Alias for field number 0

zeustools.leapseconds.dTAI_UTC_from_tai(tai_time): UTC time = tai_time - dTAI_UTC_from_tai(tai_time).

zeustools.leapseconds.dTAI_UTC_from_utc(utc_time): TAI time = utc_time + dTAI_UTC_from_utc(utc_time).

zeustools.leapseconds.gps_to_tai(gps_time)

Convert GPS time given as datetime object to TAI time.

Parameters: gps_time (datetime) – Datetime object containing GPS time.

zeustools.leapseconds.gps_to_utc(gps_time)

Convert GPS time given as datetime object to UTC time.

Parameters: gps_time (datetime) – Datetime object containing GPS time.

zeustools.leapseconds.leapseconds(tzfiles=['/usr/share/zoneinfo/right/UTC', '/usr/lib/zoneinfo/right/UTC'], use_fallback=False): Extract leap seconds from tzfiles.

zeustools.leapseconds.tai_to_gps(tai_time)

Convert TAI time given as datetime object to GPS time.

Parameters: tai_time (datetime) – Datetime object containing TAI time.

zeustools.leapseconds.tai_to_utc(tai_time)

Convert TAI time given as datetime object to UTC time.

Parameters: tai_time (datetime) – Datetime object containing TAI time.

zeustools.leapseconds.utc_to_gps(utc_time)

Convert UTC time given as datetime object to GPS time.

Parameters: utc_time (datetime) – Datetime object containing UTC time. If this object does not have a timezone, it is treated as if it is in the UTC time zone, which is NOT how naive datetimes are usually treated. Datetimes with timezones are treated appropriately.

zeustools.leapseconds.utc_to_tai(utc_time)

Convert UTC time given as datetime object to TAI time.

Parameters: utc_time (datetime) – Datetime object containing UTC time. If this object does not have a timezone, it is treated as if it is in the UTC time zone, which is NOT how naive datetimes are usually treated. Datetimes with timezones are treated appropriately.