API Reference¶

The main class for the pycev package is Cev (also aliased to CEV). This class can be used to interpret SEL CEV files, and provides access to the various informational data-points for the event record.

class pycev.Cev(file: Optional[str] = None, data: Optional[Union[str, bytes]] = None, **kwargs)[source]¶

SEL CEV File Reader.

This class serves to provide functionality to read SEL (Schweitzer Engineering Laboratories) Compressed EVent records (CEV files) and grant pragmatic access to the key components of these records. The methods, attributes, and properties of this class serve to expose data in a manner that supports scientific analysis and allow common data-science tools such as NumPy, Matplotlib, Pandas, and others to conveniently interpret information. This all is in an effort to support data scientists and engineers to make empowered, intelligent decisions about the power systems which they are responsible for.

Within this module, this class (Cev) is also aliased as CEV for programming convenience, and to allow users to access the functionality in a format that is consistent with their work.

Parameters:

file (str, optional) – String describing the relative or fully qualified path to the CEV file that should be read. Optionally used during class initialization, may also be loaded using the load method.
data (str, optional) – String describing all contents of the CEV file as read. Optionally used during class initialization to pre-load the contents of the CEV file.
**kwargs (dict, optional) –
Additional optional parameters which may be specified during class initialization. Common arguments include:
- encoding: str, file encoding such as ‘utf-8’
- decode_opt: str, file decoding option such as
  ’strict’, ‘ignore’, ‘replace’, or ‘backslashreplace’ as defined by standard str.decode method.
- ignore_warnings: bool, control to ignore warnings
Class initialization may include one or more kwargs, but none are required.

analog_channels¶

List of lists containing the analog samples for each channel.

Type:: list of list of float

analog_channel_ids¶

List of the analog channel names whose index values correspond directly to the channel datasets in analog_channels.

Type:: list of str

analog_count¶

Number of analog channels present in CEV.

Type:: int

channels_count¶

Total number of analog and digital (status) channels in CEV.

Type:: int

data¶

Full string context of the entire CEV record; includes both the event information and relay settings that were included with the record.

Type:: str

digital_channels¶

List of lists containing boolean states for each digital (status) channel present in CEV. This list presents itself as an alias to the status_channels class attribute.

Type:: list of list of bool

digital_channel_ids¶

List of the digital (status) channel names whose index values correspond directly to the channel datasets in digital_channels. This list presents itself as an alias to the status_channel_ids class attribute.

Type:: list of str

digital_count¶

Number of digital channels present in the CEV.

Type:: int

fid¶

Relay firmware identification string; does not include the ‘FID=’ specifier.

Type:: str

frequency¶

The recorded nominal frequency present in the CEV.

Type:: float

raw_fid¶

“Raw” relay firmware identification string; includes the ‘FID=’ specifier to lead the string.

Type:: str

record¶

Event record data-sub-section contents; contains only the event-related data and heading fields of the CEV that was loaded.

Type:: str

record_lines¶

Row-wise split contents of the record with all newline and carriage-return characters removed.

Type:: list of str

settings¶

Relay settings data-sub-section contents; contains only the relay settings portion of the CEV that was loaded.

Type:: str

status_channels¶

List of lists containing boolean states for each status (digital) channel present in CEV. This list is aliased to the digital_channels class attribute.

Type:: list of list of bool

status_channel_ids¶

List of the status (digital) channel names whose index values correspond directly to the channel datasets in status_channels. This list is aliased to the digital_channel_ids class attribute.

Type:: list of str

status_count¶

Number of status channels present in the CEV.

Type:: int

trigger_time¶

Date-time structure indicating when the event was “triggered” by protection logic in the relay.

Type:: datetime

Examples

>>> from pycev import CEV
>>> # Load a file and parse, directly.
>>> record = CEV(file="./event-report.cev")
>>> print("Trigger time = {}s".format(record.trigger_time))

Methods

`get_analog`(channel_name)	Extract an analog channel by name.
`get_digital`(channel_name)	Extract an digital channel by name.
`get_status`(channel_name)	Extract an digital channel by name.
`load`(file[, encoding])	CEV File Loader Method.
`load_data`(data[, encoding])	CEV Data Loader Method.

get_analog(channel_name: str)[source]¶

Extract an analog channel by name.

Use this method to return the list of analog values associated with the particular analog channel with the specified name.

Parameters:: channel_name (str) – Name of the analog channel which should be extracted.
Returns:: channel – The analog channel values in a zero-based list.
Return type:: list of float

See also

get_status: Collect the digital channel status for a specified name.
get_digital: Collect the digital channel status for a specified name.

Examples

>>> from pycev import CEV
>>> # Load a file and parse, directly.
>>> record = CEV() # Create the parser instance
>>> record.load(file="./event-report.cev")
>>> record.get_analog("FREQ")
[...]

get_digital(channel_name: str)¶

Extract an digital channel by name.

