Merge pull request #88 from EPFL-Center-for-Imaging/control_point_deriv

Add methods for analytically computed derivatives with respect to control points for common loss functions.

Author: faymanns

README.md

@@ -1,7 +1,7 @@
 <img style="float: right;" src="https://imaging.epfl.ch/resources/logo-for-gitlab.svg">
 
 # splinebox
-A python package for fitting splines.
+A Python package for fitting splines.
 Developed by the [EPFL Center for Imaging](https://imaging.epfl.ch/) as part of a collaboration with the [Uhlmann Group at EMBL-EBI](https://www.ebi.ac.uk/research/uhlmann/) in Feb 2024.
 
 [![Documentation Status](https://readthedocs.org/projects/splinebox/badge/?version=latest)](https://splinebox.readthedocs.io/en/latest/?badge=latest)
@@ -15,7 +15,7 @@ Developed by the [EPFL Center for Imaging](https://imaging.epfl.ch/) as part of
 ## Features
 * Flexible spline fitting for various applications.
 * Support for many spline types in any dimensionality.
-* High-perfomance implementation in Python
+* High-performance implementation in Python.
 * Extensive [documentation](https://splinebox.readthedocs.io/en/latest/?badge=latest) with [examples](https://splinebox.readthedocs.io/en/latest/_auto_examples/index.html)
 
 ## Installation
@@ -48,7 +48,7 @@ plt.show()
 
 ## Support
 
-If you encounter any problems, please [file and issue](https://github.com/EPFL-Center-for-Imaging/splinebox/issues/new) describing the issue and include minimal example to reproduce the issue.
+If you encounter any problems, please [file an issue](https://github.com/EPFL-Center-for-Imaging/splinebox/issues/new) describing the issue and include a minimal example to reproduce the issue.
 
 ## Contributing
 
@@ -57,12 +57,12 @@ We welcome contributions! Before you submit a pull request, please ensure that t
 ## Citing splinebox
 
 If you use splinebox in the context of scientific publication, please cite it as follows.
-Note, that you will have to fill in the version yourself. If you are unsure what version you are running,
+Note that you will have to fill in the version yourself. If you are unsure what version you are running,
 you can find out by running
 
 ```python
 import splinebox
-print(splinbox.__version__)`
+print(splinebox.__version__)
 ```
 
 BibTeX:

docs/getting_started/citation.rst

@@ -22,4 +22,4 @@ you can find out by running:
 .. code-block:: python
 
    import splinebox
-   print(splinbox.__version__)
+   print(splinebox.__version__)

docs/getting_started/padding.rst

@@ -21,13 +21,13 @@ Despite the first and last control point, the spline curves inward toward the or
 .. plot:: pyplots/plot_no_padding.py
    :include-source: false
 
-By padding with two additional points on the circle, this behavior is corrected.
+By padding with two additional points on the circle, this behaviour is corrected.
 
 .. plot:: pyplots/plot_padding.py
    :include-source: false
 
 If you set the control points manually, you are responsible for handling the padding.
-This design choice allows full control over the spline's behavior at the ends.
+This design choice allows full control over the spline's behaviour at the ends.
 
 .. code-block:: python
 

docs/index.rst

@@ -33,9 +33,9 @@ SplineBox
        <h1 style="margin-bottom: 0.2rem">SplineBox</h1>
        <h2 style="margin-top: 0.2rem">Take control of your splines</h2>
        <p style="margin-right: 3em">
-         SplineBox is an open-source python package for anyone trying to fit splines.
+         SplineBox is an open-source Python package for anyone trying to fit splines.
          It offers a wide variety of spline types including Hermite splines and makes
-         it easy to specify custom loss function to control spline properties such as
+         it easy to specify custom loss functions to control spline properties such as
          smoothness.
        </p>
 
@@ -97,7 +97,7 @@ SplineBox
        </svg>
        <p>
          <strong> Custom loss functions </strong> <br/>
-         Compatibility with python optimization frame works makes it easy to use custom loss functions for fitting.
+         Compatibility with Python optimisation frameworks makes it easy to use custom loss functions for fitting.
        </p>
      </div>
 
@@ -117,7 +117,7 @@ SplineBox
        </svg>
        <p>
          <strong> High performance </strong> <br/>
-         Just-in-time compilation allows us to match and in some cases overcome the performance of SciPy's fortran based splines.
+         Just-in-time compilation allows us to match and in some cases overcome the performance of SciPy's Fortran-based splines.
        </p>
      </div>
 
@@ -185,7 +185,7 @@ SplineBox
      .. raw:: html
 
        <p style="margin-left: 3em">
-         Scipy requires you to pre-compute the parameter values for all knots and data points
+         SciPy requires you to pre-compute the parameter values for all knots and data points
          accounting for padding and periodicity of the data.
          This can be confusing and difficult to do.
        </p>
@@ -207,14 +207,14 @@ SplineBox
     .. raw:: html
 
       <p>
-        We compare the performance to splinbox to SciPy's splines
+        We compare the performance of splinebox to SciPy's splines
         on three main tasks:
         <ul>
-        <li>Spline creation give a set of knots</li>
+        <li>Spline creation given a set of knots</li>
         <li>Evaluation of a spline at a given parameter value</li>
         <li>Data approximation using least-squares fitting</li>
         </ul>
-        Splinebox out performs SciPy by approximately two orders of magnitude on the first task, achieves comparable performance on the second task, and is out performed for least-squares fitting of splines.
+        Splinebox outperforms SciPy by approximately two orders of magnitude on the first task, achieves comparable performance on the second task, and is outperformed for least-squares fitting of splines.
         <a href="./_auto_examples/plot_performance_comparison_with_scipy.html">See detailed comparison →</a>
       </p>
 

docs/pyplots/plot_b1.py

@@ -2,6 +2,7 @@
 import numpy as np
 import splinebox.basis_functions
 
+
 fig, axes = plt.subplots(2, 1, sharex=True)
 
 b1 = splinebox.basis_functions.B1()
@@ -12,9 +13,9 @@
 b1_1st = b1(t, derivative=1)
 
 fig.suptitle("B1 basis function and its derivatives")
-axes[0].plot(t, b1_0th, label=r"$\Phi(t)$")
+axes[0].plot(t, b1_0th, label=r"$\beta_1(t)$")
 axes[0].legend()
-axes[1].plot(t, b1_1st, label=r"$\frac{d\Phi}{dt}(t)$")
+axes[1].plot(t, b1_1st, label=r"$\frac{d\beta_1}{dt}(t)$")
 axes[1].legend()
 axes[1].set_xlabel(r"$t$")
 plt.tight_layout()

docs/pyplots/plot_b2.py

@@ -14,11 +14,11 @@
 
 
 fig.suptitle("B2 basis function and its derivatives")
-axes[0].plot(t, b2_0th, label=r"$\Phi(t)$")
+axes[0].plot(t, b2_0th, label=r"$\beta_2(t)$")
 axes[0].legend()
-axes[1].plot(t, b2_1st, label=r"$\frac{d\Phi}{dt}(t)$")
+axes[1].plot(t, b2_1st, label=r"$\frac{d\beta_2}{dt}(t)$")
 axes[1].legend()
-axes[2].plot(t, b2_2nd, label=r"$\frac{d^2\Phi}{dt^2}(t)$")
+axes[2].plot(t, b2_2nd, label=r"$\frac{d^2\beta_2}{dt^2}(t)$")
 axes[2].legend()
 axes[2].set_xlabel(r"$t$")
 plt.tight_layout()

docs/pyplots/plot_b3.py

@@ -13,11 +13,11 @@
 b3_2nd = b3(t, derivative=2)
 
 fig.suptitle("B3 basis function and its derivatives")
-axes[0].plot(t, b3_0th, label=r"$\Phi(t)$")
+axes[0].plot(t, b3_0th, label=r"$\beta_3(t)$")
 axes[0].legend()
-axes[1].plot(t, b3_1st, label=r"$\frac{d\Phi}{dt}(t)$")
+axes[1].plot(t, b3_1st, label=r"$\frac{d\beta_3}{dt}(t)$")
 axes[1].legend()
-axes[2].plot(t, b3_2nd, label=r"$\frac{d^2\Phi}{dt^2}(t)$")
+axes[2].plot(t, b3_2nd, label=r"$\frac{d^2\beta_3}{dt^2}(t)$")
 axes[2].legend()
 axes[2].set_xlabel(r"$t$")
 plt.tight_layout()

docs/pyplots/plot_catmullrom.py

@@ -13,11 +13,11 @@
 basis_2nd = basis(t, derivative=2)
 
 fig.suptitle("Catmull Rom basis function and its derivatives")
-axes[0].plot(t, basis_0th, label=r"$\Phi(t)$")
+axes[0].plot(t, basis_0th, label=r"$\varphi(t)$")
 axes[0].legend()
-axes[1].plot(t, basis_1st, label=r"$\frac{d\Phi}{dt}(t)$")
+axes[1].plot(t, basis_1st, label=r"$\frac{d\varphi}{dt}(t)$")
 axes[1].legend()
-axes[2].plot(t, basis_2nd, label=r"$\frac{d^2\Phi}{dt^2}(t)$")
+axes[2].plot(t, basis_2nd, label=r"$\frac{d^2\varphi}{dt^2}(t)$")
 axes[2].legend()
 axes[2].set_xlabel(r"$t$")
 plt.tight_layout()

docs/pyplots/plot_cubichermite.py

@@ -13,18 +13,18 @@
 basis_2nd = basis(t, derivative=2)
 
 fig.suptitle("Cubic Hermite basis function and its derivatives")
-axes[0][0].plot(t, basis_0th[:, 0], label=r"$\Phi_1(t)$")
+axes[0][0].plot(t, basis_0th[:, 0], label=r"$\varphi_1(t)$")
 axes[0][0].legend()
-axes[1][0].plot(t, basis_1st[:, 0], label=r"$\frac{d\Phi_1}{dt}(t)$")
+axes[1][0].plot(t, basis_1st[:, 0], label=r"$\frac{d\varphi_1}{dt}(t)$")
 axes[1][0].legend()
-axes[2][0].plot(t, basis_2nd[:, 0], label=r"$\frac{d^2\Phi_1}{dt^2}(t)$")
+axes[2][0].plot(t, basis_2nd[:, 0], label=r"$\frac{d^2\varphi_1}{dt^2}(t)$")
 axes[2][0].legend()
 axes[2][0].set_xlabel(r"$t$")
-axes[0][1].plot(t, basis_0th[:, 1], label=r"$\Phi_2(t)$")
+axes[0][1].plot(t, basis_0th[:, 1], label=r"$\varphi_2(t)$")
 axes[0][1].legend()
-axes[1][1].plot(t, basis_1st[:, 1], label=r"$\frac{d\Phi_2}{dt}(t)$")
+axes[1][1].plot(t, basis_1st[:, 1], label=r"$\frac{d\varphi_2}{dt}(t)$")
 axes[1][1].legend()
-axes[2][1].plot(t, basis_2nd[:, 1], label=r"$\frac{d^2\Phi_2}{dt^2}(t)$")
+axes[2][1].plot(t, basis_2nd[:, 1], label=r"$\frac{d^2\varphi_2}{dt^2}(t)$")
 axes[2][1].legend()
 axes[2][1].set_xlabel(r"$t$")
 plt.tight_layout()

docs/pyplots/plot_exponential.py

@@ -14,11 +14,11 @@
 basis_2nd = basis(t, derivative=2)
 
 fig.suptitle(f"Exponential basis function and its derivatives for $M={M}$")
-axes[0].plot(t, basis_0th, label=r"$\Phi(t)$")
+axes[0].plot(t, basis_0th, label=r"$\varphi(t)$")
 axes[0].legend()
-axes[1].plot(t, basis_1st, label=r"$\frac{d\Phi}{dt}(t)$")
+axes[1].plot(t, basis_1st, label=r"$\frac{d\varphi}{dt}(t)$")
 axes[1].legend()
-axes[2].plot(t, basis_2nd, label=r"$\frac{d^2\Phi}{dt^2}(t)$")
+axes[2].plot(t, basis_2nd, label=r"$\frac{d^2\varphi}{dt^2}(t)$")
 axes[2].legend()
 axes[2].set_xlabel(r"$t$")
 plt.tight_layout()