XNAT Display Documents for Data Types

Problem: How to generate accurate and efficient display listings (tables) of the data represented by a XML Schema?

A great deal of information can be gained from an XML Schema to determine what data should be stored or processed by XDAT. However, when the user desires straight forward representations of their data in more user-friendly formats, the additional forms of meta-data are needed. For example, without additional meta-data, a tabular representation of a Schema Element would contain every possible field for that element without any formatting and without any derived data. In order to display data in a user-friendly format, we’ve created a system of xml-based meta-data documents which provide additional information about how Schema Elements should be displayed.

Through xml-based meta-data documents, or display documents, a developer is able to define which individual fields are visible to outside users, what formatting should be done on those columns, what additional derived data can be visible to a user, and what fields are searchable.

Developers can create a collection of custom Display documents to detail the searches and listings available to users. For any visible Schema Elements, developers are encouraged to build separate Display documents which will define the specific columns available for presentation (DisplayFields), the different patterns of columns available for different situations (DisplayVersions), and additional database views which will allow for more robust listing information.

The meta-data defined in the Display documents is used to generate database views which will be used by the XDAT search engine. For any ‘displayable’ element several views are created, including the schemalink views (which contain the available fields for the specified element including all fields from any additional elements which can be joined to the displayable element), linked views (which contain the fields from the schemalink view with the fields defined through custom views), and displayfields views which contain all of the DisplayFields defined in the display document.

<Displays>

A Display document contains one <Displays> element. This <Displays> element can contain <DisplayField>, <DisplayVersion>, <SchemaLink>, <ViewLink>, and <SQLView> elements. Each <Displays> element maps to one and only one element from the XML Schema. The <Displays> element must have a schema-element attribute which identifies which XML Schema element this <Displays> is associated with. The optional value_field, display_field, and display_label attributes are used to identify the default label for this element, id/value fields for this element.

<DisplayField>

The most important elements in the <Displays> element are the <DisplayField> elements. These elements define what schema fields are available to be used in listings and searches. They can be simple representations of one schema field’s value or a complex combination of multiple schema fields. A <DisplayField> can have the following attributes:

Id (required) : This is a UNIQUE string which identifies this field.
Header (required) : This is the header which will be displayed in the event this field is used in a listing.
Image (optional) : true if this field should be an <IMAGE>, otherwise false.
Sort-by (optional) : default: sorts by itself, otherwise a different <DisplayField>’s id is specified for sorting.
Sort-order (optional) : ASC OR DESC
Searchable (optional) : true if this field should show up in dynamic search pages.
Data-type (optional) : specifies the XML data type of this field, necessary if the <DisplayField> involves some reformatting.

A <DisplayField> can have several child elements.

DisplayFieldElement: used to specify the schema field(s) or view column(s) used in this <DisplayField>.
Content: Specifies the formatting which will be done to the specified DisplayFieldElements.
HTML-Link: Specifies that an <A> (HTML-Anchor) should be used for this field.
HTML-Cell: Specifies the formatting of the HTML Cell surrounding this field.
HTML-Image: Specifies the options for the surrounding <IMAGE> tag.

A <DisplayField> element must be defined for every field which the developer wants to be displayed in the application.

Example:

CODE

