Altimetry

Altimetry#

Altimetry data (water level, significant wave height and wind speed) obtained from satellites are very useful for validation of models as the data are available globally since 1985 and up to 12 hour before now.

DHI has an altimetry portal with an api where you can download the data. If you have an api key you can access the data through this repo.

class watobs.DHIAltimetryRepository(api_key)#

Get altimetry observations from DHI

Notes

Get a API key by contacting https://www.dhi-gras.com/ API documentation: https://altimetry-shop-data-api.dhigroup.com/apidoc

Examples

>>> repo = DHIAltimetryRepository(api_key="...")
>>> repo.satellites
['gs',
 'e1',
 'tx',
 'pn',
 'e2',
 'g1',
 'j1',
 'n1',
 'j2',
 'c2',
 'sa',
 'j3',
 '3a',
 '3b']
>>> df = repo.get_daily_count("lon=10.9&lat=55.9&radius=10.0", start_time="2021")
>>> data = repo.get_altimetry_data("lon=10.9&lat=55.9&radius=10.0", start_time="2021")
>>> data.to_dfs0('alti_data.dfs0')

get_altimetry_data(area, start_time='20200101', end_time=None, satellites='', qual_filters=None)#

Main function that retrieves altimetry data from api

Parameters:

area (str) –
String specifying location of desired data. The three forms allowed by the API are:
- polygon=6.811,54.993,8.009,54.993,8.009,57.154,6.811,57.154,6.811,54.993
- bbox=115,28,150,52
- lon=10.9&lat=55.9&radius=100
A few named domains can also be used:
- GS_NorthSea, GS_BalticSea, GS_SouthChinaSea
start_time (str, datetime, optional) – Start of data to be retrieved, by default ‘20200101’
end_time (str, datetime, optional) – End of data to be retrieved, by default datetime.now()
satellites (str, list of str, optional) – Satellites to be downloaded, e.g. ‘’, ‘3a’, ‘j3, by default ‘’
qual_filters (int, list[int], optional) – Accepted qualities 0=god, 1=acceptable, 2=bad, e.g. [0, 1], by default None meaning no filter (=all data)

Examples

>>> repo = DHIAltimetryRepository(api_key="...")
>>> data = repo.get_altimetry_data("lon=10.9&lat=55.9&radius=10.0", start_time="2021")
Succesfully retrieved 133 records from API in 0.69 seconds

Returns:: With columns ‘longitude’, ‘latitude’, ‘water_level’, …
Return type:: DataFrame

get_altimetry_data_raw(payload: dict) → DataFrame#

Request data from altimetry api

Parameters:: payload (dict) – params dict build with _create_query_payload()
Raises:: APIAuthenticationFailed – if api key is wrong:
Returns:: with altimetry data
Return type:: pd.DataFrame

get_daily_count(area, start_time='20200101', end_time=None, satellites='')#

Get total number of daily observations for a given area

Parameters:

area (str) –
area specification in one of three allowed formats:
- polygon=6.811,54.993,8.009,54.993,8.009,57.154,6.811,57.154,6.811,54.993
- bbox=115,28,150,52
- lon=10.9&lat=55.9&radius=100
start_time (str or datetime, optional) – start of time interval, by default “2020-01-01”
end_time (str or datetime, optional) – end of time interval, by default datetime.now()
satellites (str, optional) – Satellites to be downloaded, e.g. ‘’, ‘3a’, ‘j3, by default ‘’ (=all)

Returns:

number of observations per day

Return type:

pd.DataFrame

get_observation_stats()#

Get a summary of the data per satellite missions

Returns:: min and max date and observation count per satellite
Return type:: pd.DataFrame

get_quality_filters()#

Get a list of available quality filters with descriptions.

Returns:: available quality filters with descriptions
Return type:: pd.DataFrame

get_satellites()#

Get short and long names for available satellites

Returns:: short and long satellite names
Return type:: pd.DataFrame

get_spatial_coverage(area, start_time='20200101', end_time=None, satellites='')#

Get spatial observation coverage as count per spatial bin in a rectangle covering the specified area

Parameters:

