API reference

general functions

xsarsea.sigma0_detrend(*args, **kwargs)

compute sigma0_detrend from sigma0 and inc_angle

Parameters:

sigma0 (numpy-like) – linear sigma0
inc_angle (numpy-like) – incidence angle (deg). Must be same shape as sigma0
wind_speed_gmf (int, optional) – wind speed (m/s) used by gmf, by default 10
wind_dir_gmf (int, optional) – wind dir (deg relative to antenna) used, by default 45

Returns:

sigma0 detrend.

Return type:

numpy-like

xsarsea.dir_meteo_to_sample(meteo_dir, ground_heading)

Convert meteorological N/S direction to image convention

Parameters:

meteo_dir (meteorological direction in degrees north) –
ground_heading (azimuth at position, in degrees north) –

Returns:

same shape as input. angle in radian, relative to sample, anticlockwise

Return type:

np.float64

xsarsea.dir_sample_to_meteo(sample_dir, ground_heading)

Convert image direction relative to antenna to meteorological direction

Parameters:

sample_dir (angle in degrees, relative to sample, anticlockwise) –
ground_heading (azimuth at position, in degrees north) –

Returns:

same shape as input. meteorological direction in degrees north

Return type:

np.float64

xsarsea.dir_meteo_to_oceano(meteo_dir)

Convert meteorological direction to oceanographic direction

Parameters:: meteo_dir (float) – Wind direction in meteorological convention (clockwise, from), ex: 0°=from north, 90°=from east
Returns:: Wind direction in oceanographic convention (clockwise, to), ex: 0°=to north, 90°=to east
Return type:: float

xsarsea.dir_oceano_to_meteo(oceano_dir)

Convert oceanographic direction to meteorological direction

Parameters:: oceano_dir (float) – Wind direction in oceanographic convention (clockwise, to), ex: 0°=to north, 90°=to east
Returns:: Wind direction in meteorological convention (clockwise, from), ex: 0°=from north, 90°=from east
Return type:: float

xsarsea.dir_to_180(angle)

Convert angle to [-180;180]

Parameters:: angle (float) – angle in degrees
Returns:: angle in degrees
Return type:: float

xsarsea.dir_to_360(angle)

Convert angle to [0;360]

Parameters:: angle (float) – angle in degrees
Returns:: angle in degrees
Return type:: float

xsarsea.get_test_file(fname, iszip=True)

get test file from https://cyclobs.ifremer.fr/static/sarwing_datarmor/xsardata/ file is unzipped if needed and extracted to config[‘data_dir’]

This function is for examples only, it should not be not used in production environments.

Parameters:

fname (str) – file name to get (without ‘.zip’ extension)
iszip (boolean) – true if file have to be unzipped ;

Returns:

path to file, relative to config[‘data_dir’]

Return type:

str

xsarsea.read_sarwing_owi(owi_file)

read sarwing owi file, compatible with xsar.

Parameters:: owi_file (str) –
Returns:: in xsar like format
Return type:: xarray.Dataset

gradients

Implemented from:

‘W. Koch, “Directional analysis of SAR images aiming at wind direction,” IEEE Trans. Geosci. Remote Sens., vol. 42, no. 4, pp. 702-710, 2004.’

https://ieeexplore.ieee.org/document/1288365

https://www.climate-service-center.de/imperia/md/content/gkss/institut_fuer_kuestenforschung/ksd/paper/kochw_ieee_2004.pdf

class xsarsea.gradients.Gradients(sigma0, windows_sizes=[1600], downscales_factors=[1], window_step=1)

Gradients class to compute weighted direction histogram at multiscale and multi resolution

Parameters:

sigma0 (xarray.DataArray) – sigma0 at medium resolution (i.e 100m), with optional ‘pol’ dimension.
windows_sizes (list of int) –
list of windows size, like [1600, 3200].

to have 16km and 32km windows size (if sensor sigma0 resolution is 10m)
downscales_factors (list of int) –
list of downscale factors, like [1,2]

