processTrk234

Processing of NASA Deep Space Network (DSN) tracking data files (TRK-2-34 format).

This module provides tools to read, parse, and convert DSN radiometric tracking data (Doppler, range, and ramp data) from TNF/TRK files into Tudat observation formats.

Classes

Trk234Processor(tnf_file_paths, requested_types)

Processor for TNF files using pytrk234.

converters.Converter()

converters.RadioBase()

converters.DerivedDopplerConverter()

converters.DerivedSraRangeConverter()

converters.RampConverter()

Main Processor

class Trk234Processor(tnf_file_paths: list[str], requested_types: list[str], spacecraft_name: str | None = None)[source]

Bases: object

Processor for TNF files using pytrk234.

For a given set of requested observables types (e.g. [‘doppler’, ‘range’]), this processor iterates file-by-file, uses each converter’s extract method to obtain per-file data, merges the outputs, and then calls each converter’s process method to produce final observation collection. If simulation bodies are provided, ramp data are processed and used to set the stations’ frequency interpolator with the set_tnf_information_in_bodies() method.

Examples

from tudatpy.data import Trk234Processor

# Define TNF file paths
tnf_files = ["mro_kernels/mromagr2012_002_1426xmmmv1.tnf"]

# Create processor for both Doppler and range data
tnf_processor = Trk234Processor(
    tnf_files,
    ["doppler", "range"],
    spacecraft_name="MRO"
)

# Process observations
observations = tnf_processor.process()

# Set frequency information in the bodies assuming you have a bodies object tudatpy.dynamics.environment.SystemOfBodies
tnf_processor.set_tnf_information_in_bodies(bodies)
__init__(tnf_file_paths: list[str], requested_types: list[str], spacecraft_name: str | None = None) → None[source]
Parameters:

  • tnf_file_paths (list[str]) – List of TNF file paths to be processed.

  • requested_types (list[str]) – List of requested radiometric data types, e.g., [‘doppler’, ‘range’]. Note: “ramp” should NOT be included here.

  • spacecraft_name (str, optional) – The spacecraft name for building link definitions.

process() → ObservationCollection[source]

Process all TNF files provided at initialization. For each file, decode the SFDU data, and for each requested radiometric data type, extract data via the converter’s extract method. Ramp data is also extracted separately if a ramp converter is available. Then, merge the per-file outputs and process them to produce the final outputs.

Returns:

An ObservationCollection containing all radiometric observation sets, if none were extracted, an empty collection is returned.

Return type:

ObservationCollection

set_tnf_information_in_bodies(bodies: SystemOfBodies) → None[source]

Update stations in bodies by setting the frequency interpolators from the ramp data. Set the transponder turnaround ratio for the spacecraft.

NOTE: It’s not optimal to set the transponder turnaround ratio here, but it’s done for now

Parameters:

bodies (SystemOfBodies) – The simulation bodies container.

Converters

class Converter[source]

Bases: ABC

abstractmethod extract(sfdu_list: list[SFDU]) → DataFrame[source]

Extract data from a list of SFDU objects and return a pandas DataFrame.

abstractmethod process(merged_df: DataFrame, spacecraftName: str | None = None) → list[SingleObservationSet][source]

Process a merged DataFrame (from multiple files extract outputs) into Tudat structured format. For observable converters, this will be a list of SingleObservationSet objects.

Parameters:

  • merged_df (pandas.DataFrame) – Merged DataFrame containing data from multiple files.

  • spacecraftName (str, optional) – The spacecraft name used for building link definitions, if None the NAIF ID of the spacecraft is extracted from the tracking file.

Returns:

A list of single observation sets.

Return type:

list[SingleObservationSet]

class RadioBase[source]

Bases: Converter

Construct a link ends dictionary for Doppler/Range observation creation.

Parameters:

  • link_end_tuple (tuple) – A tuple containing the uplink, spacecraft, and downlink identifiers.

  • spacecraftName (str, optional) – The name of the spacecraft to use in the simulation. If not provided, the spacecraft name is extracted from the TNF file.

Returns:

A dictionary with link ends constructed according to the following logic: - If the uplink identifier (first element) is “nan”, use the spacecraft as the transmitter and assign the downlink using Earth’s reference point (from the third element). - Otherwise, assign the transmitter using Earth’s reference point from the first element, the reflector as the spacecraft, and the receiver using Earth’s reference point from the third element.

Return type:

dict

from_datetime_UTC_to_TDB(datetime_utc: datetime, station: str) → float[source]

Convert a datetime object in UTC into seconds since J2000 in TDB.

Parameters:

datetime_utc (datetime) – The datetime object to convert.

Returns:

The time in seconds since J2000 in TDB.

Return type:

float

get_band(sfdu: SFDU) → tuple[str, str][source]

Returns the uplink and downlink radio bands for a given SFDU record. The secondary CHDO has to be decoded before calling this function.

Parameters:

sfdu (trk234.SFDU) – The SFDU record to extract the radio bands from.

Returns:

A tuple containing the uplink and downlink radio bands.

Return type:

tuple(str, str)

Returns the uplink, spacecraft, and downlink IDs for a given SFDU record. The secondary CHDO has to be decoded before calling this function.

Parameters:

sfdu (trk234.SFDU) – The SFDU record to extract the link ends from.

Returns:

A tuple containing the uplink, spacecraft, and downlink IDs. If the uplink is unknown or not valid, the uplink entry is a “nan” string.

Return type:

tuple(str, str, str)

get_tracking_mode(sfdu: SFDU) → str[source]

