Documentation / generated/octave-operations.md
Core 11629ae · View or edit Markdown on GitHub ↗

Octave operation reference

Generated from the current declarations. Do not edit this file by hand.

Types, limits and defaults below describe resolved values. Runtime expressions must produce these types. Unknown options are rejected; defaults apply only when omitted. Constructor options must be constant after document composition.

Index#

derivative, fft, integral, linearFit, movingMean, readCSV, resample, samples, scale, sequence, wave

derivative#

Estimates dy/dx at every sample with Octave's gradient using the x coordinates, so nonuniform spacing is handled. Interior values are the secant slope between the two neighbours, (y[i+1] - y[i-1]) / (x[i+1] - x[i-1]); the first and last values use the one-sided slope to the adjacent sample. The output keeps x and has units of y per x.

Common mistakes and assumptions:

• Requires strictly increasing x.
• Differentiation amplifies noise; smooth with movingMean or fit with linearFit first for measured data.

Native binding: derivative. Output kind: ["table"].

Options: none.

fft#

Computes the one-sided amplitude spectrum of uniformly sampled real y with Octave's fft: x becomes frequency in cycles per x unit (0 to the Nyquist frequency, n/2 + 1 values) and y the amplitude, scaled so that a sinusoid of amplitude A centred on a frequency bin shows a peak of A. Choose it to identify dominant frequencies in a signal. No window or detrending is applied.

Common mistakes and assumptions:

• Requires 4-8192 samples in a power of two and uniform x spacing; use resample first for irregular data. x becomes frequency; amplitudes double interior bins but not DC or Nyquist.
• Frequencies that fall between bins leak into neighbouring bins with a lower peak; choose the record length to contain whole cycles where possible.
• Phase is discarded; only magnitudes are published.

Native binding: fft. Output kind: ["table"].

Options: none.

integral#

Accumulates the trapezoidal integral of y over x (Octave cumtrapz) and adds a constant initial value, so output y[i] is initial plus the area from the first x to x[i]. Choose it for running totals such as displacement from velocity or energy from power. The output keeps x and has units of y times x.

Common mistakes and assumptions:

• Requires strictly increasing x; the first output equals initial and units are y-unit times x-unit.
• The trapezoidal rule is exact only for piecewise-linear data; coarse sampling of curved signals under- or over-estimates the area.

Native binding: integral. Output kind: ["table"].

linearFit#

Fits the least-squares straight line y = slope * x + intercept to the input (Octave polyfit, degree 1) and outputs the fitted y at each original x. Slope, intercept and residual sum of squares are recorded in the run's native.json evidence, not in the published CSV or statistics.json. Choose it to summarise a linear trend or calibration; use the R adaptor's regression for uncertainty estimates.

Common mistakes and assumptions:

• Requires varying x. Slope, intercept and residual sum of squares are retained in native metadata.
• No standard errors, R squared or outlier handling are produced; inspect the residuals separately if fit quality matters.

Native binding: linearFit. Output kind: ["table"].

Options: none.

movingMean#

Smooths y with a centred moving average over an odd number of neighbouring samples (Octave movmean with Endpoints shrink), keeping x. Choose it to reduce noise before differentiation or plotting; a wider window smooths more but flattens peaks and blurs steps.

Common mistakes and assumptions:

• The window counts samples, not x distance, so irregular spacing gives an uneven smoothing length.
• The window shrinks at endpoints and must not exceed the number of samples.

Native binding: movingMean. Output kind: ["table"].

readCSV#

Reads two named numeric columns from an existing CSV file as the x and y of a table. Schemaxis validates and copies the file into the run, so the analysis and its verification use the captured bytes. Choose it for measurements exported from instruments, spreadsheets or other Schemaxis runs (for example a Calc or Cantera CSV); use samples for a few literal values.

Common mistakes and assumptions:

• Every cell in the file must be a finite number below a header row; missing values, text or dates fail with INVALID_TABLE, even in columns you do not select.
• The file is limited to 8 MiB and 10000 data rows. Units are not read from the file; keep track of them yourself.

Native binding: readCSV. Output kind: ["table"].

Inputs: none.

resample#

Linearly interpolates the input table (Octave interp1, method linear) onto count evenly spaced x values from its first to its last x. Choose it to turn irregular measurements into a uniform grid, for example before fft, or to change the number of samples.

Common mistakes and assumptions:

• Requires strictly increasing x. Interpolation changes the sampling and does not preserve extrema between samples.
• Resampling to fewer points discards detail without low-pass filtering; apply movingMean first if the data are noisy.

Native binding: resample. Output kind: ["table"].

samples#

Creates a table directly from literal x and y vectors typed into the document, with no file involved. Choose it for small measured data sets, test cases with known answers, or calibration points; use readCSV for data already in a file and sequence or wave for generated data. The table passes unchanged to later nodes; any ordering requirement comes from the operation that consumes it.

Common mistakes and assumptions:

• x and y must have the same length (2-10000 values), otherwise planning fails with INVALID_TABLE.
• derivative, integral, resample and fft need strictly increasing x; sort the pairs before entering them.

Native binding: samples. Output kind: ["table"].

Inputs: none.

scale#

Applies a linear transformation y' = factor * y + offset to the input table and leaves x unchanged. Choose it to apply a calibration, change sign, or convert units when you know the conversion factor and offset (for example degrees Celsius to kelvin with factor 1 and offset 273.15).

Common mistakes and assumptions:

• No implicit unit conversion; select factor and offset for the intended physical convention.
• Only y is transformed; to rescale x, there is no operation in this adaptor.

Native binding: scale. Output kind: ["table"].

sequence#

Generates count evenly spaced values from start to stop inclusive with Octave's linspace and uses them as both x and y, giving the identity line y = x. Choose it as a synthetic or calibration input, for example followed by scale to build a known linear relationship; choose wave for an oscillating signal.

Common mistakes and assumptions:

• Both endpoints are included, so the spacing is (stop - start) / (count - 1), not (stop - start) / count.
• A stop below start gives decreasing x, which derivative, integral, resample and fft reject.

Native binding: sequence. Output kind: ["table"].

Inputs: none.

wave#

Generates a sampled sinusoid y = offset + amplitude * sin(2 pi frequency x + phase) (or cos) at x = start, start + step, ... for count samples. Choose it for synthetic test signals, for example to check an fft, movingMean or derivative chain against a known answer. Frequency is in cycles per x unit and phase in radians.

Common mistakes and assumptions:

• Keep frequency below 1 / (2 step) cycles per x unit; faster signals are undersampled and alias to a lower apparent frequency.
• For an fft, choose count as a power of two from 4 to 8192.

Native binding: wave. Output kind: ["table"].

Inputs: none.