spec — Core tools for reading spec data files

The spec module provides an interface to data stored in files created by Certified Scientific’s “spec” program.

Files are opened using the open() function, which returns a read-only dictionary-like interface to the scans contained in the file:

>>> from praxes.io import spec

>>> f = spec.open('spec_file.dat')

Each scan is also a read-only dictionary-like interface to the scalar and vector data.

At the top of the spec hierarchy is the Mapping class, which provides a dictionary interface similar to the dictionaries in python-3. Extending Mapping is SpecFile, which scans the file and creates an index of available scans:

>>> f.keys()
dict_keys(['1'])

>>> scan = f['1']

SpecFile.update() is provided to update the file’s index in the event that data has been appended to the file.

Also extending Mapping is SpecScan, which scans a portion of the file and creates an index of available datasets and metadata:

>>> scan.keys()
dict_keys(['motor1', 'Epoch', 'Seconds', 'counter'])

Ordinary dictionary access of SpecScan yields proxies to the underlying data, which can be indexed to yield in-memory copies of the data:

>>> counter = scan['counter'] # counter is a proxy, no data has been loaded
>>> counter[...]
array([100, 101, 102])
>>> counter[0]
100

SpecScan.data provides another means of accessing the scalar data:

>>> scan.data[:, 0] # return the first column of data
>>> scan.data[3, :] # return the fourth row of data

Note that vector data (keys starting with “@”) is not accessible using this mechanism.

If data has been appended to the file, the existing proxies will reflect this change:

>>> f.update() # or scan.update()
>>> counter[...]
array([100, 101, 102, 103])

Note, however, that the indices for the file and the scans are not completely reconstructed. They are only updated based on the assumption that data has only been appended to the file, and that any existing data in the file has not been modified.

SpecScan stores scan metadata in a read-only dictionary, which can be accessed using the SpecScan.attrs attribute:

>>> scan.attrs.keys()
dict_keys(['command', 'date'])
>>> scan.attrs['command']
'dscan motor1 -1 1 10 1'

Module Interface

praxes.io.spec.open(file_name)

Open file_name and return a read-only dictionary-like interface. If the file cannot be opened, an IOError is raised.

class praxes.io.spec.Mapping

The base class for all spec dictionary-like access to read-only data.

len(d)

Return the number of items in the dictionary d

d[key]

Return the item of d with key key. Raises a KeyError if key is not in d.

key in d

return True if d has a key key, else False.

get(key[, default=None])

Return the value for key, or return default

keys()

Return a new view of the keys.

items()

Return a new view of the (key, value) pairs.

values()

Return a new view of the values.

class praxes.io.spec.SpecFile

A class providing high-level access to scans stored in a “spec” data file. It inherits Mapping.

update()

Updates the file’s index of scans in the file, if necessary. Also updates the indices for the scans in the file.

class praxes.io.spec.SpecScan

A class providing high-level access to datasets associated with a scan in a “spec” data file. It inherits Mapping.

attrs

A Mapping instance containing the metadata for the scan.

data

A proxy providing access to the scan’s scalar data.

update()

Updates the scan’s index of the data in the file, if necessary.