Merge pull request #117 from knutfrode/dev

Dev

Author: knutfrode

docs/source/conf.py

@@ -40,27 +40,34 @@
 }
 
 extensions = [
+    #"sphinxcontrib.mermaid",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.napoleon",
     'sphinx.ext.duration',
     'sphinx.ext.doctest',
     'sphinx.ext.autodoc',
-    # 'autoapi.extension',
+    'autoapi.extension',
     'sphinx.ext.autosummary',
     'sphinx_autosummary_accessors',
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinx.ext.mathjax',
     'sphinx_gallery.gen_gallery',
-    'numpydoc',
+    #'numpydoc',
     'matplotlib.sphinxext.plot_directive',
 ]
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
+    'numpy': ('https://numpy.org/doc/stable', None),
+    'matplotlib': ('https://matplotlib.org/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy', None),
+    'cftime': ('https://unidata.github.io/cftime', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
-    "xarray": ("https://xarray.pydata.org/en/stable/", None),
-    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
+    'xarray': ('https://xarray.pydata.org/en/stable/', None),
+    'pandas': ("https://pandas.pydata.org/pandas-docs/stable", None),
 }
-intersphinx_disabled_domains = ['std']
+#intersphinx_disabled_domains = ['std']
 
 templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
 
@@ -77,16 +84,81 @@
 }
 
 autosummary_generate = True
-
-autodoc_typehints = "description"
+autodoc_typehints = "none"
 autodoc_typehints_description_target = "documented"
 autodoc_default_options = {
     "members": True,
     "undoc-members": True,
     "private-members": True,
 }
-napoleon_use_param = True
-napoleon_use_rtype = True
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = False
+napoleon_use_ivar = True
+napoleon_use_rtype = False
+napoleon_preprocess_types = True
+napoleon_type_aliases = {
+    # general terms
+    "sequence": ":term:`sequence`",
+    "iterable": ":term:`iterable`",
+    "callable": ":py:func:`callable`",
+    "dict_like": ":term:`dict-like <mapping>`",
+    "dict-like": ":term:`dict-like <mapping>`",
+    "path-like": ":term:`path-like <path-like object>`",
+    "mapping": ":term:`mapping`",
+    "file-like": ":term:`file-like <file-like object>`",
+    # special terms
+    # "same type as caller": "*same type as caller*",  # does not work, yet
+    # "same type as values": "*same type as values*",  # does not work, yet
+    # stdlib type aliases
+    "MutableMapping": "~collections.abc.MutableMapping",
+    "sys.stdout": ":obj:`sys.stdout`",
+    "timedelta": "~datetime.timedelta",
+    "string": ":class:`string <str>`",
+    # numpy terms
+    "array_like": ":term:`array_like`",
+    "array-like": ":term:`array-like <array_like>`",
+    "scalar": ":term:`scalar`",
+    "array": ":term:`array`",
+    "hashable": ":term:`hashable <name>`",
+    # matplotlib terms
+    "color-like": ":py:func:`color-like <matplotlib.colors.is_color_like>`",
+    "matplotlib colormap name": ":doc:`matplotlib colormap name <matplotlib:gallery/color/colormap_reference>`",
+    "matplotlib axes object": ":py:class:`matplotlib axes object <matplotlib.axes.Axes>`",
+    "colormap": ":py:class:`colormap <matplotlib.colors.Colormap>`",
+    # xarray terms
+    "dim name": ":term:`dimension name <name>`",
+    "var name": ":term:`variable name <name>`",
+    # objects without namespace: xarray
+    "DataArray": "~xarray.DataArray",
+    "Dataset": "~xarray.Dataset",
+    "Variable": "~xarray.Variable",
+    "DataTree": "~xarray.DataTree",
+    "DatasetGroupBy": "~xarray.core.groupby.DatasetGroupBy",
+    "DataArrayGroupBy": "~xarray.core.groupby.DataArrayGroupBy",
+    "Grouper": "~xarray.groupers.Grouper",
+    "Resampler": "~xarray.groupers.Resampler",
+    # objects without namespace: numpy
+    "ndarray": "~numpy.ndarray",
+    "MaskedArray": "~numpy.ma.MaskedArray",
+    "dtype": "~numpy.dtype",
+    "ComplexWarning": "~numpy.ComplexWarning",
+    # objects without namespace: pandas
+    "Index": "~pandas.Index",
+    "MultiIndex": "~pandas.MultiIndex",
+    "CategoricalIndex": "~pandas.CategoricalIndex",
+    "TimedeltaIndex": "~pandas.TimedeltaIndex",
+    "DatetimeIndex": "~pandas.DatetimeIndex",
+    "IntervalIndex": "~pandas.IntervalIndex",
+    "Series": "~pandas.Series",
+    "DataFrame": "~pandas.DataFrame",
+    "Categorical": "~pandas.Categorical",
+    "Path": "~~pathlib.Path",
+    # objects with abbreviated namespace (from pandas)
+    "pd.Index": "~pandas.Index",
+    "pd.NaT": "~pandas.NaT",
+}
 
 # numpydoc_show_class_members = False
 # Report warnings for all validation checks except the ones listed after "all"

