uataq.sites.MobileSite.locate

MobileSite.locate(frames, group=None, time_range=None, lvl='final', num_processes=1)

Merge GPS locations onto instrument data, joining each row on its own clock.

Parameters:

• frames (Mapping[str, DataFrame]) – Data per instrument name, indexed by Time_UTC, as read with group and time_range (e.g. from read_data()).

• group (str | Mapping[str, str] | None) – The group selection the frames were read with. It is used to replay each instrument’s read plan, so it must be the same one.

• time_range (TimeRange | str | tuple[str | datetime | datetime64 | None, str | datetime | datetime64 | None] | list[str | datetime | datetime64 | None] | slice | None) – The time range the frames were read with.

• lvl (str | None) – The GPS data level to read. Default ‘final’; None reads the highest level available.

• num_processes (int | Literal['max']) – Number of processes to use for reading GPS data. Default is 1.

Returns:

The rows that found a location, indexed by Time_UTC (EPSG:4326). GPS_Group names the group whose GPS located each row, and so the clock its Time_UTC is on (lin: GPS time; horel: CR1000).

Return type:

GeoDataFrame

Raises:

• uataq.errors.ReaderError – If no GPS data could be read for any of the rows.

• ValueError – If rows would be located with another group’s GPS.

Notes

A row is joined to the GPS of the group it was read from, since the two share a logger clock: lin instruments and lin’s GPS are stamped by the Pi (joined on Pi_Time), horel’s by the CR1000 (joined on Time_UTC; the instrument and GPS values share one record). The clocks disagree: on TRX01 the CR1000 ran 1-20 s ahead of GPS time on dates sampled 2019-2026, so joining horel rows to lin’s GPS on the Pi clock placed them that many seconds along the track, and dropped rows with no lin GPS record at their second (uataq#42).

The Pi’s clock itself has been hours to days off GPS time (up to 5 days on TRX01 in 2022-11), and a GPS read selects fixes by GPS time, so lin’s GPS is read a week past the rows’ range on each side: the fixes of rows near the ends are then read too (uataq#94). Rows are still selected by the Pi’s clock, so a located row’s Time_UTC (GPS time) can fall outside time_range by as much as the Pi was off.

One group’s rows are never located with another group’s GPS. A GPS group the caller names explicitly (a mapping entry for gps) that differs from the group some rows were read from raises ValueError, as does a group that logs no GPS at this site.