Utilities

Data readers

Functions for input/output and file reading.

seastar.utils.readers.find_seastar_project_root()

Find seastar_project root directory.

Gets the current directory and builds a root directory to /seastar_project

Returns:

ROOT_DIR – Full path to the ‘seastar_project’ root directory.

Return type:

str

seastar.utils.readers.md5_checksum_from_file(file_name)

Create hexidecimal MD5 checksum from input file.

Parameters:

file_name (str) – Full filename including path to create MD5 checksum from.

Returns:

md5_checksum – Hexidecimal MD5 checksum based on input file.

Return type:

str

seastar.utils.readers.read_OSCAR_track_names_config(campaign, flight)

Read track names configuration file.

Reads in an OSCAR campaign track names INI file and parses it as a dict of {track_time : track_name}.

Parameters:

  • campaign (str) – OSCAR campaign name

  • flight (str) – OSCAR flight date, in the form YYYYMMDD

Returns:

track_names_dict – Dict of {Track_time : Track_name}. Track time identical to L1A / L1AP track time in file name.

Return type:

dict

seastar.utils.readers.read_config_OSCAR(config_type, info_dict=None)

Read configuration file related to OSCAR campaigns.

Reads in an OSCAR campaign names INI file or in an OSCAR campaign track names INI file and parses it as a dict

Parameters:

  • config_type (str) –

    Config requested. Can be either:

    ”campaign” to extract the campaign names “track” to extract the track names “phase_sign_convention” to extract the phase direction convention

  • info_dict (dict, default : None) – Dict containing the campaign name and the date of the flight with the following format {campaign: “campaign_name”, flight: “YYYYMMDD”} or Dict containing the data version with format {‘version’: data_version}

Returns:

config_mapping – Dict of {Track_time : Track_name}. Track time identical to L1A / L1AP track time in file name. or Dict of {date : campaign_name} or Dict of {date : phase sign convention}

Return type:

dict

seastar.utils.readers.short_file_name_from_md5(md5_checksum)

Create short name from an MD5 checksum.

Parameters:

md5_checksum (str) – Hexidecimal MD5 checksum.

Returns:

file_short_name – 4-character hexidecimal name based on first 4 characters from MD5 checksum.

Return type:

str

Tools

seastar.utils.tools.EarthRelativeSpeedDir2all(ds)

Convert a dictionary with Earth Relative wind to Ocean Surface Wind.

Parameters:

mydict (xarray.Dataset) – A dictionary with [‘EarthRelativeWindSpeed’], [‘EarthRelativeWindDirection’], [‘CurrentVelocity’], [‘CurrentDirection’] elements

Returns:

mydict – A dictionary with previous fields + OceanSurfaceWind elements

Return type:

xarray.Dataset

seastar.utils.tools.EarthRelativeUV2all(ds)

Convert a dictionary with Earth Relative wind to Ocean Surface Wind.

Parameters:

mydict (xarray.Dataset) – a dictionary with [‘EarthRelativeWindU’], [‘EarthRelativeWindV’], [‘CurrentU’], [‘CurrentV’] elements

Returns:

mydict – a dictionary with previous fields + OceanSurfaceWind elements

Return type:

xarray.Dataset

seastar.utils.tools.add_version(ds, attr='seastar_version')

Add code version to dataset.

Reads the _version.py file in the seastar main repository and adds the __version__ number as an attribute.

Parameters:

  • ds (xarray.Dataset) – Dataset processed with the seastar package.

  • attr (str, default : ‘seastar_version’) – Name of the attribute to write the __version__ number to.

Returns:

ds – Dataset processed with the seastar package.

Return type:

xarray.Dataset

seastar.utils.tools.compute_land_mask_from_GSHHS(da, boundary=None, skip=0.001, erosion=False, erode_scale=3, coastline_selection=0, quiet=False)

Compute land mask.

