The reference manual in PDF format is available in the download page.
The reference manual in PDF format is available in the download page.
This manual is to explain the program execution procedures created in the “Monte Carlo Dynamic Classifier (MCDC) Tools development and experiment supporting work”. Monte Carlo Dynamic Classifier Tools is a program that performs model estimation of arbitrary observed data sequences and estimation of state sequences of its estimated model. The estimated model can be used for class separation of observed data sequences by applying it to different observed data sequences and calculating the likelihood of the model.
MCDC Tools is composed of the following program bundle:
The following chapters of this manual
explain the execution methods and examples of these
programs (Chapter 2), and program
structures (Chapter 3). Further, in
a section of the sample program attached to these
tools, motion capture data is used. The motion
capture data is offered publicly in the CMU Graphics
Lab Motion Capture Database. The use
permission conditions are stated in Chapter
4.
MCDC
Tools offers MCDC Train that performs model estimation
for observed data sequences, and MCDC Test, which
conduct an estimation of state sequences of unknown
observed data sequences using the estimated model.
MCDCTrain function is a program, which performs model estimation for observed data sequences.
MCDCTrain function can be executed as follows :
[ IDX, SKP, OKP, FV, GV, XE, YE, loglik ] = MCDCTrain( ...
algorithm, ...
grids, ...
stateKernelGens, ...
obsKernelGens, ...
stateMeanFuncs, ...
obsMeanFuncs, ...
gridDimForGM, ...
splineHandle, ...
x0, ...
xaux, ...
u, ...
y', ...
N, ...
J, ...
K, ...
aspect ...
);
It can also read the output file from past executions and perform continuous iterative executions. In this case, the MCDC Train function is executed as follows. In case of iterative executions, read the parameters from the designated MAT-File and resume execution with the same configurations as previously. However, by assigning a class of Name and Value, the previous configuration can be overwritten and executed.
[IDX, SKP, OKP, FV, GV, XE, YE, loglik] = MCDCTrain(matfile, aspect, Name, Value. ...)
The parameters of MCDCTrain function are as follows:
| Parameter |
Data type |
Description |
|---|---|---|
| algorithm | Algorithm | Kind of algorithm |
| xGrids | G double[] cell | Coordinates of lattice point formed on state space. Display each dimensional value as cell array stored as double array. |
| stateKernelGens | Dx handle cell | Kernel prior distribution of state transition function. Dx indicates the number of dimensions subject to estimation in state space. |
| obsKernelGens | P handle cell | Kernel prior distribution of observation function. |
| gridDimForGramMatrix | int | Dimensions used to create gram matrix. |
| splineHandle | handle | Algorithm used for spline interpolation. Currently, it is fixed as generic spline handle. |
| x0 | Dx*1 double | Initial state of state variables. |
| xaux | Da*T double | Additional state data. |
| u | D*T double | Control data. |
| z | P*T double | Observed data. |
| N | int | Number of particles when particle filter is executed. |
| J | int | Entire number of MCMC iterations. |
| K | int | Observed offset. |
| aspect | Aspect | System configuration information (log output destination, etc.). |
Select algorithm parameter from any of the classes below:
| Class name |
Description of algorithm |
|---|---|
| PSMC | Generate state transition function and observed function by random sampling from Gaussian process. This does not perform parameter estimation. |
| PMCMC | Generate state transition function and observed function by random sampling from Gaussian process. Use particle Markov chain Monte Carlo (PMCMC) method for parameter estimation. |
| PMCMC2 | Generate state transition function and observed function by random sampling from Gaussian process. Use particle Markov chain Monte Carlo method for parameter estimation. Use one dimension only specific to state space for covariance function. |
When PMCMC2 is used as algorithm, select a learning method of mean value function and covariance function, or a learning method of kernel parameters used in covariance function from below:
| Class name |
Description of algorithm |
|---|---|
| MCDCStrategyChoice1 | Without learning average function, always use anchor model. Use kernel function for covariance function. |
| MCDCStrategyChoice2 | Perform sampling of functions from present GP surface used as a mean value function. Use kernel function for covariance function. |
| MCDCStrategyChoice3 | Perform sampling of functions from present GP surface used as a mean value function. Use fixed covariance matrix without using kernel function for covariance function. |
| RBFKernelGeneratorStrategyChoice1 | Perform a random sampling of RBF kernel’s kernel-parameters from prior distribution. |
| RBFKernelGeneratorStrategyChoice2 | Generate RBF kernel’s kernel-parameters from present value of random walk. |
Returned values as a result of MCDC Train function are as follows:
| Value |
Data type |
Description |
|---|---|---|
| IDX | J*1 double | Number of cumulative receipts until j-th iteration. |
| SKP | A*D*2 double | At a-th received iteration, kernel parameters of state transition function (sigma, l). |
| OKP | A*P*2 double | At a-th received iteration, kernel parameters of observed function (sigma, l). |
| FV | A*D*G double | At a-th received iteration, values on lattice point by state transition function. G indicates a multidimensional array that corresponds with the size of lattice point. |
| GV | A*P*G double | At a-th received iteration, values on lattice point by observation function. G indicates a multidimensional array that corresponds with the size of lattice point. |
| XE | A*T*D double | At a-th received iteration, estimated mean of state variables at time t. |
| YE | A*T*P double | At a-th received iteration, estimated mean of observed variables at time t. |
| loglik | A*1 double | At a-th received iteration, estimated logarithmic likelihood by particle filter. |
Intermediate state will be stored in accordance with the aspect settings when executing. This will be output as a dump file in .MAT format. The data stored in the file is as follows:
| Value |
Data type |
Description |
|---|---|---|
| algorithm | Algorithm | Algorithm passed to MCDC Train parameters. |
| in | MCDCInput | All MCDC Train parameters excluding algorithm and aspect. |
| out | MCDCOutput | All return values of MCDC Train (halfway state) and present number of iteration (j). |
The log file will be outputted in accordance with the aspect settings when executing. This is a text format file. The log file will be the following format.
2014/04/26 11:29:36 - Iteration 18 / 200 2014/04/26 11:29:36 - StateKernel[1]: [ Sigma=8.932992, L=7.409991 ] 2014/04/26 11:29:36 - StateKernel[2]: [ Sigma=4.410584, L=2.304895 ] 2014/04/26 11:29:36 - ObsKernel[1]: [ Sigma=1.711191, L=9.248074 ] 2014/04/26 11:29:36 - ObsKernel[2]: [ Sigma=9.867704, L=9.599577 ] 2014/04/26 11:29:36 - ObsKernel[3]: [ Sigma=7.700470, L=8.679293 ] 2014/04/26 11:29:36 - Creating GramMatrix using 1 dim... 2014/04/26 11:29:36 - StateKernel[1] Done 2014/04/26 11:29:36 - StateKernel[2] Done 2014/04/26 11:29:36 - ObsKernel[1] Done 2014/04/26 11:29:36 - ObsKernel[2] Done 2014/04/26 11:29:36 - ObsKernel[3] Done 2014/04/26 11:29:36 - Drawing GP surface... 2014/04/26 11:29:36 - Estimating using particle filter... (N=500) 2014/04/26 11:30:20 - Acceptance log probability = 232745.510426 2014/04/26 11:30:20 - logLH = -5347068.232758, accepted 2014/04/26 11:30:20 - Elapsed time is 44.324939 seconds. 2014/04/26 11:30:20 - j: 8 bytes 2014/04/26 11:30:20 - IDX: 1600 bytes 2014/04/26 11:30:20 - SKP: 128 bytes 2014/04/26 11:30:20 - OKP: 192 bytes 2014/04/26 11:30:20 - FV: 61504 bytes 2014/04/26 11:30:20 - GV: 92256 bytes 2014/04/26 11:30:20 - XE: 122752 bytes 2014/04/26 11:30:20 - YE: 184128 bytes 2014/04/26 11:30:20 - loglik: 32 bytes
MCDCTest function estimates unknown state
of data using the acquired model by MCDC Train. This can be
applied to a class separation problem by performing
state estimation using multiple different models and
comparing the likelihood of each.
MCDCTest function is executed as follows.
[ result, FnState, FnObs ] = MCDCTest(u, y, N, modelFile)
Parameters of MCDC Test function are as follows:
| Parameter |
Data type |
Description |
|---|---|---|
| u | D*T double | Control data. |
| y | P*T double | Observed data. |
| N | int | Number of particles when particle filter is executed. |
| modelFile | chars | Model file. |
Returned values as a result of MCDCTest function are as follows:
| Value |
Data type |
Description |
|---|---|---|
| result | ParticleFilter | Number of cumulative receipts up to j-th iteration. |
| FnState | handle | State transition function. |
| FnObs | handle | Observation function. |
The result of return value includes the result of state estimation by particle filter, which has the following structures:
| Value |
Data type |
Description |
|---|---|---|
| Particles | N*T*D double | Coordinates of each particle at time t. |
| Weights | N*T double | Weight of each particle at time t. |
| Loglik | double | Logarithmic likelihood of estimated state. |
The model estimated by MCDC Train can be outputted into a PDF file using a set of functions defined in Graph class. The following graphs can be outputted.
This outputs a temporal transition graph of results by pursuing observed data by particle filters using observed data sequences and estimated models. In MCMC iteration, it outputs the results using an estimated model at designated specific iterations. It also outputs graphs with respect to each dimension of observed data sequences. It is executed as follows:
Graphs.YE( ... outputFileNamePrefix, ... matFileName, ... iterations, ... times ... );
Parameters are as follows:
| Parameter |
Data type |
Description |
|---|---|---|
| outputFileNamePrefix | char[] | File name prefix of output graph file. The file name will be a designated prefix followed by the number of dimensions and extension of .PDF. |
| matFileName | char[] | MATLAB data file name, including estimated model. |
| iterations | int[] | Matrix that lists MCMC iteration of plotted estimated values. |
| times | int[] | Range of plotted data sequence. Output the entire data sequence when omitted. |
It outputs a temporal transition graph of state sequences estimated values by particle filters using estimated models. In MCMC iteration, it outputs a result using an estimated model at a designated specific iteration. It also outputs a graph with respect to each dimension of state sequences. It is executed as follows. It is executed as follows.
Graphs.XE( ... outputFileNamePrefix, ... matFileName, ... iterations, ... times ... );
Parameters are as follows:
| Parameter |
Data type |
Description |
|---|---|---|
| outputFileNamePrefix | char[] | File name prefix of output graph file. The file name will be a designated prefix followed by the number of dimensions and extension of .PDF. |
| matFileName | char[] | MATLAB data file name, including estimated model. |
| iterations | int[] | Matrix that lists MCMC iteration of plotted estimated values. |
| times | int[] | Range of plotted data sequence. Output the entire data sequence when omitted. |
This outputs a temporal transition graph of results by pursuing observed data by particle filters using observed data sequences and estimated models. It uses the mean estimated model of entire MCMC iteration. It also outputs graphs with respect to each dimension of observed data sequences. It is executed as follows.
Graphs.YEMean( ... outputFileNamePrefix, ... matFileName, ... times ... );
Parameters are as follows:
| Parameter |
Data type |
Description |
|---|---|---|
| outputFileNamePrefix | char[] | File name prefix of output graph file. The file name will be a designated prefix followed by the number of dimensions and extension of .PDF. |
| matFileName | char[] | MATLAB data file name, including estimated model. |
| times | int[] | Range of plotted data series. Output the entire data sequence when omitted. |
This outputs a temporal transition graph of state sequence of estimated values by particle filters using estimated models. It uses the mean estimated model of the entire MCMC iteration. It also outputs a graph with respect to each dimension of state sequence. It is executed as follows.
Graphs.XEMean( ... outputFileNamePrefix, ... matFileName, ... times ... );
Parameters are as follows:
| Parameter |
Data type |
Description |
|---|---|---|
| outputFileNamePrefix | char[] | File name prefix of output graph file. The file name will be a designated prefix followed by the number of dimensions and extension of .PDF. |
| matFileName | char[] | MATLAB data file name, including estimated model. |
| times | int[] | Range of plotted data series. Output the entire data sequence when omitted. |
In model estimation, it outputs logarithmic likelihood models estimated by each MCMC iteration, which is executed as follows.
Graphs.Loglik( ... outputFileNamePrefix, ... matFileName1, ... matFileName2, ... ... );
Parameters are as follows:
| Parameter |
Data type |
Description |
|---|---|---|
| outputFileNamePrefix | char[] | File name prefix of output graph file. The file name will be a designated prefix followed by extension of .PDF. |
| matFileName1, 2, ... | char[] | MATLAB data file name, including estimated model. If multiple files are selected, it draws graphs of each individually as one sequence. |
In model estimation, it outputs mean square error of the results of estimated observed data sequences using estimated models up to each MCMC iteration, which is executed as follows.
Graphs.Rmse( ... outputFileNamePrefix, ... matFileName ... );
Parameters are as follows:
| Parameter |
Data type |
Description |
|---|---|---|
| outputFileNamePrefix | char[] | File name prefix of output graph file. The file name will be a designated prefix followed by extension of .PDF. |
| matFileName | char[] | MATLAB data file name, including estimated model. |
As an
execution example of model estimation by MCDC
Train, the performing of estimation of observed
data sequences generated from Kitagawa’s model
is shown.
The following code samples are included in samples/KitagawaModelPMCMCEstimation2.m.
First, prepare observed data subject to model estimation. Generally, observed data should be provided in advance, here we use data sequences generated from Kitagawa’s model as observed data.
[x, y] = KitagawaModel(1000, 0.5, 28, 8, 0.6, 30, 10, 0.05, 0.06, 0.07, 0.08, 0.1, 0.1); u = repmat(cos(1.2 * [1:T]), 2, 1)';
Due to this code, observed data sequences are stored in y. State sequences are stored in x, but x is not going to be used after this process. Further, in Kitagawa’s model, to give time-varying control data, control data sequences are also generated here together with observed data.
MCDC Train performs model estimations with state space models being unknown. With the current program, the number of dimensions of state space and the moving range for values of state variables need to be given. In the following, consider the two-dimensional state space and configure the lattice point in the range from -30 to 30 at 2.0 increments for each dimension.
grids = { ...
[-30:2:30], ...
[-30:2:30] ...
};
In the process of model estimation, perform sampling a value of function from the Gaussian process on the lattice point configured here and by performing spline interpolation so that state transition function and observation function are created. The expressive power of the model is stronger when many lattice points are selected in a wider extent. However, it will significantly increase the processing time and the amount of memory used.
Next, design models for state transition function and observed function. In MCDC Train, mean value function when sampling functions from Gaussian process and kernel covariance matrix can be given to both state transition function and observation function.
stateKernelGens = { ...
RBFKernelGenerator(UniformDistribution(0.01, 10), UniformDistribution(0.01, 10)), ...
RBFKernelGenerator(UniformDistribution(0.01, 10), UniformDistribution(0.01, 10)) ...
};
obsKernelGens = {
RBFKernelGenerator(UniformDistribution(0.01, 10), UniformDistribution(0.01, 10)), ...
RBFKernelGenerator(UniformDistribution(0.01, 10), UniformDistribution(0.01, 10)), ...
RBFKernelGenerator(UniformDistribution(0.01, 10), UniformDistribution(0.01, 10)) ...
};
stateMeanFuncs = { ...
@(x) (a1 .* x(1,:) + b1 .* x(1,:) / (1 + x(1,:) .^ 2)), ...
@(x) (a2 .* x(2,:) + b2 .* x(2,:) / (1 + x(2,:) .^ 2)) ...
};
obsMeanFuncs = { ...
@(x) (d1 .* x(1,:) .^ 2 + d2 .* x(2,:) .^ 2), ...
@(x) (d3 .* x(1,:) .^ 2 ), ...
@(x) ( d4 .* x(2,:) .^ 2) ...
};
In the
example codes above, use RBF kernel conforming
to uniform distribution with parameters, σ and
l, both being [0.01, 10], and configure
Kitagawa’s model state transition function and
observed function to mean value function. (In
general, a true model is unknown, configuring a
ture model as mean value function cannot be
set.)
Select Algorithm used for MCMC
iteration of MCDC Train. Choose
either fixing kernel parameters and mean value
function in prior distribution or transit it
every time.
kernelGeneratorStrategy = @RBFKernelGeneratorStrategyChoice2; mcdcStrategy = @MCDCStrategyChoice2; algorithm = PMCMC2(kernelGeneratorStrategy, mcdcStrategy); gridDimForGramMatrix = 1; splineHandle = @GenericSpline;
Configure the number of iterations
of model estimation, number of particles and
output destination of log files.
x0 = zeros(1, 2); N = 500; J = 100000; aspect = Aspect(); aspect.LogFileName = 'logs/KitagawaModelPMCMC2.log'; aspect.MatFileNamePrefix = 'logs/KitagawaModelPMCMC2'; aspect.SavesIntermediateMat = true; aspect.IntermediateMatInterval = 100;
Use all the configurations up to here and execute model estimation by MCDCTrain.
[ IDX, SKP, OKP, FV, GV, XE, YE, loglik ] = MCDCTrain( ... algorithm, … grids, ... stateKernelGens, ... obsKernelGens, ... stateMeanFuncs, ... obsMeanFuncs, ... gridDimForGramMatrix, ... splineHandle, ... x0, ... [], ... % No auxiliary states u', ... y', ... N, ... J, ... 0, ... aspect ... );
MCDC Tools is created as a MATLAB program. The list of program files is as follows:
| File name |
Description |
|---|---|
| Algorithm.m | Abstract base class that represents algorithm used for model estimation. |
| Aspect.m | Configuration class to set program operation. |
| BoundedNormalDistribution.m | Normal distribution limited within positive range. |
| CheckGridTransformation.m | Ranges check function for grid mapping. |
| Distribution.m | Abstract base class that represents probability distribution. |
| PSMC.m | Model estimation algorithm. Generate state transition function and observed function by random sampling from Gaussian process. Parameter estimation is not performed. |
| GPSurface.m | Function that requires grid mapping. |
| GenericSpline.m | Multidimensional spline interpolation function. Use Spapi function. |
| Graphs.m | Graph drawing function group. |
| GridData.m | Grid structure in state space. |
| Kernel.m | Kernel function (abstract base class). |
| KernelGenerator.m | Kernel function generator (abstract base class). |
| LogMvnPdf.m | Calculation of the probability density function of multivariate normal distribution. |
| MCDCInput.m | Input data of model estimation. |
| MCDCMatFile.m | Intermediate file output class of model estimation. |
| MCDCOutput.m | Output result of model estimation. |
| MCDCStrategy.m | Abstract base class that determines MCMC’s operations. |
| MCDCStrategyChoice1.m | Class that determines MCMC’s operations. Without learning mean value function, always use anchor model. |
| MCDCStrategyChoice1_PSMC.m | Class that determines MCMC’s operations. Without learning mean value function, always use anchor model. |
| MCDCStrategyChoice2.m | Class that determines MCMC’s operations. Perform sampling of functions from present GP surface used as mean value function. |
| MCDCStrategyChoice3.m | Class that determines MCMC’s operations. Perform sampling of functions from present GP surface used as mean value function. Without learning covariance function, use fixed covariance matrix. |
| MCDCTest.m | Likelihood calculation program of estimation model. |
| MCDCTrain.m | Model estimation program. |
| ModelFunctions.m | Spline function for grid mapping. |
| ModelFunctions2.m | Spline function for grid mapping. |
| NormalDistribution.m | Normal distribution. |
| PMCMC.m | Model estimation algorithm. Generate state transition function and observed function by random sampling from Gaussian process. Use particle Markov chain Monte Carlo (PMCMC) method for parameter estimation. |
| PMCMC2.m | Model estimation algorithm. Generate state transition function and observed function by random sampling from Gaussian process. Use particle Markov chain Monte Carlo methed for parameter estimation. Use one dimension only specific to state space for covariance function. |
| PMCMCParticleFilter.m | Particle filter. Perform ancestor sampling to use it by PMCMC method. |
| ParticleFilter.m | Particle filters. |
| PlotGraph.m | Graph drawing subroutines. Used from Graphs.m. |
| RBFKernel.m | BF kernel. Use it as a covariance function of the Gaussian process. |
| RBFKernelGenerator.m | RBF kernel function generator. |
| RBFKernelGeneratorStrategy.m | Abstract base class that determines a generating method for RBF kernel function. |
| RBFKernelGeneratorStrategyChoice1.m | RBF kernel function generating algorithm. Perform random sampling of kernel parameters from prior distribution. |
| RBFKernelGeneratorStrategyChoice2.m | RBF kernel function generating algorithm. Generate kernel parameters by random walk from present value. |
| UniformDistribution.m | Uniform distribution. |
| VectorValuedFunction.m | Routines that compile scalar valued functions of each dimension to vector valued functions. |
Also, the following sample directories contain program files to perform model estimation using MCDC Tools and conduct discrimination experiments for sample data. The list of files included in the sample directories is as follows:
| File name |
Description |
|---|---|
| KitagawaModel.m | Time series generating function by Kitagawa’s model. |
| KitagawaModelPSMCEstimation.m | Kitagawa’s model estimation experiment program (use PSMC algorithm). |
| KitagawaModelPMCMC2Estimation.m | Kitagawa’s model estimation experiment program (use PMCMC2 algorithm). |
| KitagawaModelPMCMCEstimation.m | Kitagawa’s model estimation experiment program (use PMCMC Algorithm). |
| KitagawaModel_WriteGraphs.m | Kitagawa’s model estimation result drawing program. |
| LinearStateSpaceModel.m | Time series generating function by linear state space model. |
| LinearStateSpaceModelPSMCEstimation.m | Linear state space model estimation experiment program (use PSMC algorithm). |
| LinearStateSpaceModelPMCMC2Estimation.m | Linear state space model estimation experiment program (use PMCMC2 algorithm). |
| LinearStateSpaceModelPMCMCEstimation.m | Linear state space model estimation experiment program (use PMCMC algorithm). |
| LorenzModel.m | Time series generating function by Lorenz’s model. |
| LorenzModelPSMCEstimation.m | Lorenz’s model estimation experiment program (use PSMC algorithm). |
| LorenzModelPMCMC2Estimation.m | Lorenz’s model estimation experiment program (use PMCMC2 algorithm). |
| LorenzModelPMCMCEstimation.m | Lorenz’s model estimation experiment program (use PMCMC algorithm). |
| LorenzModel_WriteGraphs.m | Lorenz’s model estimation result drawing program. |
| MotionCapture.m | Time series generating function from motion capture data. |
| MotionCapturePMCMC2Estimation.m | Motion capture model estimation experiment program (use PMCMC2 algorithm). |
| MotionCapturePMCMC2Test.m | Motion capture class separation experiment program. |
| MotionCapture_WriteGraphs.m | Motions capture model estimation result drawing program. |
| amc_to_matrix.m | Transfer function from AMC file to MATLAB matrix format. |