{
    "command": "sgfieldin",
    "description": "Use INPUT==AUX mappings to compare real numeric input scalars with auxiliary\nscalars or vector samples. Matching retains the first candidate whose summed\nsquared difference is less than 0.001. Use OUTPUT=AUX mappings to import numeric\nscalars, selected numeric/complex vector samples, or complete fixed-width text.\nText is metadata, not a numeric lookup key. The auxiliary dataset must contain\none nonempty group. Without scalar conditions its first column is used; without\nany conditions numeric vector samples are selected by input column index.\n\nEach invocation accepts at most 100 matching conditions (INPUT==AUX) and,\nseparately, 100 import mappings (OUTPUT=AUX). Scalar and vector conditions count\ntogether; all import types share the separate import limit. Unmapped dataset\nfields do not count. These limits do not cap dataset columns or vector samples.\nExceeding either mapping limit is an error, not silent truncation.\n\nA nonnegative flag indicates a match; -1 indicates no match. Unmatched columns\nretain original input fields and leave newly added fields zero/empty, never\nvalues from a prior match. Numeric zeros in unmatched fields are placeholders;\ninspect the flag before analysis. Existing destinations must have exactly the\nimported type and width.",
    "examples": [
        {
            "command": "sgfieldin -aux=auxiliary.sg swath==swath shot==spnb \\\n  shotx=sx shoty=sy firetime=ft_us <input.sg >output.sg",
            "expected": "input.sg must contain scalar swath and shot fields. auxiliary.sg must contain\nscalar swath, spnb, sx, sy and ft_us fields, with its columns in one group.\nFor matching input columns, output.sg retains the original fields and imports\nauxiliary sx, sy and ft_us values into scalar shotx, shoty and firetime fields.\nCheck flag >= 0 before using imported measurements. Names are illustrative.",
            "title": "Import shot coordinates and fire time for matching swath and shot values"
        },
        {
            "command": "sgfieldin -aux=labels.sg id==id label=name <input.sg >output.sg",
            "expected": "Both datasets must contain a real numeric scalar id. Auxiliary name is a\nfixed-width text field; output label preserves its complete type and width.\nNo string matching or character-by-character sample lookup is performed.",
            "title": "Attach fixed-width sample labels using a numeric sample ID"
        }
    ],
    "input_description": "input dataset; numeric matching conditions require scalar input fields",
    "notes": [],
    "output_description": "output dataset retaining original input fields, with imported numeric/complex\nscalar values, complete fixed-width text and the match-status field",
    "package": "sigclear-soig",
    "parameters": [
        {
            "choices": [],
            "default": "stdin",
            "default_known": false,
            "description": "input dataset; numeric matching conditions require scalar input fields",
            "name": "in",
            "required": false,
            "type": "ifile",
            "units": null
        },
        {
            "choices": [],
            "default": null,
            "default_known": false,
            "description": "auxiliary dataset: exactly one nonempty group; numeric keys and values or fixed-width text metadata",
            "name": "-aux",
            "required": true,
            "type": "ifile",
            "units": null
        },
        {
            "choices": [],
            "default": "flag",
            "default_known": true,
            "description": "match status field:\n-1: no complete match; new fields are zero/empty, not valid measurements\nvector conditions: zero-based matched sample index\nscalar-only conditions: zero on success\nno conditions: zero-based input column index",
            "name": "-flag",
            "required": false,
            "type": "str",
            "units": null
        },
        {
            "choices": [],
            "default": "stdout",
            "default_known": false,
            "description": "output dataset retaining original input fields, with imported numeric/complex\nscalar values, complete fixed-width text and the match-status field",
            "name": "out",
            "required": false,
            "type": "ofile",
            "units": null
        }
    ],
    "related": [],
    "schema_version": 1,
    "summary": "Import auxiliary fields using numeric matching conditions",
    "synopsis": "sgfieldin <stdin -aux= -flag=\"flag\" >stdout",
    "version": "1.2.2"
}