# mpypost

This tool provides various statistical and mathematical operations for analyzing
time-series and spatial data from simulations, including averaging, standard
deviation, extrema finding, gradient calculation, and Fourier transforms.

Supported operations:

- Weighted average (avg)
- Standard deviation (std)
- Minimum and maximum (minmax)
- Gradient calculation (grad)
- Fast Fourier Transform (fft)
- Zig-zag Detection (zigzag)

## Usage

```bash
mpypost <function> [options] file
```

## Functions

### avg - Weighted Average

Calculate weighted average over time or space.

```bash
mpypost avg [options] file
```

**Options:**

- `--output FILE` - Output file name
- `--coordinate NAME` - Base coordinate name (default: Time, x, y, z,
  distance, col1)
- `--starttime TIME` - Start averaging from this time (default: 0)

**Example:**

```bash
mpypost avg --coordinate Time --starttime 5.0 probe_data.csv
```

### std - Standard Deviation

Calculate weighted standard deviation.

```bash
mpypost std [options] file
```

**Options:**

- `--output FILE` - Output file name
- `--coordinate NAME` - Base coordinate name
- `--starttime TIME` - Start calculation from this time (default: 0)

**Example:**

```bash
mpypost std --coordinate Time --starttime 10.0 velocity.csv
```

### minmax - Extrema

Find minimum and maximum values in data series.

```bash
mpypost minmax [options] file
```

**Options:**

- `--output FILE` - Output file name
- `--coordinate NAME` - Base coordinate name
- `--starttime TIME` - Start searching from this time (default: 0)

**Example:**

```bash
mpypost minmax --coordinate distance pressure_distribution.csv
```

### grad - Gradient Calculation

Calculate gradient using numpy.gradient.

```bash
mpypost grad [options] file
```

**Options:**

- `--output FILE` - Output file name
- `--coordinate NAME` - Coordinate name(s), can be used multiple times

**Example:**

```bash
mpypost grad --coordinate x --coordinate y temperature.csv
```

### fft - Fast Fourier Transform

Perform Fourier transform on time-series data.

```bash
mpypost fft [options] file
```

**Options:**

- `--output FILE` - Output file name
- `--coordinate NAME` - Base coordinate name (typically Time)
- `--periodic` - Data is periodic (skips detrending and windowing)

**Example:**

```bash
mpypost fft --coordinate Time signal.csv
```

### zigzag - Zig-Zag (Oscillation) Detection

Detect zig-zag (oscillatory) behavior in a data series by analyzing consecutive
direction changes and their oscillation amplitude.

A zig-zag is defined as alternating increases and decreases in the selected
signal. Only intervals with a minimum number of direction changes and a minimum
oscillation amplitude (relative to the signal range) are considered significant.

```bash
mpypost zigzag [options] file
```

**Options:**

- `--output FILE` - Output file name
- `--coordinate NAME` - Name of the signal to analyze (e.g. Time, x, y, z)
- `--min-changes N` - Minimum number of direction changes to detect a zigzag
  (default: 5)
- `--min-fraction F` - Minimum oscillation amplitude as a fraction of the global
  signal range (default: 0.1)

**Output:**

The output file contains a single-row table with the following columns:

- `IsZigzag` - 1 if zig-zag behavior is detected, otherwise 0
- `NumChanges` - Total number of detected direction changes
- `MaxConsecutive` - Maximum number of consecutive direction changes
- `IntervalDiffs_1`, `IntervalDiffs_2`, etc. - Oscillation amplitudes of
  significant zig-zag intervals

Additional diagnostic information (e.g. indices of direction changes and input
parameters) is stored in the file metadata.

**Example:**

```bash
mpypost zigzag --coordinate Pressure --min-changes 6 --min-fraction 0.2 p.csv
```