Skip to content

Commit

Permalink
Add documentation (#11)
Browse files Browse the repository at this point in the history 
Add documentation
  • Loading branch information
@espdev
espdev committed Jan 13, 2020
1 parent 5531b5d commit f694123
Show file tree
Hide file tree
Showing 17 changed files with 997 additions and 262 deletions.
24 changes: 24 additions & 0 deletions .readthedocs.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
builder: html
configuration: docs/conf.py

# Optionally build your docs in additional formats such as PDF and ePub
formats:
- pdf

# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- method: pip
path: .
extra_requirements:
- docs
25 changes: 19 additions & 6 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,37 @@
# v0.7.0
# Changelog

## v0.8.0.dev1

* Add `csaps` function that can be used as the main API
* Refactor the internal structure of the package
* Add the [documentation](https://csaps.readthedocs.io)

**Attention**

This is the last version that supports Python 3.5.
The next versions will support Python 3.6 or above.

## v0.7.0

* Add Generic-based type-hints and mypy-compatibility

# v0.6.1
## v0.6.1

* A slight refactoring and extra data copies removing

# v0.6.0
## v0.6.0

* Add "axis" parameter for univariate/multivariate cases

# v0.5.0
## v0.5.0

* Reorganize the project to package-based structure
* Add the interface class for all smoothing spline classes

# v0.4.2
## v0.4.2

* FIX: "smooth" value is 0.0 was not used

# v0.4.1
## v0.4.1

* First PyPI release
190 changes: 23 additions & 167 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,206 +1,59 @@
# CSAPS: Cubic spline approximation (smoothing)

[![PyPI version](https://img.shields.io/pypi/v/csaps.svg)](https://pypi.python.org/pypi/csaps)
[![Documentation Status](https://readthedocs.org/projects/csaps/badge/?version=latest)](https://csaps.readthedocs.io/en/latest/?badge=latest)
[![Build status](https://travis-ci.org/espdev/csaps.svg?branch=master)](https://travis-ci.org/espdev/csaps)
[![Coverage Status](https://coveralls.io/repos/github/espdev/csaps/badge.svg?branch=master)](https://coveralls.io/github/espdev/csaps?branch=master)
![Supported Python versions](https://img.shields.io/pypi/pyversions/csaps.svg)
[![License](https://img.shields.io/pypi/l/csaps.svg)](LICENSE)

This module provides cubic smoothing spline for univariate/multivariate/gridded data approximation.
The smoothing parameter can be calculated automatically or it can be set manually.

The smoothing parameter should be in range `[0, 1]` where bounds are:
* 0: The smoothing spline is the least-squares straight line fit to the data
* 1: The natural cubic spline interpolant

The calculation of the smoothing spline requires the solution of a linear system
whose coefficient matrix has the form `p*A + (1 - p)*B`, with the matrices `A` and `B`
depending on the data sites `X`. The automatically computed smoothing parameter makes
`p*trace(A) equal (1 - p)*trace(B)`.
**csaps** is a package for univariate, multivariate and nd-gridded data approximation using cubic smoothing splines.

## Installation

Python 3.5 or above is supported.

```
pip install csaps
pip install -U csaps
```

The module depends only on NumPy and SciPy.

On Windows we highly recommend to use unofficial builds [NumPy+MKL](https://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy)
and [SciPy](https://www.lfd.uci.edu/~gohlke/pythonlibs/#scipy) from Christoph Gohlke.
## Simple Examples

```
> mkdir depends
Here are a couple of examples of smoothing data.

download numpy (https://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy) to "depends" directory
download scipy (https://www.lfd.uci.edu/~gohlke/pythonlibs/#scipy) to "depends" directory
> pip install --find-links depends/ csaps
```

## Smoothing univariate data

Univariate data are two vectors: X and Y with the same size. X is data sites, Y is data values.
For univariate case X-values must satisfy the condition: `x1 < x2 < ... < xN`.

You can use `UnivariateCubicSmoothingSpline` class for uivariate data smoothing.
An univariate data smoothing:

```python
import numpy as np
import matplotlib.pyplot as plt
import csaps

from csaps import csaps

np.random.seed(1234)

x = np.linspace(-5., 5., 25)
y = np.exp(-(x/2.5)**2) + (np.random.rand(25) - 0.2) * 0.3

sp = csaps.UnivariateCubicSmoothingSpline(x, y, smooth=0.85)

xs = np.linspace(x[0], x[-1], 150)
ys = sp(xs)

ys = csaps(x, y, xs, smooth=0.85)

plt.plot(x, y, 'o', xs, ys, '-')
plt.show()
```

![csaps1d](https://user-images.githubusercontent.com/1299189/27611703-f3093c14-5b9b-11e7-9f18-6d0c3cc7633a.png)

### Smoothing weighted univariate data

The algorithm supports weighting. You can set weights vector that will determine
weights for all data values:

```python
import csaps

x = [1., 2., 4., 6.]
y = [2., 4., 5., 7.]
w = [0.5, 1, 0.7, 1.2]

sp = csaps.UnivariateCubicSmoothingSpline(x, y, w)
...
```

### Smoothing univariate data with vectorization

The algorithm supports vectorization. You can compute smoothing splines for
`X`, `Y` data where `X` is data site vector and `Y` is ND-array of data value vectors.
The shape of `Y` array must be: `(d0, d1, ..., dN)` where `dN` must equal of `X` vector size.

In this case the smoothing splines will be computed for all `Y` data vectors at a time.

For example:

```python
import numpy as np
import csaps

# data sites
x = [1, 2, 3, 4]

# two data vectors
y = np.array([(2, 4, 6, 8),
(1, 3, 5, 7)])

sp = csaps.UnivariateCubicSmoothingSpline(x, y)

xi = np.linspace(1, 4, 10)
yi = sp(xi)

print(yi.shape) # (2, 10)
assert yi.shape[:-1] == y.shape[:-1]
assert yi.shape[-1] == xi.size
```

**Important**:
The same weights vector and the same smoothing parameter will be used for all Y data.

## Smoothing multivariate data

We can easily smooth multivariate data using univariate smoothing spline, vectorization and parametrization.
We should define parametric data sites vector `t` with condition `t1 < t2 < ... < tN` and make spline for each dimension `X(t), Y(t), ..., M(t)`.

The module provides `MultivariateCubicSmoothingSpline` class for this case.

This class is a simple wrapper and it just automatically computes `t` vector by default and calls `UnivariateCubicSmoothingSpline`:

```python
# Construct multivariate spline from t and X, Y, Z, ..., M
sx = UnivariateCubicSmoothingSpline(t, data[x])
sy = UnivariateCubicSmoothingSpline(t, data[y])
sz = UnivariateCubicSmoothingSpline(t, data[z])
...
sm = UnivariateCubicSmoothingSpline(t, data[m])

# Or the same with using vectorization
sxyz_m = UnivariateCubicSmoothingSpline(t, data)
```

### Smoothing 3D noisy parametric curve example

In this example we make parametric 3D curve from `theta` parameter and compute spline from the same `theta` parameter.
In fact we could use `UnivariateCubicSmoothingSpline` with vectorization instead of `MultivariateCubicSmoothingSpline` in this case.

```python
import numpy as np

import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D

import csaps

n = 100
theta = np.linspace(-4 * np.pi, 4 * np.pi, n)
z = np.linspace(-2, 2, n)
r = z ** 2 + 1
np.random.seed(1234)
x = r * np.sin(theta) + np.random.randn(n) * 0.3
np.random.seed(5678)
y = r * np.cos(theta) + np.random.randn(n) * 0.3

data = np.vstack((x, y, z))

sp_theta = csaps.MultivariateCubicSmoothingSpline(data, theta, smooth=0.95)

# or the same
# sp_theta = csaps.UnivariateCubicSmoothingSpline(theta, data, smooth=0.95)

theta_i = np.linspace(-4 * np.pi, 4 * np.pi, 250)
data_i = sp_theta(theta_i)

xi = data_i[0, :]
yi = data_i[1, :]
zi = data_i[2, :]

fig = plt.figure()
ax = fig.gca(projection='3d')
plt.show()
```

<img width="663" alt="2019-04-04_02-28-52" src="https://user-images.githubusercontent.com/1299189/55519724-a75a6580-5681-11e9-8beb-2111664f8ee3.png">

## Smoothing ND-gridded data

The algorithm can make smoothing splines for ND-gridded data approximation.
In this case we use coordinatewise smoothing (tensor-product of univariate splines coefficients).

You can use `NdGridCubicSmoothingSpline` class for ND-gridded data smoothing.
You also can set weights and smoothing parameters for each dimension.

Currently the implementation does not support vectorization for ND-gridded data.

### Smoothing 2D-gridded data (surface) example
A surface data smoothing:

```python
import numpy as np

import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D

import csaps
from csaps import csaps

xdata = [np.linspace(-3, 3, 61), np.linspace(-3.5, 3.5, 51)]
i, j = np.meshgrid(*xdata, indexing='ij')
Expand All @@ -212,38 +65,41 @@ ydata = (3 * (1 - j)**2. * np.exp(-(j**2) - (i + 1)**2)
np.random.seed(12345)
noisy = ydata + (np.random.randn(*ydata.shape) * 0.75)

sp = csaps.NdGridCubicSmoothingSpline(xdata, noisy, smooth=0.988)
ysmth = sp(xdata)
ysmth = csaps(xdata, noisy, xdata, smooth=0.988)

fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')

ax.plot_wireframe(j, i, noisy, linewidths=0.5, color='r')
ax.scatter(j, i, noisy, s=5, c='r')

ax.plot_surface(j, i, ysmth, linewidth=0, alpha=1.0)

plt.show()
```

<img width="653" alt="2019-03-22_10-22-59" src="https://user-images.githubusercontent.com/1299189/54817564-2ff30200-4c8f-11e9-8afd-9055efcd6ea0.png">

## More examples
## Documentation

More examples of usage and the full documentation can be found at ReadTheDocs.

Please look through [csaps.ipynb](examples/csaps.ipynb) file for more examples.
https://csaps.readthedocs.io

## Testing

We use pytest and tox (on Travis CI) for testing.
Please see [test_csaps.py](tests/test_csaps.py) file.
pytest, tox and Travis CI are used for testing. Please see [test_csaps.py](tests).

## Algorithms and implementations

`csaps` is a Python modified port of MATLAB [CSAPS](https://www.mathworks.com/help/curvefit/csaps.html) function that is an implementation of
**csaps** package is a Python modified port of MATLAB [CSAPS](https://www.mathworks.com/help/curvefit/csaps.html) function that is an implementation of
Fortran routine SMOOTH from [PGS](http://pages.cs.wisc.edu/~deboor/pgs/) (originally written by Carl de Boor).

[csaps-cpp](https://github.com/espdev/csaps-cpp) C++11 Eigen based implementation of the algorithm.

## References

C. de Boor, A Practical Guide to Splines, Springer-Verlag, 1978.

## License

[MIT](https://choosealicense.com/licenses/mit/)
4 changes: 2 additions & 2 deletions csaps/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,12 +26,12 @@
MultivariateDataType,
NdGridDataType,
)
from csaps._shortcut import csaps, SmoothingResult
from csaps._shortcut import csaps, AutoSmoothingResult

__all__ = [
# Shortcut
'csaps',
'SmoothingResult',
'AutoSmoothingResult',

# Classes
'SplinePPFormBase',
Expand Down

0 comments on commit f694123

Please sign in to comment.