CSV format specification

Every tool in this workbench imports the same three table shapes, and ninety percent of import failures trace to a handful of causes: a missing header row, a semicolon where a comma was expected, a renamed velocity column, or decimal commas from a regional Excel locale. This page defines exactly what the importer expects, which column names it recognises from each major InSAR software's exports, and how the diagnostic messages map to fixes. Read it once before your first import; return to it whenever an import fails, because the error messages are written to point back at specific sections here.

The three table shapes

Point-velocity tables feed the LOS Converter, the Hazard Classifier and the GNSS Validation tool's InSAR side: one row per persistent point, with coordinates, a velocity and geometry. Ground observation tables feed the validation tool's GNSS side: one row per benchmark with coordinates and a vertical velocity. Time-series tables feed the Time-series Calculator: one row per point per epoch (the "long format"), with a point identifier, a date and a cumulative displacement. Files are plain text with a header row — mandatory in every case — and the delimiter is detected automatically among comma, semicolon and tab.

Required and recognised columns

The importer matches your header names against a synonym table rather than demanding exact strings, which absorbs most software differences. Matching is case-insensitive and takes the first synonym that appears.

• Point velocity tables. Required: velocity (los_vel, los_velocity, velocity, mean_velocity, vel, v_los, defo), incidence angle (incidence_angle, incidence, look_angle, inc_angle), LOS azimuth (azimuth, los_azimuth, az, heading, track). Recognised: longitude (lon, longitude, lng), latitude (lat, latitude), UTM easting/northing variants, slope, aspect, point identifier (point_id, point, id, name, ps_id).
• Ground observation tables. Required: vertical velocity (vertical_vel_gnss, vertical_velocity, gnss_vel, up_vel), longitude, latitude. Recognised: accuracy (gnss_accuracy, accuracy, sigma), survey date, point identifier.
• Time-series tables. Required: point identifier, date (date, date_end, time, acquisition), displacement (displacement_mm, displacement, cumulative_mm, deformation_mm).

Two conventions are critical and worth fixing in muscle memory. Sign convention: velocity is expected negative away from the satellite (the standard InSAR export behaviour); a column exported with the opposite sign must be flipped before import or every downstream map inverts. Azimuth definition: the tools expect the horizontal azimuth of the ground-to-satellite line of sight; some software reports antenna heading instead, which differs by roughly ninety degrees — check your exporter's documentation rather than guessing.

Common export sources

MintPy. After processing, velocities typically live in the geo_velocity.h5 product; users generally extract a CSV via the bundled viewing utilities or a short script, and the extracted table usually carries longitude, latitude and velocity columns plus geometry if requested. Include the geometry layer in the extraction — without incidence angle and azimuth the LOS Converter cannot run. LiCSBAS. The cumulative displacement and velocity products can be tabulated with the bundle's plotting utilities; the same advice applies — carry geom_inc and the azimuth equivalent into the export. insarmaps. Point exports from the viewer are close to ready: coordinates plus velocity per point; geometry columns may need to be joined from the underlying processing outputs. HyP3 / RTC products. These deliver raster and UNW products rather than point tables; extract point values with your GIS or a script first. GNSS solutions. Most adjustment software exports benchmark tables with identifiers, coordinates and velocities — add an accuracy column if available; it survives the pipeline into the validation report. Because these products evolve with software versions, treat this list as orientation and verify your actual headers — the importer's diagnosis will confirm what it found.

Diagnostics: what each failure means

• "Empty input" — the pasted text contained only blank lines. Copy the rows including the header.
• "No data rows detected below header" — the header was recognised but every subsequent line was filtered out. Usual cause: a trailing block of blank lines or comment lines starting with #.
• "Detected: missing column(s) [los_vel, …]" — the synonym table found no match for a required field. Either rename the column in your export, or check that the value column is truly the LOS velocity and not, say, coherence.
• Numeric columns arriving as text — decimal commas from locale-specific Excel settings. Re-export with the decimal separator set to point, or find-and-replace before pasting.
• Points landing in the wrong hemisphere on the scatter plot — latitude and longitude columns swapped, or lon/lat order reversed in a GeoJSON. The scatter is the fastest detector; fix the source table.
• Wild velocity values (hundreds of mm/yr) — usually a units mismatch (mm vs cm) or a coherence column mistaken for velocity. Check the column's actual range before importing.

Encoding, line endings and the pre-flight checklist

The importer reads UTF-8 text; UTF-8 with BOM also works, but legacy Windows-1252 exports containing special characters can garble header names just enough to break synonym matching — if headers look right but matching fails, check the file encoding. Both Unix and Windows line endings are handled. Before any campaign import, run this sixty-second checklist: open the file in a plain text editor and confirm a single header row, one delimiter style throughout, decimal points not commas, no blank gap rows, and a point identifier column present; then import, and confirm the row count in the tool's summary matches your source table. That last check catches silently dropped rows — the failure mode no one notices until a reviewer counts.

Opening CSVs in spreadsheet software without corrupting them

Most corrupt tables are not born corrupt — they are corrupted by the tool used to inspect them. Spreadsheet applications reformat CSVs silently the moment a file is opened and saved, and three failure modes account for nearly all of the damage. Coordinate precision loss: a longitude such as 116.397128 gets displayed as 116.397 and, on save, the display value can overwrite the stored one, moving points tens of metres; treat any column that lands points a block away from where they belong as a precision casualty. The defence is to never round-trip coordinate columns through a spreadsheet — open the file read-only to inspect, or use a plain text editor. Identifier mangling: long numeric point identifiers convert to scientific notation (2.31E+09), which does not survive a round trip either; quote identifiers or prefix them with a letter when the schema allows. Delimiter and decimal drift: a locale set to decimal-comma will re-save the file with semicolons or commas in the wrong places, breaking the delimiter detection this importer performs on the next open.

The safe pattern when a spreadsheet is genuinely needed for editing — recoding labels, dropping rows, joining columns — is to keep the CSV as the source of truth, do the edit on a copy, and export the copy back to CSV explicitly (choosing UTF-8 and point decimals in the export dialog) rather than saving over the original. Then re-open the result in a text editor and check the first two lines before importing: the header row intact, one delimiter style, decimals as points. Thirty seconds here routinely saves an hour of debugging a table that "worked yesterday".

Recommendations for clean tables

Keep one header row, no merged cells, no footnote rows; export as plain CSV rather than copying formatted sheets that carry invisible formatting characters; keep coordinates in decimal degrees with the point as the sign separator for negatives; and include a point identifier column even when the tools would number rows automatically — identifiers are what make flagged points traceable back to the source dataset in a review. If your workflow produces tables repeatedly, standardise the export script once against this specification; every subsequent campaign then imports without a second thought.

Worked check with the sample dataset

The sample dataset guide documents three files built exactly to this specification: an 87-point LOS velocity table with full geometry, a 12-point GNSS observation table, and a six-point twelve-epoch time series. Import each into its tool and compare what you see against the guide's expected results — the trio doubles as a round-trip test of your understanding of this page. When a real export resists after this page has been consulted, the fastest diagnosis is to open it in a plain text editor and look at the first two lines; almost every failure is visible there.