Model

java.lang.Object
- la.la.Value
- - mml.Model

All Implemented Interfaces:

java.lang.Comparable<Value>

Direct Known Subclasses:

FunctionModel, KnownClass, Model.Defaults, SeriesModel, UPModel.M
```
public abstract class Model
extends Value
```
The abstract class of fully parameterised statistical Models. The main job of a Model is to return the probability, pr(d), and negative-log probability, nlPr(d), of a datum, d. Most instances of Model are likely to be instances of UPModel.M and often the UnParameterised-Model's Estimator estimates a fully parameterised Model from a given data-set, for example, MML.Normal estimates a Normal (Gaussian) probability distribution, N_μ,σ. Among example Models, MultiState.M has non-trivial statistical-parameters but Discretes.Uniform.M does not. There are sub-classes of Model, such as Discretes.M and Multivariate.M, that make it easier to create certain kinds of Model. Note that a Model is a first-class Value.
Also see FunctionModel and SeriesModel.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Model.Defaults` A subclass of `Model` that sets default methods `stats(ds,lo,hi)`, `stats(add,ss0,ss1)` and `nlLH(ss)`, even if they are slow.
`class`	`Model.Transform` Transform (the data for) Model.this by Function f (which is the problem defining parameter).

Nested classes/interfaces inherited from class la.la.Value
Value.Atomic, Value.Bool, Value.Char, Value.Chars, Value.Cts, Value.Defer, Value.Discrete, Value.Enum, Value.Inc_Or, Value.Int, Value.Lambda, Value.List, Value.Maybe, Value.Option, Value.Real, Value.Scannable, Value.Structured, Value.Triv, Value.Tuple

Field Summary

Fields
Modifier and Type	Field and Description
`protected double`	`msg1` Where appropriate, the lengths of the first (msg1), and second (msg2) parts of an [MML] message transmitting (i) a Model (parameter estimate) θ, and (ii) training data-set ds\|θ.
`protected double`	`msg2` Where appropriate, the lengths of the first (msg1), and second (msg2) parts of an [MML] message transmitting (i) a Model (parameter estimate) θ, and (ii) training data-set ds\|θ.
`protected Value`	`sp` Holds the statistical parameter(s), if any, of 'this' Model; is returned by `statParams()`.

Fields inherited from class la.la.Value
C, comparator, CR, E, eight, ffalse, five, fiveR, four, fourR, half, negCR, negOne, negOneR, negTenR, nilVal, nine, None, one, oneR, PI, PIby2, point01, point1, point5, point9, quarter, seven, six, ten, tenR, three, threeR, triv, ttrue, two, twoR, zero, zeroR

Constructor Summary

Constructors
Constructor and Description
`Model(double msg1, double msg2, Value sp)` `msg1` and `msg2` are the lengths, in nits, of transmitting (i) the Model's statistical parameter(s), `sp`, and (ii) training data-set, ds\|sp, where D was the training-data used to estimate sp.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`Estimator`	`asEstimator(Value ps)` Return an Estimator that always "estimates" 'this' Model.
`Model`	`asGiven(double msg2)` Return 'this' Model as a "given", with zero first-part message length, and a specified second-part, msg2, `asGiven(0,msg2)`.
`Model`	`asGiven(double msg1, double msg2)` Enables setting the first- and second-part message lengths, msg1 and msg2, after having estimated the statistical parameter(s) of a Model, say.
`UPModel`	`asUPModel()` It might be necessary, in some context, to treat 'this' fully parameterised Model as an `UnParameterised` Model, having trivial problem-definition parameter, that always produces (by `apply`, `estimator`, etc.) 'this' Model `asGiven`, so to say.
`Value.Tuple`	`m1m2sp()` Return the triple(`msg1()`, `msg2()`, `statParams()`).
`double`	`msg()` The length of a two-part MML message, 'M; (ds\|M)', where ds was the training-data used when estimating 'this' Model 'M'.
`double`	`msg1()` Length of the 1st part, 'M', of a two-part MML message 'M; (ds\|M)', where ds was the training data.
`double`	`msg1bits()` `msg1()` in bits.
`double`	`msg2()` Length of the 2nd part, '(ds\|M)', of a two-part MML message 'M; (ds\|M)', where D was the training-data.
`double`	`msg2bits()` `msg2()` in bits.
`double`	`msgBits()` `msg()` in bits.
`double`	`nl2LH(Value ss)` The `nlLH(ss)` of (sufficient stats, ss, of) a data-set, ds, but in bits, instead of nits.
`double`	`nl2Pr(Value d)` Return the negative log₂ probability, nl2Pr, of datum 'd', in bits.
`abstract double`	`nlLH(Value ss)` Given sufficient statistics, ss = `stats(ds)`, of a data-set, ds, return the negative log LikeliHood, nlLH(ss), of ds.
`abstract double`	`nlPr(Value d)` The negative log_e `probability` of a datum, 'd', in nits; nlPr must be defined when implementing a Model.
`double`	`pr(Value d)` The probability of a datum, 'd', given 'this' Model; also see `nlPr(d)`.
`Value`	`random()` Return a random Value from the modelled population, if possible.
`Vector`	`random(int n)` Return 'n' `random()` Values, if possible.
`Series`	`randomSeries()` Return a `Series` which repeatedly `returns` a `random()` Value from 'this' Model, provided the Model can do so.
`Value`	`statParams()` The statistical parameters (possibly `estimated`), if any, of 'this' Model as stored in `sp`.
`abstract Value`	`stats(boolean add, Value ss0, Value ss1)` Combine `statisticses`, ss0 ± ss1.
`Value`	`stats(boolean add, Value ss0, Vector ds, int lo, int hi)` `Combine` statisticses ss0 and `stats(ds,lo,hi)`.
`Value`	`stats(Vector ds)` Return sufficient statistics, `stats(ds,0,ds.nElts())`, of a data-set 'ds'.
`abstract Value`	`stats(Vector ds, int lo, int hi)` For 'this' Model, calculate sufficient statistics, 'ss', of elements [lo, hi) of 'ds', e.g., for use in `nlLH(ss)`.
`double`	`sumNlPr(Vector ds)` ∑ negative log probability over all data elements in data-set ds; you might want `nlLH(ss)` and `stats(ds)` instead? `sumNlPr(ds)` and `nlLH(ss)` should be equal but the latter is often quicker (where ss=`stats(ds)`).
`java.lang.String`	`toString()` Show the details of 'this' Model.
`Model`	`transform(Function f)` Transform 'this' already parameterised Model by Function 'f', roughly transform: (a→b)→Model a→Model b.
`Type`	`type()` Returns `Type.MODEL`.
`protected void`	`zeroTriv(double msg1, Value sp)` Check msg1 = 0 and sp = (), that both are trivial.

Methods inherited from class la.la.Value
AoM, apply, bOp, compareTo, cons, cts, elt, errMsg, error, force, isTuple, just, main, n, nElts, nlAoM, pair, print, quad, real, RTE, triple, tuple, UOE, uOp, x

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - msg1
```
protected final double msg1
```
    Where appropriate, the lengths of the first (msg1), and second (msg2) parts of an [MML] message transmitting (i) a Model (parameter estimate) θ, and (ii) training data-set ds|θ. Failing that, e.g., if the Model is a given, such as N_0,1, set msg1 and msg2 to zero.
  - msg2
```
protected final double msg2
```
    Where appropriate, the lengths of the first (msg1), and second (msg2) parts of an [MML] message transmitting (i) a Model (parameter estimate) θ, and (ii) training data-set ds|θ. Failing that, e.g., if the Model is a given, such as N_0,1, set msg1 and msg2 to zero.
  - sp
```
protected final Value sp
```
    Holds the statistical parameter(s), if any, of 'this' Model; is returned by statParams(). Also see the problem-defining parameters.
- Constructor Detail
  - Model
```
public Model(double msg1,
             double msg2,
             Value sp)
