py_eddy_tracker.observations.network.NetworkObservations

class py_eddy_tracker.observations.network.NetworkObservations(*args, **kwargs)

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 given segments
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_longer_than	Select network on time duration
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_mask	Get mask from list of segment
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.
swap_track
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
time_datetime64
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)

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)

birth_event()

Extract birth events.

close_network(other, nb_obs_min=10, **kwargs)

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)

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)

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

Extract death events.

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

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

Dissociate networks with no known interaction (splitting/merging)

property elements

Return all the names of the variables.

event_map(ax, **kwargs)

Add the merging and splitting events to a map

event_timeline(ax, field=None, method=None, factor=1, colors_mode='roll')

Mark events in plot

extract_event(indices)

extract_light_with_mask(mask, track_extra_variables=[])

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)

Extract given segments

Parameters:

• segments (array,tuple,list) – list of segment to extract

• absolute (bool) – keep for compatibility, defaults to False

Return NetworkObservations:

Return observations from selected segment

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

extract_with_period(period)

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)

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)

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

Check if first network is Trash

Return bool:

True if first network is trash

fix_next_previous_obs()

Function used after ‘insert_virtual’, to correct next_obs and previous obs.

classmethod from_split_network(group_dataset, indexs, **kwargs)

Build a NetworkObservations object with Group dataset and indices

Parameters:

• group_dataset (TrackEddiesObservations) – Group dataset

• indexs – result from split_network

Returns:

NetworkObservations

fully_connected()

Suspicious

generation_event()

Extract birth events.

get_mask_with_period(period)

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)

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)

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

loess_filter(half_window, xfield, yfield, inplace=True)

longer_than(nb_day_min=-1, nb_day_max=-1)

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)

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)

mask_longer_than(nb_day_min=-1, nb_day_max=-1)

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

mask_obs_close_event(merging=True, spliting=True, dt=3)

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)

median_filter(half_window, xfield, yfield, inplace=True)

merging_event(triplet=False, only_index=False)

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)

network_segment(id_network, id_segment)

network_segment_size(id_networks=None)

Get number of segment by network

Return array:

network_size(id_networks=None)

Return size for specified network

Parameters:

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

network_slice(id_network)

Return slice for one network

Parameters:

id_network (int) – id to identify network

networks(id_networks)

networks_mask(id_networks, segment=False)

normalize_longitude()

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)

New numbering of network

numbering_segment(start=0)

New numbering of segment

obs_relative_order(i_obs)

only_one_network()

Raise a warning or error? if there are more than one network

plot(ax, ref=None, color_cycle=None, **kwargs)

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)

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)

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)

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

Remove the lonely eddies (only 1 obs in segment, associated network number is 0)

reset_index()

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

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)

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

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)

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_mask(segments)

Get mask from list of segment

Parameters:

segments (list,array) – absolute id of segment

segment_relative_order(seg_origine)

Compute the relative order of each segment to the chosen segment

segment_size()

segment_slice(id_network, id_segment)

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

Sort observations

Parameters:

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

splitting_event(triplet=False, only_index=False)

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.

swap_track(length_main_max_after_event=2, length_secondary_min_after_event=10, delta_pct_max=-0.2)

tag_segment()

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)

Return id network and id segment for a unique id

Parameters:

id_unique (array) –