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

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

Clustering.

Various clustering algrorithms backed by SMILE library.

Only partition clustering is implemented.

### 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 averages
* `: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 or `:outliers`
* `:data` - samples which belong to the cluster
* `:representative` - centroid 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.

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

Warning: All `bool-` evaluate all parameters.

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.

Distance objects.

Objects implement IFn, Smile and Apache Commons Math distance interfaces.

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.

Gaussian Processes

See more [here](https://nextjournal.com/generateme/gaussian-processes#gp%2B)

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
* [SSJ B-Spline](http://umontreal-simul.github.io/ssj/docs/master/classumontreal_1_1ssj_1_1functionfit_1_1BSpline.html)

Note: Smile interpolators also extrapolate values outside range.

### 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]]

### Examples

Examples below use following functions:

#### 1d
![1d](images/i/1d.png)

#### 2d
![2d](images/i/2d.jpg)

Various kernel functions.

* RBF (double -> double functions)
* vector kernels (vector x vector -> double function; may be positive definite, conditional positive definite, positive semi-definite, mercer)
* density estimation
* some kernel operations

Optimization.

Namespace provides various optimization methods.

* Brent (1d functions)
* Bobyqa (2d+ functions)
* Powell
* Nelder-Mead
* Multidirectional simplex
* CMAES
* Gradient
* Bayesian Optimization (see below)

All optimizers require bounds.

## Optimizers

To optimize functions call one of the following functions:

* [[minimize]] or [[maximize]] - to perform actual optimization
* [[scan-and-minimize]] or [[scan-and-maximize]] - functions find initial point using brute force and then perform optimization paralelly for best initialization points. Brute force scan is done using jitter low discrepancy sequence generator.

You can also create optimizer (function which performs optimization) by calling [[minimizer]] or [[maximizer]]. Optimizer accepts initial point.

All above accept:

* one of the optimization method, ie: `:brent`, `:bobyqa`, `:nelder-mead`, `:multidirectional-simplex`, `:cmaes`, `:gradient`
* function to optimize
* parameters as a map

For parameters meaning refer [Optim package](https://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/index.html?org/apache/commons/math3/optim/package-summary.html)

### Common parameters

* `:bounds` (obligatory) - search ranges for each dimensions as a seqence of [low high] pairs
* `:initial` - initial point other then mid of the bounds as vector
* `:max-evals` - maximum number of function evaluations
* `:max-iters` - maximum number of algorithm interations
* `:bounded?` - should optimizer force to keep search within bounds (some algorithms go outside desired ranges)
* `:stats?` - return number of iterations and evaluations along with result
* `:rel` and `:abs` - relative and absolute accepted errors

For `scan-and-...` functions additionally you can provide:

* `:N` - number of brute force iterations
* `:n` - fraction of N which are used as initial points to parallel optimization
* `:jitter` - jitter factor for sequence generator (for scanning domain)

### Specific parameters

* BOBYQA - `:number-of-points`, `:initial-radius`, `:stopping-radius`
* Nelder-Mead - `:rho`, `:khi`, `:gamma`, `:sigma`, `:side-length`
* Multidirectional simples - `:khi`, `:gamma`, `:side-length`
* CMAES - `:check-feasable-count`, `:diagonal-only`, `:stop-fitness`, `:active-cma?`, `:population-size`
* Gradient - `:bracketing-range`, `:formula` (`:polak-ribiere` or `:fletcher-reeves`), `:gradient-h` (finite differentiation step, default: `0.01`) 

## Bayesian Optimization

Bayesian optimizer can be used for optimizing expensive to evaluate black box functions. Refer this [article](http://krasserm.github.io/2018/03/21/bayesian-optimization/) or this [article](https://nextjournal.com/a/LKqpdDdxiggRyHhqDG5FH?token=Ss1Qq3MzHWN8ZyEt9UC1ZZ)

Set of protocols for fastmath.

Includes:

* random generator protocol
* distribution protocols
* vector protocol

(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.
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 combined in following variants:

* 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. Returning value from `[0,1]` range:

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

For random noise generation you can use [[random-noise-cfg]] and [[random-noise-fn]]. Both can be feed with configuration. Additional configuration:

* `:generator` can be set to one of the noise variants, defaults to `:fbm`
* `:warp-scale` - 0.0 - do not warp, >0.0 warp
* `:warp-depth` - depth for warp (default 1.0, if warp-scale is positive)

#### 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.

Signal processing (effect) and generation (oscillators).

Singal is any sequence with double values.

## Signal processing

To process signal use [[apply-effects]] or [[apply-effects-raw]] (operates on `double-array` only) function.

Effect is signal filter, created by [[effect]] multimethod. Effects can be composed with [[compose-effects]]. Effect can be treated as function and can be called for given sample.

Each effect has it's own parametrization which should be passed during creation.

List of all available effects is under [[effects-list]] value.

### Effects parametrization

Each effect has its own parameters.

#### :simple-lowpass, :simple-highpass

* `:rate` - sample rate (default 44100.0)
* `:cutoff` - cutoff frequency (default 2000.0)

#### :biquad-eq

Biquad equalizer

* `:fc` - center frequency
* `:gain` - gain
* `:bw` - bandwidth (default: 1.0)
* `:fs` - sampling rate (defatult: 44100.0)

#### :biquad-hs, :biquad-ls

Biquad highpass and lowpass shelf filters

* `:fc` - center frequency
* `:gain` - gain
* `:slope` - shelf slope (default 1.5)
* `:fs` - sampling rate (default 44100.0)

#### :biquad-lp, :biquad-hp, :biquad-bp

Biquad lowpass, highpass and bandpass filters

* `:fc` - cutoff/center frequency
* `:bw` - bandwidth (default 1.0)
* `:fs` - sampling rate (default 44100.0)

#### :dj-eq

* `:high` - high frequency gain (10000Hz)
* `:mid` - mid frequency gain (1000Hz)
* `:low` - low frequency gain (100Hz)
* `:shelf-slope` - shelf slope for high frequency (default 1.5)
* `:peak-bw` - peak bandwidth for mid and low frequencies (default 1.0)
* `:rate` - sampling rate (default 44100.0)

#### :phaser-allpass

* `:delay` - delay factor (default: 0.5)

#### :divider

* `:denom` (long, default 2.0)

#### :fm

Modulate and demodulate signal using frequency

 * `:quant` - quantization value (0.0 - if no quantization, default 10)
 * `:omega` - carrier factor (default 0.014)
 * `:phase` - deviation factor (default 0.00822)

#### :bandwidth-limit

https://searchcode.com/file/18573523/cmt/src/lofi.cpp#

* `:rate` - sample rate (default 44100.0)
* `:freq` - cutoff frequency (default 1000.0)

#### :distort

* `:factor` - distortion factor (default 1.0)

#### :foverdrive

Fast overdrive

* `:drive` - drive (default 2.0)

#### :decimator

* `:bits` - bit depth (default 2)
* `:fs` - decimator sample rate (default 4410.0)
* `:rate` - input sample rate (default 44100.0)

#### :basstreble

* `:bass` - bass gain (default 1.0)
* `:treble` - treble gain (default 1.0)
* `:gain` - gain (default 0.0)
* `:rate` - sample rate (default 44100.0)
* `:slope` - slope for both (default 0.4)
* `:bass-freq` - bass freq (default 250.0)
* `:treble-freq` - treble freq (default 4000.0)

#### :echo

* `:delay` - delay time in seconds (default 0.5)
* `:decay` - decay (amount echo in signal, default 0.5)
* `:rate` - sample rate (default 44100.0)

_Warning! Echo filter uses mutable array as a internal state, don't use the same filter in paraller processing._

#### :vcf303

* `:rate` - sample rate (default 44100.0)
* `:trigger` - boolean, trigger some action (default `false`), set true when you reset filter every line
* `:cutoff` - cutoff frequency (values 0-1, default 0.8)
* `:resonance` - resonance (values 0-1, default 0.8)
* `:env-mod` - envelope modulation (values 0-1, default 0.5)
* `:decay` - decay (values 0-1, default 1.0)
* `:gain` - gain output signal (default: 1.0)

#### :slew-limit

http://git.drobilla.net/cgit.cgi/omins.lv2.git/tree/src/slew_limiter.c

* `:rate` - sample rate
* `:maxrise` - maximum change for rising signal (in terms of 1/rate steps, default 500)
* `:maxfall` - maximum change for falling singal (default 500)

#### :mda-thru-zero

* `:rate` - sample rate
* `:speed` - effect rate
* `:depth`
* `:mix`
* `:depth-mod`
* `:feedback`

_Warning: internal state is kept in doubles array._

## Oscillators

[[oscillator]] creates function which generates signal value for given time.

To sample generated wave to signal, call [[oscillator->signal]] with following parameters:

* `f` - oscillator
* `samplerate` - sample rate (samples per second)
* `seconds` - duration

To convert signal to oscillator (using interpolation) use [[signal->oscillator]] passing signal and duration.

Add oscillators using [[oscillators-sum]].

## Smoothing filter

Savitzky-Golay smoothing filter [[savgol-filter]].

## File operations

You can [[save-signal]] or [[load-signal]]. Representation is 16 bit signed, big endian. Use Audacity or SoX to convert to/from audio files.

Statistics functions.

* Descriptive statistics.
* Correlation / covariance
* Outliers
* Confidence intervals
* Extents
* Effect size
* Student's t-test
* Histogram
* ACF/PACF
* Bootstrap
* Binary measures

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]]

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)

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.