trajan/traj.py

@@ -593,33 +593,33 @@ def seltime(self, t0=None, t1=None) -> xr.Dataset:
 
 
     @abstractmethod
-    def skill(self, other, method='liu-weissberg', **kwargs) -> xr.DataArray:
+    def skill(self, other, method='liu-weissberg', **kwargs) -> xr.Dataset:
         """
         Compare the skill score between this trajectory and `other`.
 
         Parameters
         ----------
 
-        other: Another trajectory dataset.
+        other : Dataset
+            Another trajectory dataset.
 
-        method: skill-score method, currently only liu-weissberg. See :mod:`trajan.skill`.
+        method : str
+            skill-score method, currently only liu-weissberg.
 
-        **kwargs: passed on to the skill-score method.
+        **kwargs :
+            Passed on to the skill-score method.
 
         Returns
         -------
 
-        skill: The skill-score in the same dimensions as this dataset.
+        skill : :class:`xarray.Dataset`
+            The skill-score in the same dimensions as this dataset.
 
-        .. note::
-
-            The datasets must be sampled (or have observations) at approximately the same timesteps. Consider using :meth:`trajan.traj2d.gridtime` to interpolate one of the datasets to the other.
-
-
-        .. note::
-
-            The datasets must have the same number of trajectories. If you wish to compare a single trajectory to many others, duplicate it along the trajectory dimension to match the trajectory dimension of the other. See further down for an example.
+        Notes
+        -----
+        The datasets must be sampled (or have observations) at approximately the same timesteps. Consider using :meth:`gridtime` to interpolate one of the datasets to the other.
 
+        The datasets must have the same number of trajectories. If you wish to compare a single trajectory to many others, duplicate it along the trajectory dimension to match the trajectory dimension of the other. See further down for an example.
 
         Examples
         --------
@@ -634,37 +634,29 @@ def skill(self, other, method='liu-weissberg', **kwargs) -> xr.DataArray:
         >>> other = other.traj.gridtime(ds.time)
         >>> skill = ds.traj.skill(other)
 
-        >>> print(skill)
-        <xarray.DataArray 'Skill-score' (trajectory: 2)> Size: 8B
+        >>> skill
+        <xarray.DataArray 'Skillscore' (trajectory: 2)> Size: 8B
         array([1., 1.], dtype=float32)
         Coordinates:
           * trajectory  (trajectory) int64 16B 0 1
         Attributes:
             method:   liu-weissberg
 
-
         If you need to broadcast a dataset with a single drifter to one with many you can use `xarray.broadcast` or `xarray.Dataset.broadcast_like`:
 
         .. note::
 
             If the other dataset has any other dimensions, on any other variables, you need to exclude those when broadcasting.
 
-        .. testcode::
-
-            b0 = ds.isel(trajectory=0) # `b0` now only has a single drifter (no trajectory dimension)
-
-            b0 = b0.broadcast_like(ds)
-            skill = b0.traj.skill(ds)
-
-            print(skill)
-
-        .. testoutput::
-
-            <xarray.DataArray 'Skill-score' (trajectory: 2)>
-            array([1.        , 0.60894716], dtype=float32)
-            Coordinates:
-              * trajectory  (trajectory) int64 0 1
-            Attributes:
-                method:   liu-weissberg
+        >>> b0 = ds.isel(trajectory=0) # `b0` now only has a single drifter (no trajectory dimension)
+        >>> b0 = b0.broadcast_like(ds)
+        >>> skill = b0.traj.skill(ds)
 
+        >>> skill
+        <xarray.DataArray 'Skillscore' (trajectory: 2)> Size: 8B
+        array([1.      , 0.608058], dtype=float32)
+        Coordinates:
+          * trajectory  (trajectory) int64 16B 0 1
+        Attributes:
+            method:   liu-weissberg
         """

trajan/traj1d.py

@@ -122,7 +122,7 @@ def skill(self, other, method='liu-weissberg', **kwargs):
                 raise ValueError(f"Unknown skill-score method: {method}.")
 
         return xr.DataArray(s,
-                            name='Skill-score',
+                            name='Skillscore',
                             coords={'trajectory': self.ds.trajectory},
                             attrs={'method': method})