py_eddy_tracker.observations.observation.EddiesObservations¶

class py_eddy_tracker.observations.observation.EddiesObservations(size=0, track_extra_variables=None, track_array_variables=0, array_variables=None, only_variables=None, raw_data=False)[source]¶

Bases: object

Class to store eddy observations.

Methods

`add_fields`	Add a new field.
`add_rotation_type`
`align_on`	Align the variable indices of two datasets.
`append`	Merge.
`basic_formula_ellipse_major_axis`	Give major axis in km with a given latitude
`bins_stat`	param str,array xname: variable to compute stats on
`box_display`	Return values evenly spaced with few numbers
`build_var_list`
`circle_contour`	Set contours as circles from radius and center data.
`coherence`	Check coherence between two datasets.
`compare_units`
`concatenate`
`contains`	Return index of contour containing (x,y)
`copy`
`copy_data_to_zarr`	Copy with buffer for zarr.
`cost_function`	Return the cost function between two obs.
`cost_function_common_area`	How does it work on x bound ?
`create_particles`	Create particles inside contour (Default : speed contour).
`create_variable`
`create_variable_zarr`
`display`	Plot the speed and effective (dashed) contour of the eddies
`display_color`	Plot colored contour of eddies
`distance`	Use haversine distance for distance matrix between every self and other eddies.
`empty_dataset`
`extract_with_area`	Extract geographically with a bounding box.
`extract_with_mask`	Extract a subset of observations.
`field_table`	Produce description table of the fields available in this object
`filled`	param matplotlib.axes.Axes ax: matplotlib axe used to draw
`first_obs`	Get first obs of each trajectory.
`fixed_ellipsoid_mask`
`format_label`
`from_array`
`from_netcdf`
`from_zarr`
`get_color`	Return colors as a cyclic list
`get_filters_zarr`	Get filters to store in zarr for known variable
`get_infos`
`grid_box_stat`	Get percentile of eddies in each bin
`grid_count`	Count the eddies in each bin (use all pixels in each contour)
`grid_stat`	Return the mean of the eddies' variable in each bin
`hist`	Build histograms.
`index`	Return obs from self at the index.
`insert_observations`	Insert other obs in self at the given index.
`inside`	True for each point inside the effective contour of an eddy
`intern`
`interp_grid`	Interpolate a grid on a center or contour with mean, min or max method
`is_convex`	Get flag of the eddy's convexity
`iter_on`	Yield observation group for each bin.
`last_obs`	Get Last obs of each trajectory.
`load_file`	Load the netcdf or the zarr file.
`load_from_netcdf`	Load data from netcdf.
`load_from_zarr`	Load data from zarr.
`mask_from_polygons`	Return mask for all observations in one of polygons list
`mask_function`
`match`	Return index and score computed on the effective contour.
`merge`	Merge two datasets.
`merge_filters`	Compute an intersection between all filters after to evaluate each of them
`needed_variable`
`netcdf_create_dimensions`
`new_like`
`obs_dimension`
`parse_varname`
`post_process_link`
`propagate`	Fill virtual obs (C).
`re_reference_index`	Shift index with ref
`remove_fields`	Copy with fields listed remove
`reset`
`scatter`	Scatter data.
`set_global_attr_netcdf`
`set_global_attr_zarr`
`shifted_ellipsoid_degrees_mask`
`solve_conflict`
`solve_first`
`solve_function`
`solve_simultaneous`	Deduce link from cost matrix.
`time_sub_sample`	Time sub sampling
`to_netcdf`
`to_zarr`
`tracking`	Track obs between self and other
`write_file`	Write a netcdf or zarr with eddy obs.
`zarr_dimension`

Attributes

`track_extra_variables`
`track_array_variables`
`array_variables`
`only_variables`
`observations`
`sign_type`
`raw_data`
`period_`
`COLORS`
`ELEMENTS`
`NB_COLORS`
`dtype`	Return dtype to build numpy array.
`elements`	Return all the names of the variables.
`fields`
`global_attr`
`nb_days`	Return period in days covered by the dataset
`obs`	Return observations.
`period`	Give the time coverage.
`shape`
`sign_legend`
`time_datetime64`
`tracks`

