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)

Bases: object

Class to store eddy observations.

Methods

add_fields	Add a new field.
add_rotation_type
align_on	Align the time indexes of two datasets.
append	Merge.
basic_formula_ellips_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 value evenly spaced with few numbers
build_var_list
circle_contour	Set contours as a circles from radius and center data.
coherence	Check coherence between two datasets.
compare_units
concatenate
contains	Return index of contour which contain (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_variable
create_variable_zarr
display	Plot the speed and effective (dashed) contour of the eddies
distance	Use haversine distance for distance matrix between every self and other eddies.
extract_with_area	Extract geographically with a bounding box.
extract_with_mask	Extract a subset of observations.
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_netcdf
from_zarr
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 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_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	Filled virtual obs (C).
reset
scatter	Scatter data.
set_global_attr_netcdf
set_global_attr_zarr
shifted_ellipsoid_degrees_mask
solve_conflict
solve_first
solve_function
solve_simultaneous	Write something (TODO)
to_netcdf
to_zarr
tracking	Track obs between self and other
write_file	Write a netcdf or zarr with eddy obs.
zarr_dimension

Attributes

COLORS
ELEMENTS
NB_COLORS
array_variables
dtype	Return dtype to build numpy array.
elements	Return all the names of the variables.
global_attr
nb_days	Return period days cover by dataset
obs	Return observations.
observations
only_variables
period	Give the time coverage
period_
raw_data
shape
sign_legend
sign_type
track_array_variables
track_extra_variables
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=[])

Add a new field.

add_rotation_type()

align_on(other, var_name='time', **kwargs)

Align the time indexes of two datasets.

append(other)

Merge.

array_variables

static basic_formula_ellips_major_axis(lats, cmin=1.5, cmax=10.0, c0=1.5, lat1=13.5, lat2=5.0, degrees=False)

Give major axis in km with a given latitude

bins_stat(xname, bins=None, yname=None, method=None, mask=None)

Parameters

• xname (str,array) – variable to compute stats on

• None bins (array,) – 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)

Return value evenly spaced with few numbers

static build_var_list(var_list, remove_vars, include_vars)

circle_contour(only_virtual=False)

Set contours as a circles from radius and center data.

Display contour & circle

coherence(other)

Check coherence between two datasets.

static compare_units(input_unit, output_unit, name)

classmethod concatenate(observations)

contains(x, y, intern=False)

Return index of contour which contain (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()

static copy_data_to_zarr(handler_zarr, handler_eddies, sl_obs, buffer_size, factor, raw_data, scale_factor, add_offset)

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 zarr_dataset buffer_size: :param float zarr_dataset factor: :param bool zarr_dataset raw_data: :param None,float zarr_dataset scale_factor: :param None,float add_offset:

static cost_function(records_in, records_out, distance)

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)

How does it work on x bound ?

Parameters

• xy_in –

• xy_out –

• distance –

• intern (bool) –

create_variable(handler_nc, kwargs_variable, attr_variable, data, scale_factor=None, add_offset=None, **kwargs)

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

display(ax, ref=None, extern_only=False, intern_only=False, **kwargs)

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

Parameters

• ax (matplotlib.axes.Axes) – matplotlib axe used to draw

• ref (float,None) – western longitude reference used

• 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

Select pixel in eddies

Get Okubo Weis

Collocating external data

distance(other)

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.

extract_with_area(area, **kwargs)

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 tracks which are in bounds

Return type

EddiesObservations

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

Tracks which go through area

extract_with_mask(mask)

Extract a subset of observations.

Parameters

mask (array(bool)) – mask to select observations

Returns

same object with selected observations

Return type

self

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

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 define use like west bound?

• 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

first_obs()

Get first obs of each trajectory.

Return type

__class__

Birth and death

fixed_ellipsoid_mask(other, minor=50, major=100, only_east=False, shifted_ellips=False)

format_label(label)

classmethod from_netcdf(handler)

classmethod from_zarr(handler)

get_infos()

property global_attr

grid_box_stat(bins, varname, method=50, data=None, filter=slice(None, None, None))

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))

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

Count pixel used

Count center

grid_stat(bins, varname, data=None)

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)

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) – normalize 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)

Return obs from self at the index.

insert_observations(other, index)

Insert other obs in self at the index.

inside(x, y, intern=False)

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)

interp_grid(grid_object, varname, method='center', dtype=None, intern=None)

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

• method (str) – ‘center’, ‘mean’, ‘max’, ‘min’, ‘nearest’

• dtype (str) – if None we use var dtype

• intern (bool) – Use extern or intern contour

is_convex(intern=False)

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, bins=None)

Yield observation group for each bin.

Parameters

• xname (str,array) –

• bins (array) – bounds of each bin ,

Returns

Group observations

Return type

self.__class__

last_obs()

Get Last obs of each trajectory.

Return type

__class__

Birth and death

classmethod load_file(filename, **kwargs)

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)

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) – Indexs to laad 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)

Load data from zarr.

Parameters

• filename (str,store) – path or store 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) – Indexs to laad 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_function(other, distance)

match(other, method='overlap', intern=False, cmin=0, **kwargs)

Return index and score computed on the effective contour.

Parameters

• other (EddiesObservations) – Observations to compare

• 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 indexes of the eddies in self coupled with eddies in other and their associated score

Return type

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

Eddy detection and filter

Eddy detection on SLA and ADT

merge(other)

Merge two datasets.

merge_filters(*filters)

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 days cover by dataset

Returns

Number of days

Return type

int

classmethod needed_variable()

static netcdf_create_dimensions(handler, dim, nb)

classmethod new_like(eddies, new_size: int)

property obs

Return observations.

classmethod obs_dimension(handler)

observations

only_variables

parse_varname(name)

property period

Give the time coverage

Returns

first and last date

Return type

(int,int)

period_

post_process_link(other, i_self, i_other)

propagate(previous_obs, current_obs, obs_to_extend, dead_track, nb_next, model)

Filled 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

reset()

scatter(ax, name=None, ref=None, factor=1, **kwargs)

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 define use like west bound

• factor (float) – multiply value by

• kwargs (dict) – look at matplotlib.axes.Axes.scatter()

Returns

scatter mappable

Eddy detection : Med

Display fields

One Track

set_global_attr_netcdf(h_nc)

set_global_attr_zarr(h_zarr)

property shape

shifted_ellipsoid_degrees_mask(other, minor=1.5, major=1.5)

property sign_legend

sign_type

static solve_conflict(cost)

static solve_first(cost, multiple_link=False)

solve_function(cost_matrix)

static solve_simultaneous(cost)

Write something (TODO)

to_netcdf(handler, **kwargs)

to_zarr(handler, **kwargs)

track_array_variables

track_extra_variables

tracking(other)

Track obs between self and other

property tracks

write_file(path='./', filename='%(path)s/%(sign_type)s.nc', zarr_flag=False, **kwargs)

Write a netcdf or zarr with eddy obs. Zarr is usefull for large dataset > 10M observations

Parameters

• path (str) – set path variable

• filename (str) – model to store file

• zarr_flag (bool) – If True, method will use zarr format instead of netcdf

• kwargs (dict) – look at to_zarr() or to_netcdf()

static zarr_dimension(filename)