<DisplayField id="SUBJECTID" header="Subject" visible="true">
<DisplayFieldElement name="Field1" schema-element="oas:subjectType.subjectData.ID"/>
<HTML-Link>
<Property name="HREF" value="none"/>
<Property name="ONCLICK" value="return rpt('@Field1','oas:subjectType','oas:subjectType.subjectData.ID');">
<InsertValue id="Field1" field="SUBJECTID"/>
</Property>
</HTML-Link>
</DisplayField>
<DisplayField id="AGE" header="Age" visible="true">
<DisplayFieldElement name="Field1" schema-element="oas:subjectType.subjectData.age"/>
</DisplayField>
<DisplayField id="GENDER" header="Gender" visible="true">
<DisplayFieldElement name="Field1" schema-element="oas:subjectType.subjectData.gender"/>
</DisplayField>
<DisplayField id="STATUS" header="Status" visible="true">
<DisplayFieldElement name="Field1" schema-element="oas:visitData.clinicalAssessmentData.CDR.score"/>
<Content type="sql">CASE WHEN @Field1 IS NULL THEN 'young' WHEN @Field1 >0 THEN 'dat' ELSE 'normal' END</Content>
</DisplayField>
<DisplayField id="WBV" header="WBV" visible="true">
<DisplayFieldElement name="Field1" viewName="SUBJECT_FSL_VIEW" viewColumn="volumes_brain_percent"/>
</DisplayField>
<DisplayField id="ETIV" header="eTIV" visible="true">
<DisplayFieldElement name="Field1" viewName="SUBJECT_ASF_VIEW" viewColumn="etiv"/>
</DisplayField>
<DisplayField id="CLIN_DELAY" header="Clin. Delay" visible="true">
<DisplayFieldElement name="Field1" schema-element="oas:visitData.clinicalAssessmentData.delayFromMr"/>
</DisplayField>
<DisplayField id="CDR" header="CDR" visible="true">
<DisplayFieldElement name="Field1" schema-element="oas:visitData.clinicalAssessmentData.CDR.score"/>
</DisplayField>
<DisplayField id="MMSE" header="MMSE" visible="true">
<DisplayFieldElement name="Field1" schema-element="oas:visitData.clinicalAssessmentData.MMSE"/>
</DisplayField>

<DisplayVersion>

The <DisplayVersion> elements specify the different combination of <DisplayField>s. A <DisplayVersion> can have the following attributes:

versionName:

Each <DisplayVersion> must have a unique versionName. The first defined <DispayVersion> will be considered the default version. The primary html version is expected to be called ‘listing’. Also, smaller sub-sets of the fields can be defined in ‘brief’ and ‘detailed’ which will be used in Super Searches. It is recommended that the developer create separate versions of HTML <DisplayVersion>s to be used for CSV output of those versions. The CSV versionName should be titled the same as its matching HTML listing with ‘_csv’ appended to the end. So the name of the primary listing’s CSV version would be ‘listing_csv’. Similarly, ‘brief_csv’ and ‘detailed_csv’ can be defined.

Default-order-by: This is the DisplayField which will be used in the ORDER BY statement, if no ORDER BY is defined.
Brief-description: Description used in the Browse/Search/Listin menus to identify this element.
Dark-color/Light-color: Alternating colors to be used in alternating rows in HTML listings.

The <DisplayVersion> uses child <DisplayFieldRef> elements to define which <DisplayField>s are included in this listing. The <DisplayFieldRef> identifies the <DispayField> with its id attribute. A new header can be defined in the header attribute which will overrule the header defined in the <DisplayField>.

Example:

CODE

<DisplayVersion versionName="listing" default-order-by="SUBJECTID" brief-description="Subject Data" dark-color="DEDEDE" light-color="FFFFFF">
<DisplayFieldRef id="SUBJECTID"/>
<DisplayFieldRef id="AGE"/>
<DisplayFieldRef id="GENDER"/>
<DisplayFieldRef id="STATUS"/>
<DisplayFieldRef id="WBV"/>
<DisplayFieldRef id="ETIV"/>
<DisplayFieldRef id="CLIN_DELAY"/>
<DisplayFieldRef id="CDR"/>
<DisplayFieldRef id="MMSE"/>
</DisplayVersion>

<SchemaLink>

In some situations, the developer may want to include fields from another Schema Element, whose relation to the Display element is not clear from the XML Schema. In this instance, a <SchemaLink> element is used to specify the relation between the two elements. This involves defining a mapping between the two elements (usually involving a database table or view which maps the two elements). The developer defines <MappingColumn> elements to define how the root element and the linked element relate to the mapping table.

For example:

CODE