COLORS = ['sienna', 'red', 'darkorange', 'gold', 'palegreen', 'limegreen', 'forestgreen', 'mediumblue', 'dodgerblue', 'lightskyblue', 'violet', 'blueviolet', 'darkmagenta', 'darkgrey', 'dimgrey', 'steelblue']¶

ELEMENTS = ['lon', 'lat', 'radius_s', 'radius_e', 'amplitude', 'speed_average', 'time', 'shape_error_e', 'shape_error_s', 'speed_area', 'effective_area', 'nb_contour_selected', 'num_point_e', 'num_point_s', 'height_max_speed_contour', 'height_external_contour', 'height_inner_contour']¶

NB_COLORS = 16¶

add_fields(fields=[], array_fields=[])[source]¶: Add a new field.

add_rotation_type()[source]¶

align_on(other, var_name='time', all_ref=False, **kwargs)[source]¶

Align the variable indices of two datasets.

Parameters:

other – other compare with self
var_name (str,tuple) – variable name to align or two array, defaults to “time”
all_ref (bool) – yield all value of ref, if false only common value, defaults to False

Yield array,array,float,float:

index in self, index in other, lower bound, upper bound

append(other)[source]¶: Merge.

array_variables¶

static basic_formula_ellipse_major_axis(lats, cmin=1.5, cmax=10.0, c0=1.5, lat1=13.5, lat2=5.0, degrees=False)[source]¶: Give major axis in km with a given latitude

bins_stat(xname, bins=None, yname=None, method=None, mask=None)[source]¶

Parameters:

xname (str,array) – variable to compute stats on
bins (array, None) – bins to perform statistics, if None bins = arange(variable.min(), variable.max() + 2)
yname (None,str,array) – variable used to apply method
method (None,str) – If None method counts the number of observations in each bin, can be “mean”, “std”
mask (None,array(bool)) – If defined use only True position

Returns:

x array and y array

Return type:

array,array

Get Okubo Weis

static box_display(value)[source]¶: Return values evenly spaced with few numbers

static build_var_list(var_list, remove_vars, include_vars)[source]¶

circle_contour(only_virtual=False, factor=1)[source]¶: Set contours as circles from radius and center data.

Display contour & circle

Display contour & circle

coherence(other)[source]¶: Check coherence between two datasets.

static compare_units(input_unit, output_unit, name)[source]¶

classmethod concatenate(observations)[source]¶

contains(x, y, intern=False)[source]¶

Return index of contour containing (x,y)

Parameters:

x (array) – longitude
y (array) – latitude
intern (bool) – If true use speed contour instead of effective contour

Returns:

indexs, -1 if no index

Return type:

array[int32]

copy()[source]¶

static copy_data_to_zarr(handler_zarr, handler_eddies, sl_obs, buffer_size, factor, raw_data, scale_factor, add_offset)[source]¶

Copy with buffer for zarr.

Zarr need to get real value, and size could be huge, so we use a buffer to manage memory :param zarr_dataset handler_zarr: :param array handler_eddies: :param slice zarr_dataset sl_obs: :param int buffer_size: :param float factor: :param bool raw_data: :param None,float scale_factor: :param None,float add_offset:

static cost_function(records_in, records_out, distance)[source]¶

Return the cost function between two obs.

\[cost = \sqrt{({Amp_{_{in}} - Amp_{_{out}} \over Amp_{_{in}}}) ^2 + ({Rspeed_{_{in}} - Rspeed_{_{out}} \over Rspeed_{_{in}}}) ^2 + ({distance \over 125}) ^2 }\]

Parameters:

records_in – starting observations
records_out – observations to associate
distance – computed between in and out

classmethod cost_function_common_area(xy_in, xy_out, distance, intern=False)[source]¶

How does it work on x bound ?

Parameters:

xy_in –
xy_out –
distance –
intern (bool) –

create_particles(step, intern=True)[source]¶

Create particles inside contour (Default : speed contour). Avoid creating too large numpy arrays, only to be masked

Parameters:

step (float) – step for particles
intern (bool) – If true use speed contour instead of effective contour

Returns:

lon, lat and indices of particles

Return type:

tuple(np.array)

