You can work with documents in MAT either in file mode or in workspace mode. In this
section, we describe each mode and the differences between the
In file mode, you work with documents on an individual basis. MAT
doesn't care where they're loaded from, or where they're saved to.
If they're in MAT's rich standoff annotation format, they'll know
what steps have already been applied to them, but other than that,
the user must specify all the other parameters of any file mode
File mode is provided by MATEngine
on the command line, and via "File -> Open file..." in the Web
From the point of view of the UI, file mode in the Web server is
stateless. Files are
loaded from the client, and saved to the client, and the Web
server has no access to the file system to load and save the
files. The Web server is still crucial for the file loading and
saving, due to the nature of Web interfaces, and also applies all
the automated steps.
A workspace is a directory, which contains a set of predefined
subdirectories for storing documents. We call these subdirectories
folders. Each folder has a
set of operations that you can perform on documents in that
folder; these operations may create versions of the file in other
folders, or move the file to another folder as a result of the
operation. Unlike file mode, the way you interact with a workspace
is almost entirely defined for you.
Workspace mode is provided by MATWorkspaceEngine on the command line, and via "File -> Open workspace..." in the Web UI. Unlike file mode, workspace mode is stateful from the point of view of the UI. It is the server that accesses the workspaces and loads and saves all the files.
File mode requires more of the user at each step, but is also
significantly more flexible than workspace mode. Workspace mode,
on the other hand, provides considerably more structured support
and bookkeeping for the user, at the sacrifice of flexibility. For
There are numerous other advantages to workspace mode, if you're
a task maintainer or you're managing multiple annotators. If
you're interested, look here.
If you choose workspace mode, you can find more information about it here.
It's important to stress that file mode and workspace mode cannot be freely mixed. You
can invoke the file mode engine on a file in a workspace, but
you'll likely make a mess of things if you save it back to the
workspace. Similarly, you can't invoke the workspace engine on any
file that hasn't been imported into it. You can, for instance,
process some documents in file mode, and then import them into the
workspace, but you can make a mess of things by importing them
into the wrong folder in the workspace. Ideally, you'll load raw
documents into the "core" folder in the workspace and do all your
operations on those documents starting from there.
If you switch modes, you'll want to do it all at once. To switch
from workspace mode to file mode, copy the contents of the
"folders/core" subdirectory out of the workspace, and discard the
workspace directory. To switch from file mode to workspace mode,
just create a workspace and import your files into it. But you
should never use file mode operations on files when
they're in a workspace.