File and workspace modes

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 two.

File mode

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 operation:

• the task
• the workflow
• the language
  
• the input encoding of raw documents
• the exact location of the document or directory of documents to be processed
• the exact name of the input and output documents, including whatever suffixes should be removed or added in order to distinguish them from one another
• whether the input and output are rich or raw
• the workflow steps to apply to the document

File mode is provided by MATEngine on the command line, and via "File -> Open file..." in the Web UI.

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.

Workspace mode

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.

Comparing the two modes

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 instance:

• In file mode, you can undo steps in the UI. Your ability to undo steps in workspace mode is much more limited.
• In workspace mode, you never have to worry about where your documents live, or what they're named. In file mode, you have to manage this yourself.
• In workspace mode, the advancement to the next hand annotation step is handled for you by default, when you import the documents and when you mark them gold or complete a document review. In file mode, you have to perform these steps by hand.
• In workspace mode, you have a database which tracks the state of each document, so you know what you've done and what needs to be done.
  
• Using workspace logging, you can keep a record of every change you've made to a document.

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.

Switching modes

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.