create_variable(handler_nc, kwargs_variable, attr_variable, data, scale_factor=None, add_offset=None, **kwargs)[source]¶

create_variable_zarr(handler_zarr, kwargs_variable, attr_variable, data, scale_factor=None, add_offset=None, filters=None, compressor=None, chunck_size=2500000)[source]¶

display(ax, ref=None, extern_only=False, intern_only=False, **kwargs)[source]¶

Plot the speed and effective (dashed) contour of the eddies

Parameters:

ax (matplotlib.axes.Axes) – matplotlib axe used to draw
ref (float,None) – if defined, all coordinates are wrapped with ref as western boundary
extern_only (bool) – if True, draw only the effective contour
intern_only (bool) – if True, draw only the speed contour
kwargs (dict) – look at matplotlib.axes.Axes.plot()

Display contour & circle

Display identification

Get mean of grid in each eddies

Eddy detection : Med

Eddy detection : Gulf stream

Eddy detection and filter

Eddy detection on SLA and ADT

Eddy detection : Antartic Circumpolar Current

Select pixel in eddies

Get Okubo Weis

LAVD detection and geometric detection

Collocating external data

Network basic manipulation

display_color(ax, field, ref=None, intern=False, **kwargs)[source]¶

Plot colored contour of eddies

Parameters:

ax (matplotlib.axes.Axes) – matplotlib axe used to draw
field (str,array) – color field
ref (float,None) – if defined, all coordinates are wrapped with ref as western boundary
intern (bool) – if True, draw the speed contour
kwargs (dict) – look at matplotlib.collections.LineCollection()

distance(other)[source]¶: Use haversine distance for distance matrix between every self and other eddies.

property dtype¶: Return dtype to build numpy array.

property elements¶: Return all the names of the variables.

empty_dataset()[source]¶

extract_with_area(area, **kwargs)[source]¶

Extract geographically with a bounding box.

Parameters:

area (dict) – 4 coordinates in a dictionary to specify bounding box (lower left corner and upper right corner)
kwargs (dict) – look at extract_with_mask()

Returns:

Return all eddy trajetories in bounds

Return type:

EddiesObservations

area = dict(llcrnrlon=x0, llcrnrlat=y0, urcrnrlon=x1, urcrnrlat=y1)

Tracks which go through area

extract_with_mask(mask)[source]¶

Extract a subset of observations.

Parameters:: mask (array(bool)) – mask to select observations
Returns:: same object with selected observations
Return type:: self

field_table()[source]¶: Produce description table of the fields available in this object

property fields¶

filled(ax, varname=None, ref=None, intern=False, cmap='magma_r', lut=10, vmin=None, vmax=None, factor=1, **kwargs)[source]¶

Parameters:

ax (matplotlib.axes.Axes) – matplotlib axe used to draw
varname (str,array,None) – variable used to fill the contours, or an array of same size than obs
ref (float,None) – if defined, all coordinates are wrapped with ref as western boundary
intern (bool) – if True draw speed contours instead of effective contours
cmap (str) – matplotlib colormap name
lut (int,None) – Number of colors in the colormap
vmin (float,None) – Min value of the colorbar
vmax (float,None) – Max value of the colorbar
factor (float) – multiply value by

Returns:

Collection drawed

Return type:

matplotlib.collections.PolyCollection

Display identification

Get mean of grid in each eddies

Eddy detection : Med

Eddy detection : Gulf stream

Grid advection

LAVD detection and geometric detection

first_obs()[source]¶

Get first obs of each trajectory.

Return type:: __class__

Birth and death

fixed_ellipsoid_mask(other, minor=50, major=100, only_east=False, shifted_ellipse=False)[source]¶

format_label(label)[source]¶

classmethod from_array(arrays, **kwargs)[source]¶

classmethod from_netcdf(handler)[source]¶

classmethod from_zarr(handler)[source]¶

get_color(i)[source]¶: Return colors as a cyclic list

static get_filters_zarr(name)[source]¶

Get filters to store in zarr for known variable

Parameters:: name (str) – private variable name
Return list:: filters list

get_infos()[source]¶

property global_attr¶

grid_box_stat(bins, varname, method=50, data=None, filter=slice(None, None, None))[source]¶

Get percentile of eddies in each bin