Use this method to return the list of digital values associated with the particular digital channel with the specified name.

Parameters:: channel_name (str) – Name of the digital channel which should be extracted.
Returns:: channel – The digital channel values in a zero-based list.
Return type:: list of bool

See also

get_analog: Collect the analog channel status for a specified name.
get_status: Collect the digital channel status for a specified name.
get_digital: Collect the digital channel status for a specified name.

Examples

>>> from pycev import CEV
>>> # Load a file and parse, directly.
>>> record = CEV() # Create the parser instance
>>> record.load(file="./event-report.cev")
>>> record.get_status("TRIPLED")
[...]
>>> record.get_digital("TRIPLED")
[...]

get_status(channel_name: str)[source]¶

Extract an digital channel by name.

Use this method to return the list of digital values associated with the particular digital channel with the specified name.

Parameters:: channel_name (str) – Name of the digital channel which should be extracted.
Returns:: channel – The digital channel values in a zero-based list.
Return type:: list of bool

See also

get_analog: Collect the analog channel status for a specified name.
get_status: Collect the digital channel status for a specified name.
get_digital: Collect the digital channel status for a specified name.

Examples

>>> from pycev import CEV
>>> # Load a file and parse, directly.
>>> record = CEV() # Create the parser instance
>>> record.load(file="./event-report.cev")
>>> record.get_status("TRIPLED")
[...]
>>> record.get_digital("TRIPLED")
[...]

load(file: str, encoding: Optional[str] = None)[source]¶

CEV File Loader Method.

Use this method to load a CEV file, and parse its contents into the valuable class attributes and structure.

Parameters:

file (str) – String describing the relative or fully qualified path to the CEV file that should be read. Optionally used during class initialization, may also be loaded using the load method.
encoding (str, optional) – String specifying the encoding format (if required) in which the file is stored. This may be used for files of format ‘utf-8’, for example.

See also

load_data: Load data which has already been read from a file, or is presented as a stream.

Raises:

FileNotFoundError – If the file cannot be located on the system
MalformedHeadingDataMismatch – If the file contains a header and content row pair which do not share an equal number of columns.

Warns:

UnexpectedFileExtension – If the uppercase-cast file extension is not “.CEV”
MalformedChecksumFailure – If any of the CEV line-wise checksums do not evaluate successfully

Examples

>>> from pycev import CEV
>>> # Load a file and parse, directly.
>>> record = CEV() # Create the parser instance
>>> record.load(file="./event-report.cev")
>>> print("Trigger time = {}s".format(record.trigger_time))

load_data(data: Union[str, bytes], encoding: Optional[str] = None)[source]¶

CEV Data Loader Method.

Use this method to load the data from a CEV file which has already been read, or data which is being streamed to the class (i.e., an active connection to a relay). This method will parse the data and load the class attributes and structures appropriately.

Parameters:

data ([str, bytes]) – String of the full file content.
encoding (str, optional) – String specifying the encoding format (if required) in which the file is stored. This may be used for files of format ‘utf-8’, for example.

See also

load: Load data from a CEV file.

Raises:: MalformedHeadingDataMismatch – If the file contains a header and content row pair which do not share an equal number of columns.
Warns:: MalformedChecksumFailure – If any of the CEV line-wise checksums do not evaluate successfully

Examples

>>> from pycev import CEV
>>> # Load a file and parse, directly.
>>> record = CEV() # Create the parser instance
>>> with open("./event-report.cev", 'r') as file:
...     data = file.read()
>>> record.load_data(data=data)
>>> print("Trigger time = {}s".format(record.trigger_time))

Additional Package Functions¶

pycev.row_wise_checksum(row_data, constrain=True)[source]¶

Identify the data and validate it with included checksum.

Events should contain rows of data, where each row appears as:

“some,data,in,the,event”,”checksum”

Knowing this format, this function will separate the data from the checksum, and use the checksum to evaluate the validity of the data. The resulting data will be returned as a namedtuple as: Row(‘data’:str, ‘validity’:bool)

Parameters:: row_data (str) – The string containing all row data in form described above.
Returns:: row – The namedtuple containing the separated data and validity marker in the form of: Row(‘data’:str, ‘validity’:bool)
Return type:: namedtuple

pycev.split_event_and_relay_data(data)[source]¶

Split the Event Data from Relay Settings.

This function accepts the full text from a CEV file, and separates the event-record data from the relay’s configuration settings. These two separated items are returned as a named-tuple which is formed as: EventData(‘record’:str, ‘settings’:str)

Parameters:: data (str) – The string containing all data read from the CEV file.
Returns:: event – The namedtuple containing the ‘record’ and ‘settings’ information, each being the so-described elements from the event record which have been read. namedtuple is of the form: EventData(‘record’:str, ‘settings’:str) where ‘record’ is the event information, and ‘settings’ is the relay’s configuration settings.
Return type:: namedtuple