The StudyArch Format

What is a 'Study Archive'?

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.

Why Do We Need Study Archives?

Study archives offer a simple, cross-platform format for study cards, allowing you to get at your data, and import it into other applications. You can also prepare your own study archives — for example, on a PC — and import them into Studies for iOS.

How Do I Create a Study Archive?

The simplest way to create a study archive is to select a stack in Studies, and export it in Study Archive Format. But even without Studies installed, it is not difficult to create a study archive. You simply need a text editor and file compression utility. Here's how.

Directory Structure

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. (Note that these names are case sensitive, so enter them exactly as shown.)

The Ungrouped directory contains notes that do not belong to any group. In the terminology of Studies, these would be in Loose Notes. The Ungrouped directory should have 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 and stacks. The subdirectory name is the name of the group/stack. A given group can contain other groups; if it is a stack, it contains notes (ie a Data.csv or Data.tsv file).

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

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

Data File Format

The notes/cards in an archive are stored in files named Data.csv or Data.tsv, depending on whether CSV or TSV format is being used. 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 or side of the note. In this example, there are only two sides. The type label can be text, html, image, audio, or video, and is case insensitive. The html label can be used to provide formatted text.

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, 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 note/card, an empty column can be entered. For example, if a particular side should not have an image, the image column for that side should be left vacant.

You need to be careful what tool you use to prepare the data file. Some tools don't support Unicode text, which can cause loss of special characters. You should try to choose a tool that supports Unicode text. For example, Excel does support Unicode, but only if you use the TSV format — not CSV — and make sure you save as Unicode (UTF16).

Zip It

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 on the directory, and choosing the Compress menu item. Once you do that, change the file extension to studyarch, instead of zip.

Distribute It

If you are a teacher distributing notes to students, you should make the zipped study archive available online somewhere. You could upload to a school intranet, or make it available via a public web site or online storage service such as Dropbox. Students can then download the file, choose Open In..., and import into Studies.

You can also just email a study archive. If the extension is studyarch, and the recipient has Studies installed, the app will open when the attachment is opened, and offer to import it.

An Example

The easiest way to see how to setup a study archive is to look at an existing one. Download a demo study archive and play with it. If you want to unzip the archive, to look at its contents, you can just change the extension from studyarch to zip, and then use a standard decompression utility (eg Finder) to expand the archive.

Note that the zip file is named 'Demo', but the root of the folder hierarchy after you unpack it is 'Archive', as described above. When preparing an archive, make sure you name the folder 'Archive', zip it up, and then you can rename the zip file if you choose to.