Parameters:

bins ((numpy.array,numpy.array)) – bins (grid) to count
varname (str) – variable to apply the method if data is None and will be output name
method (str,float) – method to apply. If float, use ?
data (array) – Array used to compute stat if defined
filter (array,mask,slice) – keep the data selected with the filter

Returns:

return grid of method

Return type:

py_eddy_tracker.dataset.grid.RegularGridDataset

grid_count(bins, intern=False, center=False, filter=slice(None, None, None))[source]¶

Count the eddies in each bin (use all pixels in each contour)

Parameters:

bins ((numpy.array,numpy.array)) – bins (grid) to count
intern (bool) – if True use speed contour only
center (bool) – if True use of center to count
filter (array,mask,slice) – keep the data selected with the filter

Returns:

return the grid of counts

Return type:

py_eddy_tracker.dataset.grid.RegularGridDataset

Stastics on identification files

Count pixel used

Count center

Network Analysis

grid_stat(bins, varname, data=None)[source]¶

Return the mean of the eddies’ variable in each bin

Parameters:

bins ((numpy.array,numpy.array)) – bins (grid) to compute the mean on
varname (str) – name of variable to compute the mean on and output grid_name
data (array) – Array used to compute stat if defined

Returns:

return the gridde mean variable

Return type:

py_eddy_tracker.dataset.grid.RegularGridDataset

Geographical statistics

hist(varname, x, bins, percent=False, mean=False, nb=False)[source]¶

Build histograms.

Parameters:

varname (str,array) – variable to use to compute stat
x (str,array) – variable to use to know in which bins
bins (array) –
percent (bool) – normalized by sum of all bins
mean (bool) – compute mean by bins
nb (bool) – only count by bins

Returns:

value by bins

Return type:

array

index(index, reverse=False)[source]¶: Return obs from self at the index.

insert_observations(other, index)[source]¶: Insert other obs in self at the given index.

inside(x, y, intern=False)[source]¶

True for each point inside the effective contour of an eddy

Parameters:

x (array) – longitude
y (array) – latitude
intern (bool) – If true use speed contour instead of effective contour

Returns:

flag

Return type:

array[bool]

static intern(flag, public_label=False)[source]¶

interp_grid(grid_object, varname, i=None, method='center', dtype=None, intern=None)[source]¶

Interpolate a grid on a center or contour with mean, min or max method

Parameters:

grid_object (py_eddy_tracker.dataset.grid.RegularGridDataset) – Handler of grid to interp
varname (str) – Name of variable to use
i (array[bool,int],None) – Index or mask to subset observations, it could avoid to build a specific dataset.
method (str) – ‘center’, ‘mean’, ‘max’, ‘min’, ‘nearest’
dtype (str) – if None we use var dtype
intern (bool) – Use extern or intern contour

Get mean of grid in each eddies

Get Okubo Weis

Collocating external data

is_convex(intern=False)[source]¶

Get flag of the eddy’s convexity

Parameters:: intern (bool) – If True use speed contour instead of effective contour
Returns:: True if the contour is convex
Return type:: array[bool]

iter_on(xname, window=None, bins=None)[source]¶

Yield observation group for each bin.

Parameters:

xname (str,array) –
window (float,None) – if defined we use a moving window with value like half window
bins (array) – bounds of each bin

Yield array,float,float:

index in self, lower bound, upper bound

Network group process

last_obs()[source]¶

Get Last obs of each trajectory.

Return type:: __class__

Birth and death

classmethod load_file(filename, **kwargs)[source]¶

Load the netcdf or the zarr file.

Load only latitude and longitude on the first 300 obs :

kwargs_latlon_300 = dict(
    include_vars=[
        "longitude",
        "latitude",
    ],
    indexs=dict(obs=slice(0, 300)),
)
small_dataset = TrackEddiesObservations.load_file(
    filename, **kwargs_latlon_300
)

For **kwargs look at load_from_zarr() or load_from_netcdf()

classmethod load_from_netcdf(filename, raw_data=False, remove_vars=None, include_vars=None, indexs=None, **class_kwargs)[source]¶

Load data from netcdf.

Parameters:

