Skip to content

PhaseFront

PQ strEEm Exploratory Data Analysis tool

Installation

Use pip to automatically download and install the phasefront package from its hosted location on PyPI.

pip install phasefront

Configuration

Configuration is through a TOML file named phasefront.toml and placed in an accessible location. The software will check the following locations in priority order: 1. Path specified by --config argument 2. Path in PHASEFRONT_CONFIG environment variable 3. ./phasefront.toml (current directory) 4. ~/.config/phasefront.toml 5. /etc/phasefront.toml

If you do not have phasefront.toml file, you can create one in a text editor using the following entries:

[host]
address = "192.168.1.2"
username = "admin"
password = "secret"

Connection

The

with your host credentials. Typically the host is a PQ strEEm gateway but it can be any computer that supports SSH access and hosts PQ strEEM waveform and power monitor files 'wave' and 'pmon' folders respectively.

with SSH acc that possible hosts include but are not limited to PQ strEEm gateways.

Usage

Basic Commands

List remote files:

wave-list --config phasefront.toml '*.parquet'

Download files:

wave-fetch --config phasefront.toml '202411*.parquet'

Create plots:

wave-plot data.parquet

Windows PowerShell Usage

When using patterns on Windows PowerShell, be sure to wrap them in single quotes to prevent glob expansion:

wave-list '*.parquet'
wave-list '20241113_*.parquet'

Remote File Patterns

The wave-list command supports flexible file matching patterns:

# List all Parquet files in a directory
wave-list '*.parquet'
# List files for a specific date
wave-list '20241113_*.parquet'
# List files for a specific hour
wave-list '20241113_12*.parquet'
# List files within a time range
wave-list '20241113_{12,13,14}*.parquet'

The pattern matching uses Python's Path.match() function, which supports: - *: Matches any number of characters except slashes - ?: Matches any single character except slashes - [seq]: Matches any character in seq - [!seq]: Matches any character not in seq - {a,b,c}: Matches any of the comma-separated alternatives

Pipeline Usage

Chain commands together:

wave-list '24111*.parquet' | wave-fetch | wave-plot

Plot Options

Wave Plot Options

Wave Plot supports multiple plot types that can be combined

# All plots (default)
wave-plot data.parquet

# Combine any plot types
wave-plot --wave --vhist data.parquet # Show waveforms and voltage histograms
wave-plot --vhist --ihist data.parquet # Show both histogram types
wave-plot --vderiv --ideriv data.parquet # Show both derivative plots

# Available plot types:
--wave # Voltage and current waveforms
--vhist # Voltage histograms
--ihist # Current histograms
--vderiv # Voltage derivative histograms
--ideriv # Current derivative histograms

# Show metadata for each file
wave-plot --verbose data.parquet

Power Monitoring Plot Options

Power monitoring plots support different metrics that can be combined:

# All plots (default)
pmon-plot data.parquet

# Combine any metrics
pmon-plot --freq --voltage data.parquet # Show frequency and voltage
pmon-plot --current --power data.parquet # Show current and power

# Available metrics:
--freq Frequency over time
--voltage RMS voltage
--current RMS current
--power Active and reactive power

# Show metadata for each file
pmon-plot --verbose data.parquet

Time Slicing

# First 100ms (default for wave plots)
wave-plot data.parquet

# Start at 2.0 seconds, show 500ms
wave-plot --start 2.0 --duration-millis 500 data.parquet

# Show 2 hours of power monitoring data starting at 14:00 UTC
pmon-plot --start 14:00 --duration-hrs 2 data.parquet

File Handling

When downloading files that already exist: - wave-fetch will prompt for action: - [s]kip once: Skip this file - [S]kip all: Skip all existing files - [f]orce once: Overwrite this file - [F]orce all: Overwrite all existing files - Use -f or --force to always overwrite without prompting

Exit Codes

All commands: - 0: Success - 1: Complete failure - 2: Partial success (some files processed)