Skip to content

Commit

Permalink
NPI-3676 update docstrings in sp3.py for consistency, in response to …
Browse files Browse the repository at this point in the history 
…PR comments
  • Loading branch information
@treefern
treefern committed Jan 8, 2025
1 parent a1358e4 commit ee7507a
Showing 1 changed file with 24 additions and 25 deletions.
49 changes: 24 additions & 25 deletions gnssanalysis/gn_io/sp3.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -290,8 +290,7 @@ def read_sp3(
) -> _pd.DataFrame:
"""Reads an SP3 file and returns the data as a pandas DataFrame.
:param str sp3_path: The path to the SP3 file.
:param Union[str, Path, bytes] sp3_path_or_bytes: SP3 file path (as str or Path) or SP3 data as bytes object.
:param bool pOnly: If True, only P* values (positions) are included in the DataFrame. Defaults to True.
:param bool nodata_to_nan: If True, converts 0.000000 (indicating nodata) to NaN in the SP3 POS column
and converts 999999* (indicating nodata) to NaN in the SP3 CLK column. Defaults to True.
Expand All @@ -300,9 +299,9 @@ def read_sp3(
:param bool continue_on_ep_ev_encountered: If True, logs a warning and continues if EV or EP rows are found in
the input SP3. These are currently unsupported by this function and will be ignored. Set to false to
raise a NotImplementedError instead.
:return pandas.DataFrame: The SP3 data as a DataFrame.
:raise FileNotFoundError: If the SP3 file specified by sp3_path_or_bytes does not exist.
:raise Exception: For other errors reading SP3 file/bytes
:return _pd.DataFrame: The SP3 data as a DataFrame.
:raises FileNotFoundError: If the SP3 file specified by sp3_path_or_bytes does not exist.
:raises Exception: For other errors reading SP3 file/bytes
:note: The SP3 file format is a standard format used for representing precise satellite ephemeris and clock data.
This function reads the SP3 file, parses the header information, and extracts the data into a DataFrame.
Expand Down Expand Up @@ -396,7 +395,7 @@ def _reformat_df(sp3_df: _pd.DataFrame) -> _pd.DataFrame:
"""
Reformat the SP3 DataFrame for internal use
:param pandas.DataFrame sp3_df: The DataFrame containing the SP3 data.
:param _pd.DataFrame sp3_df: The DataFrame containing the SP3 data.
:return _pd.DataFrame: reformated SP3 data as a DataFrame.
"""
name_float = [
Expand Down Expand Up @@ -437,7 +436,7 @@ def parse_sp3_header(header: bytes, warn_on_negative_sv_acc_values: bool = True)
Parse the header of an SP3 file and extract relevant information.
:param bytes header: The header of the SP3 file (as a byte string).
:return pandas.Series: A Series containing the parsed information from the SP3 header.
:return _pd.Series: A pandas Series containing the parsed information from the SP3 header.
"""
try:
sp3_heading = _pd.Series(
Expand Down Expand Up @@ -516,8 +515,8 @@ def parse_sp3_header(header: bytes, warn_on_negative_sv_acc_values: bool = True)
def getVelSpline(sp3Df: _pd.DataFrame) -> _pd.DataFrame:
"""Returns the velocity spline of the input dataframe.
:param DataFrame sp3Df: The input dataframe containing position data.
:return DataFrame: The dataframe containing the velocity spline.
:param _pd.DataFrame sp3Df: The input pandas DataFrame containing SP3 position data.
:return _pd.DataFrame: The dataframe containing the velocity spline.
:caution :This function cannot handle *any* NaN / nodata / non-finite position values. By contrast, getVelPoly()
is more forgiving, but accuracy of results, particulary in the presence of NaNs, has not been assessed.
Expand All @@ -538,9 +537,9 @@ def getVelPoly(sp3Df: _pd.DataFrame, deg: int = 35) -> _pd.DataFrame:
"""
Interpolates the positions for -1s and +1s in the sp3_df DataFrame and outputs velocities.
:param DataFrame sp3Df: A pandas DataFrame containing the sp3 data.
:param _pd.DataFrame sp3Df: A pandas DataFrame containing the sp3 data.
:param int deg: Degree of the polynomial fit. Default is 35.
:return DataFrame: A pandas DataFrame with the interpolated velocities added as a new column.
:return _pd.DataFrame: A pandas DataFrame with the interpolated velocities added as a new column.
"""
est = sp3Df.unstack(1).EST[["X", "Y", "Z"]]
Expand Down Expand Up @@ -579,7 +578,7 @@ def gen_sp3_header(sp3_df: _pd.DataFrame) -> str:
"""
Generate the header for an SP3 file based on the given DataFrame.
:param pandas.DataFrame sp3_df: The DataFrame containing the SP3 data.
:param _pd.DataFrame sp3_df: The DataFrame containing the SP3 data.
:return str: The generated SP3 header as a string.
"""
sp3_j2000 = sp3_df.index.levels[0].values
Expand Down Expand Up @@ -649,9 +648,9 @@ def gen_sp3_content(
it otherwise.
Args:
:param pandas.DataFrame sp3_df: The DataFrame containing the SP3 data.
:param _pd.DataFrame sp3_df: The DataFrame containing the SP3 data.
:param bool sort_outputs: Whether to sort the outputs. Defaults to False.
:param io.TextIOBase buf: The buffer to write the SP3 content to. Defaults to None.
:param _io.TextIOBase buf: The buffer to write the SP3 content to. Defaults to None.
:param bool continue_on_unhandled_velocity_data: If (currently unsupported) velocity data exists in the DataFrame,
log a warning and skip velocity data, but write out position data. Set to false to raise an exception instead.
:return str or None: The SP3 content if `buf` is None, otherwise None.
Expand Down Expand Up @@ -849,9 +848,9 @@ def clk_std_formatter(x):


def write_sp3(sp3_df: _pd.DataFrame, path: str) -> None:
"""sp3 writer, dataframe to sp3 file
"""Takes a DataFrame representation of SP3 data, formats and writes it out as an SP3 file at the given path.
:param pandas.DataFrame sp3_df: The DataFrame containing the SP3 data.
:param _pd.DataFrame sp3_df: The DataFrame containing the SP3 data.
:param str path: The path to write the SP3 file to.
"""
content = gen_sp3_header(sp3_df) + gen_sp3_content(sp3_df) + "EOF"
Expand All @@ -863,7 +862,7 @@ def merge_attrs(df_list: List[_pd.DataFrame]) -> _pd.Series:
"""Merges attributes of a list of sp3 dataframes into a single set of attributes.
:param List[pd.DataFrame] df_list: The list of sp3 dataframes.
:return pd.Series: The merged attributes.
:return _pd.Series: The merged attributes.
"""
df = _pd.concat(list(map(lambda obj: obj.attrs["HEADER"], df_list)), axis=1)
mask_mixed = ~_gn_aux.unique_cols(df.loc["HEAD"])
Expand Down Expand Up @@ -901,7 +900,7 @@ def sp3merge(
:param Union[List[str], None] clkpaths: The list of paths to the clk files, or None if no clk files are provided.
:param bool nodata_to_nan: Flag indicating whether to convert nodata values to NaN.
:return pd.DataFrame: The merged sp3 DataFrame.
:return _pd.DataFrame: The merged SP3 DataFrame.
"""
sp3_dfs = [read_sp3(sp3_file, nodata_to_nan=nodata_to_nan) for sp3_file in sp3paths]
# Create a new attrs dictionary to be used for the output DataFrame
Expand All @@ -921,10 +920,10 @@ def sp3_hlm_trans(a: _pd.DataFrame, b: _pd.DataFrame) -> tuple[_pd.DataFrame, li
"""
Rotates sp3_b into sp3_a.
:param DataFrame a: The sp3_a DataFrame.
:param DataFrame b : The sp3_b DataFrame.
:param _pd.DataFrame a: The sp3_a DataFrame.
:param _pd.DataFrame b: The sp3_b DataFrame.
:returntuple[pandas.DataFrame, list]: A tuple containing the updated sp3_b DataFrame and the HLM array with applied computed parameters and residuals.
:return tuple[_pd.DataFrame, list]: A tuple containing the updated sp3_b DataFrame and the HLM array with applied computed parameters and residuals.
"""
hlm = _gn_transform.get_helmert7(pt1=a.EST[["X", "Y", "Z"]].values, pt2=b.EST[["X", "Y", "Z"]].values)
b.iloc[:, :3] = _gn_transform.transform7(xyz_in=b.EST[["X", "Y", "Z"]].values, hlm_params=hlm[0])
Expand All @@ -942,16 +941,16 @@ def diff_sp3_rac(
"""
Computes the difference between the two sp3 files in the radial, along-track and cross-track coordinates.
:param DataFrame sp3_baseline: The baseline sp3 DataFrame.
:param DataFrame sp3_test: The test sp3 DataFrame.
:param string hlm_mode: The mode for HLM transformation. Can be None, "ECF", or "ECI".
:param _pd.DataFrame sp3_baseline: The baseline sp3 DataFrame.
:param _pd.DataFrame sp3_test: The test sp3 DataFrame.
:param str hlm_mode: The mode for HLM transformation. Can be None, "ECF", or "ECI".
:param bool use_cubic_spline: Flag indicating whether to use cubic spline for velocity computation. Caution: cubic
spline interpolation does not tolerate NaN / nodata values. Consider enabling use_offline_sat_removal if
using cubic spline, or alternatively use poly interpolation by setting use_cubic_spline to False.
:param bool use_offline_sat_removal: Flag indicating whether to remove satellites which are offline / have some
nodata position values. Caution: ensure you turn this on if using cubic spline interpolation with data
which may have holes in it (nodata).
:return: The DataFrame containing the difference in RAC coordinates.
:return _pd.DataFrame: The DataFrame containing the difference in RAC coordinates.
"""
hlm_modes = [None, "ECF", "ECI"]
if hlm_mode not in hlm_modes:
Expand Down

0 comments on commit ee7507a

Please sign in to comment.