documentation improved (AntSimi#34)

Author: CoriPegliasco

notebooks/python_module/02_eddy_identification/pet_filter_and_detection.ipynb

@@ -176,7 +176,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.7.7"
+      "version": "3.7.6"
     }
   },
   "nbformat": 4,

src/py_eddy_tracker/observations/observation.py

@@ -70,7 +70,7 @@
 @njit(cache=True, fastmath=True)
 def shifted_ellipsoid_degrees_mask2(lon0, lat0, lon1, lat1, minor=1.5, major=1.5):
     """
-    work only if major is an array but faster * 6
+    Work only if major is an array but faster * 6
     """
     # c = (major ** 2 - minor ** 2) ** .5 + major
     c = major
@@ -189,7 +189,8 @@ def _repr_html_(self):
         return f"""<b>{infos['nb_obs']} observations from {infos['t0']} to {infos['t1']} </b>"""
 
     def hist(self, varname, x, bins, percent=False, mean=False, nb=False):
-        """
+        """ Build histograms.
+
             :param str varname: variable to use to compute stat
             :param str x: variable to use to know in which bins
             :param array bins:
@@ -216,7 +217,7 @@ def box_display(value):
 
     def __repr__(self):
         """
-        Return general informations on dataset as a string
+        Return general informations on dataset as strings.
 
         :return: informations on datasets
         :rtype: str
@@ -292,7 +293,7 @@ def obs_dimension(cls, handler):
 
     def add_fields(self, fields=list(), array_fields=list()):
         """
-        Add a new field
+        Add a new field.
         """
         nb_obs = self.obs.shape[0]
         new = self.__class__(
@@ -321,7 +322,7 @@ def add_rotation_type(self):
 
     def circle_contour(self, only_virtual=False):
         """
-        Set contour as a circle with radius and center data
+        Set contours as a circles from radius and center data.
 
         .. minigallery:: py_eddy_tracker.EddiesObservations.circle_contour
         """
@@ -346,7 +347,7 @@ def circle_contour(self, only_virtual=False):
 
     @property
     def dtype(self):
-        """Return dtype to build numpy array
+        """Return dtype to build numpy array.
         """
         dtype = list()
         for elt in self.elements:
@@ -363,7 +364,7 @@ def dtype(self):
 
     @property
     def elements(self):
-        """Return all the names of the variables
+        """Return all the names of the variables.
         """
         elements = [i for i in self.ELEMENTS]
         if self.track_array_variables > 0:
@@ -376,7 +377,7 @@ def elements(self):
         return list(set(elements))
 
     def coherence(self, other):
-        """Check coherence between two dataset
+        """Check coherence between two datasets.
         """
         test = self.track_extra_variables == other.track_extra_variables
         test *= self.track_array_variables == other.track_array_variables
@@ -402,7 +403,7 @@ def concatenate(cls, observations):
         return eddies
 
     def merge(self, other):
-        """Merge two dataset
+        """Merge two datasets.
         """
         nb_obs_self = len(self)
         nb_obs = nb_obs_self + len(other)
@@ -424,7 +425,7 @@ def reset(self):
 
     @property
     def obs(self):
-        """Return an array observations
+        """Return observations.
         """
         return self.observations
 
@@ -437,7 +438,7 @@ def __iter__(self):
 
     def iter_on(self, xname, bins=None):
         """
-        Yield observation group for each bin
+        Yield observation group for each bin.
 
         :param str varname:
         :param array bins: bounds of each bin ,
@@ -467,7 +468,7 @@ def iter_on(self, xname, bins=None):
 
     def align_on(self, other, var_name="time", **kwargs):
         """
-        Align the time indexes of two datasets
+        Align the time indexes of two datasets.
         """
         iter_self, iter_other = (
             self.iter_on(var_name, **kwargs),
@@ -486,7 +487,7 @@ def align_on(self, other, var_name="time", **kwargs):
             yield indexs_self, indexs_other, b0_self, b1_self
 
     def insert_observations(self, other, index):
-        """Insert other obs in self at the index
+        """Insert other obs in self at the index.
         """
         if not self.coherence(other):
             raise Exception("Observations with no coherence")
@@ -508,7 +509,7 @@ def insert_observations(self, other, index):
         return self
 
     def append(self, other):
-        """Merge
+        """Merge.
         """
         return self + other
 
@@ -517,7 +518,7 @@ def __add__(self, other):
 
     def distance(self, other):
         """ Use haversine distance for distance matrix between every self and
-        other eddies"""
+        other eddies."""
         return distance_grid(
             self.obs["lon"], self.obs["lat"], other.obs["lon"], other.obs["lat"]
         )
@@ -534,7 +535,7 @@ def new_like(eddies, new_size):
         )
 
     def index(self, index, reverse=False):
