es_sfgtools.sonardyne_tools package

es_sfgtools.sonardyne_tools.batch_qc_by_day(dataframes: List[DataFrame], date_column: str = 'pingTime') → Dict[str, DataFrame]

Batch QC dataframes by day.

Parameters:

  • dataframes (List[pd.DataFrame]) – List of QC dataframes to be batched.

  • date_column (str, optional) – Name of the column containing datetime information, by default ‘timestamp’.

Returns:

Dictionary with keys as date strings (YYYY-MM-DD) and values as concatenated dataframes for that day.

Return type:

Dict[str, pd.DataFrame]

es_sfgtools.sonardyne_tools.dfop00_to_SFGDSTFSeafloorAcousticData(source: str | Path, siteData: SFGDTSFSite) → SFGDSTFSeafloorAcousticData | None

Parses a DFOP00-format file and converts it to SFGDSTFSeafloorAcousticData.

The function reads the specified file line by line, expecting each line to be a JSON object representing either an “interrogation” or “range” event. It processes and merges interrogation and range events, transforming them into a unified format suitable for geodetic analysis.

Parameters:

  • source (str | Path) – Path to the DFOP00-format file containing event data.

  • siteData (SFGDTSFSite) – The site data.

Returns:

A SFGDSTFSeafloorAcousticData containing processed and merged event data, or None if no valid data was found or an error occurred during file reading.

Return type:

SFGDSTFSeafloorAcousticData | None

es_sfgtools.sonardyne_tools.dfop00_to_shotdata(source: str | Path) → DataFrame[ShotDataFrame] | None

Parses a DFOP00-format file and converts it into a ShotDataFrame.

The function reads the specified file line by line, expecting each line to be a JSON object representing either an “interrogation” or “range” event. It processes and merges interrogation and range events, transforming them into a unified format suitable for geodetic analysis.

Parameters:

source (str | Path) – Path to the DFOP00-format file containing event data.

Returns:

A ShotDataFrame containing processed and merged event data, or None if no valid data was found or an error occurred during file reading.

Return type:

ShotDataFrame | None

es_sfgtools.sonardyne_tools.merge_interrogation_reply(interrogation: SV3InterrogationData, reply: SV3ReplyData) → dict | None

Merges interrogation and reply data from SV3 devices.

This is merged into a single dictionary. Validates that the sum of pingTime, tt (two-way travel time), tat (turn-around time), and any trigger delay matches the reported returnTime in the reply data. If the calculated return time does not match the reply’s returnTime within a small tolerance, an AssertionError is raised.

Parameters:

  • interrogation (SV3InterrogationData) – The interrogation data object containing pingTime.

  • reply (SV3ReplyData) – The reply data object containing tt, tat, and returnTime.

Returns:

A merged dictionary containing all fields from both interrogation and reply data. Returns None if either input is None.

Return type:

dict | None

Raises:

AssertionError – If the calculated return time does not match the reply’s returnTime.

es_sfgtools.sonardyne_tools.novatelInterrogation_to_garpos_interrogation(novatel_interrogation: NovatelInterrogationEvent) → SV3InterrogationData

Converts a NovatelInterrogationEvent to an SV3InterrogationData object.

This function extracts GNSS and AHRS observation data from the input NovatelInterrogationEvent, transforms geodetic coordinates (latitude, longitude, height above ellipsoid) to ECEF coordinates, and populates an SV3InterrogationData instance with the relevant positional, orientation, and standard deviation values. The ping time is adjusted by subtracting LEAP_SECONDS.

Parameters:

novatel_interrogation (NovatelInterrogationEvent) – The interrogation event containing GNSS and AHRS data.

Returns:

The converted interrogation data with ECEF coordinates and associated metadata.

Return type:

SV3InterrogationData

es_sfgtools.sonardyne_tools.novatelReply_to_garpos_reply(novatel_reply: NovatelRangeEvent) → SV3ReplyData

Converts a NovatelRangeEvent object to an SV3ReplyData object.

This function extracts GNSS and AHRS observation data from the NovatelRangeEvent, converts geodetic coordinates (latitude, longitude, height above ellipsoid) to ECEF coordinates, calculates the travel time, and populates an SV3ReplyData object with the relevant fields.

Parameters:

novatel_reply (NovatelRangeEvent) – The input event containing GNSS, AHRS, and range data.

Returns:

The converted reply data containing transponder ID, orientation, position, standard deviations, range, diagnostics, return time, and travel time.

Return type:

SV3ReplyData

es_sfgtools.sonardyne_tools.qcjson_to_shotdata(source: str | Path) → DataFrame[ShotDataFrame] | None

Convert a QC.pin file into a ShotDataFrame.

Parameters:

source (str | Path) – Path to the QC.pin file in JSON format.

Returns:

  • DataFrame[ShotDataFrame] | None – A validated ShotDataFrame if successful, else None.

  • The QC file is expected to contain a single top-level .pin object with an

  • ”interrogation” entry and one or more range entries (keyed by

  • transponder IDs). This function mirrors the logic of

  • dfop00_to_shotdata by

    • Parsing the interrogation block into SV3InterrogationData

    • Parsing each range block into SV3ReplyData

    • Merging interrogation and range data with merge_interrogation_reply

    • Returning a validated ShotDataFrame.

Submodules