Level-2 (L2) Processing

Currents

Ambiguity removal

Functions for ambiguitay removal of simultaneous retrieval data products.

seastar.retrieval.ambiguity_removal.ambiguity_closest_to_truth(lmout, truth, windcurrentratio=10)

Find ambiguity closest to truth.

Define a dictionary (windcurrent, wind, current) of indexes for lmout.x on Ambiguities closest to the Truth. Closest distances are defined as euclidian distance on the wind only (wind), current only (current) or combining distance between wind and current using the given windcurrent ratio (windcurrent).

Parameters:

lmout (xarray.Dataset) –

Have to contain the following .x data_vars and
coordinates x_variables = [u,v,c_u,c_v]; Ambiguities;
truth (xarray.Dataset) – Have to contain the following geophysical parameters: EarthRelativeWindSpeed, EarthRelativeWindDirection, CurrentVelocity, CurrentDirection, others (waves) Should be in the same dimension as lmout
windcurrentratio (float) – ratio to combine the distance between wind and current. Default value of 10

Returns:

index – with keys windcurrent, wind, current corresponding on which quantity the distance is calculated combining dataArray. Can be applied directly to lmout with lmout.isel(Ambiguities=ind['windcurrent'])

Return type:

dict of xarray.DataArray

seastar.retrieval.ambiguity_removal.ambiguity_sort_by_cost(lmout)

Find ambiguity by cost.

Return an indexes for lmout on Ambiguities for the smallest cost.

Parameters:: lmout (xarray.Dataset) – Have to contain the following .cost data_vars
Returns:: index – a dataArray index. Can be applied directly to lmout with lmout.isel(Ambiguities=index_cost)
Return type:: xarray.DataArray

seastar.retrieval.ambiguity_removal.solve_ambiguity(lmout, ambiguity)

Solve ambiguity.

Send back the solution after resolving the ambiguities following the algorithm defined in the ambiguity dictionary.

Parameters:

lmout (xarray.Dataset) – dataset of N dimension with required fields, .x and .cost and required coords: Ambiguities, x_variables
ambiguity (dict) – Dictionary with keys name: - name = sort_by_cost - name = closest_truth. truth HAVE to be in the dict. Optional method within windcurrent (default), wind, current. Optional windcurrentratio default = 10

Returns:

sol – solution with ambiguities resolved

Return type:

xarray.Dataset

Cost function

Functions to define and compute the cost function for simultaneous retrieval.

seastar.retrieval.cost_function.create_null_lmout_dict(lmout_dict)

Create null lmout dict.

Creates a null output from least-squares fitting in the event of x0 being found to be infeasible (out of bounds). Uses the output from the first minima as input and returns a copy with all variables set to NaN, along with a message and fail flag.

Parameters:: lmout_dict (dict) – Dict output from scipy.optimize.least_squares.
Returns:: lmout_null – copy of lmout_dict with variables changed to NaN.
Return type:: dict

seastar.retrieval.cost_function.find_initial_values(sol1st_x, level1_inst, gmf)

Find the rough position of the ambiguities given a first solution.

Parameters:

sol1st (xarray.Dataset??) – 1st solution in term of U, V, C_U, C_V
level1_inst (xarray.Dataset??) – Instrument characteristics (geometry)
gmf (dict or dotdict) – dictionary with gmf.nrcs.name and gmf.doppler.name fields

Returns:

out – list of the 3 new initial values to look for ambiguities

Return type:

list of dotdict.x0 containing [u,v,c_u,c_v]

seastar.retrieval.cost_function.find_minima(level1_pixel, noise_pixel, gmf)

Perform least squares minimisation.

Function to find the minima of the residual function at a Level-1 pixel using least squares.

Parameters:

level1_pixel (xarray.Dataset) – level1 dataset at a pixel with Antenna as a dimension, with the mandatory following fields: IncidenceAngleImage, RSV, Sigma0
noise_pixel (xarray.Dataset) – Noise DataSet at a pixel with fields RSV and Sigma0 of the same size as level1
gmf (dict or dotdict) – dictionary with gmf[‘nrcs’][‘name’] and gmf[‘doppler’][‘name’] items. cf compute_nrcs and compute_wasv for the gmf input

Returns:

dslmout – Dataset output of least squares minimisation.

Return type:

xarray.Dataset

Raises:

Exception – Exception raised if intial value x0 is out of bounds for the least squares minimisation

seastar.retrieval.cost_function.fun_residual(variables, level1, noise, gmf)

Function which computes the vector of residuals between the observations and the model divide by the noise

Parameters:

variables (numpy.array others…) – [u, v, c_u, c_v]; u, v, c_u, c_v being floats
level1 (xarray.Dataset) –

level1 dataset with Antenna as a dimension, with the mandatory following fields:
IncidenceAngleImage, RSV, Sigma0
noise (xarray.Dataset) – Noise DataSet with fields RSV and Sigma0 of the same size as level1
gmf (dict or dotdict) – dictionary with gmf[‘nrcs’][‘name’] and gmf[‘doppler’][‘name’] items. cf compute_nrcs and compute_wasv for the gmf input

Returns:

out – numpy array of size level1.isel(Antenna=0).shape times the sum of Antenna (observation) dimension of Sigma0 + RSV. if 4 antennas (Fore, Aft, MidVV, MidHH) for Sigma0 and RSV => 8 NaN are replaced by 0

Return type:

numpy.array

seastar.retrieval.cost_function.uvcucv2x(mydict)

Convert a dictionary with [‘u’], [‘v’], [‘c_u’], [‘c_v’] elements to the array x = [u, v, c_u, c_v]

Parameters:: out (dict or dotdict) – a dictionary with [‘u’], [‘v’], [‘c_u’], [‘c_v’] elements
Returns:: x – array x = [u, v, c_u, c_v]
Return type:: numpy.array

seastar.retrieval.cost_function.x2uvcucv(x)

Convert the array x = [u, v, c_u, c_v] to a dict with .u, .v, .c_u, .c_v elements

Parameters:: x (list numpy.array) – array x = [u, v, c_u, c_v]
Returns:: out – a dictionary with .u, .v, .c_u, .c_v elements
Return type:: dotdict