example as python script

examples/mosaic-floenavi-example.py

+# To add a new cell, type '# %%'
+# To add a new markdown cell, type '# %% [markdown]'
+# %% [markdown]
+# # Ice Drift Correction with MOSAiC FloeNavi
+# 
+# This example illustrated steps to convert GPS positions from MOSAiC field data into (x, y) coordinates of the floe grid. The translation and rotation correction of the drifting ice floe during MOSAiC is based on the so-called _master solution_ of the MOSAiC floe navi grid. 
+# 
+# The master solution is defined by the geographical position of the origin, the true heading of the x-axis of the grid, as well the the uncertainties as a function of time. The master solution is synthesized by evaluating AIS base station locations distributed inside the MOSAiC central observatory.
+# 
+# ---
+# **NOTES**
+# 
+# 1. At the moment the FloeNavi grid is supported from Oct 16, 2019 through May 10, 2020. 
+# 2. FloeNavi master solutions are provided as one file per leg
+# 3. Occasional periods are not covered due to gaps in input AIS base station data or strong ice movement. 
+# 4. An integration of this functionality on the MCS workspace is under investigation
+# 
+# ---
+# 
+# ## Requirements
+# 
+# 1. python 3.x
+# 2. `icedrift` module (https://gitlab.awi.de/floenavi-crs/icedrift). See [readme](https://gitlab.awi.de/floenavi-crs/icedrift/-/blob/master/README.md) for how to install `icedrift`. 
+# 3. floenavi master solution (*.csv in https://gitlab.awi.de/floenavi-crs/floenavi/-/tree/master/data%2Fmaster-solution, one solution per MOSAiC leg)
+# 4. the current implementation of the icedrift module assumes GPS tracks. A specific solution for swath data is yet to be developed.
+# 
+# 
+# ## Feedback and Issue Reporting
+# 
+# The preferred for any issues found with either the software or the data are filing an issue in the gitlab webpage (repositories are public, but registering may be necessary for entering an issue). Alternatively an issue report can be send to [Stefan Hendricks](mailto:Stefan.Hendricks@awi.de).
+# 
+# ### Software issues
+# 
+# Bugs in the `icedrift` module should be reported in the [issue tracker](https://gitlab.awi.de/floenavi-crs/icedrift/-/issues) of the `icedrift` package. Please add the following information whenever possible: 
+# 
+# 1. detailed description of the issue
+# 2. steps to reproduce
+# 3. full traceback in case of an software exception 
+# 
+# ### Data issues 
+# 
+# Issues with quality of the floenavi master solution should be reported in in the [issue tracker](https://gitlab.awi.de/floenavi-crs/floenave/-/issues) of this project. Please provide the following information
+# 
+# 1. detailed description of the issue
+# 2. steps to reproduce
+# 
+# 
+# ## Example
+# 
+# The following example illustrates the workflow, which can be broken down in four steps: 
+# 
+# 1. Creating an icedrift reference station with the floenavi master solution data
+# 2. Creating an ice coordinate system with the reference station
+# 3. Ingesting external GPS data into an icedrift compatible data class
+# 4. Coordinate transformation from (time, lon, lat) to (x, y) for the external GPS data
+# 
+# This specific data shows the transect tracks from MOSAiC leg 1.
+# 
+# 
+# ### Preparations
+# 
+# 
+# 
+# 
+
+# %%
+import sys
+# Allow to find icedrift 
+# NOTE: this only works if `floenavi` (this module) and `icedrift` are cloned to the same directory
+sys.path.append('../../icedrift/')
+
+
+# %%
+from icedrift import GeoReferenceStation, IceCoordinateSystem, GeoPositionData
+
+# %% [markdown]
+# ### Create reference station object
+# 
+# The reference station is defined either by one geographic position plus the true heading of the x-axis, or by two positions with the true heading between both station defining the true heading of the x-axis. The floenavi master solution provided data for the first option in a file format that can be directly used to initialize the data class. 
+
+# %%
+refstat_csv_file = r"../data/master-solution/mosiac-leg1-20191016-20191213-floenavi-refstat-v1p0.csv"
+refstat = GeoReferenceStation.from_csv(refstat_csv_file)
+
+# %% [markdown]
+# ### Create ice coordinate system object
+# 
+# The reference station is used to establish the ice coordinate system. This object can then be used to transform external GPS data with in the time coverage of the reference station. 
+
+# %%
+icecs = IceCoordinateSystem(refstat)
+
+# %% [markdown]
+# ### Creating GPS position object
+# 
+# The ice coordinates system only accepts certain data classes of the `icedrift` module as input for the transformation. These can be constructed based on the inputs:
+# 
+# 1. time (datetime)
+# 2. longitude
+# 3. latitude
+# 
+# A standardized csv format has been defined for position data, so the corresponding class can be created in a similar way to the reference station:
+
+# %%
+track_csv_filepath = r"../data/rover/transect-examples/mosaic-transect-20191031-gem2-556-track.csv"
+pos = GeoPositionData.from_csv(track_csv_filepath, latlon=True, header=None)
+
+# %% [markdown]
+# Notes:
+# 
+# 1. The keyword `latlon=True` tells the method that the data is ordered as (time, lat, lon) in the file. Omitting the keyword will cause the file to be parsed as (time, lon, lat)
+# 2. Following keywords are piped into the `pandas.read_csv`. In this case, the csv file does not contains a header
+# 
+# 
+# ### Transforming GPS positions
+# 
+# The next step will create a position object with (x, y) coordinates (The time, lat, lon data is also included). 
+
+# %%
+icepos = icecs.get_xy_coordinates(pos)
+
+# %% [markdown]
+# In this specific example the transect path is continuous: 
+
+# %%
+import matplotlib.pyplot as plt 
+
+
+plt.figure(figsize=(10, 10))
+plt.scatter(icepos.longitude, icepos.latitude, s=6)
+plt.title("GPS coordinates")
+plt.xlabel("Longitude (degrees east)")
+plt.ylabel("Latitude (degrees north)")
+plt.show()
+
+plt.figure(figsize=(10, 10))
+plt.gca().set_aspect('equal')
+plt.scatter(icepos.xc, icepos.yc, s=6)
+plt.title("floe grid coordinates")
+plt.xlabel("x-coordinate (m)")
+plt.ylabel("y-coordinate (m)")
+plt.grid()
+plt.show()
+
+# %% [markdown]
+# In the Floenavi grid, the northern transect loop is in the lower right and the southern loop in the upper left as the x-axis pointed to Polarsterns starboard side. 
+# 
+# ### Multiple transect files
+# 
+# In the next step all transect tracks from leg 1 can be converted to (x, y) coordinates. This can be done with the same ice coordinate system instance, as the data coverage of the floe navi master solution is for the full leg 1. 
+
+# %%
+from pathlib import Path
+
+all_transect_files = Path(r"../data/rover/transect-examples").glob("*.csv")
+
+plt.figure(figsize=(10, 10))
+plt.gca().set_aspect('equal')
+
+for i, track_csv_filepath in enumerate(all_transect_files):
+    pos = GeoPositionData.from_csv(track_csv_filepath, latlon=True, header=None)
+    icepos = icecs.get_xy_coordinates(pos)
+    plt.scatter(icepos.xc, icepos.yc, s=20-i*2, label=track_csv_filepath.name)
+plt.grid()
+plt.legend()
+plt.show()
+
+# %% [markdown]
+# The transect tracks between Oct. 24 and Dec 5, 2019 fall more or less on the same location. It is not possible to attribute offsets between tracks on the different dates to either errors/uncertainties in the floenavi master solution or ice motion with respect to the grid. 
+# 
+# Aligning locations over a longer period of time (weeks, months) will require accouting for local ice movements. Such an example is the southern transect loop from Dec. 5 (upper right) that has is on the same track as the previous southern transects, but the ice has been sheared several hundreds of meters with respect to its former location in the floenavi grid. 
+#