Computes a boolean mask with size, coords and dims corresponding to a supplied xarray.DataArray, with mask values = True where the point lies within the coastline from the GSHHS global coastline dataset.

Parameters:

  • da (xarray.DataArray) – xarray.DataArray to compute the land mask for. Must contain longitude and latitude coordinates as well as coords and dims to align the new mask to.

  • boundary (list, default : None) – Optional boundary to check for the presence of coastlines in the GSHHS dataset. Supply boundary in the form: [min(long), max(long), min(lat), max(lat)]. The default boundary will be set to the minimum and maximum extent of the longitude and latitude data present in the coords of da.

  • skip (float, default : 1/1000) – Speed-up factor in degrees longitude / latitude. Lower than 1/250 resolution will result in a coarsening of the computed mask.

  • erosion (bool, default : False) – Boolean switch to trigger binary erosion of the resulting mask.

  • erode_scale (int, float, default : 3) – Scale for the array-like structure used for optional binary erosion. When default is used but erosion=True then a erode_scale of 3 is assumed.

  • coastline_selection (int, list, default : 0) – Manual choice of which identified coastlines present within the boundary are used in the generation of the mask. Choice is a key or list of keys of type int. The default is 0. The default behaviour is the first identified coastline within boundary is used to generate the mask, corresponding to the largest coastline within the boundary by internal area.

  • quiet (bool, default : False) – Quiet mode, supressing console output.

Raises:

Exception – ‘longitude and latitude missing from input dataset’. ‘coastline_selection out of bounds of identified coastlines within boundary’

Returns:

mask – An xr.DataArray containing an array-like boolean mask of land pixels.

Return type:

bool, array, xr.DataArray

seastar.utils.tools.compute_relative_wind_direction(windDirection, lookDirection)

Compute relative wind direction.

Compute angle between radar beam and wind direction (degrees) 0 degrees = up-wind 180 degrees = down-wind 90, -90 degrees = cross-wind

Parameters:

  • windDirection (array, float) – Wind direction (degrees N) in wind convention.

  • lookDirection (array, float) – Antenna look direction (degrees N) in oceanographic convention

Returns:

relative_wind_direction – Angle between radar beam and wind direction (degrees)

Return type:

array, float

Notes

Be aware of the difference in direction convention between the wind in windDirection and antenna look direction in lookDirection.

The wind direction is in wind convention (degrees N), i.e. the direction from where the wind is blowing: e.g., a wind direction of 0 degrees corresponds to a wind blowing from the North.

The antenna look direction is in oceanographic convention(degrees N), i.e., the direction to where the antenna is looking: e.g., a look direction of 0 degrees is looking North and with a wind direction of 0 degrees is looking Up-Wind.

seastar.utils.tools.currentUV2VelDir(u, v)

Convert u,v vector components to velocity and direction.

Parameters:

  • u (float, numpy.array, numpy.ndarray, xarray.DataArray) – u vector component in positive East direction

  • v (float, numpy.array, numpy.ndarray, xarray.DataArray) – v vector component in positive North direction

Returns:

  • vel (float, numpy.array, numpy.ndarray, xarray.DataArray) – Magnitude of the converted vector with same units as u and v

  • cdir (float, numpy.array, numpy.ndarray, xarray.DataArray) – Direction of the converted vector (degrees)

seastar.utils.tools.currentVelDir2UV(vel, cdir)

Compute current vector components from direction and magnitude.

Parameters:

  • vel (float, numpy.array, numpy.ndarray, xarray.DataArray) – Magnitude of current (m/s).

  • cdir (float, numpy.array, numpy.ndarray, xarray.DataArray) – Direction of current (degrees N) in oceanographic convention.

Returns:

  • u (float, numpy.array, numpy.ndarray, xarray.DataArray) – u component (positive East) of current vector.

  • v (float, numpy.array, numpy.ndarray, xarray.DataArray) – v component (positive North) of current vector..

seastar.utils.tools.db2lin(db)