filename (str,ExFileObject) – path or handler to load data
raw_data (bool) – If true load data without apply scale_factor and add_offset
remove_vars (None,list(str)) – List of variable name which will be not loaded
include_vars (None,list(str)) – If defined only this variable will be loaded
indexs (None,dict) – Indexes to load only a slice of data
class_kwargs – argument to set up observations class

Returns:

Obsevations selected

Return type:

class

classmethod load_from_zarr(filename, raw_data=False, remove_vars=None, include_vars=None, indexs=None, buffer_size=5000000, **class_kwargs)[source]¶

Load data from zarr.

Parameters:

filename (str,store) – path or store to load data
raw_data (bool) – If true load data without scale_factor and add_offset
remove_vars (None,list(str)) – List of variable name that will be not loaded
include_vars (None,list(str)) – If defined only this variable will be loaded
indexs (None,dict) – Indexes to load only a slice of data
buffer_size (int) – Size of buffer used to load zarr data
class_kwargs – argument to set up observations class

Returns:

Obsevations selected

Return type:

class

mask_from_polygons(polygons)[source]¶

Return mask for all observations in one of polygons list

Parameters:: polygons (list((array,array))) – list of x/y array which be used to identify observations

mask_function(other, distance)[source]¶

match(other, i_self=None, i_other=None, method='overlap', intern=False, cmin=0, **kwargs)[source]¶

Return index and score computed on the effective contour.

Parameters:

other (EddiesObservations) – Observations to compare
i_self (array[bool,int],None) – Index or mask to subset observations, it could avoid to build a specific dataset.
i_other (array[bool,int],None) – Index or mask to subset observations, it could avoid to build a specific dataset.
method (str) –
- “overlap”: the score is computed with contours;
- ”circle”: circles are computed and used for score (TODO)
intern (bool) – if True, speed contour is used (default = effective contour)
cmin (float) – 0 < cmin < 1, return only couples with score >= cmin
kwargs (dict) – look at vertice_overlap()

Returns:

return the indices of the eddies in self coupled with eddies in other and their associated score

Return type:

(array(int), array(int), array(float))

Stastics on identification files

Eddy detection and filter

Eddy detection on SLA and ADT

Eddy detection : Antartic Circumpolar Current

merge(other)[source]¶: Merge two datasets.

merge_filters(*filters)[source]¶

Compute an intersection between all filters after to evaluate each of them

Parameters:: filters (list(callable,None,slice,array[int],array[bool])) –
Returns:: Return applicable object to numpy.array
Return type:: slice, index, mask

property nb_days¶

Return period in days covered by the dataset

Returns:: Number of days
Return type:: int

classmethod needed_variable()[source]¶

static netcdf_create_dimensions(handler, dim, nb)[source]¶

classmethod new_like(eddies, new_size: int)[source]¶

property obs¶: Return observations.

classmethod obs_dimension(handler)[source]¶

observations¶

only_variables¶

parse_varname(name)[source]¶

property period¶

Give the time coverage. If collection is empty, return nan,nan

Returns:: first and last date
Return type:: (int,int)

period_¶

post_process_link(other, i_self, i_other)[source]¶

propagate(previous_obs, current_obs, obs_to_extend, dead_track, nb_next, model)[source]¶

Fill virtual obs (C).

Parameters:

previous_obs – previous obs from current (A)
current_obs – previous obs from virtual (B)
obs_to_extend –
dead_track –
nb_next –
model –

Returns:

New position C = B + AB

raw_data¶

static re_reference_index(index, ref)[source]¶

Shift index with ref

Parameters:

index (array,int) – local index to re ref
ref (slice,array) – reference could be a slice in this case we juste add start to index or could be indices and in this case we need to translate

remove_fields(*fields)[source]¶: Copy with fields listed remove

reset()[source]¶

scatter(ax, name=None, ref=None, factor=1, **kwargs)[source]¶

Scatter data.

Parameters:

ax (matplotlib.axes.Axes) – matplotlib axe used to draw
name (str,array,None) – variable used to fill the contour, if None all elements have the same color
ref (float,None) – if defined, all coordinates are wrapped with ref as western boundary
factor (float) – multiply value by
kwargs (dict) – look at matplotlib.axes.Axes.scatter()

Returns: