The CLI must be called with a list of arguments that describes what you expect the program to do. If it is called with the single help
argument, it prints a short help. When a filename must be given, it can be relative to the current directory or absolute; the special "-
" filename opens the standard input (or output) for reading (writing).
The first argument to be given is one of
create
(creates a new HMM description file, see Section 6.2.2).
print
(prints a HMM in a human readable way, see Section 6.2.3).
learn-kmeans
(applies the k-Means algorithm, see Section 6.2.4).
learn-bw
(applies the Baum-Welch algorithm, see Section 6.2.5).
generate
(generates an observation sequence given a HMM, see Section 6.2.6).
distance-kl
(computes the distance between two HMMs, see Section 6.2.7).
Each of those options takes additional arguments.
Most of the time, you will be required to give a description of the observation distributions associated with the states of a HMM. This can be done via the -opdf
argument; it must be followed by one of: integer
(distribution over a finite set of integers), gaussian
(normal distribution), gaussian_mixture
(mixture of gaussians), multi_gaussian
(normal distribution over real vectors).
When using integer distributions, the -r
argument is required; it specifies over which range of integers the distribution is defined. For example, -opdf integer -r 4
defines a distribution over the integers 0, 1, 2, 3
..
When using mixture of gaussians, the -ng
argument is required; it specifies the number of gaussians this distribution is made of. For example, -opdf gaussian_mixture -ng 3
defines a distribution made of 3 gaussians.
When using normal distributions over real vectors, the -d
argument is required; it specifies the dimension of the vectors involved. For example, -opdf multi_gaussian -d 3
defines a distribution whose covariance is a 3x3 matrix.
This argument is used to create a new HMM and to write it to a file.
This option requires a distribution specification, the required number of states (specified using the -n
parameter) and an output file (specified using the -o
parameter).
For example:
jahmm-cli create -opdf integer -r 4 -n 3 -o test.hmm
The HMM is created with uniform parameters (all the states have the same probability of being initial ad the state transition probability matrix is uniform). As the file created is textual, it can be easily edited by hand.
This argument is used to print a HMM in a human-readable way.
This option only requires to provide an input file using the -i
argument.
For example:
jahmm-cli print -i test.hmm
This argument is used to apply the k-Means learning algorithm. A learning algorithm finds the parameters of a HMM that best match a set of observation sequences.
This option requires a distribution specification, the resulting HMM's number of states, an input observation sequences file (parameter -is
) and an output file (parameter -o
).
For example:
jahmm-cli learn-kmeans -opdf integer -r 10 -n 2 -is testInteger.seq -o test.hmm
This argument is used to apply the Baum-Welch learning algorithm. A learning algorithm finds the parameters of a HMM that best match a set of observation sequences. The Baum-Welch algorithm requires a initial HMM whose parameters are improved according to the provided sequences; it only finds a local optimum.
This option requires a distribution specification, the resulting HMM's number of states, an input observation sequences file (parameter -is
), a first HMM estimate (parameter -i
) and an output file (parameter -o
). The number of iterations of the algorithm can be set using the -ni
argument.
For example:
jahmm-cli learn-bw -opdf integer -r 4 -is testInteger.seq -ni 5 -i initial.hmm -o test.hmm
This argument is used to generate sequences of observations that match a HMM.
This option requires a distribution specification and an input HMM (parameter -i
).
For example:
jahmm-cli generate -opdf integer -r 4 -i test.hmm
Computes the distance between two HMMs. This distance measure is based on the Kullback-Leibler distance, which is not symmetric.
This option requires a distribution specification, an input HMM (parameter -i
) and a second input HMM against which the distance is computed (-ikl
parameter).
For example:
jahmm-cli distance-kl -opdf integer -r 4 -i hmm1.hmm -ikl hmm2.hmm