Logarithmic to linear conversion.

Convert a base 10 logarithmic value to linear scale.

Parameters:

db (float) – Value or values in logarithmic dB scale.

Returns:

Value or values in linear scale.

Return type:

float

class seastar.utils.tools.dotdict

dot.notation access to dictionary attributes.

seastar.utils.tools.find_coincident_looks(ds_l1_star, star_pattern_tracks, file_time_triplets, rounding=10, d_precision=5)

Find coincident looks in star pattern.

Function to find the file list indices of antenna datasets containing data in coincident look directions within the SEASTARex star pattern on May 22nd 2022.

Parameters:

  • ds_l1_star (dict) – Dictionary of antenna L1 datasets.

  • star_pattern_tracks (dict) – Dictionary of track names and their associated file indices

  • rounding (int, default : 10) – Look direction rounding number in degrees.

  • d_precision (int, default : 5) – Precision of look direction comparison in degrees.

Returns:

look_files – Dictionary of look direction (degrees) in the star pattern as keys and matching tuples of (Track, Antenna)

Return type:

dict

seastar.utils.tools.lin2db(lin)

Linear to logarithmic conversion.

Convert a linear level to base 10 logarithmic for Decibels

Parameters:

lin (float) – Value or values in linear scale

Returns:

Value or values in dB

Return type:

float

seastar.utils.tools.list_duplicates(seq)

Find indices of duplicate entries in list.

Finds the indicies of duplicate list entries and returns a generator object that can be sorted to create a list of [(seq, index)].

Suggested use: sorted(list_duplicates(seq))

Parameters:

seq (list) – DESCRIPTION.

Returns:

  • key (same as in seq) – List of entries in seq

  • locs (list of int) – List of indexes of duplicate entries of key in seq

seastar.utils.tools.polarizationStr2Val(da)

Transform Polarization string (‘VV’ or ‘HH’) towards values (1, 2).

Parameters:

da (xr.DataArray)

Returns:

out

Return type:

xr.DataArray

seastar.utils.tools.polarizationVal2Str(da)

Transform Polarization values (1, 2) to string (‘VV’ or ‘HH’).

Parameters:

da (xr.DataArray)

Returns:

out

Return type:

xr.DataArray

seastar.utils.tools.reduce_0_360_to_0_180(input_degree)

Convert the direction range 0-360 to 0-180 assuming a symetry around zero. Useful for GMFs in Sigma0 or WASV.

Parameters:

input_degree (numpy, xarray)

Return type:

output in the same format as the input

seastar.utils.tools.wavenumber2wavelength(wavenumber)

Convert wavenumber to wavelength.

Parameters:

wavenumber (float) – Wavenumber (rad / m)

Returns:

wavelength – Wavelength (m)

Return type:

float

seastar.utils.tools.wgs2utm_v3(lat, lon, utmzone, utmhemi)

Convert WGS84 coordinates into UTM coordinates.

Parameters:

  • lat (float) – WGS84 Latitude scalar, vector or array in decimal degrees.

  • lon (float) – WGS84 Longitude scalar, vector or array in decimal degrees.

  • utmzone (int) – UTM longitudinal zone. Scalar or same size as Lat and Lon.

  • utmhemi (str) – UTM hemisphere as a single character, ‘N’ or ‘S’, or array of ‘N’ or ‘S’ characters of same size as Lat and Lon.

Returns:

  • x (float) – UTM Easting (m)

  • y (float) – UTM Northing (m)

Notes

Author:
Alexandre Schimel, MetOcean Solutions Ltd. New Zealand
Adapted to python by:
David McCann, National Oceanography Centre, U.K.
From the original author:
I downloaded and tried deg2utm.m from Rafael Palacios but found differences of up to 1m with my reference converters in southern hemisphere so I wrote my own code based on “Map Projections - A Working Manual” by J.P. Snyder (1987). Quick quality control performed only by comparing with LINZ converter and Chuck Taylor’s on a few test points, so use results with caution. Equations not suitable for a latitude of +/- 90 deg.

