Classification algorithms.

### Input data

* features - sequence of sequences of numbers
* categories - sequence of any values

### Workflow

* create classifier with parameters
* cross validate [[cv]]
* repeat or [[predict]]
* to validate model against test data, call [[validate]]

Classifier parameters are map of values specific for given algorithm. Check documentation in backend library to find documentation. Classifier can be retrained using [[train]]. New instance will be created.

Classifier training is delayed to the actual use. To force training, call [[train]] or [[predict]].

### Implementation notes

* only doubles as input data
* categories can be any type

### Cross validation

Every classifier exposes it's own cross validation method with configuration [[cv]].

~~Additionally three Clojure level methods are defined: [[cv]], [[loocv]] and [[bootstrap]].~~

### SMILE

[documentation](https://haifengl.github.io/smile/classification.html)

What is missed:

* other types than doubles (attributes)
* maxent
* Online classifiers
* General Naive Bayes

Native cross validation config is a map with keys:

* `:k` - number of folds (default: 10)
* `:type` - type of cross validation, one of `:cv` (default), `:loocv` and `:bootstrap`

### Liblinear

https://github.com/bwaldvogel/liblinear-java

Native cross validation expects a number as number of folds (default: 10)

### Examples

Iris database is used.

[1 2 3]
;; or
[[1] [2] [3]]

(let [cl (k-means data 10)] (cl [0 1 2]))

Clustering algorithms.

Various clustering algrorithms backed by SMILE library.

Currently implemented: only partition clustering.

### Input data

It's always sequence of n-sized samples as sequences.

For example, 2d samples `[[1 2] [2 2] [3 3] ...]`

For 1d data you can pass sequence of numbers of sequence of 1d seqs of numbers

```clojure
[1 2 3]
;; or
[[1] [2] [3]]
```

### Distances

Some of the methods use distance functions, use [[fastmath.distance]] namespace to create one.

### Output

Every function returns record which contains:

* `:type` - name of the method used
* `:data` - input data
* `:clustering` - sequence of cluster ids
* `:sizes` - sizes of clusters
* `:clusters` - number of clusters
* `:predict` - predicting function (see below), qualify additional sample
* `:representatives` - list of centroids or medoids if available
* `:info` - additional statistics for your samples (like distortion)
* `:obj` - SMILE object

Cluster id is a integer ranging from 0 to the number of clusters minus 1. Some methods mark outliers with [[outlier-id]].

Record acts as function and can qualify additonal sample by calling `:predict` function (or just call [[predict]]), for example (`data` is sequence of 3d samples):

```clojure
(let [cl (k-means data 10)] (cl [0 1 2]))
```

See [[k-means]]

#### Regrouping

Clustering record can be regroupped to the list of individual clusters. Call [[regroup]] and get list of maps with following structure:

* `:key` - cluster id
* `:data` - samples which belong to the cluster
* `:outliers?` - does it contain outliers or not
* `:representative` - centroid/medoid or average vector if the former is not available
* `:size` - size of cluster

Complex numbers functions.

Complex number is represented as `Vec2` type (from [[clojure2d.math.vector]] namespace).

To create complex number use [[complex]], [[vec2]] or [[->Vec2]].

Simplified implementation based on Apache Commons Math. Functions don't check NaNs or INF values.

Graphs are generated as follows, background is based on:

* argument as HUE
* absolute value as BRIGHTNESS

with transformed points painted white.

Complex plane (identity) looks as follows:

![identity](images/c/identity.jpg)

Collection of fast math functions and plethora of constants known from other math libraries.

### Primitive math operators

Based on [Primitive Math by Zach Tellman](https://github.com/ztellman/primitive-math) several operators are introduced and replace `clojure.core` functions. All operators are macros and can't be used as functions. List includes:

Known from Clojure: `*` `+` `-` `/` `>` `<` `>=` `<=` `==` `rem` `quot` `mod` `bit-or` `bit-and` `bit-xor` `bit-not` `bit-shift-left` `bit-shift-right` `unsigned-bit-shift-right` `inc` `dec` `zero?` `neg?` `pos?` `min` `max` `even?` `odd?`

And additionally:

* `bool-and` - `and` working on booleans
* `bool-or` - boolean `or`
* `bool-xor` - boolean `xor`
* `bool-not` - boolean `not`
* `<<` - bit shift left
* `>>` - signed bit shift right
* `>>>` - unsigned bit shift right
* `not==` - not equal

To turn on primitive math on your namespace call [[use-primitive-operators]].
To turn off and revert original versions call [[unuse-primitive-operators]]

### Fast Math

Almost all math functions are backed by [FastMath](https://github.com/jeffhain/jafama) library. Most of them are macros. Some of them are wrapped in Clojure functions. Almost all operates on primitive `double` and returns `double` (with an exception [[round]] or [[qround]] which returns `long`).

### Other functions

Additionally namespace contains functions which are common in frameworks like OpenFrameworks and Processing.

* For random/noise functions check [[fastmath.random]] namespace.
* [[fastmath.vector]] contains vector (2,3,4 dim. + double array + clojure vector) protocol and implementations.
* [[fastmath.complex]] contains complex number operations.

Distance functions.

Distances objects which work with Smile, Apache Commons, fastmath vectors and native clojure sequences.

Easing functions.

List of all are in [[easings-list]].

Vector field functions.

Vector fields are functions R^2->R^2.

Names are taken from fractal flames world where such fields are call `variations`. Most implementations are taken from [JWildfire](http://jwildfire.org/) software.

### Creation

To create vector field call [[field]] multimethod with name of the field as keyword.

Some of the vector fields require additional configuration as a map of parameters as keywords and values. Call [[parametrization]] to create random one or to merge with provided.

Additionally you can provide `amount` parameter which is scaling factor for vector field (default: `1.0`).

### Derived fields

You can use several method to derive new vector field from the other one(s). Possible options are:

* [[derivative]], [[grad-x]], [[grad-y]] - directional derivative of the field
* [[sum]] - sum of two fields
* [[multiply]] - multiplication of the fields
* [[composition]] - composition of the fields
* [[angles]] - angles of the field vectors

### Scalar fields

You can derive scalar fields from given vector field(s):

* [[jacobian]] - determinant of jacobian matrix
* [[divergence]] - divergence of the field
* [[cross]] - cross product of the fields (as a determinant of the 2x2 matrix of vectors)
* [[dot]] - dot product
* [[angle-between]] - angle between vectors from fields.

### Combinations

The other option is to create vector field using some of the above possibilities. Combination is a tree of field operations with parametrizations. Functions:

* [[combine]] - create vector field randomly of from given parametrization.
* [[random-configuration]] - returns random configuration as a map
* [[randomize-configuration]] - change parametrization for given configuration.

Grid calculation functions.

Convert 2d coordinates into various grid coordinates and back.

Terms used:

* cell type - grid cell shape: square, triangular, hexagonal, rhomboidal
* coords - 2d euclidean coordinates (x,y)
* cell - cell coordinates (q,r)
* anchor - cell position in 2d euclidean space
* corners - shape vertices
* size - size of the cell.

### Grids

Each grid is defined by cell type and size. Optionally you can provide translating vector.

Each cell has it's own coordinates, mostly axial based (only square has offset).

For hexagonal cell size is a radius from midpoint to corner. For the rest it is the size of the side.

Cell types are:

* `:square`
* `:shifted-square`
* `:triangle`
* `:rhombus`
* `:flat-hex` - flat topped
* `:pointy-hex` - pointy topped

### Notes

* Hexagonal grids are based on https://www.redblobgames.com/grids/hexagons/
* Only hexagonal cells have anchor at the center. For the rest the anchor is at the top left vertex.
    * Anchors for triangular grids are shared between two cells: even and odd `q` coordinate. Even `q` is pointy topped, odd `q` is flat topped.

1d, 2d interpolation functions.

See more:

* [Apache Commons Math](http://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/org/apache/commons/math3/analysis/interpolation/package-summary.html)
* [Smile Interpolation](http://haifengl.github.io/smile/api/java/smile/interpolation/package-summary.html)

Note: Smile interpolators doesn't check ranges.

### Input data

You provide data as sequence or double array.

#### 1d interpolation

You provide two sequences:

* `xs` - x axis coorditanes, strictly monotonic (increasing)
* `ys` - function values

See [[kriging-spline-interpolator]]

#### 2d interpolation

This is grid based interpolation.

* `xs` - x axis coordinates, strictly monotonic (increasing)
* `ys` - y axis coordinates, strictly monotonic (increasing)
* `vs` - sequence of sequences of values (2d array) for all possible pairs. Array is column-wise: `[ [first column] [second column] ...]`.

See [[cubic-2d-interpolator]]

(let [rng (rng :isaac 1337)]
  (irandom rng))

Various random and noise functions.

Namespace defines various random number generators (RNGs), different types of random functions, sequence generators and noise functions.

### RNGs

You can use a selection of various RNGs defined in [Apache Commons Math](http://commons.apache.org/proper/commons-math/apidocs/org/apache/commons/math3/random/package-summary.html) library.

Currently supported RNGs:

* `:jdk` - default java.util.Random
* `:mersenne` - MersenneTwister
* `:isaac` - ISAAC
* `:well512a`, `:well1024a`, `:well19937a`, `:well19937c`, `:well44497a`, `:well44497b` - several WELL variants

To create your RNG use [[rng]] multimethod. Pass RNG name and (optional) seed. Returned RNG is equipped with [[RNGProto]] protocol with methods: [[irandom]], [[lrandom]], [[frandom]] [[drandom]], [[grandom]], [[brandom]] which return random primitive value with given RNG.

```
(let [rng (rng :isaac 1337)]
  (irandom rng))
```

For conveniency default RNG (`:jdk`) with following functions are created: [[irand]], [[lrand]], [[frand]], [[drand]], [[grand]], [[brand]].

Each prefix denotes returned type:

* i - int
* l - long
* f - float
* d - double
* g - gaussian (double)
* b - boolean

Check individual function for parameters description.

### Random Vector Sequences

Couple of functions to generate sequences of numbers or vectors.

To create generator call [[sequence-generator]] with generator name and vector size [1,4].
Following generators are available:

* `:halton` - Halton low-discrepancy sequence; range [0,1]
* `:sobol` - Sobol low-discrepancy sequence; range [0,1]
* `:r2` - R2 low-discrepancy sequence; range [0,1], [more...](http://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/)
* `:sphere` - uniformly random distributed on unit sphere
* `:gaussian` - gaussian distributed (mean=0, stddev=1)
* `:default` - uniformly random; range:[0,1]

`:halton`, `:sobol` and `:r2` can be also randomly jittered according to this [article](http://extremelearning.com.au/a-simple-method-to-construct-isotropic-quasirandom-blue-noise-point-sequences/). Call [[jittered-sequence-generator]].

After creation you get lazy sequence

### Noise

List of continuous noise functions (1d, 2d and 3d):

* `:value` - value noise
* `:gradient` - gradient noise (improved Ken Perlin version)
* `:simplex` - simplex noise

First two (`:value` and `:gradient`) can use 4 different interpolation types: `:none`, `:linear`, `:hermite` (cubic) and `:quintic`.

All can be used as into:

* Noise - pure noise value, create with [[single-noise]]
* FBM - fractal brownian motion, create with [[fbm-noise]]
* Billow - billow noise, [[billow-noise]]
* RidgedMulti - ridged multi, [[ridgedmulti-noise]]

Noise creation requires detailed configuration which is simple map of following keys:

* `:seed` - seed as integer
* `:noise-type` - type of noise: `:value`, `:gradient` (default), `:simplex`
* `:interpolation` - type of interpolation (for value and gradient): `:none`, `:linear`, `:hermite` (default) or `:quintic`
* `:octaves` - number of octaves for combined noise (like FBM), default: 6
* `:lacunarity` - scaling factor for combined noise, default: 2.00
* `:gain` - amplitude scaling factor for combined noise, default: 0.5
* `:normalize?` - should be normalized to `[0,1]` range (true, default) or to `[-1,1]` range (false)

For usage convenience 3 ready to use functions are prepared. Return is normalized to `[0,1]` range:

* [[noise]] - Perlin Noise (gradient noise, 6 octaves, quintic interpolation)
* [[vnoise]] - Value Noise (as in Processing, 6 octaves, hermite interpolation)
* [[simplex]] - Simpled Noise (6 octaves)

#### Discrete Noise

[[discrete-noise]] is a 1d or 2d hash function for given integers. Returns double from `[0,1]` range.

### Distribution

Various real and integer distributions. See [[DistributionProto]] and [[RNGProto]] for functions.

To create distribution call [[distribution]] multimethod with name as a keyword and map as parameters.

Statistics functions.

* Descriptive statistics for sequence.
* Correlation / covariance of two sequences.
* Outliers

All functions are backed by Apache Commons Math or SMILE libraries. All work with Clojure sequences.

### Descriptive statistics

All in one function [[stats-map]] contains:

* `:Size` - size of the samples, `(count ...)`
* `:Min` - [[minimum]] value
* `:Max` - [[maximum]] value
* `:Range` - range of values
* `:Mean` - [[mean]]/average
* `:Median` - [[median]], see also: [[median-3]]
* `:Mode` - [[mode]], see also: [[modes]]
* `:Q1` - first quartile, use: [[percentile]], [[quartile]]
* `:Q3` - third quartile, use: [[percentile]], [[quartile]]
* `:Total` - [[sum]] of all samples
* `:SD` - sample standard deviation
* `:Variance` - variance
* `:MAD` - [[median-absolute-deviation]]
* `:SEM` - standard error of mean
* `:LAV` - lower adjacent value, use: [[adjacent-values]]
* `:UAV` - upper adjacent value, use: [[adjacent-values]]
* `:IQR` - interquartile range, `(- q3 q1)`
* `:LOF` - lower outer fence, `(- q1 (* 3.0 iqr))`
* `:UOF` - upper outer fence, `(+ q3 (* 3.0 iqr))`
* `:LIF` - lower inner fence, `(- q1 (* 1.5 iqr))`
* `:UIF` - upper inner fence, `(+ q3 (* 1.5 iqr))`
* `:Outliers` - list of [[outliers]], samples which are outside outer fences
* `:Kurtosis` - [[kurtosis]]
* `:Skewness` - [[skewness]]
* `:SecMoment` - second central moment, use: [[second-moment]]

Note: [[percentile]] and [[quartile]] can have 10 different interpolation strategies. See [docs](http://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/org/apache/commons/math3/stat/descriptive/rank/Percentile.html)

### Correlation / Covariance / Divergence

* [[covariance]]
* [[correlation]]
* [[pearson-correlation]]
* [[spearman-correlation]]
* [[kendall-correlation]]
* [[kullback-leibler-divergence]]
* [[jensen-shannon-divergence]]

### Other

Normalize samples to have mean=0 and standard deviation = 1 with [[standardize]].

[[histogram]] to count samples in evenly spaced ranges.

Transforms.

See [[transformer]] and [[TransformProto]] for details.

### Wavelet

Based on [JWave](https://github.com/cscheiblich/JWave/) library.

Be aware that some of the wavelet types doesn't work properly. `:battle-23`, `:cdf-53`, `:cdf-97`.

### Cos/Sin/Hadamard

Orthogonal or standard fast sine/cosine/hadamard 1d transforms.

### Fourier

DFT.

Mathematical vector operations.

### Types

* Fixed size (custom types):
    * Number - 1d vector
    * Vec2 - 2d vector, creator [[vec2]]
    * Vec3 - 3d vector, creator [[vec3]]
    * Vec4 - 4d vector, creator [[vec4]]
    * ArrayVec - fixed size double array wrapper, n-dimensional, creator [[array-vec]]
* Fixed size
    * doubles - double array itself
* Variable size:
    * Clojure's IPersistentVector, creator `[]`
    * Clojure's ISeq

[[VectorProto]] defines most of the functions.

Vectors implements also:

* `Sequable`
* `Sequencial`
* `IFn`
* `Counted`
* `Reversible`
* `Indexed`
* `ILookup`
* `equals` and `toString` from `Object`
* `IPersistentVector`
* `Associative`
* `clojure.core.matrix.protocols`

That means that vectors can be destructured, treated as sequence or called as a function. See [[vec2]] for examples.