Update docs with info about ILVIS2 data's multiple sets of lat/lon/elev

Author: trey-stafford

docs/altimetry-data-overview.md

@@ -130,6 +130,36 @@ guides or contact NSIDC user services at [email protected]
 
 ```
 
+### ILVIS2 data
+
+ILVIS2 contain multiple sets of latitude/longitude/elevation values.
+
+- `GLAT`/`GLON`/`GZ` represent the center of the lowest mode in the waveform.
+- `HLAT`/`HLON`/`HZ` represent the center of the highest detected mode within
+  the waveform. Both of these sets of lat/lon/elev are available across v1 and
+  v2 ILIVS data.
+
+ILVIS V1 data:
+
+- `CLAT`/`CLON`/`ZC` represent the centroid of the corresponding LVIS Level-1B
+  waveform.
+
+ILVIS V2 data:
+
+- `TLAT`/`TLON`/`ZT`, which represent the highest detected signal.
+
+By default, `iceflow` will use `GLAT`/`GLON`/`GZ` as the primary
+latitude/longitude/elevation fields in `IceflowDataFrame`s. Use the
+`ilvis2_coordinate_set` kwarg on `read_iceflow_datafile(s)` or
+`make_iceflow_parquet` to select an different primary set of
+latitude/longitude/elevation fields. Alternatively, manually set the fields:
+
+```
+# TLAT/TLON/TZ are only available in ILVIS2v2 data:
+sel_ilvis2v2 = data.dataset == "ILVIS2v2"
+data.loc[sel_ilvis2v2, ["latitude", "longitude", "elevation"]] = data.loc[sel_ilvis2v2, ["TLAT", "TLON", "ZT"]]
+```
+
 ## Challenges
 
 The wealth of data from these missions presents an opportunity to study the

docs/getting-started.md

@@ -101,14 +101,15 @@ from nsidc.iceflow import make_iceflow_parquet
 parquet_path = make_iceflow_parquet(
     data_dir=Path("/path/to/data/dir/"),
     target_itrf="ITRF2014",
+    ilvis2_coordinate_set="low_mode",
 )
 df = dd.read_parquet(parquet_path)
 ```
 
 Note that `make_iceflow_parquet` creates a parquet datastore for the data in the
 provided `data_dir` with the data transformed into a common
-[ITRF](https://itrf.ign.fr/) to facilitate analysis. Only datetime, lat, lon,
-and elevation fields are preserved in the parquet datastore.
+[ITRF](https://itrf.ign.fr/) to facilitate analysis. Only datetime, latitude,
+longitude, elevation, and dataset fields are preserved in the parquet datastore.
 
 To access and analyze the full data record in the source files, use
 [`read_iceflow_datafiles`](nsidc.iceflow.read_iceflow_datafiles):
@@ -117,7 +118,10 @@ To access and analyze the full data record in the source files, use
 from nsidc.iceflow import read_iceflow_datafiles
 
 # Read all of the data in the source files - not just lat/lon/elev.
-df = read_iceflow_datafiles(downloaded_files)
+df = read_iceflow_datafiles(
+    downloaded_files,
+    ilvis2_coordinate_set="low_mode",
+)
 
 # Optional: transform lat/lon/elev to common ITRF:
 from nsidc.iceflow import transform_itrf
@@ -130,3 +134,12 @@ df = transform_itrf(
 Note that `read_iceflow_datafiles` reads all of the data from the given
 filepaths. This could be a large amount of data, and could cause your program to
 crash if physical memory limits are exceeded.
+
+#### Special considerations for ILVIS2 data
+
+Users of ILVIS2 data should be aware that ILVIS2 data contains multiple sets of
+lat/lon/elev that may be of interest. By default, the `low_mode` set is used as
+the primary set of latitude/longitude/elevation used by `iceflow`.
+
+See [ILVIS2 data](./altimetry-data-overview.md#ilvis2-data) for more
+information.