(for 100m and 200m multi resolution if input sigma0 resolution is 100m)
window_step (float) –
The overlapping factor for windows slidind. 0.5 is for half overlaping, 1 is no overlaping.

Note that this overlapping is only for windows_sizes[0] : others windows sizes are aligned with the 1st one.

property histogram

xarray.Dataset

With dims:

line, sample : windows centers
pol, if sigma0 was provided with pol dim
window_size : as windows_sizes parameter
downscale_factor: as downscales_factors parameters
angles: histogram dimension (binned angles)

class xsarsea.gradients.Gradients2D(sigma0, window_size=1600, window_step=None, windows_at=None)

Low level gradients analysis class, for mono pol (2D) sigma0, and single windows size

Parameters:

sigma0 (xarray.DataArray) – mono-pol, at medium resolution (like 100m)
window_size (int) –
window size, asample coordinate (so it’s independent of sigma0 resolution).

if sensor pixel size is 10m, 1600 will set a 16km window size (i.e 160 pixels if sigma0 is 100m, or 80 pixels if sigma0 res is 200m).
window_step (float) – stepping of windows sliding. (0.5 is half of the windows, 1 is for non overlapping windows)
windows_at (dict) –

n_angles: Bin angles count, in the range [-pi/2, pi/2] (can be changed)

property histogram: direction histogram as a xarray.Dataset, for all windows from self.stepping_gradients. This is the main attribute needed by user.

property i2: reduced sigma0 by factor 2, without moiré effect

property ampl: amplitude (sqrt) of i2

property local_gradients: local gradients from amplitude as an xarray.Dataset ( reduced by a factor 2 from self.ampl, so a factor 4 from self.sigma0), with ‘G2’ variable that is a complex number whose argument is the direction and module the gradient weight, and ‘c’ variable that is a quality index

property rolling_gradients: rolling window over self.local_gradient (all, with step 1)

property windows_at

dict

Dict {‘line’: dataarray, ‘sample’: dataarray} of windows center coordinates where locals histograms are computed.

By default, those coordinates are computed by sliding windows with a step from windows_step

This property can be set by user.

xsarsea.gradients.circ_smooth(hist)

Smooth histogram with kernels Bx Bx2 Bx4 Bx8. Histogram coordinates are angles, so begin and end are circulary wrapped.

Parameters:: hist (xarray.DatArray, with 'angles' dim.) –
Returns:: same as hist, but smoothed.
Return type:: xarray.DataArray

class xsarsea.gradients.PlotGradients(gradients_hist)

Plotting class

Parameters:: gradients_hist (xarray.Dataset) – from Gradients2D.histogram or mean from Gradients.histogram.

vectorfield(tap=True): Show gradients as a hv.VectorField object

histogram_plot(sample=None, line=None, x=None, y=None): plot histogram at sample, line

xsarsea.gradients.circ_hist(hist_at)

convert xarray.Dataset hist_at with angles modulo pi to a pandas.Dataframe modulo 2pi

