py_eddy_tracker.observations.network.NetworkObservations¶

class py_eddy_tracker.observations.network.NetworkObservations(*args, **kwargs)[source]¶

Bases: GroupEddiesObservations

Methods

`add_fields`	Add a new field.
`add_rotation_type`
`align_on`	Align the variable indices of two datasets.
`analysis_coherence`	Global function to analyse segments coherence, with network preprocessing. :param callable date_function: python function, takes as param int (julian day) and return data filename associated to the date :param dict uv_params: dict of parameters used by `from_netcdf_list()` :param int n_days: nuber of days for advection :param float step_mesh: step for particule mesh in degrees :param str output_name: path/name for the output (without extension) to store the clean network in .nc and the coherence results in .zarr. Works only for advection_mode = "both" :param bool dissociate_network: If True apply `dissociate_network()` :param int correct_close_events: Number of days in `correct_close_events()` :param int remove_dead_end: Number of days in `remove_dead_end()` :return target_forward, target_bakward: 2D numpy.array with the eddy observation the particles ended in after advection :return target_forward, target_bakward: percentage of ending particles within the eddy observation with regards to the starting number.
`append`	Merge.
`astype`
`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
`birth_event`	Extract birth events.
`box_display`	Return values evenly spaced with few numbers
`build_var_list`
`circle_contour`	Set contours as circles from radius and center data.
`close_network`	Get close network from another atlas.
`coherence`	Check coherence between two datasets.
`compare_units`
`concatenate`
`connexions`	Create dictionnary for each segment, gives the segments in interaction with
`contains`	Return index of contour containing (x,y)
`copy`
`copy_data_to_zarr`	Copy with buffer for zarr.
`correct_close_events`	Transform event where segment A splits from segment B, then x days after segment B merges with A to segment A splits from segment B then x days after segment A merges with B (B will be longer) These events have to last less than nb_days_max to be changed.
`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`
`death_event`	Extract death events.
`display`	Plot the speed and effective (dashed) contour of the eddies
`display_color`	Plot colored contour of eddies
`display_timeline`	Plot the timeline of a network.
`dissipation_event`	Extract death events.
`dissociate_network`	Dissociate networks with no known interaction (splitting/merging)
`distance`	Use haversine distance for distance matrix between every self and other eddies.
`empty_dataset`
`event_map`	Add the merging and splitting events to a map
`event_timeline`	Mark events in plot
`extract_event`
`extract_light_with_mask`	extract data with mask, but only with variables used for coherence, aka self.array_variables
`extract_segment`
`extract_with_area`	Extract geographically with a bounding box.
`extract_with_mask`	Extract a subset of observations.
`extract_with_period`	Extract within a time period
`field_table`	Produce description table of the fields available in this object
`fill_coherence`	_summary_
`filled`	param matplotlib.axes.Axes ax matplotlib axe used to draw
`filled_by_interpolation`	Fill selected values by interpolation
`find_link`	Find all observations where obs i_observation could be in future or past.
`find_segments_relative`	Find all relative segments from obs linked with merging/splitting events at a specific order.
`first_is_trash`	Check if first network is Trash
`first_obs`	Get first obs of each trajectory.
`fix_next_previous_obs`	Function used after 'insert_virtual', to correct next_obs and previous obs.
`fixed_ellipsoid_mask`
`format_label`
`from_array`
`from_netcdf`
`from_split_network`	Build a NetworkObservations object with Group dataset and indices
`from_zarr`
`fully_connected`	Suspicious
`generation_event`	Extract birth events.
`get_color`	Return colors as a cyclic list
`get_filters_zarr`	Get filters to store in zarr for known variable
`get_infos`
`get_mask_with_period`	obtain mask within a time period
`get_missing_indices`	Find indices where observations are missing.
`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.
`identify_in`	Return couple of segment or network which are equal
`index`	Return obs from self at the index.
`infos`
`insert_observations`	Insert other obs in self at the given index.
`insert_virtual`	Insert virtual observations on segments where observations are missing
`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.
`keep_tracks_by_date`	Find tracks that exist at date date and lasted at least nb_days after.
`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.
`loess_filter`
`longer_than`	Select network on time duration
`map_network`	Transform data y with method method for each track.
`map_segment`
`mask_from_polygons`	Return mask for all observations in one of polygons list
`mask_function`
`mask_obs_close_event`	Build a mask of close observation from event
`match`	Return index and score computed on the effective contour.
`mean_by_segment`
`median_filter`
`merge`	Merge two datasets.
`merge_filters`	Compute an intersection between all filters after to evaluate each of them
`merge_particle_result`	Copy local result in merged result with global indexation
`merging_event`	Return observation after a merging event.
`needed_variable`
`netcdf_create_dimensions`
`network`
`network_segment`
`network_segment_size`	Get number of segment by network
`network_size`	Return size for specified network
`network_slice`	Return slice for one network
`networks`
`networks_mask`
`new_like`
`normalize_longitude`	Normalize all longitudes
`numbering_network`	New numbering of network
`numbering_segment`	New numbering of segment
`obs_dimension`
`obs_relative_order`
`only_one_network`	Raise a warning or error? if there are more than one network
`parse_varname`
`particle_candidate_atlas`	Select particles within eddies, advect them, return target observation and associated percentages
`plot`	This function draws the path of each trajectory
`position_filter`
`post_process_link`
`propagate`	Fill virtual obs (C).
`re_reference_index`	Shift index with ref
`relative`	Extract the segments at a certain order from multiple observations.
`relatives`	Extract the segments at a certain order from multiple observations.
`remove_dead_end`	Remove short segments that don't connect several segments
`remove_fields`	Copy with fields listed remove
`remove_trash`	Remove the lonely eddies (only 1 obs in segment, associated network number is 0)
`reset`
`reset_index`
`scatter`	This function scatters the path of each network, with the merging and splitting events
`scatter_timeline`	Must be called on only one network
`segment_coherence_backward`	Percentage of particules and their targets after backward advection from a specific eddy.
`segment_coherence_forward`	Percentage of particules and their targets after forward advection from a specific eddy.
`segment_relative_order`	Compute the relative order of each segment to the chosen segment
`segment_size`
`segment_slice`	Return slice for one segment
`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.
`sort`	Sort observations
`splitting_event`	Return observation before a splitting event.
`tag_segment`	For each segment, method give a new network id, and all segment are connected
`time_sub_sample`	Time sub sampling
`to_netcdf`
`to_zarr`
`tracking`	Track obs between self and other
`unique_segment_to_id`	Return id network and id segment for a unique id
`write_file`	Write a netcdf or zarr with eddy obs.
`zarr_dimension`

Attributes

`COLORS`
`ELEMENTS`
`NB_COLORS`
`NOGROUP`
`array_variables`
`dtype`	Return dtype to build numpy array.
`elements`	Return all the names of the variables.
`fields`
`global_attr`
`index_network`
`index_segment_track`
`nb_days`	Return period in days covered by the dataset
`nb_network`	Count and return number of network
`nb_segment`	Count and return number of segment in all network
`obs`	Return observations.
`observations`
`only_variables`
`period`	Give the time coverage.
`period_`
`raw_data`
`ref_index`
`ref_segment_track_index`
`segment_track_array`	Return a unique segment id when multiple networks are considered
`shape`
`sign_legend`
`sign_type`
`track_array_variables`
`track_extra_variables`
`tracks`

NOGROUP = 0¶

analysis_coherence(date_function, uv_params, advection_mode='both', n_days=14, step_mesh=0.02, output_name=None, dissociate_network=False, correct_close_events=0, remove_dead_end=0)[source]¶

Global function to analyse segments coherence, with network preprocessing. :param callable date_function: python function, takes as param int (julian day) and return

data filename associated to the date

Parameters

uv_params (dict) – dict of parameters used by from_netcdf_list()
n_days (int) – nuber of days for advection
step_mesh (float) – step for particule mesh in degrees
output_name (str) – path/name for the output (without extension) to store the clean network in .nc and the coherence results in .zarr. Works only for advection_mode = “both”
dissociate_network (bool) – If True apply dissociate_network()
correct_close_events (int) – Number of days in correct_close_events()
remove_dead_end (int) – Number of days in remove_dead_end()

Return target_forward, target_bakward

2D numpy.array with the eddy observation the particles ended in after advection

Return target_forward, target_bakward

percentage of ending particles within the eddy observation with regards to the starting number

astype(cls)[source]¶

birth_event()[source]¶: Extract birth events.

close_network(other, nb_obs_min=10, **kwargs)[source]¶

Get close network from another atlas.

Parameters

other (self) – Atlas to compare
nb_obs_min (int) – Minimal number of overlap for one trajectory
kwargs (dict) – keyword arguments for match function

Returns

return other atlas reduced to common tracks with self

Warning

It could be a costly operation for huge dataset

connexions(multi_network=False)[source]¶

Create dictionnary for each segment, gives the segments in interaction with

Parameters: multi_network (bool) – use segment_track_array instead of segment, defaults to False
Return dict: Return dict of set, for each seg id we get set of segment which have event with him

correct_close_events(nb_days_max=20)[source]¶

Transform event where segment A splits from segment B, then x days after segment B merges with A to segment A splits from segment B then x days after segment A merges with B (B will be longer) These events have to last less than nb_days_max to be changed.

——————- A

/ /

B ——————– to

–A–

/ B ———————————–

Parameters: nb_days_max (float) – maximum time to search for splitting-merging event

death_event()[source]¶: Extract death events.

display_timeline(ax, event=True, field=None, method=None, factor=1, colors_mode='roll', **kwargs)[source]¶

Plot the timeline of a network. Must be called on only one network.

Parameters

ax (matplotlib.axes.Axes) – matplotlib axe used to draw
event (bool) – if True, draw the splitting and merging events
field (str,array) – yaxis values, if None, segments are used
method (str) – if None, mean values are used
factor (float) – to multiply field
colors_mode (str) – color of lines. “roll” means looping through colors, “y” means color adapt the y values (for matching color plots)

Returns

plot mappable

dissipation_event()¶: Extract death events.

dissociate_network()[source]¶: Dissociate networks with no known interaction (splitting/merging)

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

event_map(ax, **kwargs)[source]¶: Add the merging and splitting events to a map

event_timeline(ax, field=None, method=None, factor=1, colors_mode='roll')[source]¶: Mark events in plot

extract_event(indices)[source]¶

extract_light_with_mask(mask, track_extra_variables=[])[source]¶

extract data with mask, but only with variables used for coherence, aka self.array_variables

Parameters: mask (np.array(bool)) – mask used to extract
Returns: new EddiesObservation with data wanted
Return type: self

extract_segment(segments, absolute=False)[source]¶

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

extract_with_period(period)[source]¶

Extract within a time period

Parameters: period ((int,int)) – two dates to define the period, must be specified from 1/1/1950
Returns: Return all eddy trajectories in period
Return type: NetworkObservations

find_link(i_observations, forward=True, backward=False)[source]¶

Find all observations where obs i_observation could be in future or past.

If forward=True, search all observations where water from obs “i_observation” could go

If backward=True, search all observation where water from obs i_observation could come from

Parameters

i_observation (int,iterable(int)) – indices of observation. Can be int, or iterable of int.
backward (bool forward,) – if forward, search observations after obs. else mode==backward search before obs

find_segments_relative(obs, stopped=None, order=1)[source]¶

Find all relative segments from obs linked with merging/splitting events at a specific order.

Parameters

obs (int) – index of observation after the event
stopped (int) – index of observation before the event
order (int) – order of relatives accepted

Returns

all relative segments

Return type

EddiesObservations

first_is_trash()[source]¶

Check if first network is Trash

Return bool: True if first network is trash

fix_next_previous_obs()[source]¶: Function used after ‘insert_virtual’, to correct next_obs and previous obs.

classmethod from_split_network(group_dataset, indexs, **kwargs)[source]¶

Build a NetworkObservations object with Group dataset and indices

Parameters

group_dataset (TrackEddiesObservations) – Group dataset
indexs – result from split_network

Returns

NetworkObservations

fully_connected()[source]¶: Suspicious

generation_event()¶: Extract birth events.

get_mask_with_period(period)[source]¶

obtain mask within a time period

Parameters: period ((int,int)) – two dates to define the period, must be specified from 1/1/1950
Returns: mask where period is defined
Return type: np.array(bool)

get_missing_indices(dt)[source]¶

Find indices where observations are missing.

As network have all untracked observation in tracknumber self.NOGROUP,: we don’t compute them

Parameters: dt (int,float) – theorical delta time between 2 observations

identify_in(other, size_min=1, segment=False)[source]¶

Return couple of segment or network which are equal

Parameters

other – other atlas to compare
size_min (int) – number of observation in network/segment
segment (bool) – segment mode

property index_network¶

property index_segment_track¶

infos(label='')[source]¶

loess_filter(half_window, xfield, yfield, inplace=True)[source]¶

longer_than(nb_day_min=-1, nb_day_max=-1)[source]¶

Select network on time duration

Parameters

nb_day_min (int) – Minimal number of days covered by one network, if negative -> not used
nb_day_max (int) – Maximal number of days covered by one network, if negative -> not used

map_network(method, y, same=True, return_dict=False, **kw)[source]¶

Transform data y with method method for each track.

Parameters

method (Callable) – method to apply on each track
y (np.array) – data where to apply method
same (bool) – if True, return an array with the same size than y. Else, return a list with the edited tracks
return_dict (bool) – if None, mean values are used
kw (float) – to multiply field

Returns

array or dict of result from method for each network

map_segment(method, y, same=True, **kw)[source]¶

mask_obs_close_event(merging=True, spliting=True, dt=3)[source]¶

Build a mask of close observation from event

Parameters

n – Network
merging (bool) – select merging event, defaults to True
spliting (bool) – select splitting event, defaults to True
dt (int) – delta of time max , defaults to 3

Return array

mask

mean_by_segment(y, **kw)[source]¶

median_filter(half_window, xfield, yfield, inplace=True)[source]¶

merging_event(triplet=False, only_index=False)[source]¶

Return observation after a merging event.

If triplet=True return the eddy after a merging event, the eddy before the merging event, and the eddy stopped due to merging.

property nb_network¶: Count and return number of network

property nb_segment¶: Count and return number of segment in all network

network(id_network)[source]¶

network_segment(id_network, id_segment)[source]¶

network_segment_size(id_networks=None)[source]¶

Get number of segment by network

Return array

network_size(id_networks=None)[source]¶

Return size for specified network

Parameters: id_networks (list,array, None) – ids to identify network

network_slice(id_network)[source]¶

Return slice for one network

Parameters: id_network (int) – id to identify network

networks(id_networks)[source]¶

networks_mask(id_networks, segment=False)[source]¶

normalize_longitude()[source]¶

Normalize all longitudes

Normalize longitude field and in the same range : - longitude_max - contour_lon_e (how to do if in raw) - contour_lon_s (how to do if in raw)

numbering_network(start=1)[source]¶: New numbering of network

numbering_segment(start=0)[source]¶: New numbering of segment

obs_relative_order(i_obs)[source]¶

only_one_network()[source]¶: Raise a warning or error? if there are more than one network

plot(ax, ref=None, color_cycle=None, **kwargs)[source]¶

This function draws the path of each trajectory

Parameters

ax (matplotlib.axes.Axes) – ax to draw
ref (float,int) – if defined, all coordinates are wrapped with ref as western boundary
kwargs (dict) – keyword arguments for Axes.plot

Returns

a list of matplotlib mappables

position_filter(median_half_window, loess_half_window)[source]¶

property ref_index¶

property ref_segment_track_index¶

relative(obs, order=2)¶

Extract the segments at a certain order from multiple observations.

Parameters

obs (iterable,int) – indices of observation for relatives computation. Can be one observation (int) or collection of observations (iterable(int))
order (int) – order of relatives wanted. 0 means only observations in obs, 1 means direct relatives, …

Returns

all segments’ relatives

Return type

EddiesObservations

relatives(obs, order=2)[source]¶

Extract the segments at a certain order from multiple observations.

Parameters

obs (iterable,int) – indices of observation for relatives computation. Can be one observation (int) or collection of observations (iterable(int))
order (int) – order of relatives wanted. 0 means only observations in obs, 1 means direct relatives, …

Returns

all segments’ relatives

Return type

EddiesObservations

remove_dead_end(nobs=3, ndays=0, recursive=0, mask=None)[source]¶

Remove short segments that don’t connect several segments

Parameters

nobs (int) – Minimal number of observation to keep a segment
ndays (int) – Minimal number of days to keep a segment
recursive (int) – Run method N times more
mask (int) – if one or more observation of the segment are selected by mask, the segment is kept

Warning

It will remove short segment that splits from then merges with the same segment

remove_trash()[source]¶: Remove the lonely eddies (only 1 obs in segment, associated network number is 0)

reset_index()[source]¶

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

This function scatters the path of each network, with the merging and splitting events

Parameters

ax (matplotlib.axes.Axes) – matplotlib axe used to draw
name (str,array,None) – variable used to fill the contours, if None all elements have the same color
ref (float,None) – if defined, ref is used as western boundary
factor (float) – multiply value by
edgecolor_cycle (list) – list of colors
kwargs (dict) – look at matplotlib.axes.Axes.scatter()

Returns

a dict of scattered mappables

scatter_timeline(ax, name, factor=1, event=True, yfield=None, yfactor=1, method=None, **kwargs)[source]¶: Must be called on only one network

segment_coherence_backward(date_function, uv_params, n_days=14, step_mesh=0.02, contour_start='speed', contour_end='speed')[source]¶

Percentage of particules and their targets after backward advection from a specific eddy.

Parameters

date_function (callable) – python function, takes as param int (julian day) and return data filename associated to the date (see note)
uv_params (dict) – dict of parameters used by from_netcdf_list()
n_days (int) – days for advection
step_mesh (float) – step for particule mesh in degrees

Returns

observations matchs, and percents

Note

the param date_function should be something like :

def date2file(julian_day):
    date = datetime.timedelta(days=julian_day) + datetime.datetime(
        1950, 1, 1
    )

    return f"/tmp/dt_global_{date.strftime('%Y%m%d')}.nc"

segment_coherence_forward(date_function, uv_params, n_days=14, step_mesh=0.02, contour_start='speed', contour_end='speed', **kwargs)[source]¶

Percentage of particules and their targets after forward advection from a specific eddy.

Parameters

date_function (callable) – python function, takes as param int (julian day) and return data filename associated to the date (see note)
uv_params (dict) – dict of parameters used by from_netcdf_list()
n_days (int) – days for advection
step_mesh (float) – step for particule mesh in degrees

Returns

observations matchs, and percents

Note

the param date_function should be something like :

def date2file(julian_day):
    date = datetime.timedelta(days=julian_day) + datetime.datetime(
        1950, 1, 1
    )

    return f"/tmp/dt_global_{date.strftime('%Y%m%d')}.nc"

segment_relative_order(seg_origine)[source]¶: Compute the relative order of each segment to the chosen segment

segment_size()[source]¶

segment_slice(id_network, id_segment)[source]¶

Return slice for one segment

Parameters

id_network (int) – id to identify network
id_segment (int) – id to identify segment

property segment_track_array¶: Return a unique segment id when multiple networks are considered

sort(order=('track', 'segment', 'time'))[source]¶

Sort observations

Parameters: order (tuple) – order or sorting. Given to numpy.argsort()

splitting_event(triplet=False, only_index=False)[source]¶

Return observation before a splitting event.

If triplet=True return the eddy before a splitting event, the eddy after the splitting event, and the eddy starting due to splitting.

tag_segment()[source]¶

For each segment, method give a new network id, and all segment are connected

Return array: for each unique seg id, it return new network id

unique_segment_to_id(id_unique)[source]¶

Return id network and id segment for a unique id

Parameters: id_unique (array) –