VNA exports to DAT ================== ``mpylab-vna2dat`` converts CSV or Touchstone exports to DAT files. It preserves the measured frequency points and writes ``FUNIT: Hz`` and ``UNIT: dB`` with three polar values per point. It does not resample or access instruments. .. code-block:: console mpylab-vna2dat exports/ --output-dir dat/ --dry-run mpylab-vna2dat exports/ --output-dir dat/ mpylab-vna2dat cable.s2p --parameter S21 --magnitude-error-db 0.2 --phase-error-deg 1 mpylab-vna2dat cable.s2p --parameter all CSV files with one trace keep their basename; multi-trace CSV and Touchstone outputs append the parameter (for example ``cable_S21.dat``). Existing files require ``--overwrite``; symbolic-link destinations are rejected. Outputs are written atomically per file. A failed input does not stop independent files; any failure gives exit status 1, malformed CLI syntax gives 2, success gives 0. The summary counts outputs and failures, not necessarily source files. ``--recursive`` searches subdirectories. An explicit output directory is flat; colliding names are rejected before writing either file. ``--dry-run`` validates content and names without creating directories or files; it does not guarantee that the destination will be writable later. CSV input --------- The recognized header is, for example:: freq[Hz],db:Trc1_S21,ang:Trc1_S21, The matching trace prefix and S-parameter identify a dB/phase pair. Multiple traces require ``--parameter Sij`` or ``--parameter all``. Comments beginning with ``#`` or ``!``, blank lines, UTF-8 BOM, CRLF and trailing separators are accepted. Frequency units are Hz, kHz, MHz and GHz; phase is always degrees. Comma, semicolon and tab separators are detected automatically. The decimal separator is a point. A semicolon separator uses ``--delimiter ';'``. For a different export layout, specify all three columns (one-based) and the frequency unit explicitly:: mpylab-vna2dat export.csv --columns 1,2,3 --frequency-unit MHz --skip-rows 3 Explicit columns select one dB/degree trace; ``--parameter`` optionally labels it. Header inference is then disabled. Invalid selected values, non-finite numbers, negative frequencies, duplicate or decreasing frequencies are errors. No sorting or duplicate averaging is performed. Touchstone input ---------------- Supported: one- and two-port S parameters, ``.s1p``/``.s2p``, RI, MA and DB representations and the standard option-line defaults. A restricted Touchstone 2.0 subset also accepts ``.ts``, full single-ended matrices, both two-port data orders and positive per-port reference resistances. Required 2.0 keywords and the declared frequency count are checked. One-port files default to S11; two-port files require explicit selection. No impedance renormalization occurs. Reference resistances are retained in comments; DAT consumers do not enforce these comments, so their reference system must match the intended application. Unsupported keywords, mixed-mode data, noise records, triangular matrices, more than two ports and wrapped one/two-port records are rejected. Zero magnitudes are rejected because finite dB DAT values cannot represent them; no arbitrary floor is substituted. Very large or small values that overflow or underflow the linear DAT representation are also rejected. The parser follows the `IBIS Touchstone 2.0 specification `_, specifically Option Line, Two-Port Data Order, Reference and Single-Ended Network Parameter Data. Support for the subset above is not a claim of full Touchstone 2.0 support. Sweep and uncertainty --------------------- Constant frequency differences identify linear spacing; constant log-frequency differences identify logarithmic spacing. ``--sweep-rtol`` controls relative spacing tolerance (default 1e-5). Fewer than three points, or a grid satisfying both tests, are ambiguous. Other grids are irregular and remain unchanged. The classification and an INI frequency-interpolation suggestion, where unambiguous, are recorded in comments. These are diagnostics, not automatic channel configuration: the spacing alone does not establish the physically best interpolation model. Zero frequency excludes logarithmic classification. Defaults are a 0.2 dB magnitude half-span and 1 degree phase uncertainty. Both are configurable, finite and nonnegative; phase uncertainty must be less than 180 degrees. DAT uses half the *linearized* magnitude span as a standard uncertainty. This is not an automatic conversion of a manufacturer's tolerance or an expanded uncertainty. Magnitude and phase are independent; no correlation between frequencies or traces is inferred. Zero magnitude uncertainty is supported, with the middle supplied polar value retaining the nominal phase when all three magnitudes coincide. Phase bounds may cross +/-180 degrees. Polar dB contract ----------------- For magnitude ``d`` in dB and transfer phase ``phi``, the existing DAT reader stores ``10**(d/10) * exp(1j*phi)`` as POWERRATIO. This is a power-scaled *transfer representation*, not a complex physical power. To recover the amplitude S-parameter, only the magnitude is square-rooted; phase is retained. Thus ``[-3, 60]`` becomes approximately ``0.707946 * exp(1j*pi/3)`` in AMPLITUDERATIO, not a 30-degree value. :func:`mpylab.tools.ratio_conversion.convert_transfer_ratio` converts both ways between these representations while preserving SCUQ uncertainty dependencies. MGraph now uses this conversion for power-scaled DAT to amplitude ratio; older versions incorrectly halved the transfer phase. Existing scalar power corrections remain unchanged. MGraph's amplitude-to-physical-power conversion continues to use ``abs(S)**2`` and deliberately discards phase. Generic unit relabeling or a complex square root must not replace the explicit conversion. No DAT grammar or existing persisted unit is changed.