QuickData.Numbers.FSharp 0.1.0

QuickData.Numbers.FSharp

Contents

• Overview
• Normal Sequences
  • Conversion with code examples
  • Building with code examples
  • Normal Equations
  • Bell Shapes and Positions
  • Variations with code examples
• Variance Sequences
  • Conversion with code examples
  • Building with code examples
  • Natural Variance Degree
  • Variations with code examples
• Boolean Sequences
  • Conversion
  • Building
  • Variations
• Combining Sequences with code examples
• Dependencies
• Usage

Overview

This QuickData.Numbers.FSharp package contains the QuickData.Numbers.FSharp namespace for F# developers which provides some types, modules, and their related functions for building and manipulating sequences of various (usually numerical) types.

All of the sequences generated by the functions in this package are standard F# sequences, and all of the internal processing is done exclusively with standard F# sequences, so they give you all of the benefits of, and follow the same rules as, standard F# sequences.

See the QuickData.Core.FSharp documentation for more information about the Normal and Variance types.

The modules provided are:

• Normal.Seq : Create and manipulate sequences of Normal;
• Variance.Seq : Create and manipulate sequences of Variance;
• Boolean.Seq : Create and manipulate sequences of bool.

The types provided are:

• BellShape : The different shapes which is used with the Normal.Seq.bell function;
• BellPosition : The different positions which is used with the Normal.Seq.bell function;
• NormalEquation : The equations which is used with the Normal.Seq.byEquation function.
• NaturalVarianceDegree : These are the degrees to which the Variance.Seq.natural function will create a sequence of (close to) naturally changing values;

Note: You can use IntelliSense in your code editor to get more information about each type, module, and function.

Normal Sequences

The Normal.Seq module provides functions for working with sequences of Normal.

Normal Sequence Conversion

A number of functions are available for the conversion of sequences from and to Normals, Variances, floats and booleans.

For example, fromFloats creates a new sequence of Normal from a sequence of float, and toVariances creates a new sequence of Variance from a sequence of Normal.

The denormalise function creates a new sequence of float, via a calculation, from a sequence of Normal.

See the QuickData.Core.FSharp documentation for more information about the Normal and Variance types.

Normal Sequence Conversion Code Examples

let normals = seq { 0.5 ; 0.2 ; 0.6 } |> Normal.Seq.fromfloats
let floats = normals |> Normal.Seq.toFloats
let booleans = normals |> Normal.Seq.toBooleans

Normal Sequence Building

A number of functions are available for the building of a sequence of Normal, including:

• random : Values generated via a random number generator;
• randomised : Randomly chosen values from another sequence (with some convenience functions);
• repeated : An endlessly repeated value (with some convenience functions);
• byEquation : Values are calculated via an equation (see NormalEquation module);
• linearBounce : Values rise from 0.0 to (nearly always) +1.0 then back down to 0.0;
• cycled : Endlessly cycled values from another sequence (with some convenience functions);
• tombola : Endlessly shuffled values from another sequence (with some convenience functions);
• bell : Values whose 'shape' resembles a bell curve.

Note: The functions which require a count parameter will produce a sequence of finite length.

The byEquation function will raise an exception if the internal calculations produce an error. This hasn't been seen in testing but it could be a possibility in some circumstances. If you don't want an exception to be raised then there are three alternative functions, each of which returns a different thing instead of raising an exception, and these are:

• Normal.Seq.FailSafe.byEquation : Returns an empty sequence instead of raising an exception;
• Normal.Seq.Option.byEquation : Returns None instead of raising an exception, otherwise Some seq;
• Normal.Seq.Result.byEquation : Returns Error InternalCalculationError instead of raising an exception, otherwise Ok seq.

Normal Sequence Building Code Examples

let rng = System.Random.Shared // Any random number generator.
let random = Normal.Seq.random rng 
let smoothCurve = Normal.Seq.byEquation NormalEquation.quarterPipe 100 
let minAndMax = Normal.Seq.alternatingMinimumMaximum 
let cycled = seq { Normal.oneFifth ; Normal.fourFifths } |> Normal.Seq.cycled 
let tombola = seq { Normal.oneThird ; Normal.OneHalf ; Normal.twoThirds } |> Normal.Seq.tombola

Normal Equations

The NormalEquation module provides lots of different equations which can be used by the byEquation function to create various shapes of curves.

