# Experiment Hierarchy

## Overview

As illustrated in , the XCEDE experiment hierarchy consists of several levels representing divisions of experiment data at various granularities. Elements at each level contain level-specific info elements, whose schema types may be derived to store experiment-specific or data modality-specific metadata. The linking mechanism between levels is flexible enough to support the omission of levels if the schema user finds them unnecessary.

XCEDE hierarchy

### Hierarchy Levels

In the typical intended usage, a project is the top-level division of experiment data, and represents a research project which collects and analyzes data from one or more subjects which are divided (within the project) into subject groups. A subject may be a member of multiple research projects, and it is the subject group that maintains and distinguishes the mappings between subjects and research projects.

A visit may represent a subject's appearance at an experiment site (for collaborative projects, this could be the institution or lab at which the data is being collected or analyzed). A visit may be further subdivided into one or more studies, each of would consist of one or more data collection episodes.

Visit and study are more or less arbitrary divisions of the data that exist for convenience, and do not in themselves have any inherent meaning as far as the schema is concerned. However, an episode does have a meaning, and is intended to represent a unit of data collection by one or more instruments over a given time interval. Each set of data collected (perhaps by different instruments) over this time interval should be represented by an acquisition. Multiple acquisitions within an episode should be understood to occur simultaneously over the time interval represented by the episode. So, for example, an episode in an fMRI study may encapsulate the acquisition of a time-series of volume images from an MR scanner, as well as other acquisitions of behavioral or physiological data; all these (simultaneously collected) data would be stored as individual acquisitions and stored as part of the same episode.

At first thought, it might seem natural to represent the experiment hierarchy as described as a traditional XML hierarchy, where higher-level elements encapsulate lower-level elements as child elements. However, in XCEDE, all level elements (`<project>`, `<visit>`, etc.) are stored as children of the root `<XCEDE>` element. Links between levels are implicit in the level IDs assigned to each element and propagated to elements in lower levels. The great benefit of this approach is that applications are easier to write because all major elements are stored in the same place (under the XCEDE root element), and that XCEDE documents can be merged by merely concatenating the lists of top-level elements under a single XCEDE root element. Another advantage is to allow users of the schema to omit levels merely by omitting the unnecessary elements and IDs/links.

### IDs and Linking

Specifying one or more level IDs allows one to explicitly define the hierarchical relations between XCEDE elements in different levels in the experiment hierarchy. Every level element has a set of these level IDs, composed of the element's own `ID` attribute, plus its ancestor ID attributes, indicating which higher-level elements have this element in their scope. For example, the `<visit>` element contains the ancestor ID attributes `subjectGroupID`, `subjectID`, and `projectID`. Level elements are linked to their ancestors in the hierarchy by sharing the appropriate subset of level IDs. In addition, any level element can linked from another XCEDE element that likewise specifies the appropriate level IDs.

For example, a link to a visit element may specify `visitID`, `subjectID`, `subjectGroupID`, and `projectID` attributes, and a `level` attribute with the value `visit`, indicating that this link is to a visit element. An application resolving this link will search for a visit element in the XCEDE 2 dataset whose attributes match those specified in the link (the `visitID` attribute in the link is matched against the `ID` attribute in the visit element).

Though the individual `ID` attributes are not required to be unique, the set of these level IDs applied to a level element must be unique. In addition, any link to a level element must provide enough level IDs to uniquely describe a single target level element. Level ID attributes not specified in the link are understood to match any value, but a link must specify enough of these IDs match at most one level element.

The elements that can link to level elements are `<catalog>`, `<resource>`, and `<data>` (children of the `<XCEDE>` root element), and `<inputRef>` and `<outputRef>` (children of the `<analysis>` element). As previously described, level elements (except for `<project>` and `<subject>`, which are at the top of the experiment hierarchy), by virtue of specifying their own ancestor IDs, automatically incorporate links to their ancestor elements.

## Examples

### Metadata hierarchy

The metadata hierarchy illustrated in can be represented in XCEDE as shown in (only those elements/attributes relevant to linking are shown; the actual metadata contents of the elements are omitted for space). Note that subject 1 in the illustration is represented in two different projects, and so the corresponding `<subject>` element may be an ancestor for visits in both project A and B. However, the subject's role in each project is specified by the combination of the project ID and subject group ID (defined in the subject group lists in `<project>`), and these are used in every level element starting with `<visit>` and below.

Metadata hierarchy instance