Returns the tracking mode for a given SFDU record. The secondary CHDO has to be decoded before calling this function.

Parameters:

sfdu (trk234.SFDU) – The SFDU record to extract the tracking mode from.

Returns:

The tracking mode of the SFDU record.

Return type:

str

class DerivedDopplerConverter[source]

Bases: RadioBase

extract(sfdu_list: list[SFDU]) → DataFrame[source]

Extract data from a list of SFDU objects and return a pandas DataFrame.

Returns the transmit time tag delay, spacecraft transmit delay, and receive time tag delay for a given SFDU record. The secondary CHDO has to be decoded before calling this function.

Parameters:

sfdu (trk234.SFDU) – The SFDU record to extract the time tag delays from.

Returns:

A tuple containing the transmit time tag delay, spacecraft transmit delay, and receive time tag delay. If the values are not valid or not provided, the function sets the delays to 0.

Return type:

tuple(float, float, float)

process(doppler_df: DataFrame, spacecraftName: str | None = None) → list[SingleObservationSet][source]

Process a merged DataFrame (from multiple files extract outputs) into Tudat structured format. For observable converters, this will be a list of SingleObservationSet objects.

Parameters:

  • merged_df (pandas.DataFrame) – Merged DataFrame containing data from multiple files.

  • spacecraftName (str, optional) – The spacecraft name used for building link definitions, if None the NAIF ID of the spacecraft is extracted from the tracking file.

Returns:

A list of single observation sets.

Return type:

list[SingleObservationSet]

class DerivedSraRangeConverter[source]

Bases: RadioBase

extract(sfdu_list: list[SFDU]) → DataFrame[source]

Extract data from a list of SFDU objects and return a pandas DataFrame.

Returns the transmit time tag delay, spacecraft transmit delay, and receive time tag delay for a given SFDU record. The secondary CHDO has to be decoded before calling this function. If the ruToSeconds parameter is provided,

There are several range calibration and delay fields in the records. The most crucial one is stn_cal, which represents the round-trip measured range calibration for a single pass. If the measured calibration has been split into two parts, it may appear in dl_stn_cal and ul_stn_cal.

stn_cal contains the uplink, downlink, and array_delay calibrations. The array_delay is a delay that applies only to the downlink. If the calibration is split, it will be part of the dl_stn_cal field. The other calibration fields, rcv_timetag_delay and transmit_time_tag_delay, are nominal values and should be disregarded.

Tudat uses range calibrations as time delays. The calibration is divided into rcvr (downlink) and xmtr (uplink) delays, which are set into each measurement.

Since the stn_cal includes the uplink and downlink calibrations (which are identical for two-way data), we can remove the array_delay from stn_cal and divide it by two to obtain the individual leg calibration. Then, we can add the array_delay back into the downlink.

The final step in the calibration is the z-height delays. These are the last leg of the electronics in the antenna and are not included in the calibration electronics. To obtain the final calibration values, we need to add the uplink and downlink z-height delays to each leg.

Parameters:

  • sfdu (trk234.SFDU) – The SFDU record to extract the time tag delays from.

  • ruToSeconds (float, optional) – The conversion factor to convert the station calibration from range unit to seconds. Default is None.

Returns:

A tuple containing the transmit time tag delay, spacecraft transmit delay, and receive time tag delay. If the values are not valid or not provided, the function sets the delays to 0.

Return type:

tuple(float, float, float)

get_zero_phase_times(sfdu: SFDU) → tuple[datetime, datetime][source]

Get the zero phase times from the three way SRA Range.

Parameters:

sfdu (SFDU) – The SFDU object to extract the zero phase times from.

Returns:

A tuple containing the transmit and receive zero phase times.

Return type:

tuple

process(range_df: DataFrame, spacecraftName: str | None = None) → list[SingleObservationSet][source]

Process a merged DataFrame (from multiple files extract outputs) into Tudat structured format. For observable converters, this will be a list of SingleObservationSet objects.

Parameters:

  • merged_df (pandas.DataFrame) – Merged DataFrame containing data from multiple files.

  • spacecraftName (str, optional) – The spacecraft name used for building link definitions, if None the NAIF ID of the spacecraft is extracted from the tracking file.

Returns:

A list of single observation sets.

Return type:

list[SingleObservationSet]

class RampConverter[source]

Bases: object

process(ramp_df: DataFrame) → DataFrame[source]

Concatenate ramp records and merge them per station following these rules:

  1. Each ramp DataFrame has an ‘epoch’ column and a ‘type’ column. A row with type==1 indicates the start of a new ramp; rows with type==4 or type==5 mark ramp end events.

  2. If a ramp has no end time (i.e. a start event is followed by a new start event), update the previous ramp’s end time to the new ramp’s start time.

  3. If a new start event is a continuation of the previous ramp, meaning that its frequency equals the frequency extrapolated from the previous ramp’s (freq, rate) and its rate matches the previous ramp’s rate (within a tolerance), then update the previous ramp’s end time and do not add a new record.

  4. If two ramp intervals (with fully specified end times) overlap, the new ramp takes priority and the previous ramp’s end time is updated to the new ramp’s start time.

Ramp merging is done separately per station. A default tolerance of 1e-6 Hz is used when comparing frequency and rate values, which corresponds to the precision from TNF data.

Parameters:

ramp_df (pandas.DataFrame) – Ramp DataFrame to process. Each DataFrame must have at least the columns: “station”, “epoch” (datetime-like), “type” (int), “freq” (float), “rate” (float).

Returns:

A merged ramp DataFrame with ramp intervals merged per station.

Return type:

pandas.DataFrame