Parameters:: hist_at (xarray.Dataset) – Only one histogram (i.e. at one (line,sample) position.
Return type:: pd.DataFrame, with columns [‘sample_g’, ‘line_g’]

windspeed

windspeed module, for retrieving wind speed from sigma0 and models.

xsarsea.windspeed.invert_from_model(*args, **kwargs)

Invert sigma0 to retrieve windspeed from model (lut or gmf).

Parameters:

inc (xarray.DataArray) – incidence angle
sigma0 (xarray.DataArray) – sigma0 to be inverted.
sigma0_dual (xarray.DataArray (optional)) – sigma0 in cross pol for dualpol invertion
ancillary_wind= (xarray.DataArray (numpy.complex28)) –

ancillary wind

(for example ecmwf winds), in antenna convention
model= (str or tuple) –
model to use.

If mono pol invertion, it could be a single str

If dualpol, it should be ordered (model_co, model_cr)
dsig_co= (float) –
parameter used for

Jsig_co=((sigma0_gmf - sigma0) / dsig_co) ** 2
dsig_cr= (float or xarray.DataArray) –
parameters used for

Jsig_cr=((sigma0_gmf - sigma0) / dsig_cr) ** 2

Returns:

If available (copol or dualpol), the returned array is np.complex64, with the angle of the returned array is inverted direction in antenna convention

Return type:

xarray.DataArray or tuple

See also

xsarsea.windspeed.available_models

xsarsea.windspeed.available_models(pol=None)

get available models

Parameters:: pol (str or None) – Filter models by pol (ie pol=’VV’) if None, no filters
Return type:: pandas.DataFrame

xsarsea.windspeed.get_model(name)

get model by name

Parameters:: name (str) – model name
Return type:: Model

xsarsea.windspeed.register_cmod7(topdir)

Register cmod7.

This function return nothing. See xsarsea.windspeed.available_models to see registered models.

Parameters:: topdir (str) – top dir path to cmod7 lut.

Examples

Notes

Source : https://scatterometer.knmi.nl/cmod7

xsarsea.windspeed.register_pickle_luts(path)

Register LUTs from a specified path. The path can be a directory containing multiple LUTs or a single LUT file.

This function returns nothing. See xsarsea.windspeed.available_models to see registered models.

Parameters:: path (str) – Path to a LUT or a directory containing multiple LUTs.

Examples

Register a single LUT:

>>> xsarsea.windspeed.register_pickle_luts(xsarsea.get_test_file('sarwing_luts_subset/GMF_cmodms1ahw'))

Register all LUTs from a directory:

>>> xsarsea.windspeed.register_pickle_luts('/home/datawork-cersat-public/cache/project/sarwing/GMFS/v1.6')

Notes

LUTs can be downloaded from https://cyclobs.ifremer.fr/static/sarwing_datarmor/xsardata/sarwing_luts

xsarsea.windspeed.register_nc_luts(topdir, gmf_names=None)

Register all netcdf luts found under topdir.

This function return nothing. See xsarsea.windspeed.available_models to see registered models.

Parameters:

topdir (str) –

top dir path to netcdf luts.

gmf_names (list, optional): List of names to filter the registrated gmfs.: If None, all registrated gmfs are processed.

Examples

register a subset of sarwing luts

>>> xsarsea.windspeed.register_nc_luts(xsarsea.get_test_file('nc_luts_subset'))

register all pickle lut from ifremer path

>>> xsarsea.windspeed.register_pickle_luts('/home/datawork-cersat-public/cache/project/sarwing/xsardata/nc_luts')

xsarsea.windspeed.register_luts(topdir=None, topdir_cmod7=None)

Register gmfModel luts and ncLutModel luts

Parameters:

topdir (str) – top dir path to nc luts.
topdir_cmod7 (str) – top dir path to cmod7 luts.
kwargs (dict) – kwargs to pass to register_nc_luts

xsarsea.windspeed.nesz_flattening(noise, inc)

Noise flatten by polynomial fit (order 1)

Parameters:

noise (array-like) – linear noise array (nesz), with shape (line, sample)
inc (array-like) – incidence array

Returns:

flattened noise

Return type:

array-like

Examples

Compute dsig_cr keyword for xsarsea.windspeed.invert_from_model

>>> nesz_flat = nesz_flattening(nesz_cr, inc)
>>> dsig_cr = (1.25 / (sigma0_cr / nesz_flat )) ** 4.

See also

xsarsea.windspeed.invert_from_model

class xsarsea.windspeed.GmfModel(name, gmf_pyfunc_scalar, wspd_range=[0.2, 50.0], pol=None, units=None, **kwargs)

Bases: Model

GmfModel class for handling model from analitycal functions. See Model()

classmethod register(name=None, pol=None, units='linear', defer=True, **kwargs)

provide a decorator for registering a gmf function.

The decorated function should be able to handle float as input.

Parameters:

name (str) – name of the registered gmf. Should start with gmf_. default to function name.
wspd_range (list) – windspeed interval validity. Default to [0.2, 50.] for copol, or [3.0, 80.] for crosspol
pol (str) – gmf polarisation. for ex ‘VV’ or ‘VH’
units (str) – sigma0 units returned by this gmf. Should be ‘linear’ or ‘dB’

Examples

Register a new gmf

>>> @xsarsea.windspeed.gmfs.GmfModel.register(pol='VH', units='linear')
>>> def gmf_dummy(inc, wspd, phi=None):
>>>     a0 = 0.00013106836021008122
>>>     a1 = -4.530598283705591e-06
>>>     a2 = 4.429277425062766e-08
>>>     b0 = 1.3925444179360706
>>>     b1 = 0.004157838450541205
>>>     b2 = 3.4735809771069953e-05
>>>
>>>     a = a0 + a1 * inc + a2 * inc ** 2
>>>     b = b0 + b1 * inc + b2 * inc ** 2
>>>     sig = a * wspd ** b
>>>    return sig
>>>
>>> gmf_dummy
<GmfModel('gmf_dummy') pol=VH>
>>> gmf_dummy(np.arange(20,22), np.arange(10,12))
<xarray.DataArray (incidence: 2, wspd: 2)>
array([[0.00179606, 0.00207004],
[0.0017344 , 0.00200004]])
Coordinates:
* incidence  (incidence) int64 20 21
* wspd       (wspd) int64 10 11
Attributes:
units:    linear

Returns:: (if used as a decorator)
Return type:: GmfModel

classmethod activate_gmfs_impl(gmfs_names=None, **kwargs)

Process all deferred registrations based on the provided config and optional name filter.

Parameters

gmfs_names (list, optional): List of names to filter the registrated gmfs.: If None, all registrated gmfs are processed.

classmethod get_function(name)

windspeed.models

class xsarsea.windspeed.models.NcLutModel(path, **kwargs): Class to handle luts in netcdf xsarsea format

windspeed.gmfs

class xsarsea.windspeed.gmfs.GmfModel(name, gmf_pyfunc_scalar, wspd_range=[0.2, 50.0], pol=None, units=None, **kwargs)

GmfModel class for handling model from analitycal functions. See Model()

classmethod register(name=None, pol=None, units='linear', defer=True, **kwargs)

provide a decorator for registering a gmf function.

The decorated function should be able to handle float as input.

Parameters:

name (str) – name of the registered gmf. Should start with gmf_. default to function name.
wspd_range (list) – windspeed interval validity. Default to [0.2, 50.] for copol, or [3.0, 80.] for crosspol
pol (str) – gmf polarisation. for ex ‘VV’ or ‘VH’
units (str) – sigma0 units returned by this gmf. Should be ‘linear’ or ‘dB’

Examples

Register a new gmf

>>> @xsarsea.windspeed.gmfs.GmfModel.register(pol='VH', units='linear')
>>> def gmf_dummy(inc, wspd, phi=None):
>>>     a0 = 0.00013106836021008122
>>>     a1 = -4.530598283705591e-06
>>>     a2 = 4.429277425062766e-08
>>>     b0 = 1.3925444179360706
>>>     b1 = 0.004157838450541205
>>>     b2 = 3.4735809771069953e-05
>>>
>>>     a = a0 + a1 * inc + a2 * inc ** 2
>>>     b = b0 + b1 * inc + b2 * inc ** 2
>>>     sig = a * wspd ** b
>>>    return sig
>>>
>>> gmf_dummy
<GmfModel('gmf_dummy') pol=VH>
>>> gmf_dummy(np.arange(20,22), np.arange(10,12))
<xarray.DataArray (incidence: 2, wspd: 2)>
array([[0.00179606, 0.00207004],
[0.0017344 , 0.00200004]])
Coordinates:
* incidence  (incidence) int64 20 21
* wspd       (wspd) int64 10 11
Attributes:
units:    linear

Returns:: (if used as a decorator)
Return type:: GmfModel

classmethod activate_gmfs_impl(gmfs_names=None, **kwargs)

Process all deferred registrations based on the provided config and optional name filter.

Parameters

gmfs_names (list, optional): List of names to filter the registrated gmfs.: If None, all registrated gmfs are processed.