********************************************
********************************************
README
********************************************
********************************************
NOT ALL COMMENTS IN CODE ARE UP TO DATE. This file and README_EXAMPLE
are currently the best guides.
The program is intended primarily to be used for finding, according to
our model, the outcome of the execution of a speech goal, where the
user provides:
Motor space and perceptual space, populated with clusters
The motor goal i.e. the silhouette
The perceptual goal i.e. the exemplar
Optionally, a few parameters
This model can be used with real data, or it can be used with made-up
values as a demonstration of how it works/visualization of the model.
A few sets of made-up values are provided for the convenience of the user.
Additionally, parameters that are embedded deeper in the model, or more
fundemental aspects of how the model works, may be changed by changing
the code directly. An effort has been made to make the code
straightforward, readable, and heavily commented so that this is possible.
A more narrative description is given below; if you would prefer to
start exploring by running code immediately, checkout the file
README_EXAMPLE.m
If someone wants to use this program to find the outcome of the
execution of a speech goal according to our model, they will need to
first decide what the Space is. A Space object is the computational
model's representation of motor space and perceptual space as well as
the link between them. In particular, the Space consists of
- A Cluster array
- A SpaceTransformation
That is, to make an instance space of type Space, we write:
space = Space(clusterArray, spaceTransformation)
Each Cluster is defined in terms of the motor and perceptual
coordinates of its Junctures -- so the user must decide what the motor
dimensions andthe perceptual dimensions are, and then what the
Junctures in each Clusterare in terms of these coordinates. We write:
cluster = Cluster(MotorCoordinateMatrix, PerceptualCoordinateMatrix).
There are also some optional arguments that will determine which
dimensions of the Cluster are used when graphing (detailed in the
Cluster file).
The SpaceTransformation is the function that takes a motor coordinates
as an input and gives the corresponding perceptual coordinates as the
output. This transformation is not known to the speaker, but it must be
known to the modeler in order to model the consequences of perceptual
outcomes from motor actions (essentially in order to simulate the
perceptual consequences of speaking).
spaceTransformation = SpaceTransformation(@TransformationFunction)
where TransformationFunction is a matlab function. The "@" in the
front is necessary since it is a function. TransformationFunction must
be defined in a place that is accessible to the above definition -- in
the same file, or as the main function in a file in the path. That
definition will look like:
function PerceptualCoordinates = TransformationFunction(MotorCoordinates)
% definition goes here -- e.g.
% PerceptualCoordinates = MotorCoordinates;
% OR
% PerceptualCoordinates = (2 * MotorCoordinates) - 5;
% OR
% PerceptualCoordinates(1) = MotorCoordinates(1) * MotorCoordinates(2);
% PerceptualCoordinates(2) = MotorCoordinates(3)^2 - MotorCoordinates(2);
end
A specific space will be specified for each goal, since a goal cannot
exist without the context of the space (linked perceptual and motor
spaces) in which the goal lies. Other than the space, the other two
things that a goal consists of are
- a silhouette (MotorSilhouette object; the motor goal)
- an exemplar (PerceptualTrajectory object; the percdeptual goal).
That is, we write
goal = Goal(space, silhouette, exemplar)
We've covered what space looks like. Now we'll describe the
silhouette. The silhouette consists of a series of T regions, where
each region corresponds to a particular time in the silhouette. We
write
silhouette = MotorSilhouette(MotorRegions)
where, for example, MotorRegions = [Region1 Region2 Region3] (with more
or fewer regions). Region1, Region2, and Region3 are all objects of
type WeightedMotorSimplicialComplex, which is an object that specifies
a homogenous simplicial complex in motor space along with a weight
assigned to each simplex.
Finally, the exemplar is a perceptual trajectory -- that is, a series
of points in perceptual space. We write exemplar =
PerceptualTrajectory(PerceptualCoordinateMatrix), and there are also
some optional arguments, detailed in the PerceptualTrajectory file.
Once the goal is defined, now it is possible to use the program to find
the results of executing that goal. There are just a few more
parameters that need to be chosen first, and this will be done by
creating an ExecutionParameters object:
executionParameters = ExecutionParameters(LookBackAmount, LookAheadAmount)
If the code were to be modified to include more global-speaking-setting
type parameters (for example, speaking rate, clarity of speech, etc.)
this object would be the appropriate place to add those parameters
to -- they don't belong in the space itself, and they don't belong in
the goal -- they really are external to those things, and they belong
in the set of parameters that are independent from those things and
that could be chosen differently for different utterances based on the
same goal.
To find the final results, we write
[AverageJunctureEstimates, FinalJunctureActivationValues] =
goal.SimpleMacroEstimates(executionParameters)
FinalJunctureActivationValues is a matrix where
FinalJunctureActivationValues(j, t) is the activation of the jth
juncture at the tth time step. AverageJunctureEstimates is a vector
where AverageJunctureEstimates(t) is the estimated location in motor
space and perceptual space at time t, written in juncture format. That
is, AverageJunctureEstimates(t) is a juncture J such that
J.MotorPoint.Coordinates is the estimated motor coordinates at time t,
and J.PerceptualPoint.Coordinates is the estimated perceptual
coordinates at time t.
This is all the information that is necessary to plot the results,
which can be plotted using a FullFigureData object -- this is done in
the README_EXAMPLE file.