Python Comtrade is a module for Python 3 designed to read Common Format for Transient Data Exchange (COMTRADE) files. These consists of oscillography data recorded during power system outages, control systems tests, validation and tests of field equipment, protective relaying logs, etc. The COMTRADE format is defined by IEEE Standards, summarized in the table below. Some equipment vendors put additional information in proprietary versions of it. This module aims IEEE definitions but may support those proprietary versions.

pip install comtrade

Or just copy comtrade.py from this repository.

The examples below shows how to open both CFG and DAT files or the new CFF file to plot (using pyplot) analog channel oscillography.

Comtrade files separated in CFG and DAT formats can also be read with Comtrade.load. A CFG file path must be passed as an argument and, optionaly, a DAT file path too (if the file name is not equal of the CFG file).

import matplotlib.pyplot as plt
from comtrade import Comtrade

rec = Comtrade()
rec.load("sample_files/sample_ascii.cfg", "sample_files/sample_ascii.dat")
print("Trigger time = {}s".format(rec.trigger_time))

plt.figure()
plt.plot(rec.time, rec.analog[0])
plt.plot(rec.time, rec.analog[1])
plt.legend([rec.analog_channel_ids[0], rec.analog_channel_ids[1]])
plt.show()

It will read the contents of additional header (*.hdr) and information (*.inf) files. Their contents are available through Comtrade.hdr and Comtrade.inf properties.

import matplotlib.pyplot as plt
from comtrade import Comtrade

rec = Comtrade()
rec.load("sample_files/sample_ascii.cff")
print("Trigger time = {}s".format(rec.trigger_time))

plt.figure()
plt.plot(rec.time, rec.analog[0])
plt.plot(rec.time, rec.analog[1])
plt.legend([rec.analog_channel_ids[0], rec.analog_channel_ids[1]])
plt.show()

A Comtrade class must be instantiated and the method load called with the CFF file path.

Comtrade.analog and Comtrade.status lists stores analog and status channel sample lists respectively. These can be accessed through zero-based indexes, i.e., Comtrade.analog[0]. The list Comtrade.time stores each sample time in seconds.

More information can be accessed through Comtrade.cfg object, which stores data such as detailed channel information.

Data of additional sections, such as HDR and INF, can be accessed through hdr and inf properties, respectively.

This module implements some of the functionality described in each of the Standard revisions. The tables below lists some features and file formats and which revision supports it. It also shows whether this module support the feature or the format.

Feel free to pull requests implementing one of these unsupported features or fixing bugs.

• Nanoseconds time base within Python's datetime objects (such as start_timestamp and trigger_timestamp properties). It warns the user but doesn't use it, truncating the numbers.
• Use of multiple sample rates in time calculations for binary data.
• Null fields in ASCII data (blank columns).
• Missing data fields in binary data (0xFFFF...) are treated as any other value.

The use of numpy.array as a data structure to hold time, analog and status data can be enforced in Comtrade object constructor:

obj = Comtrade(use_numpy_arrays=True)

It may improve performance for computations after loading data.

Specify the encoding as a keyword argument on all load methods as you'd specify for common file loading:

rec = Comtrade()
rec.load("sample_files/sample_ascii.cff", encoding="iso-8859-1")

https://github.com/dparrini/python-comtrade

Feel free to report any bugs you find. You are welcome to fork and submit pull requests.

To run tests, use Python's unittest. From a clone of the GitHub repository, run the command:

python -m unittest tests\tests.py

python3 -m unittest ./tests/tests.py

The module is available at GitHub under the MIT license.