minor changes (testing fork)

Author: CoriPegliasco

src/py_eddy_tracker/observations/observation.py

@@ -68,7 +68,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
@@ -203,7 +203,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:
@@ -230,7 +231,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
@@ -282,7 +283,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__(
@@ -311,7 +312,7 @@ def add_rotation_type(self):
 
     def circle_contour(self):
         """
-        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
         """
@@ -334,7 +335,7 @@ def circle_contour(self):
 
     @property
     def dtype(self):
-        """Return dtype to build numpy array
+        """Return dtype to build numpy array.
         """
         dtype = list()
         for elt in self.elements:
@@ -351,7 +352,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:
@@ -364,7 +365,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
@@ -390,7 +391,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)
@@ -412,7 +413,7 @@ def reset(self):
 
     @property
     def obs(self):
-        """Return an array observations
+        """Return an array observations.
         """
         return self.observations
 
@@ -425,7 +426,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 ,
@@ -455,7 +456,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),
@@ -474,7 +475,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")
@@ -496,7 +497,7 @@ def insert_observations(self, other, index):
         return self
 
     def append(self, other):
-        """Merge
+        """Merge.
         """
         return self + other
 
@@ -505,7 +506,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"]
         )
@@ -522,7 +523,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))
@@ -547,21 +548,24 @@ 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 :
 
-        ```python
-        kwargs_latlon_300 = dict(
-            include_vars=[
-            "longitude",
-            "latitude",
-            ],
-            indexs=dict(obs=slice(0, 300)),
-        )
-        small_dataset = TrackEddiesObservations.load_file(
-            nc_file.nc,
-            **kwargs_latlon_300)
-        ```
+        .. code-block:: python
+
+            kwargs_latlon_300 = dict(
+                include_vars=[
+                "longitude",
+                "latitude",
+                ],
+                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
@@ -832,7 +836,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)
@@ -891,12 +895,12 @@ 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
+            - "overlap": the score is computed with contours;
+            - "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:`vertice_overlap`
@@ -970,12 +974,14 @@ def mask_function(self, other, distance):
 
     @staticmethod
     def cost_function(records_in, records_out, distance):
-        """Return cost function between obs to associate
-        ```python
-        CF = sqrt ( [( amplitude_in - amplitude_out)/amplitude_in]^2 +
-                    [( speed_radius_in - speed_radius_out)/speed_radius_in]^2 +
-                    [ distance / 125]^2 )
-        ```
+        """Return the cost function between two obs
+
+        .. math::
+
+            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
@@ -1087,7 +1093,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)
@@ -1459,16 +1465,18 @@ 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)
-        ```python
-        area = dict(llcrnrlon=x0, llcrnrlat=y0, urcrnrlon=x1, urcrnrlat=y1)
-        ```
-        :param dict kwargs: look at :py:meth:`extract_with_mask`
+        .. code-block:: python
+
+            area = dict(llcrnrlon=x0, llcrnrlat=y0, urcrnrlon=x1, urcrnrlat=y1)
+
+	:param dict kwargs: look at :py:meth:`extract_with_mask`
         :return: Return all eddy tracks which are in bounds
         :rtype: EddiesObservations
 
+        
         .. minigallery:: py_eddy_tracker.EddiesObservations.extract_with_area
         """
         mask = (self.latitude > area["llcrnrlat"]) * (self.latitude < area["urcrnrlat"])
@@ -1479,7 +1487,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
@@ -1505,6 +1513,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
@@ -1604,6 +1614,7 @@ def display(
         self, ax, ref=None, extern_only=False, intern_only=False, nobs=True, **kwargs
     ):
         """Plot the speed and effective (dashed) contour of the eddies
+
         :param matplotlib.axes.Axes ax: matplotlib axe used to draw
         :param float,None ref: western longitude reference used
         :param bool extern_only: if True, draw only the effective contour