<SchemaLink element="xnat:visitData" type="mapping" alias="xnat:visitData">
<Mapping TableName="SUBJECT_VISIT_DISTINCT">
<MappingColumn rootElement="xnat:subjectType" fieldElement="xnat:subjectType.xnat_subjecttype_id" mapsTo="xnat_subjecttype_id"/>
<MappingColumn rootElement="xnat:visitData" fieldElement="xnat:visitData.id" mapsTo="xnat_visitdata_id"/>
</Mapping>
</SchemaLink>

This element can then be used in <DisplayField> elements as if it is the displayable element. An alias can be defined for the schema link, and used in place of the element name in the DisplayFields to allow the developer to link to multiple instances of the same schema element.

<SQLView>

To allow for the display of more complicated fields, a developer may need to create custom Database views. One common need for SQLViews comes from the inability to display all of a schema element’s fields. In order to maintain one row per element in the tabular structure, fields which have multiple references (maxOccurs=unbounded) are not included in the searched views. In order to display information about the multiple references, a developer must create database views which map the results to one row per element. These views are specified in the <SQLView> tags and can be joined to the displayable element via a <ViewLink>. SQLViews only have two attributes; name (name of view in database) and sql (the SELECT statement used to create the view). The CREATE VIEW statement is generated with the other sql.

Example:

CODE

<SQLView name="SUBJECT_VISIT_DISTINCT" sql=
"SELECT DISTINCT ON (xnat_subjecttype_id) xnat_subjecttype_id, visit.id AS xnat_visitdata_id FROM xnat_subjecttype sub
JOIN xnat_v_xnat_visitData_visitd_xnat_subjectType map ON sub.xnat_subjecttype_id=map.xnat_subjectType_xnat_subjecttype_id
JOIN xnat_visitdata visit ON map.xnat_visitData_xnat_visitdata_id=visit.id" />

<ViewLink>

ViewLinks are defined to join custom views to the displayable element. They specify the view to be joined through the TableName attribute. MappingColumns are then used to connect the view to the schema element. Aliases are defined to allow multiple instances of the view to be joined to the schema element.

Example:

CODE

<ViewLink alias="SUBJECT_ASF_VIEW">
<Mapping TableName="SUBJECT_ASF_VIEW">
<MappingColumn rootElement="oas:visitData" fieldElement="oas:visitData.mrSessionData.id" mapsTo="mr_expt_id_1"/>
</Mapping>
</ViewLink>

Arcs

In order to join displayVersions from separate displayable elements, an arc can be defined to specify how the two elements are related. Declaring an Arc takes to steps.

1. Define an <Arc-Definition>.

An arc is defined with a unique id and a collection of CommonFields. These are DisplayFields which every member element is expected to have. Commonly, the two elements are related by another element that they both relate to. This is called the bridge-element. The bridge-element can be specified in the Arc-Defintion. Filters can be defined on the common fields to assist in the mapping of the correct elements. The possible filter types are closest, before, equals, and distinct. The distinct filter is almost always used to guarantee that there is a one-to-one relationship between the elements. The equals filter is mandatory to join the elements.

CODE

<Arc-Definition Id="PARTICIPANT_EXPERIMENT">
<CommonField id="DATE" type="DATE"/>
<CommonField id="PART_ID" type="STRING"/>
<CommonField id="EXPT_ID" type="INTEGER"/>
<Bridge-Element name="Participant" field="PART_ID"/>
<Filter field="EXPT_ID" filterType="distinct"/>
<Filter field="DATE" filterType="closest"/>
<Filter field="PART_ID" filterType="equals"/>
</Arc-Definition>

2. Define Arc Membership

Within the member elements, include the <Arc> element to imply that this element is a member of that Arc. The <Arc> specifies the defined Arc by the name attribute. Also, the CommonFields for the Arc are specified with the local fields which correspond.

CODE

<Arc name="PARTICIPANT_EXPERIMENT">
<CommonField id="PART_ID" local-field="PART_ID"/>
<CommonField id="DATE" local-field="EXPT_DATE"/>
<CommonField id="EXPT_ID" local-field="EXPT_ID"/>
</Arc>