solve some docs problems, remove unused functions

docs/api.rst

@@ -0,0 +1,81 @@
+===
+API
+===
+
+.. _xsdba-user-api:
+
+xsdba Module
+===========
+
+.. automodule:: xsdba.adjustment
+   :members:
+   :exclude-members: BaseAdjustment
+   :special-members:
+   :show-inheritance:
+   :noindex:
+
+.. automodule:: xsdba.processing
+   :members:
+   :noindex:
+
+.. automodule:: xsdba.detrending
+   :members:
+   :show-inheritance:
+   :exclude-members: BaseDetrend
+   :noindex:
+
+.. automodule:: xsdba.utils
+   :members:
+   :noindex:
+
+.. autoclass:: xsdba.base.Grouper
+   :members:
+   :class-doc-from: init
+   :noindex:
+
+.. automodule:: xsdba.nbutils
+   :members:
+   :noindex:
+
+.. automodule:: xsdba.loess
+   :members:
+   :noindex:
+
+.. automodule:: xsdba.properties
+   :members:
+   :exclude-members: StatisticalProperty
+   :noindex:
+
+.. automodule:: xsdba.measures
+   :members:
+   :exclude-members: StatisticalMeasure
+   :noindex:
+
+.. _`xsdba-developer-api`:
+
+xsdba Utilities
+--------------
+
+.. automodule:: xsdba.base
+   :members:
+   :show-inheritance:
+   :exclude-members: Grouper
+   :noindex:
+
+.. autoclass:: xsdba.detrending.BaseDetrend
+   :members:
+   :noindex:
+
+.. autoclass:: xsdba.adjustment.TrainAdjust
+   :members:
+   :noindex:
+
+.. autoclass:: xsdba.adjustment.Adjust
+   :members:
+   :noindex:
+
+.. autofunction:: xsdba.properties.StatisticalProperty
+   :noindex:
+
+.. autofunction:: xsdba.measures.StatisticalMeasure
+   :noindex:

docs/index.rst

@@ -13,13 +13,23 @@ Welcome to xsdba's documentation!
    releasing
    authors
    changelog
+   references
+   notebooks/example
+   notebooks/advanced_example
 
 .. toctree::
    :maxdepth: 1
    :caption: All Modules
 
    apidoc/modules
 
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User API
+
+   api
+
 Indices and tables
 ==================
 * :ref:`genindex`

docs/references.bib

@@ -37,7 +37,7 @@ @article{cannon_bias_2015
 	pages = {6938--6959},
 }
 