seastar.utils.tools.windCurrentUV2all(mydict)

Wind/Current component conversion.

Convert a dictionary with [‘u’], [‘v’], [‘c_u’], [‘c_v’] elements to a full dictionary with vis_u, vis_v, vis_wspd, vis_wdir, c_vel, c_dir

Parameters:

mydict (dict or dotdict) – a dictionary with [‘u’], [‘v’], [‘c_u’], [‘c_v’] elements

Returns:

mydict – a dictionary with [‘u’], [‘v’], [‘c_u’], [‘c_v’] elements

Return type:

dict or dotdict

seastar.utils.tools.windSpeedDir2UV(wspd, wdir)

Convert wind speed and direction to u,v vector components.

Parameters:

  • wspd (float, numpy.array, numpy.ndarray, xarray.DataArray) – Magnitude of wind (m/s).

  • wdir (float, numpy.array, numpy.ndarray, xarray.DataArray) – Direction of wind (degrees N) in wind convention.

Returns:

  • u (float, numpy.array, numpy.ndarray, xarray.DataArray) – u component (positive East) of wind vector (m/s)

  • v (float, numpy.array, numpy.ndarray, xarray.DataArray) – v component (positive North) of wind vector (m/s)

Notes

Wind input direction (wdir) is in wind convention format, i.e. the direction the wind is blowing from in degrees from North. A wdir value of 0 corresponds to a wind blowing from North.

seastar.utils.tools.windUV2SpeedDir(u, v)

Convert wind u,v vector components to wind speed and direction.

Parameters:

  • u (float, numpy.array, numpy.ndarray, xarray.DataArray) – u component (positive East) of wind vector (m/s)

  • v (float, numpy.array, numpy.ndarray, xarray.DataArray) – v component (positive North) of wind vector (m/s)

Returns:

  • wspd (float, numpy.array, numpy.ndarray, xarray.DataArray) – Magnitude of wind (m/s).

  • wdir (float, numpy.array, numpy.ndarray, xarray.DataArray) – Direction of wind (degrees N) in wind convention.

Notes

Wind input direction (wdir) is in wind convention format, i.e. the direction the wind is blowing from in degrees from North. A wdir value of 0 corresponds to a wind blowing from North.

seastar.utils.tools.wind_current_component_conversion(env_dict: dict, basevarname: str) → dict

Convert wind/current components.

Add U, V to Speed/Velocity, Direction or the other way around for “Current”, “Wind”, “OceanSurfaceWind”, “EarthRelativeWind”.

Parameters:

  • env (dict) – Dictionnary with with CurrentYYY and Wind keys (either EarthRelativeWindXXX or OceanSurfaceWindXXX) with XXX being Speed, Direction, U or V. ‘YYY’ same as ‘XXX’ but ‘Velocity’ is used instead of ‘Speed’.

  • basevarname (str or list of str) – Values are within: ‘Current’, ‘OceanSurfaceWind’, ‘EarthRelativeWind’

Returns:

env – return a dictionary with completed field U, V, Speed/Velocity, Direction for Current, OceanSurfaceWind and EarthRelativeWind

Return type:

dict

Examples

env = {'CurrentVelocity': 1, 'CurrentDirection':0, 'OceanSurfaceWindSpeed':10, 'OceanSurfaceWindDirection':180}
env
{'CurrentVelocity': 1,
'CurrentDirection': 0,
'OceanSurfaceWindSpeed': 10,
'OceanSurfaceWindDirection': 180}

wind_current_component_conversion(env,'Current')
{'CurrentVelocity': 1,
'CurrentDirection': 0,
'OceanSurfaceWindSpeed': 10,
'OceanSurfaceWindDirection': 180,
'CurrentU': 6.123233995736766e-17,
'CurrentV': 1.0}

OSCAR tools