area (str) –
area specification in one of three allowed formats:
- polygon=6.811,54.993,8.009,54.993,8.009,57.154,6.811,57.154,6.811,54.993
- bbox=115,28,150,52
- lon=10.9&lat=55.9&radius=100
start_time (str or datetime, optional) – start of time interval, by default “2020-01-01”
end_time (str or datetime, optional) – end of time interval, by default datetime.now()
satellites (str, optional) – Satellites to be downloaded, e.g. ‘’, ‘3a’, ‘j3, by default ‘’ (=all)

Returns:

count per spatial bin

Return type:

geopandas.GeoDataFrame

parse_satellites(satellites)#

Parse a list of satellite names into an argument string to pass as part of a URL query.

Parameters:

satellites (Union[List[str], str]) –

List of short or long names of satellite to include, an empty string, or the string ‘sentinels’ to specify: the two sentinel satellites 3a and 3b.

Returns:

String representing argument specifying which satellites to retrieve data from.

Return type:

str

Raises:

InvalidSatelliteName – If a string that is not the empty string, ‘sentinels’, or part of the following lists is passed: [‘TOPEX’, ‘Poseidon’, ‘Jason-1’, ‘Envisat’, ‘Jason-2’, ‘SARAL’, ‘Jason-3’, ‘Geosat’, ‘GFO’, ‘ERS-1’, ‘ERS-2’, ‘CryoSat-2’, ‘Sentinel-3A’, ‘Sentinel-3B’] [‘tx’, ‘ps’, ‘j1’, ‘n1’, ‘j2’, ‘sa’, ‘j3’, ‘gs’, ‘g1’, ‘e1’, ‘e2’, ‘c2’, ‘3a’, ‘3b’]

plot_observation_stats()#

Plot graph showing temporal coverage for all satellites

Examples

>>> repo.plot_observation_stats()

property satellites#: List of avaiable satellites (short names)

property time_of_newest_data#: Time of the latest data in the altimetry database.

class watobs.altimetry.AltimetryData(df, area=None, query_params=None)#

Class returned by DHIAltimetryRepository’s get_altimetry_data() method

Examples

>>> repo = DHIAltimetryRepository(api_key="...")
>>> data = repo.get_altimetry_data("lon=10.9&lat=55.9&radius=10.0", start_time="2021")
Succesfully retrieved 133 records from API in 0.69 seconds
>>> data.satellites
['j3', '3a', 'c2', 'sa']
>>> data.df.columns
Index(['longitude', 'latitude', 'water_level', 'significant_wave_height',
   'wind_speed', 'distance_from_land', 'water_depth', 'satellite',
   'quality', 'absolute_dynamic_topography', 'water_level_rms',
   'significant_wave_height_raw', 'significant_wave_height_rms',
   'wind_speed_raw', 'wind_speed_rads'],
  dtype='object')
>>> data.df.water_level.head(3)
date
2021-01-04 15:30:45.051    0.0531
2021-01-04 15:30:46.070    0.0394
2021-01-04 15:30:47.088    0.0294
Name: water_level, dtype: float64
>>> data.to_dfs0('alti_data.dfs0')

assign_track_id(data=None, max_jump=3.0, verbose=True)#

Identify individual passings by finding gaps in data for each satellite.

The track_id will be numbered 0, 1, … for each satellite.

Parameters:

data (pd.DataFrame, optional) – altimetry data (assumed to have a “satellite” column), by default None
max_jump (float, optional) – split passings if jump larger than this number of seconds, by default 3.0
verbose (bool, optional) – print status information?, by default True

Returns:

as input data but with a new column “track_id”

Return type:

pd.DataFrame

property end_time#: End time for this data

static from_csv(filename)#

read altimetry data from csv file instead of api

Parameters:: filename (str) – path to csv file
Returns:: With datetime index containing the altimetry data
Return type:: DataFrame

property n_points#: Number of points in this dataset

plot_map(fig_size=(9, 9), markersize=10)#

plot map of altimetry data

Parameters:: fig_size (Tuple(float), optionally) – size of figure, by default (12,10)

property satellites#: Satellites for this data

property start_time#: Start time for this data

to_dfs0(filename, satellite=None, quality=0)#

Save altimetry data to dfs0 file.

Parameters:

filename (str) – path to new dfs0 file
satellite (str, optional) – short name of satellite to be saved, by default all
quality (int, optional) – highest quality flag to include: 0=good, 1=acceptable, 2=bad, if 1 is given as argument data with flag 0 and 1 will be written to file, by default 0 (i.e. only good data)

Altimetry

Contents

Altimetry#