Study Archive Format

Study archives are nothing more than zip files. They contain a simple directory hierarchy, media files such as images, video, and audio, and text in the form of Comma-Separated Values (CSV) or Tab-Separated Values (TSV). Anyone with a text editor can create a study archive, on any computing platform.

A study archive is expected to have a number of directories. At the root is a directory called Archive. Inside that directory are directories called Ungrouped and Groups.

The Ungrouped directory contains notes that do not belong to any group. In the terminology of Mental Case, these notes would be Loose Notes. The Ungrouped directory should contain a file called either Data.csv or Data.tsv, depending on whether the notes are in CSV or TSV format.

The Groups directory contains groups, or stacks in the Mental Case terminology. The subdirectory name is the name of the group. A given group can either contain other groups, which is equivalent to a case in Mental Case, or it can contain notes ( i.e. a Data.csv or Data.tsv file), which is the same as a stack in Mental Case.

Here is an example of a particular study archive, showing the hierarchy of directories, and data files.

Archive 
    Ungrouped
        Data.csv
    Groups 
        Case 1
            Stack 1
                Data.csv
            Stack 2
                Data.tsv
            Case 2
                Stack 3
                    Data.csv
                    Image 1.jpg
                    Audio 1.wav
                    Video 1.m4v
        Stack 4
            Data.tsv

The notes in an archive are stored in files named Data.csv or Data.tsv. The rows and columns are defined in the standard way, except that the first row must declare what each column represents. Here is an example:

1 Text, 1 Image, 2 Text

This CSV row contains three columns. Each column begins with a number, followed by a space, and then a data type. The number represents the facet of the note. The type label can be text, html, image, audio, or video, and is case insensitive.

After this first row, each row represents a single note. The types defined in the first row are used to interpret the data. If the label of the column is text, the data is assumed to be text; if the label is html, the data is treated as HTML text; and so forth. If the label is image, audio, or video, the entry should be a file name for the media in question. The media itself should be stored in the corresponding file in the same directory as the data file.

To omit an entry from a particular facet, an empty column can be entered. For example, if a particular facet should not have an image, the image column for that facet should be left vacant.

Once you have created the appropriate directories, and entered the note data, the Archive directory should be compressed into a zip file. On the Mac, you can do this by right-clicking (or control-clicking) on the directory, and choosing the Compress menu item.

Lastly, it is best to change the file extension of the archive to studyarch. In Finder, you can select the archive, and choose File > Get Info, in order to change the extension. By setting the extension to studyarch, OS X and iOS will know to open the zip file in Mental Case.

With the Study Archive now ready, you can send it to other Mental Case users to import, or upload it to a web server, and allow users of Mental Case for iOS to download it.

See also

Importing and Exporting
CSV and TSV Text Formats
Exporting for iOS
Importing Archives