```
    msg1 and msg2 are the lengths, in nits, of transmitting (i) the Model's statistical parameter(s), sp, and (ii) training data-set, ds|sp, where D was the training-data used to estimate sp. If this Model is a given, set msg1=msg2=0.
- Method Detail
  - type
```
public Type type()
```
    Returns Type.MODEL.
    
    Specified by:
    
    type in class Value
  - statParams
```
public Value statParams()
```
    The statistical parameters (possibly estimated), if any, of 'this' Model as stored in sp. Also see m1m2sp() and UPModel.apply(la.la.Value).
  - m1m2sp
```
public Value.Tuple m1m2sp()
```
    Return the triple(msg1(), msg2(), statParams()). That amounts to a specification of the Model.
  - msg1
```
public double msg1()
```
    Length of the 1st part, 'M', of a two-part MML message 'M; (ds|M)', where ds was the training data. More details under [msg()].
  - msg2
```
public double msg2()
```
    Length of the 2nd part, '(ds|M)', of a two-part MML message 'M; (ds|M)', where D was the training-data. More details under [msg()].
  - msg
```
public double msg()
```
    The length of a two-part MML message, 'M; (ds|M)', where ds was the training-data used when estimating 'this' Model 'M'. When MML87 is used, the standard formulae (Wallace 2005, §5.2.8, p.235) are
    - msg1 = - log(h θ') + (1/2)log(F θ') + (k/2)log κ_{k, and}
    - msg2 = - log(f(ds|θ') + k/2 nits,
    - for k-dimensional parameter estimate θ', prior h(θ'), Fisher F(θ'), lattice constant κ_k, and likelihood f(ds|θ').
    - The '+k/2' term in msg2 is the expected correction for rounding off θ' to optimal (limited) precision.
    - Statistical parameter(s) θ' is chosen to minimise msg = msg1 + msg2.
    It could be argued that msg is not a property of the Model in isolation, rather of the process of estimating the Model in some context but, given the way that Models are estimated and compared, it is very convenient in practice to have msg=msg1+msg2 easily available from the Model. Also note that if a Model is used twice in a message, it is only transmitted once, and must be "free" the second time.
  - msg1bits
```
public double msg1bits()
```
    msg1() in bits.
  - msg2bits
```
public double msg2bits()
```
    msg2() in bits.
  - msgBits
```
public double msgBits()
```
    msg() in bits.
  - pr
```
public double pr(Value d)
```
    The probability of a datum, 'd', given 'this' Model; also see nlPr(d). Note that for a large, complex datum, d, pr(d) may underflow to zero. Best stick with nlPr(d) in such cases. This default pr(d) calls nlPr(d).
  - nlPr
```
public abstract double nlPr(Value d)
```
    The negative log_e probability of a datum, 'd', in nits; nlPr must be defined when implementing a Model. Also see nl2Pr(d).
  - sumNlPr
```
public final double sumNlPr(Vector ds)
```
    ∑ negative log probability over all data elements in data-set ds; you might want nlLH(ss) and stats(ds) instead? sumNlPr(ds) and nlLH(ss) should be equal but the latter is often quicker (where ss=stats(ds)). Also see Model.Defaults.nlLH(la.la.Value).
  - nl2Pr
```
public double nl2Pr(Value d)
```
    Return the negative log₂ probability, nl2Pr, of datum 'd', in bits. Calculations are done in nits but people often like information to be displayed in bits.
  - random
```
public Value random()
```
    Return a random Value from the modelled population, if possible. Note, random() is not abstract, rather a Model optionally implements it, with this default random() throwing an Exception. (If implemented well, random() isn't very FP-unctional.-) Also see random(n) and MML.RNG.
  - random
```
public Vector random(int n)
```
    Return 'n' random() Values, if possible. The result can be used as an artificial (test-) data-set, say.
  - randomSeries
```
public Series randomSeries()
```
    Return a Series which repeatedly returns a random() Value from 'this' Model, provided the Model can do so. But don't forget to advance() or it won't be very random! Also see Adaptive.M.randomSeries().
  - stats
```
public Value stats(Vector ds)
```
    Return sufficient statistics, stats(ds,0,ds.nElts()), of a data-set 'ds'. There is unlikely to be any need for a subclass (a Model) to override stats(ds). Also see nlLH(ss).
  - stats
```
public abstract Value stats(Vector ds,
                            int lo,
                            int hi)