Some have names which suggest what the curve will look like, such as hockeyStick, but a lot of them are functions named with an 'ease' prefix, such as easeSineIn, and these names can be more difficult to interpret.

In these cases, the word after 'ease' (usually) gives an indication of the 'strength' of the curve, and then the name will have either 'In', 'Out', or 'InOut' at the end.

'In' equations start curving across the X-axis first before curving up the Y-axis. 'Out' equations start curving up the Y-axis first before curving across the X-axis. 'InOut' equations are a litle bit of both where the curve will travel across the X-axis first, then up the Y-axis and through the centre of the shape and then curving across the X-axis again later.

The 'ease' equations are very similar to easing gradients used in animation.

The 'easeBounce' equations are difficult to explain but the shape of a 'Bounce' curve looks a little bit like the path which a rubber ball might take when bounced across your point of view (kind of).

Bell Shapes and Positions

The bell function is modified by two parameters which describe how the shape of the curve is 'drawn'.

The first parameter is the BellShape which determines the width of the bell - from VeryThin to ExtraWide - and the second parameter BellPosition defines its position along the X-axis - from FullLeft to FullRight.

Normal Sequence Variations

A number of functions are available for the variation of a sequence of Normal.

These include:

• raising and lowering the values by a certain amount, e.g. raise, lowerAll, etc.;
• scaling by a given magnitude, e.g. scale and scaleAll;
• flattening the values in different ways, e.g. flattenDown, flattenUpAll, etc.;
• inverting values, e.g. invert;
• adding Variances, e.g. addVariances.

Normal Sequence Variation Code Examples

let originals = Normal.Seq.byEquation NormalEquation.sineWave 50 
let scaledByHalf = originals |> Normal.Seq.scaleAll Normal.oneHalf 
let flattenedDown = originals |> Normal.Seq.flattenDownAll Normal.oneThird 
let reversed = originals |> Seq.rev // Note: Just Seq, not Normal.Seq
let inverted = originals |> Normal.Seq.invert 

Variance Sequences

The Variance.Seq module provides functions for working with sequences of Variance.

Variance Sequence Conversion

A number of functions are available for the conversion of sequences from and to Normals, Variances, and floats.

For example, fromFloats creates a new sequence of Variance from a sequence of float, and toNormals creates a new sequence of Normal from a sequence of Variance.

The expand function creates a new sequence of float, via a calculation, from a sequence of Variance.

See the QuickData.Core.FSharp documentation for more information about the Normal and Variance types.

Variance Sequence Conversion Code Examples

let variances = seq { -0.8 ; 0.0 ; 0.6 } |> Variance.Seq.fromfloats
let normals = variances |> Variance.Seq.toNormals
let normalsSpread = variances |> Variance.Seq.toNormalsSpread

Variance Sequence Building

A number of functions are available for the building of a sequence of Variance, including:

• random : Values generated via a random number generator;
• semiRandom : Values generated via a random number generator - when scaled down they look a bit more natural than a randomly generated sequence;
• natural : Values which look like natural noise;

The natural function will raise an exception if the internal calculations produce an error. This hasn't been seen in testing but it could be a possibility in some circumstances. If you don't want an exception to be raised then there are three alternative functions, each of which returns a different thing instead of raising an exception, and these are:

• Variance.Seq.FailSafe.natural : Returns an empty sequence instead of raising an exception;
• Variance.Seq.Option.natural : Returns None instead of raising an exception, otherwise Some seq;
• Variance.Seq.Result.natural : Returns Error InternalCalculationError instead of raising an exception, otherwise Ok seq.

Variance Sequence Building Code Examples

let rng = System.Random.Shared // Any random number generator.
let random = Variance.Seq.random rng 
let semiRandom = Variance.Seq.semiRandom rng 
let noise = Variance.Seq.natural rng NaturalVarianceDegree.Medium 100

Natural Variance Degree

The natural function is modified by a parameter which describes the shape of the curve.

This parameter determines the 'strength' of noise by which values can vary on the Y-axis, from Lowest to Highest.

Variance Sequence Variations

A number of functions are available for the variation of a sequence of Variance.

These include:

• scaling by a given magnitude, e.g. scale and scaleAll;
• inverting values, e.g. invert;
• adding Variances together, e.g. add.

Variance Sequence Variation Code Examples

