.. _cookbook: ============================= `geodezyx`'s Cookbook ============================= ------------ Convert time ------------ The `geodezyx` toolbox can handle a lot of time **scales** and time **representations**. What we call `scale` is a physical definition: UTC, GPS Time, TAI... What we call `representation` is the way the physical value is represented : Julian date, year/day of year, GPS week/day of week, ISO string... The basic idea behind it is the conversion to and from the ``datetime`` objects of the Python's ``datetime`` module. The generic structure of the fuctions is ``conv.2``. Time conversion exemples ~~~~~~~~~~~~~~~~~~~~~~~~ First of all: :: import geodezyx.conv as conv # Import the conversion module import datetime as dt Get today as GPS Time (week/day of week) """""""""""""""""""""""""""""""""""""""" :: now = dt.datetime.now() ### datetime.datetime(2021, 6, 18, 15, 53, 56, 245345) gpstime = conv.dt2gpstime(now) gpstime Out: (2162, 5) Convert year/day of year to Modified Julian Day """"""""""""""""""""""""""""""""""""""""""""""" :: year,doy = (2021, 169) epoch = conv.doy(year, doy) mjd = conv.dt2MJD(epoch) mjd Out: 59383.0 Convert a SP3 name to decimal year """""""""""""""""""""""""""""""""" :: p = "/home/user/igs20726.sp3" epoch = conv.sp3name2dt(p) yeardec = conv.dt2year_decimal(epoch) yeardec Out: 2019.739611872146 It handles also RINEX names with ``conv.rinexname2dt(p_rinex)`` (old and new naming) (Documentation here: :py:func:`geodezyx.conv.conv_time.rinexname2dt`) Complete reference ~~~~~~~~~~~~~~~~~~ All the module's functionalites can be found here: :py:mod:`geodezyx.conv.conv_time` ------------------- Convert coordinates ------------------- The `geodezyx` toolbox can easily handle coordinate conversion in Geocentric (X,Y,Z), Geographic (latitude, longitude, height) and topocentric (East, North, Up). **Warning**: This is considered as the "low-level" coordinate conversions. It does not deal with the different Reference Frame and their realisations (ITRFxx, ETRFxx...). This is managed by "high-level" functions in the ``reffram`` module. These functions are optimized for arrays (multiple inputs) but can also handle scalars. Coordinates conversion exemples ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We consider as exemple the coordinates of the Helmertturm given in latitude, longitude, height from Wikipedia and the GNSS station POTS in Geocentric XYZ. :: Helmertturm = np.array([52.380278, 13.065278,147.983]) POTS = np.array([3800689.6341,882077.3857,5028791.3179 ]) We can bring POTS in Geographic and the Helmertturm in Geocentric coordinates :: POTS_geo = conv.XYZ2GEO(POTS[0],POTS[1],POTS[2]) POTS_geo = conv.XYZ2GEO(*POTS) POTS_geo Out: (52.37929737808202, 13.066091316954145, 144.41769897658378) :: Helmertturm_xyz = conv.GEO2XYZ(Helmertturm[0], Helmertturm[1], Helmertturm[2]) Helmertturm_xyz = conv.GEO2XYZ(*Helmertturm) Helmertturm_xyz Out: (89.92804903383008, 14.005569048843014, -6356604.297220887) We can also get the vector between POTS and the Helmertturm (i.e. the Helmertturm in the Topocentric frame centered on POTS) :: conv.XYZ2ENU_2(Helmertturm[0], Helmertturm[1], Helmertturm[2], POTS[0],POTS[1],POTS[2]) Out: (array([0.88515353]), array([20735.55848087]), array([-6364723.46820732])) Complete reference ~~~~~~~~~~~~~~~~~~ All the module's functionalites can be found here: :py:mod:`geodezyx.conv.conv_coords` ----------------------- Helmert Transformations ----------------------- Apply and estimate parameters for an ad-hoc Helmert Transformation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The functions :py:func:`geodezyx.reffram.geometry.helmert_trans_estim` and :py:func:`geodezyx.reffram.geometry.helmert_trans_apply` and offer an interface to estimate parameters and apply an Helmert transformation respectively. Transform coordinates between two ITRF/ETRF ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The functions :py:func:`geodezyx.reffram.geometry.itrf_helmert_get_parameters` and :py:func:`geodezyx.reffram.geometry.itrf_helmert_trans` offer an interface to get the transformation parameters between two ITREF/ETRF realization, and apply the corresponding Helmert transformation respectively. Complete reference ~~~~~~~~~~~~~~~~~~ All the module's functionalites can be found here: :py:mod:`geodezyx.reffram.geometry` ------------------------ Euler pole determination ------------------------ The toolbox proposes tools to manipulate Euler rotation poles: - to determine the tectonic plate's Euler pole based on some GNSS absolute velocities (:py:func:`geodezyx.geodyn.euler_pole_calc.euler_pole_calc`). - to analyze the quality of the Euler Pole estimation (:py:func:`geodezyx.geodyn.euler_pole_calc.euler_pole_quality`). - to convert the estimated Euler pole in a vector form to a latitude/longitude/rate form (:py:func:`geodezyx.geodyn.euler_pole_calc.euler_pole_vector_to_latlongrate`), and also do the reverse conversion (:py:func:`geodezyx.geodyn.euler_pole_calc.euler_pole_vector_from_latlongrate`). - to substract the plate's velocity to analyze the residual velocities of the stations (located at the plate's boundary for instance) (:py:func:`geodezyx.geodyn.euler_pole_calc.euler_vels_relative_to_ref`). Complete reference ~~~~~~~~~~~~~~~~~~ All the module's functionalites can be found here: :py:mod:`geodezyx.geodyn.euler_pole_calc` --------------------------------- Read and import geodetic products --------------------------------- Main import functionalities ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The toolbox mainly handles: - The GNSS products such as clock offsets (.clk files) and orbits (.sp3 files): :py:mod:`geodezyx.files_rw.read_gnss_prods` - The Earth orientation parameters: :py:mod:`geodezyx.files_rw.read_gnss_prods` - The Troposphere files: :py:mod:`geodezyx.files_rw.read_athmo` Complete reference ~~~~~~~~~~~~~~~~~~ All the module's functionalites can be found here: :py:mod:`geodezyx.files_rw` ------------------------------------ Read and import geodetic time series ------------------------------------ The toolbox is designed to import and pre-process a wide range of geodetic GNSS Time Series. Read the dedicated Jupyter notebook stored in ``<...>/geodezyx/000_exemples/timeseries_reader`` Complete reference ~~~~~~~~~~~~~~~~~~ All the module's functionalites can be found here: :py:mod:`geodezyx.files_rw.read_coords_time_series` ----------------------------- Read and import GNSS Sitelogs ----------------------------- You can easily import the content of the IGS's GNSS Sitelogs (a.k.a Logsheets) in dedicated objects Read the dedicated Jupyter notebook stored in ``<...>/geodezyx/000_exemples/logsheets_reader`` ------------------------------------------ Point and Click to detect offsets manually ------------------------------------------ The toolbox contains a tool to select manually the jumps in the Geodetic Time Series. Based on `matplotlib`, you can "point and click" the discontinuities you detected visually with your mouse. Plot first your data (in a theoretical DataFrame DF) :: fig,(axn,axe,axu) = plt.subplots(3,1) axn.plot(DF["t"],DF["n"]) axe.plot(DF["t"],DF["e"]) axu.plot(DF["t"],DF["u"]) Then, create the Point and Click object :: PnC = gcls.point_n_click_plot() multi , cid = PnC(fig=fig) The selected jumps/offsets are stored in a list attribute of the Point and Click object :: PnC.selectedX Read the dedicated script stored in ``<...>/geodezyx/000_exemples/logsheets_reader``. More details in the class documentation : :py:class:`geodezyx.time_series.ts_class.point_n_click_plot` ---------------------------------------------------- Statistics and plots for orbit and clock comparisons ---------------------------------------------------- TBC