```
    For 'this' Model, calculate sufficient statistics, 'ss', of elements [lo, hi) of 'ds', e.g., for use in nlLH(ss). An option is to return the data itself, as in Model.Defaults, but many Models can do better. Note that ss=stats(ds,lo,hi) and nlLH(ss) must be consistent. A UPModel.M's stats(ds,lo,hi) might be able to make use of an enclosing UPModel's stats(ds,lo,hi) if the same stats(...) are used for estimating, but this is not always the case, e.g., see Model BestOf.M.
  - stats
```
public abstract Value stats(boolean add,
                            Value ss0,
                            Value ss1)
```
    Combine statisticses, ss0 ± ss1. '+' if 'add' is true, else '−'. An option is to return the data itself, as in Model.Defaults, but many Models can do better. Also see stats(add,ss0,ds,lo,hi).
  - stats
```
public Value stats(boolean add,
                   Value ss0,
                   Vector ds,
                   int lo,
                   int hi)
```
    Combine statisticses ss0 and stats(ds,lo,hi). This allows advantage to be taken of additive (incremental) statistics, e.g., by Intervals. There is unlikely to be a need for a subclass (a Model) to override stats(add,ss0,ds,lo,hi).
  - nlLH
```
public abstract double nlLH(Value ss)
```
    Given sufficient statistics, ss = stats(ds), of a data-set, ds, return the negative log LikeliHood, nlLH(ss), of ds. Make sure that nlLH(ss), ss = stats(ds,lo,hi), and any Estimator are consistent!
  - nl2LH
```
public double nl2LH(Value ss)
```
    The nlLH(ss) of (sufficient stats, ss, of) a data-set, ds, but in bits, instead of nits.
  - toString
```
public java.lang.String toString()
```
    Show the details of 'this' Model.
    
    Overrides:
    
    toString in class Value
  - transform
```
public Model transform(Function f)
```
    Transform 'this' already parameterised Model by Function 'f', roughly transform: (a→b)→Model a→Model b. (Returns a Model, in fact a Model.Transform.M.) Convenience function for 'new Transform(f).Mdl. Note that 'f' must be 1-to-1.
    Also see the related but different UPModel.transform(la.la.Function); note that, as distributions, upm(sp).transform(f)=upm.transform(f)(sp).
    The result of this transform(f) is "just" a Model; if you need a more specific sub-class of Model, do as in Continuous.M.transform(f) and R_D.M.transform(f).
  - asGiven
```
public Model asGiven(double msg2)
```
    Return 'this' Model as a "given", with zero first-part message length, and a specified second-part, msg2, asGiven(0,msg2). This may be necessary because the Model may be competing against others on some new "training" data-set. For example, asUPModel() returns asGiven(msg2). Also see UPModel.M.asGiven(msg2).
  - asGiven
```
public Model asGiven(double msg1,
                     double msg2)
```
    Enables setting the first- and second-part message lengths, msg1 and msg2, after having estimated the statistical parameter(s) of a Model, say. Also see asGiven(msg2).
  - zeroTriv
```
protected void zeroTriv(double msg1,
                        Value sp)
```
    Check msg1 = 0 and sp = (), that both are trivial. If not, throw an error. This can be required of a Uniform Model, say, because the standard constructor for every Model has the form foobar(msg1, msg2, sp).
  - asUPModel
```
public UPModel asUPModel()
```
    It might be necessary, in some context, to treat 'this' fully parameterised Model as an UnParameterised Model, having trivial problem-definition parameter, that always produces (by apply, estimator, etc.) 'this' Model asGiven, so to say. Note that the result is just a UPModel so, if you want a subclass, override asUPModel suitably. If you want 'this' Model as an Estimator use asEstimator(triv). Also see FunctionModel.asUPModel() and SeriesModel.asUPModel().
  - asEstimator
```
public Estimator asEstimator(Value ps)
```
    Return an Estimator that always "estimates" 'this' Model. Note the "estimated" Model is a given, and thus has msg1=0. Also see asUPModel(). Note, ps=triv!

Class Model

Nested Class Summary

Nested classes/interfaces inherited from class la.la.Value

Field Summary

Fields inherited from class la.la.Value

Constructor Summary

Method Summary

Methods inherited from class la.la.Value

Methods inherited from class java.lang.Object

Field Detail

msg1

msg2

sp

Constructor Detail

Model

Method Detail

type

statParams

m1m2sp

msg1

msg2

msg

msg1bits

msg2bits

msgBits

pr

nlPr

sumNlPr

nl2Pr

random

random

randomSeries

stats

stats

stats

stats

nlLH

nl2LH

toString

transform

asGiven

asGiven

zeroTriv

asUPModel

asEstimator