let rng = System.Random.Shared // Any random number generator.
let originals = Variance.Seq.natural rng NaturalVarianceDegree.Medium 100
let scaledByHalf = originals |> Variance.Seq.scaleAll Normal.oneHalf 
let reversed = originals |> Seq.rev // Note: Just Seq, not Normal.Seq
let inverted = originals |> Variance.Seq.invert 

Boolean Sequences

The Boolean.Seq module provides functions for working with sequences of bool.

Boolean Sequence Conversion

You can convert a sequence of bool to a sequence of Normal via functions in the Normal.Seq module.

Boolean Sequence Building

A number of functions are available for the building of a sequence of bool:

• random : True and false values generated via a random number generator;
• repeatedTrue : The value true repeated endlessly;
• repeatedFalse : The value false repeated endlessly;
• alternatingTrueFalse : True, then false, repeated endlessly;
• alternatingFalseTrue : False, then true, repeated endlessly;
• tombola : True and false shuffled endlessly.

Note: All generated boolean sequences are of infinite length.

Boolean Sequence Variations

There is one function which varies a sequence of bool, which is

• not : If element is true then output is false, otherwise output is true.

Combining Sequences

The generated sequences can either be used individually or they can be combined in various ways to acheive something more interesting.

For example, the following code produces a long sequence where a signal is oscillating nicely - with a bit of noise - but then fades out to no signal (still with a bit of noise), and then ramps up randomly a little, and then has a big random burst which fades out, and then the signal falls to a flat zero.

// Randomly-chosen seed - try different seed values for different sequences.
let rng = System.Random 56370 

// This sequence truncates the below oscillating sequence early by being shorter.
let oscillatorNoise = 
    Variance.Seq.natural rng NaturalVarianceDegree.Low 85 

let nicelyOscillatingButNoisySignal = 
    Normal.Seq.byEquation NormalEquation.sineWave 100 
    |> Variance.Seq.fromNormalsSpread 
    |> Variance.Seq.scaleAll Normal.oneHalf  
    |> Variance.Seq.add oscillatorNoise 

let fadeOut = 
    Normal.Seq.byEquation NormalEquation.quarterPipe 100 
    |> Seq.rev 

// This sequence has the same length as the sequence which it will modify.
let signalDropOffNoise = 
    Variance.Seq.natural rng NaturalVarianceDegree.Low 50 
    |> Variance.Seq.scaleAll Normal.oneHalf  
    |> Variance.Seq.scale fadeOut 

let signalDropOff = 
    Normal.Seq.byEquation NormalEquation.easeExpoIn 50 
    |> Seq.rev 
    |> Variance.Seq.fromNormals 
    |> Variance.Seq.scaleAll Normal.oneThird  
    |> Variance.Seq.invert 
    |> Variance.Seq.add signalDropOffNoise 

let fadeIn = 
    Normal.Seq.byEquation NormalEquation.hockeyStick 100 

// The length of the fadeIn sequence truncates this infinite semiRandom sequence.
let noisySignalIncreasingSlowly = 
    Variance.Seq.semiRandom rng 
    |> Variance.Seq.scaleAll Normal.oneFifth 
    |> Variance.Seq.scale fadeIn 

// The length of the fadeOut sequence truncates this infinite random sequence.
let burstOfNoiseFadingOutSignal = 
    Variance.Seq.random rng 
    |> Variance.Seq.scale fadeOut 

// This sequence is truncated as required when the fullSequence is enumerated.
let lossOfSignal = 
    Normal.Seq.repeatedOneHalf 
    |> Variance.Seq.fromNormalsSpread 

// Join the relevant sequences together in order.
let fullSequence = 
    seq { 
        yield! nicelyOscillatingButNoisySignal 
        yield! signalDropOff 
        yield! noisySignalIncreasingSlowly 
        yield! burstOfNoiseFadingOutSignal 
        yield! lossOfSignal } 

// Create the expansion range with the required magnitudes.
let signalRange = ExpansionRange.fromFloats -24.0 +24.0 

let numberOfValues = 401 

let xAxisValues = seq { 0..(numberOfValues - 1) } 

// Expand the sequence to the necessary range.
let yAxisValues = fullSequence |> Variance.Seq.expand signalRange

Dependencies

This package is dependent upon FSharp.Core which you will be using anyway, and the QuickData.Core.FSharp package which will normally be automatically installed if you install this package.

Usage

The types and functions in this package have been designed to be used only with F#.

However, they may also be usable with C# but this has not been tested, so use them with C# at your own risk.