-@misc{cannon_mbc_2020,
+@article{cannon_mbc_2020,
 	title = {{MBC}: {Multivariate} {Bias} {Correction} of {Climate} {Model} {Outputs}},
 	copyright = {GPL-2},
 	shorttitle = {{MBC}},
@@ -62,7 +62,7 @@ @article{roy_extremeprecip_2023
 	year = {2023},
 }
 
-@misc{roy_juliaclimateclimatetoolsjl_2021,
+@article{roy_juliaclimateclimatetoolsjl_2021,
 	title = {{JuliaClimate}/{ClimateTools}.jl: v0.23.1},
 	shorttitle = {{JuliaClimate}/{ClimateTools}.jl},
 	url = {https://zenodo.org/record/5399172},
@@ -153,7 +153,7 @@ @article{szekely_testing_2004
 	year = {2004},
 }
 
-@misc{mezzadri_how_2007,
+@article{mezzadri_how_2007,
 	title = {How to generate random matrices from the classical compact groups},
 	url = {https://arxiv.org/abs/math-ph/0609050},
 	doi = {10.48550/arXiv.math-ph/0609050},
@@ -200,7 +200,7 @@ @article{cleveland_robust_1979
 	pages = {829--836},
 }
 
-@misc{gramfort_lowess_2015,
+@article{gramfort_lowess_2015,
 	title = {{LOWESS} : {Locally} weighted regression},
 	copyright = {BSD 3-Clause},
 	shorttitle = {{LOWESS}},
@@ -282,7 +282,7 @@ @article{francois_multivariate_2020
 	pages = {537--562},
 }
 
-@misc{jalbert_extreme_2022,
+@article{jalbert_extreme_2022,
 	title = {Extreme value analysis package for {Julia}.},
 	url = {https://github.com/jojal5/Extremes.jl},
 	abstract = {Extreme value analysis package for Julia},
@@ -430,3 +430,43 @@ @article{agbazo_characterizing_2020
 	keywords = {bias adjustment, climate simulations, physical inconsistency, univariate quantile mapping},
 	pages = {3868--3884},
 }
+
+
+@misc{robin_2021,
+	title = {{SBCK}: {Statistical} {Bias} {Correction} {Kit}},
+	copyright = {GPL-3},
+	shorttitle = {{SBCK}},
+	url = {https://github.com/yrobink/SBCK-python},
+	urldate = {2024-07-03},
+	author = {Robin, Yoann},
+	year = {2021},
+}
+
+@article{higham_1988,
+	title = {Computing a nearest symmetric positive semidefinite matrix},
+	journal = {Linear Algebra and its Applications},
+	volume = {103},
+	pages = {103-118},
+	year = {1988},
+	issn = {0024-3795},
+	doi = {https://doi.org/10.1016/0024-3795(88)90223-6},
+	url = {https://www.sciencedirect.com/science/article/pii/0024379588902236},
+	author = {Nicholas J. Higham},
+	abstract = {The nearest symmetric positive semidefinite matrix in the Frobenius norm to an arbitrary real matrix A is shown to be (B + H)/2, where H is the symmetric polar factor of B=(A + AT)/2. In the 2-norm a nearest symmetric positive semidefinite matrix, and its distance δ2(A) from A, are given by a computationally challenging formula due to Halmos. We show how the bisection method can be applied to this formula to compute upper and lower bounds for δ2(A) differing by no more than a given amount. A key ingredient is a stable and efficient test for positive definiteness, based on an attempted Choleski decomposition. For accurate computation of δ2(A) we formulate the problem as one of zero finding and apply a hybrid Newton-bisection algorithm. Some numerical difficulties are discussed and illustrated by example.}
+}
+
+@article{knol_1989,
+	title = "Least-squares approximation of an improper correlation matrix by a proper one",
+	abstract = "An algorithm is presented for the best least-squares fitting correlation matrix approximating a given missing value or improper correlation matrix. The proposed algorithm is based upon a solution for Mosier's oblique Procrustes rotation problem offered by ten Berge and Nevels. A necessary and sufficient condition is given for a solution to yield the unique global minimum of the least-squares function. Empirical verification of the condition indicates that the occurrence of non-optimal solutions with the proposed algorithm is very unlikely. A possible drawback of the optimal solution is that it is a singular matrix of necessity. In cases where singularity is undesirable, one may impose the additional nonsingularity constraint that the smallest eigenvalue of the solution be δ, where δ is an arbitrary small positive constant. Finally, it may be desirable to weight the squared errors of estimation differentially. A generalized solution is derived which satisfies the additional nonsingularity constraint and also allows for weighting. The generalized solution can readily be obtained from the standard “unweighted singular” solution by transforming the observed improper correlation matrix in a suitable way.",
+	keywords = "Missing value correlation, indefinite correlation matrix, IR-85889, tetrachoric correlation, constrained least-squares approximation",
+	author = "Knol, {Dirk L.} and {ten Berge}, {Jos M.F.}",
+	year = "1989",
+	doi = "10.1007/BF02294448",
+	language = "Undefined",
+	volume = "54",
+	pages = "53--61",
+	journal = "Psychometrika",
+	issn = "0033-3123",
+	publisher = "Springer",
+	number = "1",
+}

docs/references.rst

@@ -0,0 +1,10 @@
+.. only:: html
+
+    ============
+    Bibliography
+    ============
+
+    General References
+    ------------------
+
+.. bibliography::

docs/xsdba.rst

@@ -40,7 +40,7 @@ A generic bias adjustment process is laid out as follows:
 
 The train-adjust approach allows to inspect the trained adjustment object.
 The training information is stored in the underlying `Adj.ds` dataset and usually has a `af` variable with the adjustment factors.
-Its layout and the other available variables vary between the different algorithm, refer to :ref:`Adjustment methods <sdba-user-api>`.
+Its layout and the other available variables vary between the different algorithm, refer to :ref:`Adjustment methods <xsdba-user-api>`.
 
 Parameters needed by the training and the adjustment are saved to the ``Adj.ds`` dataset as a `adj_params` attribute.
 Parameters passed to the `adjust` call are written to the history attribute in the output scenario DataArray.
@@ -125,21 +125,19 @@ add them back on exit.
 User API
 ========
 
-See: :ref:`sdba-user-api`
+See: :ref:`xsdba-user-api`
 
 Developer API
 =============
 
-See: :ref:`sdba-developer-api`
+See: :ref:`xsdba-developer-api`
 
 .. only:: html or text
 
-    .. _sdba-footnotes:
+    _xsdba-footnotes:
 
     SDBA Footnotes
     ==============
 
     .. bibliography::
        :style: xcstyle
-       :labelprefix: SDBA-
-       :keyprefix: sdba-

src/xsdba/adjustment.py

@@ -481,7 +481,7 @@ class DetrendedQuantileMapping(TrainAdjust):
         F^{-1}_{ref}\left\{F_{hist}\left[\frac{\overline{hist}\cdot sim}{\overline{sim}}\right]\right\}\frac{\overline{sim}}{\overline{hist}}
 
     where :math:`F` is the cumulative distribution function (CDF) and :math:`\overline{xyz}` is the linear trend of the data.
-    This equation is valid for multiplicative adjustment. Based on the DQM method of :cite:p:`sdba-cannon_bias_2015`.
+    This equation is valid for multiplicative adjustment. Based on the DQM method of :cite:p:`cannon_bias_2015`.
 
     Parameters
     ----------
@@ -592,7 +592,7 @@ class QuantileDeltaMapping(EmpiricalQuantileMapping):
         sim\frac{F^{-1}_{ref}\left[F_{sim}(sim)\right]}{F^{-1}_{hist}\left[F_{sim}(sim)\right]}
 
     where :math:`F` is the cumulative distribution function (CDF). This equation is valid for multiplicative adjustment.
-    The algorithm is based on the "QDM" method of :cite:p:`sdba-cannon_bias_2015`.
+    The algorithm is based on the "QDM" method of :cite:p:`cannon_bias_2015`.
 
     Parameters
     ----------
@@ -643,7 +643,7 @@ class ExtremeValues(TrainAdjust):
     r"""Adjustment correction for extreme values.
 
     The tail of the distribution of adjusted data is corrected according to the bias between the parametric Generalized
-    Pareto distributions of the simulated and reference data :cite:p:`sdba-roy_extremeprecip_2023`. The distributions are composed of the
+    Pareto distributions of the simulated and reference data :cite:p:`roy_extremeprecip_2023`. The distributions are composed of the
     maximal values of clusters of "large" values.  With "large" values being those above `cluster_thresh`. Only extreme
     values, whose quantile within the pool of large values are above `q_thresh`, are re-adjusted. See `Notes`.
 
@@ -704,7 +704,7 @@ class ExtremeValues(TrainAdjust):
         \tau = \left(\frac{1}{f}\frac{S - min(S)}{max(S) - min(S)}\right)^p
 
     Code based on an internal Matlab source and partly ib the `biascorrect_extremes` function of the julia package
-    "ClimateTools.jl" :cite:p:`sdba-roy_juliaclimateclimatetoolsjl_2021`.
+    "ClimateTools.jl" :cite:p:`roy_juliaclimateclimatetoolsjl_2021`.
 
     Because of limitations imposed by the lazy computing nature of the dask backend, it
     is not possible to know the number of cluster extremes in `ref` and `hist` at the
@@ -802,7 +802,7 @@ class LOCI(TrainAdjust):
     r"""Local Intensity Scaling (LOCI) bias-adjustment.
 
     This bias adjustment method is designed to correct daily precipitation time series by considering wet and dry days
-    separately :cite:p:`sdba-schmidli_downscaling_2006`.
+    separately :cite:p:`schmidli_downscaling_2006`.
 
     Multiplicative adjustment factors are computed such that the mean of `hist` matches the mean of `ref` for values
     above a threshold.
@@ -924,7 +924,7 @@ class PrincipalComponents(TrainAdjust):
     r"""Principal component adjustment.
 
     This bias-correction method maps model simulation values to the observation space through principal components
-    :cite:p:`sdba-hnilica_multisite_2017`. Values in the simulation space (multiple variables, or multiple sites) can be
+    :cite:p:`hnilica_multisite_2017`. Values in the simulation space (multiple variables, or multiple sites) can be
     thought of as coordinate along axes, such as variable, temperature, etc. Principal components (PC) are a
     linear combinations of the original variables where the coefficients are the eigenvectors of the covariance matrix.
     Values can then be expressed as coordinates along the PC axes. The method makes the assumption that bias-corrected
@@ -984,7 +984,7 @@ class PrincipalComponents(TrainAdjust):
 
     References
     ----------
-    :cite:cts:`hnilica_multisite_2017,sdba-alavoine_distinct_2022`
+    :cite:cts:`hnilica_multisite_2017,alavoine_distinct_2022`
     """
 
     @classmethod
@@ -1108,8 +1108,8 @@ class NpdfTransform(Adjust):
 
     This adjustment object combines both training and adjust steps in the `adjust` class method.
 
-    A multivariate bias-adjustment algorithm described by :cite:t:`sdba-cannon_multivariate_2018`, as part of the MBCn
-    algorithm, based on a color-correction algorithm described by :cite:t:`sdba-pitie_n-dimensional_2005`.
+    A multivariate bias-adjustment algorithm described by :cite:t:`cannon_multivariate_2018`, as part of the MBCn
+    algorithm, based on a color-correction algorithm described by :cite:t:`pitie_n-dimensional_2005`.
 
     This algorithm in itself, when used with QuantileDeltaMapping, is NOT trend-preserving.
     The full MBCn algorithm includes a reordering step provided here by :py:func:`xsdba.processing.reordering`.
@@ -1168,23 +1168,23 @@ class NpdfTransform(Adjust):
     These three steps are repeated a certain number of times, prescribed by argument ``n_iter``. At each
     iteration, a new random rotation matrix is generated.
 
-    The original algorithm :cite:p:`sdba-pitie_n-dimensional_2005`, stops the iteration when some distance score converges.
-    Following cite:t:`sdba-cannon_multivariate_2018` and the MBCn implementation in :cite:t:`sdba-cannon_mbc_2020`, we
+    The original algorithm :cite:p:`pitie_n-dimensional_2005`, stops the iteration when some distance score converges.
+    Following cite:t:`cannon_multivariate_2018` and the MBCn implementation in :cite:t:`cannon_mbc_2020`, we
     instead fix the number of iterations.
 
-    As done by cite:t:`sdba-cannon_multivariate_2018`, the distance score chosen is the "Energy distance" from
-    :cite:t:`sdba-szekely_testing_2004`. (see: :py:func:`xsdba.processing.escore`).
+    As done by cite:t:`cannon_multivariate_2018`, the distance score chosen is the "Energy distance" from
+    :cite:t:`szekely_testing_2004`. (see: :py:func:`xsdba.processing.escore`).
 
-    The random matrices are generated following a method laid out by :cite:t:`sdba-mezzadri_how_2007`.
+    The random matrices are generated following a method laid out by :cite:t:`mezzadri_how_2007`.
 
-    This is only part of the full MBCn algorithm, see :ref:`notebooks/sdba:Statistical Downscaling and Bias-Adjustment`
+    This is only part of the full MBCn algorithm, see :ref:`notebooks/example:Statistical Downscaling and Bias-Adjustment`
     for an example on how to replicate the full method with xsdba. This includes a standardization of the simulated data
     beforehand, an initial univariate adjustment and the reordering of those adjusted series according to the rank
     structure of the output of this algorithm.
 
     References
     ----------
-    :cite:cts:`cannon_multivariate_2018,sdba-cannon_mbc_2020,sdba-pitie_n-dimensional_2005,sdba-mezzadri_how_2007,sdba-szekely_testing_2004`
+    :cite:cts:`cannon_multivariate_2018,cannon_mbc_2020,pitie_n-dimensional_2005,mezzadri_how_2007,szekely_testing_2004`
     """
 
     @classmethod
@@ -1266,8 +1266,8 @@ def _adjust(
 class MBCn(TrainAdjust):
     r"""Multivariate bias correction function using the N-dimensional probability density function transform.
 
-    A multivariate bias-adjustment algorithm described by :cite:t:`sdba-cannon_multivariate_2018`
-    based on a color-correction algorithm described by :cite:t:`sdba-pitie_n-dimensional_2005`.
+    A multivariate bias-adjustment algorithm described by :cite:t:`cannon_multivariate_2018`
+    based on a color-correction algorithm described by :cite:t:`pitie_n-dimensional_2005`.
 
     This algorithm in itself, when used with QuantileDeltaMapping, is NOT trend-preserving.
     The full MBCn algorithm includes a reordering step provided here by :py:func:`xsdba.processing.reordering`.
@@ -1356,18 +1356,18 @@ class MBCn(TrainAdjust):
 
     3. Reorder the dataset found in step 2. according to the ranks of the dataset found in step 1.
 
-    The original algorithm :cite:p:`sdba-pitie_n-dimensional_2005`, stops the iteration when some distance score converges.
-    Following cite:t:`sdba-cannon_multivariate_2018` and the MBCn implementation in :cite:t:`sdba-cannon_mbc_2020`, we
+    The original algorithm :cite:p:`pitie_n-dimensional_2005`, stops the iteration when some distance score converges.
+    Following cite:t:`cannon_multivariate_2018` and the MBCn implementation in :cite:t:`cannon_mbc_2020`, we
     instead fix the number of iterations.
 
-    As done by cite:t:`sdba-cannon_multivariate_2018`, the distance score chosen is the "Energy distance" from
-    :cite:t:`sdba-szekely_testing_2004`. (see: :py:func:`xsdba.processing.escore`).
+    As done by cite:t:`cannon_multivariate_2018`, the distance score chosen is the "Energy distance" from
+    :cite:t:`szekely_testing_2004`. (see: :py:func:`xsdba.processing.escore`).
 
-    The random matrices are generated following a method laid out by :cite:t:`sdba-mezzadri_how_2007`.
+    The random matrices are generated following a method laid out by :cite:t:`mezzadri_how_2007`.
 
     References
     ----------
-    :cite:cts:`cannon_multivariate_2018,sdba-cannon_mbc_2020,sdba-pitie_n-dimensional_2005,sdba-mezzadri_how_2007,sdba-szekely_testing_2004`
+    :cite:cts:`cannon_multivariate_2018,cannon_mbc_2020,pitie_n-dimensional_2005,mezzadri_how_2007,szekely_testing_2004`
 
     Notes
     -----