-        """Return obs from self at the index
+        """Return obs from self at the index.
         """
         if reverse:
             index = reverse_index(index, len(self))
@@ -559,7 +560,7 @@ def zarr_dimension(filename):
     @classmethod
     def load_file(cls, filename, **kwargs):
         """
-        Load the netcdf or the zarr file
+        Load the netcdf or the zarr file.
 
         Load only latitude and longitude on the first 300 obs :
 
@@ -573,6 +574,10 @@ def load_file(cls, filename, **kwargs):
                 indexs=dict(obs=slice(0, 300)),
             )
             small_dataset = TrackEddiesObservations.load_file(filename, **kwargs_latlon_300)
+        
+        Default **kwargs to load zarr are : raw_data=False, remove_vars=None, include_vars=None
+
+        Default **kwargs to load netcdf are : raw_data=False, remove_vars=None, include_vars=None, indexs=None
         """
         filename_ = (
             filename.filename if isinstance(filename, ExFileObject) else filename
@@ -843,7 +848,7 @@ def propagate(
         self, previous_obs, current_obs, obs_to_extend, dead_track, nb_next, model
     ):
         """
-        Filled virtual obs (C)
+        Filled virtual obs (C).
 
         :param previous_obs: previous obs from current (A)
         :param current_obs: previous obs from virtual (B)
@@ -902,16 +907,17 @@ def intern(flag, public_label=False):
         return labels
 
     def match(self, other, method="overlap", intern=False, cmin=0, **kwargs):
-        """Return index and score computed with the chosen method on the effective contour
+        """Return index and score computed on the effective contour.
 
         :param EddiesObservations other: Observations to compare
         :param str method:
             - "overlap": the score is computed with contours;
-            - "circle": circles are computed and used for score
+            - "circle": circles are computed and used for score (TODO)
         :param bool intern: if True, speed contour is used (default = effective contour)
         :param float cmin: 0 < cmin < 1, return only couples with score >= cmin
-        :param dict kwargs: look at :py:meth:`py_eddy_tracker.poly.vertice_overlap`
-        :return: return the indexes of the eddies in self coupled with eddies in other and their associated score
+        :param dict kwargs: look at :py:meth:`vertice_overlap`
+        :return: return the indexes of the eddies in self coupled with eddies in
+        other and their associated score
         :rtype: (array(int), array(int), array(float))
 
         .. minigallery:: py_eddy_tracker.EddiesObservations.match
@@ -980,13 +986,14 @@ def mask_function(self, other, distance):
 
     @staticmethod
     def cost_function(records_in, records_out, distance):
-        """Return cost function between obs to associate
+        """Return the cost function between two obs.
 
-        .. code-block:: python
+        .. math::
 
-            cost = sqrt(((amplitude_in - amplitude_out) / amplitude_in) ** 2 +
-                        ((speed_radius_in - speed_radius_out) / speed_radius_in) ** 2 +
-                        (distance / 125) ** 2)
+            cost = \sqrt{({Amp_{_{in}} - Amp_{_{out}} \over Amp_{_{in}}}) ^2 +
+              ({Rspeed_{_{in}} - Rspeed_{_{out}} \over Rspeed_{_{in}}}) ^2 + 
+              ({distance \over 125}) ^2
+            }
 
         :param records_in: starting observations
         :param records_out: observations to associate
@@ -1098,7 +1105,7 @@ def solve_conflict(cost):
 
     @staticmethod
     def solve_simultaneous(cost):
-        """Write something"""
+        """Write something (TODO)"""
         mask = ~cost.mask
         # Count number of link by self obs and other obs
         self_links = mask.sum(axis=1)
@@ -1470,7 +1477,7 @@ def set_global_attr_netcdf(self, h_nc):
 
     def extract_with_area(self, area, **kwargs):
         """
-        Extract geographically with a bounding box
+        Extract geographically with a bounding box.
 
         :param dict area: 4 coordinates in a dictionary to specify bounding box (lower left corner and upper right corner)
         :param dict kwargs: look at :py:meth:`extract_with_mask`
@@ -1491,7 +1498,7 @@ def extract_with_area(self, area, **kwargs):
 
     def extract_with_mask(self, mask):
         """
-        Extract a subset of observations
+        Extract a subset of observations.
 
         :param array(bool) mask: mask to select observations
         :return: same object with selected observations
@@ -1517,6 +1524,8 @@ def extract_with_mask(self, mask):
 
     def scatter(self, ax, name=None, ref=None, factor=1, **kwargs):
         """
+        Scatter data.
+
         :param matplotlib.axes.Axes ax: matplotlib axe used to draw
         :param str, None name:
             variable used to fill the contour, if None all elements have the same color