**MAD to MAGE-TAB Enhancements / project 1240/1306**

**Application: MAD**

Software Requirements Specification

**Version 1.3**

Document Change Record

  ------------- -------------- -------------------------------------------
  Version       Date           Description
  Number                       

  1.0           9/5/2007       Initial document

  1.1           11/20/2007     Miscellaneous updates

  1.1           12/17/2007     Completed changes to version 1.1.

  1.2           12/17/2007     Begin version 1.2

  1.2           12/20/2007     Expanded description of output file
                               creation in section 3.1, Req ID #1240.1.

  1.2           1/4/2008       Appendix B (example MAGE-TAB files) added

  1.3           2/25/2008      Reviewed and updated to reflect final
                               modifications.

  1.3           2/28/2008      Edits to Appendix B to reflect final output
  ------------- -------------- -------------------------------------------

TABLE OF CONTENTS

1\. Introduction [1](#introduction)

1.1 Scope [1](#scope)

1.1.1 Identification [1](#identification)

1.1.2 System Overview [1](#system-overview)

1.1.3 Document Overview [2](#document-overview)

1.2 Reference Documents [2](#reference-documents)

2\. Project Description [3](#project-description)

2.1 Project Perspective [3](#project-perspective)

2.2 Project Function [3](#project-function)

2.3 User Characteristics [3](#user-characteristics)

2.4 Constraints [3](#constraints)

2.5 Qualification Provisions [3](#qualification-provisions)

3\. Requirements [4](#requirements)

3.1 Requirements Matrix [4](#requirements-matrix)

Appendix A -- Acronym List [12](#appendix-a-acronym-list)

Appendix B -- sample Mage-tab files
[13](#appendix-b-sample-mage-tab-files)

# Introduction

The Jackson Laboratory (TJL) currently has an extensive microarray LIMS
called MAD (**M**icro**A**rray **D**atabase) which has been in use since
May 2003. The purpose of this Software Requirements Specification (SRS)
is to describe the changes necessary to MAD to permit the transfer of
experiment descriptions and data from MAD to the MAGE-TAB format.
MAGE-TAB is a standardized set of tab-delimited files designed for the
transmission of microarray data. The final deliverable is a version of
MAD that can successfully perform this operation.

The components pertinent to this change are the MAD database and the MAD
application GUI, hereinafter called the MAD PMI.

## Scope

The scope of the changes necessary to complete this project are:

-   upgrade the MAD database with the missing fields and tables
    necessary for MAGE-TAB compliance

-   upgrade the MAD application user interface to permit data entry and
    editing of new data fields.

-   upgrade the MAD application's functional capabilities to allow
    authorized users to automatically produce MAGE-TAB data files from
    selected micro array projects

MAD is composed of several other components outside of the scope of this
project, the two most prominent being an IIS-based external web
interface, written in ASP, permitting public access to The Jackson
Laboratory\'s microarray data store, and an Apache-based internal web
interface, written in JSP, permitting submission of new projects and
status query of existing ones. No changes to these components are
necessary to meet MAGE-TAB compliance.

### Identification

This will be MAD version 6.0.0.

### System Overview

MAD is the end-to-end workflow and data management system for the
microarray core services of The Jackson Laboratory.

The software that this SRS applies to is the module that exports data
from the in-house MAD database to the MAGE-TAB format for conversion
into MAGE-ML and subsequent import into caArray. The Jackson
Laboratory\'s standard Software Development Life Cycle will be followed.

### Document Overview

This SRS captures the complete software requirements for MAD as part of
the MAD to caArray enhancements project. Requirements procedural
instructions are included in the Standard Operating Procedures (SOPs).

The remaining SRS sections are organized as follows:

-   **Section 2. Project Description**: Describes the general factors
    that affect the MAD database and application GUI.

```{=html}
<!-- -->
```
-   **Section 3. Requirements**: Describes all the software requirements
    to a level of detail sufficient to enable designers to design a
    system to satisfy those requirements, and testers to test that the
    system satisfies those requirements.

-   **Appendix A. Acronym List:** Defines the abbreviations used on the
    project.

## Reference Documents

For additional project, and requirement specific information, refer to
the following documents (in TJL Computational Sciences Work Management
System -- for JAX internal use only. These links are not accessible from
outside The Jackson Laboratory network):

Table 1.1: Related Documents

  ----------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  Document Name           Document Location

  MAD Design              [\\\\hogwarts\\rescomp\\Systems\\MAD\\Releases\\5.0.4\\docs\\MAD_DesignSpec.doc](../../../../../../../../rescomp/Systems/MAD/Releases/5.0.4/docs/MAD_DesignSpec.doc)
  Specification           

  MAD Developer\'s Guide  [\\\\hogwarts\\rescomp\\Systems\\MAD\\Releases\\5.0.4\\docs\\MAD_DevelopersGuide.doc](../../../../../../../../rescomp/Systems/MAD/Releases/5.0.4/docs/MAD_DevelopersGuide.doc)

  MAD PMI Admin Guide     [\\\\hogwarts\\rescomp\\Systems\\MAD\\Releases\\5.0.4\\docs\\MAD_PMIAdminGuide.doc](../../../../../../../../rescomp/Systems/MAD/Releases/5.0.4/docs/MAD_PMIAdminGuide.doc)

  MAD PMI User Guide      [\\\\hogwarts\\rescomp\\Systems\\MAD\\Releases\\5.0.4\\docs\\MAD_PMIUserGuide.doc](../../../../../../../../rescomp/Systems/MAD/Releases/5.0.4/docs/MAD_PMIUserGuide.doc)

  MAD_1306_TechSpec.doc   [\\\\hogwarts\\rescomp\\Projects\\1300\\1306 caBIG-ICR tools
                          adoption\\docs\\MAD_1306_TechSpec.doc](../../../../../../../../rescomp/Projects/1300/1306%20caBIG-ICR%20tools%20adoption/docs/MAD_1306_TechSpec.doc)
  ----------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

# Project Description

## Project Perspective

The MAD data repository is an SQL Server 7 database residing on an HP
Proliant DL-385R01 dual-core AMD 280 (2.4GHz) server with 8 GB memory
and 900 GB hard disk, running Windows 2003 Enterprise Server.

The MAD desktop application is a Microsoft Access 2003-based program
that leverages Microsoft Access 2003 forms for its GUI and the SQL
Server 7 MAD database for its data store. The single executable is
called MAD_PMI.mdb.

## Project Function

MAD is the end-to-end workflow and data management system for the
microarray core services of The Jackson Laboratory.

## User Characteristics

The end users of this system are the investigators who typically submit
project requests, browse project status, and retrieve data products
through a web interface. The Gene Expression core service personnel
represent a distinct user group who execute the parts of the experiment
involving the microarray equipment and interact with the MAD database
through the MAD_PMI.mdb application. These proposed changes provide new
GUI application screens incorporated into the MAD_PMI permitting entry
of the new data elements required for caArray compliance. Additionally,
the MAD_PMI will have MAGE-TAB data publishing functions built in so
that Gene Expression Laboratory personnel can publish microarray
projects into caArray when they are completed.

## Constraints

The MAD database requires SQL Server 7. Microsoft Access 2003 is
required to run the application GUI. Changes to the database are carried
out by SQL scripts. Application GUI changes are carried out by
modifications to the existing VB6-based VBA code.

## Qualification Provisions

  ----------------- -----------------------------------------------------
  Qualification     Description
  Name              

  Demonstration     To insure the requirement has been met, run the
                    application, providing experiment data as input. Then
                    view the MAGE-TAB output. It should reflect the same
                    experiment input.
  ----------------- -----------------------------------------------------

# Requirements

## Requirements Matrix

Note: table names, form names, and integer definitions are in Courier
New. Database column names and form field names are in **Bold**.

+------+-----+----+---------------------------------------------------+
| Req. | R   | Do | Requirement Description                           |
| ID   | eq. | ne |                                                   |
|      | T   |    |                                                   |
|      | ype |    |                                                   |
+------+-----+----+---------------------------------------------------+
| 12   | Sys | ♦  | Automatically create a set of MAGE-TAB files for  |
| 40.1 | tem |    | a new experiment. The modifications to MAD        |
|      |     |    | require the output of at least two files:         |
|      |     |    |                                                   |
|      |     |    | -   *project_name*.idf                            |
|      |     |    |                                                   |
|      |     |    | -   *project_name*.sdrf                           |
|      |     |    |                                                   |
|      |     |    | and possibly a third:                             |
|      |     |    |                                                   |
|      |     |    | -   *project_name*.adf                            |
|      |     |    |                                                   |
|      |     |    | where *project_name* is the name of the project.  |
|      |     |    |                                                   |
|      |     |    | (see appendix B for example files)                |
|      |     |    |                                                   |
|      |     |    | The format of each file\'s contents is derived    |
|      |     |    | from the MAGE-TAB Specification Version 1.0       |
|      |     |    | document. The data to populate the fields will be |
|      |     |    | extracted from the corresponding MAD fields.      |
|      |     |    |                                                   |
|      |     |    | These files are created in the same directory as  |
|      |     |    | the project\'s data files. The path to this       |
|      |     |    | directory already exists in MAD.                  |
+------+-----+----+---------------------------------------------------+
| 12   | D   | ♦  | Add new table cv_VocabularySource to hold the     |
| 40.2 | eri |    | controlled vocabulary sources (i.e. MGED, NCI     |
|      | ved |    | Thesaurus, etc). It should have the columns       |
|      |     |    | **name**, **url**, and **active**.                |
+------+-----+----+---------------------------------------------------+
| 12   | Sys | ♦  | The project\'s experimental design and design     |
| 40.3 | tem |    | type(s) need to be captured.                      |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table cv_ExperimentalDesignType to hold   |
| 0.3a | eri |    | the experimental design type controlled           |
|      | ved |    | vocabulary. It should have the columns **name**,  |
|      |     |    | **description**, **elementId**, **active**, and   |
|      |     |    | **\_cv_vocabularySource_key**, a foreign key into |
|      |     |    | the cv_VocabularySource table identifying the     |
|      |     |    | vocabulary source.                                |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table ExperimentalDesignType to hold the  |
| 0.3b | eri |    | project\'s experimental design type(s) as foreign |
|      | ved |    | keys to MA_Project and cv_ExperimentalDesignType. |
|      |     |    | The experimental design free-text comes from      |
|      |     |    | MA_Project.expDesign. The field **orderBy**       |
|      |     |    | governs the order that a given experiment\'s      |
|      |     |    | design types are displayed.                       |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table cv_MaterialType to hold the         |
| 0.4a | eri |    | material type controlled vocabulary, with the     |
|      | ved |    | same structure as cv_ExperimentalDesign.          |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new nullable column                           |
| 0.4b | eri |    | RNASample.**\_cv_materialType_key**, which is a   |
|      | ved |    | FK into cv_MaterialType, to capture the sample\'s |
|      |     |    | material type.                                    |
+------+-----+----+---------------------------------------------------+
| 12   | D   | ♦  | Alter the cv_Organism table to have the same      |
| 40.5 | eri |    | structure as cv_ExperimentalDesign. Additionally, |
|      | ved |    | make the column name unique.                      |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | As the RNASample organism is no longer implicitly |
| 0.5a | eri |    | *mouse*:                                          |
|      | ved | ♦  |                                                   |
|      |     |    | 1.  Add a new required column                     |
|      |     | ♦  |     RNASample.**\_cv_organism_key**, which is a   |
|      |     |    |     FK into cv_Organism, to capture the sample\'s |
|      |     | ♦  |     organism.                                     |
|      |     |    |                                                   |
|      |     | ♦  | 2.  Create new cv_Organism-RNASample FK           |
|      |     |    |     constraint.                                   |
|      |     | ♦  |                                                   |
|      |     |    | 3.  Rename RNASample.**numMice** to               |
|      |     | ♦  |     **numOrganisms** and update references to it. |
|      |     |    |                                                   |
|      |     | ♦  | 4.  Rename RNASample.**mouseSex** to **sex** and  |
|      |     |    |     update references to it.                      |
|      |     | [  |                                                   |
|      |     | ]{ | 5.  Create new column RNASample.**\_age_key**,    |
|      |     | .m |     which is a FK into Age, to capture the        |
|      |     | ar |     organism\'s age information.                  |
|      |     | k} |                                                   |
|      |     |    | 6.  Migrate the data currently in                 |
|      |     | [  |     RNASample.**mouseAge** to                     |
|      |     | ]{ |     Age.**userDefined**.                          |
|      |     | .m |                                                   |
|      |     | ar | 7.  Migrate the Age.**userDefined** data just     |
|      |     | k} |     created in step 6. above, into                |
|      |     |    |     RNASample.**\_age_key**.                      |
|      |     | ♦  |                                                   |
|      |     |    | 8.  Update all references in the VB code that use |
|      |     |    |     the column RNASample.**mouseAge** to use      |
|      |     |    |     RNASample.**\_age_key** (requires changes to  |
|      |     |    |     DML statements)                               |
|      |     |    |                                                   |
|      |     |    | 9.  Remove the column RNASample.**mouseAge**      |
+------+-----+----+---------------------------------------------------+
| 12   | Sys | ♦  | Permit user to further categorize                 |
| 40.6 | tem |    | RNASample.**mouseAge** (migrated to               |
|      |     |    | RNASample.**\_age_key** in previous step) by      |
|      |     |    | *value*, *unit*, and *epoch*.                     |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table cv_TimeUnit to hold the time unit   |
| 0.6a | eri |    | controlled vocabulary, with the same structure as |
|      | ved |    | cv_ExperimentalDesign, with the additional        |
|      |     |    | columns **abbreviation** and **minutesPerUnit**,  |
|      |     |    | which is intended to be a close, if not exact,    |
|      |     |    | estimate of the time unit corresponding to        |
|      |     |    | **name**, in minutes..                            |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table cv_EpochUnit to hold the epoch unit |
| 0.6b | eri |    | controlled vocabulary, with the same structure as |
|      | ved |    | cv_ExperimentalDesign.                            |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table Age to hold the                     |
| 0.6c | eri |    | RNASample.**mouseAge** component.                 |
|      | ved |    | RNASample.**mouseAge** is replaced by             |
|      |     |    | RNASample.**\_age_key** with this change. Prior   |
|      |     |    | to this change, MAD stored the age as a string.   |
|      |     |    | This change permits easy migration from the       |
|      |     |    | existing (user-defined, free-text) string to a    |
|      |     |    | searchable controlled-vocabulary time-unit        |
|      |     |    | abstraction. Age is required (as it was           |
|      |     |    | previously in MAD). Thus, **isTimeUnit** is not   |
|      |     |    | null. The individual fields that hold the age     |
|      |     |    | components are null; thus, the user interface     |
|      |     |    | enforces the *not null* rule by requiring either  |
|      |     |    | a user-defined string or a time unit-defined      |
|      |     |    | string This table\'s columns are:                 |
|      |     |    |                                                   |
|      |     |    | 1.  **\_age_key** -- primary key                  |
|      |     |    |                                                   |
|      |     |    | 2.  **displayValue** -- the string version of the |
|      |     |    |     age, regarless whether it\'s a user-defined   |
|      |     |    |     age or a time unit-based age (varchar 32, NOT |
|      |     |    |     NULL)                                         |
|      |     |    |                                                   |
|      |     |    | 3.  **isTimeUnit** -- boolean column: if true,    |
|      |     |    |     age is in time units; otherwise, user-defined |
|      |     |    |     (NOT NULL)                                    |
|      |     |    |                                                   |
|      |     |    | 4.  **userDefined** -- the string containing the  |
|      |     |    |     user-defined age string (NULL)                |
|      |     |    |                                                   |
|      |     |    | 5.  **value** -- the float containing the numeric |
|      |     |    |     time-unit-based value (NULL)                  |
|      |     |    |                                                   |
|      |     |    | 6.  **\_cv_timeUnit_key** -- the FK into          |
|      |     |    |     cv_TimeUnit holding the time-unit-based time  |
|      |     |    |     unit. (NULL)                                  |
|      |     |    |                                                   |
|      |     |    | 7.  **\_cv_epochUnit_key** -- the FK into         |
|      |     |    |     cv_EpochUnit holding the time-unit-based      |
|      |     |    |     epoch unit. (NULL)                            |
|      |     |    |                                                   |
|      |     |    | 8.                                                |
+------+-----+----+---------------------------------------------------+
| 12   | Sys | ♦  | Integrate experimental factors into a project.    |
| 40.7 | tem |    | Prior to this enhancement, there was no way for   |
|      |     |    | Gene Expression to sketch out proposed            |
|      |     |    | experimental designs in MAD, as MAD requires the  |
|      |     |    | real samples (which don\'t yet exist). The new    |
|      |     |    | solution is:                                      |
|      |     |    |                                                   |
|      |     |    | 1.  The experiment designer enters the proposed   |
|      |     |    |     factors into the database through a new GUI   |
|      |     |    |     form. The factors may originate from any      |
|      |     |    |     readable MAD table.                           |
|      |     |    |                                                   |
|      |     |    | 2.  The experiment designer enters one or more    |
|      |     |    |     *values* for each proposed factor. Like the   |
|      |     |    |     factors themselves, the factor *values* may   |
|      |     |    |     originate from any readable MAD table.        |
|      |     |    |                                                   |
|      |     |    | 3.  The experiment designer enters the number of  |
|      |     |    |     replicates. The default is 3.                 |
|      |     |    |                                                   |
|      |     |    | 4.  The experiment designer presses a button      |
|      |     |    |     labeled **Refresh** that presents them with a |
|      |     |    |     grid labeled Sample Mapping against which     |
|      |     |    |     they can map the real samples when they are   |
|      |     |    |     ready.                                        |
|      |     |    |                                                   |
|      |     |    | Example:                                          |
|      |     |    |                                                   |
|      |     |    | Given the following experiment layout:            |
|      |     |    |                                                   |
|      |     |    | > 2 Factors: Strain, Treatment                    |
|      |     |    | >                                                 |
|      |     |    | > 2 Factor values for Strain; 3 Factor values for |
|      |     |    | > treatment                                       |
|      |     |    | >                                                 |
|      |     |    | > 3 replicates                                    |
|      |     |    |                                                   |
|      |     |    | The Sample Mappings form would look like:         |
|      |     |    |                                                   |
|      |     |    |   --------------- --------------- --------------- |
|      |     |    |   Sample Name     Strain          Treatment       |
|      |     |    |                                                   |
|      |     |    |   sample 1        Strain A        not treated     |
|      |     |    |                                                   |
|      |     |    |   sample 2        Strain A        not treated     |
|      |     |    |                                                   |
|      |     |    |   sample 3        Strain A        not treated     |
|      |     |    |                                                   |
|      |     |    |   sample 4        Strain A        10 mg Drug1     |
|      |     |    |                                                   |
|      |     |    |   sample5         Strain A        10 mg Drug1     |
|      |     |    |                                                   |
|      |     |    |   sample 6        Strain A        10 mg Drug1     |
|      |     |    |                                                   |
|      |     |    |   sample 7        Strain A        20 mg Drug2     |
|      |     |    |                                                   |
|      |     |    |   sample 8        Strain A        20 mg Drug2     |
|      |     |    |                                                   |
|      |     |    |   sample 9        Strain A        20 mg Drug2     |
|      |     |    |                                                   |
|      |     |    |   sample 10       Strain B        not treated     |
|      |     |    |                                                   |
|      |     |    |   sample 11       Strain B        not treated     |
|      |     |    |                                                   |
|      |     |    |   sample 12       Strain B        not treated     |
|      |     |    |                                                   |
|      |     |    |   sample 13       Strain B        10 mg Drug1     |
|      |     |    |                                                   |
|      |     |    |   sample 14       Strain B        10 mg Drug1     |
|      |     |    |                                                   |
|      |     |    |   sample 15       Strain B        10 mg Drug1     |
|      |     |    |                                                   |
|      |     |    |   sample 16       Strain B        20 mg Drug2     |
|      |     |    |                                                   |
|      |     |    |   sample 17       Strain B        20 mg Drug2     |
|      |     |    |                                                   |
|      |     |    |   sample 18       Strain B        20 mg Drug2     |
|      |     |    |   --------------- --------------- --------------- |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add the new table cv_ExperimentalFactorType with  |
| 0.7a | eri |    | the same structure as cv_ExperimentalDesign.      |
|      | ved |    |                                                   |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table cv_ExperimentalFactor to hold the   |
| 0.7b | eri |    | factor\'s controlled vocabulary name, type        |
|      | ved |    | (foreign key to cv_ExperimentalFactorType),       |
|      |     |    | source table, source value column name, source    |
|      |     |    | key column name, and a flag indicating whether or |
|      |     |    | not the factor is currently active. This table    |
|      |     |    | replaces the existing table                       |
|      |     |    | cv_ExperimentalFactors. Discard any data in the   |
|      |     |    | old table, as no references to it are found       |
|      |     |    | within the MAD PMI vb code. Finally, drop the old |
|      |     |    | table cv_ExperimentalFactors.                     |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table ExperimentalFactor to hold the      |
| 0.7c | eri |    | project\'s experimental factors as foreign keys   |
|      | ved |    | to MA_Project and cv_ExperimentalFactor. It       |
|      |     |    | should have the new column **orderBy** to govern  |
|      |     |    | the order in which the project\'s experimental    |
|      |     |    | factors are presented.                            |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table ExperimentalFactorValue to hold the |
| 0.7d | eri |    | factor values. This table contains a foreign key  |
|      | ved |    | to ExperimentalFactor, the value\'s foreign table |
|      |     |    | key (the value\'s source table, source value      |
|      |     |    | column, and source key column are identified in   |
|      |     |    | cv_ExperimentalFactor), the actual value , and    |
|      |     |    | its display order.                                |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table ExperimentalSample to hold the      |
| 0.7e | eri |    | project\'s computed proposed samples (see 1240.7  |
|      | ved |    | above). This table has a foreign key to the       |
|      |     |    | MA_Project table, as well as the columns          |
|      |     |    | **bioReplicateIndex** (identifies this sample\'s  |
|      |     |    | biological replicate index), **isUsed** (a        |
|      |     |    | boolean indicating whether or not this sample     |
|      |     |    | placeholder is used/desired by the experiment     |
|      |     |    | designer), and **sampleIndex** (identifies this   |
|      |     |    | sample\'s index).                                 |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table ExperimentalSampleDetail to hold    |
| 0.7f | eri |    | this sample\'s factor values (one row per         |
|      | ved |    | factor). This table contains a foreign key to     |
|      |     |    | ExperimentalSample and a nullable foreign key to  |
|      |     |    | ExperimentalFactorValue.                          |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Remove the columns **expFactor1** through         |
| 0.7g | eri |    | **expFactor6** from MA_Project and the GUI.       |
|      | ved |    |                                                   |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Remove the columns **expF1Levels** through        |
| 0.7h | eri |    | **expF6Levels** from MA_Project and the GUI.      |
|      | ved |    |                                                   |
+------+-----+----+---------------------------------------------------+
| 12   | Sys | ♦  | The table cv_TissueType currently contains        |
| 40.8 | tem |    | elements of both cell and tissue. Permit the user |
|      |     |    | to separate the cell elements from the tissue     |
|      |     |    | elements. Cell elements go into a new table       |
|      |     |    | called cv_CellType.                               |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table cv_CellType to hold the cell type   |
| 0.8a | eri |    | controlled vocabulary, with the same structure as |
|      | ved |    | cv_ExperimentalDesign.                            |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new column RNASample.**\_cv_cellType_key**,   |
| 0.8b | eri |    | which is a FK into cv_CellType, to capture the    |
|      | ved |    | sample\'s cell type. Data migration will be       |
|      |     |    | performed by the user.                            |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Alter the cv_TissueType table to have the same    |
| 0.8c | eri |    | structure as cv_ExperimentalDesign. Additionally, |
|      | ved |    | make the column **name** unique.                  |
+------+-----+----+---------------------------------------------------+
| 124  | D   | [  | Alter the existing column                         |
| 0.8d | eri | ]{ | RNASample.**tissueType**:                         |
|      | ved | .m |                                                   |
|      |     | ar | 1.  Add a new column                              |
|      |     | k} |     RNASample.**\_cv_tissueType_key**, which is a |
|      |     |    |     FK into cv_TissueType.                        |
|      |     | ♦  |                                                   |
|      |     |    | 2.  Create new cv_TissueType-RNASample constraint |
|      |     | ♦  |                                                   |
|      |     |    | 3.  Migrate the existing varchar data to use the  |
|      |     | [  |     new int key                                   |
|      |     | ]{ |                                                   |
|      |     | .m | 4.  Update all references in the VB code that use |
|      |     | ar |     the column **tissueType** to use              |
|      |     | k} |     **\_cv_tissueType_key**.                      |
|      |     |    |                                                   |
|      |     | ♦  | 5.  Delete the column RNASample.**tissueType.**   |
|      |     |    |                                                   |
|      |     |    | > **NOTE: Not all action items could be           |
|      |     |    | > completed. RNASample.tissueType contains cell   |
|      |     |    | > entries as well, which must be sorted out. This |
|      |     |    | > is not a blocker, but rather a maintenance      |
|      |     |    | > item.**                                         |
+------+-----+----+---------------------------------------------------+
| 12   | Sys | ♦  | Standardize protocols associated with a sample to |
| 40.9 | tem |    | be MAGE-TAB compliant.                            |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new table cv_ProtocolType with the same       |
| 0.9a | eri |    | structure as cv_ExperimentalDesign. This table    |
|      | ved |    | permits association of a standard protocol type   |
|      |     |    | to a protocol. Add the following protocol types,  |
|      |     |    | using vocabulary source \'MGED\':                 |
|      |     |    |                                                   |
|      |     |    |   -----                                           |
|      |     |    | ------------------------- ----------------------- |
|      |     |    |   **Protocol Type**              **Applies To**   |
|      |     |    |                                                   |
|      |     |    |   nucleic_acid_extraction        nucleic acid     |
|      |     |    |                                                   |
|      |     |    |   labeling                       nucleic acid     |
|      |     |    |                                                   |
|      |     |    |   hybridization                  microarray       |
|      |     |    |                                                   |
|      |     |    |   wash                           microarray       |
|      |     |    |                                                   |
|      |     |    |   scan                           microarray       |
|      |     |    |                                                   |
|      |     |    |   bioassay_data_transformation   microarray       |
|      |     |    |   (also known as                                  |
|      |     |    |   \'data_transformation\')                        |
|      |     |    |   -----                                           |
|      |     |    | ------------------------- ----------------------- |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add a new table cv_Protocol with the columns      |
| 0.9b | eri |    | **name**, **description**,                        |
|      | ved |    | **\_cv_protocol_type_key**, and **active**. This  |
|      |     |    | table is a repository of all protocols,           |
|      |     |    | categorized by cv_ProtocolType.                   |
|      |     |    |                                                   |
|      |     |    | Add to this table the contents of (the old)       |
|      |     |    | tables cv_RNAProtocol (using protocol type        |
|      |     |    | *nucleic_acid_extraction*) and                    |
|      |     |    | cv_HybridizationProtocol (using protocol type     |
|      |     |    | *hybridization*).                                 |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Protocol type *nucleic_acid_extraction*:          |
| 0.9c | eri |    |                                                   |
|      | ved | ♦  | 1.  Add a new *not-nullable* column               |
|      |     |    |     R                                             |
|      |     | ♦  | NASample.\_**nucleicAcidExtractionProtocol_key**, |
|      |     |    |     which is a FK into cv_Protocol identifying    |
|      |     | ♦  |     the nucleic acid extraction protocol used for |
|      |     |    |     the sample.                                   |
|      |     | ♦  |                                                   |
|      |     |    | 2.  Create the following new constraint:          |
|      |     | ♦  |     cv_Proto                                      |
|      |     |    | col-RNASample.\_nucleicAcidExtractionProtocol_key |
|      |     |    |                                                   |
|      |     |    | 3.  Migrate the *nucleic_acid_extraction          |
|      |     |    |     protocol* data by updating the column         |
|      |     |    |                                                   |
|      |     |    | RNASample.**\_nucleicAcidExtractionProtocol_key** |
|      |     |    |     with the cv_Protocol.**\_protocol_key**       |
|      |     |    |     identified by joining on cv_Protocol.**name** |
|      |     |    |     = RNASample.**protocol**.                     |
|      |     |    |                                                   |
|      |     |    | 4.  Update all references in the VB code that use |
|      |     |    |     the column RNASample.**protocol** to use      |
|      |     |    |                                                   |
|      |     |    | RNASample.**\_nucleicAcidExtractionProtocol_key** |
|      |     |    |     (requires changes to DML statements)          |
|      |     |    |                                                   |
|      |     |    | 5.  Drop the cv_RNAProtocol table.                |
|      |     |    |                                                   |
|      |     |    | 6.  Drop the RNASample.**protocol** column.       |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Protocol type *labeling*:                         |
| 0.9d | eri |    |                                                   |
|      | ved |    | 1.  Add a new *nullable* column                   |
|      |     |    |     RNASample.**\_labelingProtocol_key**, which   |
|      |     |    |     is a FK into cv_Protocol identifying the      |
|      |     |    |     labeling protocol used for the sample.        |
|      |     |    |                                                   |
|      |     |    | 2.  Create new                                    |
|      |     |    |     cv_Protocol-RNASample.\_labelingProtocol_key  |
|      |     |    |     FK constraint.                                |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Protocol type *hybridization*:                    |
| 0.9e | eri |    |                                                   |
|      | ved | ♦  | 1.  Add the following new *nullable* columns,     |
|      |     |    |     which are FKs into cv_Protocol:               |
|      |     | ♦  |                                                   |
|      |     |    |     -   Slide.**\_hybProtocol_key**               |
|      |     | ♦  |                                                   |
|      |     |    |     -   AFFYGeneChip.**\_hybProtocol_key**        |
|      |     | ♦  |                                                   |
|      |     |    |     -   ILLUMINABeadChips.**\_hybProtocol_key**   |
|      |     | ♦  |                                                   |
|      |     |    | 2.  Create the following new FK constraints:      |
|      |     |    |                                                   |
|      |     |    |     -   cv_Protocol-Slide.\_hybProtocol_key       |
|      |     |    |                                                   |
|      |     |    |                                                   |
|      |     |    |    -   cv_Protocol-AFFYGeneChip.\_hybProtocol_key |
|      |     |    |                                                   |
|      |     |    |     -                                             |
|      |     |    |   cv_Protocol-ILLUMINABeadChips.\_hybProtocol_key |
|      |     |    |                                                   |
|      |     |    | 3.  Migrate the existing Spotted Array            |
|      |     |    |     *hybridization protocol* data already in      |
|      |     |    |     Slide.**hybProtocol** by updating the column  |
|      |     |    |     Slide.**\_hybProtocol_key** with the          |
|      |     |    |     cv_Protocol.**\_protocol_key** identified by  |
|      |     |    |     joining on cv_Protocol.**name** =             |
|      |     |    |     Slide.**hybProtocol**                         |
|      |     |    |                                                   |
|      |     |    | 4.  Update all references in the VB code that use |
|      |     |    |     the column Slide.**hybProtocol** to use       |
|      |     |    |     Slide.**\_hybProtocol \_key** (requires       |
|      |     |    |     changes to DML statements)                    |
|      |     |    |                                                   |
|      |     |    | 5.  Drop the cv_HybridizationProtocol table.      |
|      |     |    |                                                   |
|      |     |    | 6.  Drop the Slide.**hybProtocol** column.        |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Protocol type *wash*:                             |
| 0.9f | eri |    |                                                   |
|      | ved |    | 1.  Add the following new *nullable* columns,     |
|      |     |    |     which are FKs into cv_Protocol:               |
|      |     |    |                                                   |
|      |     |    |     -   Slide.**\_washProtocol_key**              |
|      |     |    |                                                   |
|      |     |    |     -   AFFYGeneChip.**\_washProtocol_key**       |
|      |     |    |                                                   |
|      |     |    |     -   ILLUMINABeadChips.**\_washProtocol_key**  |
|      |     |    |                                                   |
|      |     |    | 2.  Create the following new FK constraints:      |
|      |     |    |                                                   |
|      |     |    |     -   cv_Protocol-Slide.\_washProtocol_key      |
|      |     |    |                                                   |
|      |     |    |     -   cv_Protocol-AFFYGeneChip.\_washProtocol   |
|      |     |    |         \_key                                     |
|      |     |    |                                                   |
|      |     |    |                                                   |
|      |     |    |  -   cv_Protocol-ILLUMINABeadChips.\_washProtocol |
|      |     |    |         \_key                                     |
+------+-----+----+---------------------------------------------------+
| 124  |     | ♦  | Protocol type *scan*:                             |
| 0.9g |     |    |                                                   |
|      |     | [  | 1.  Add the following new *nullable* columns,     |
|      |     | ]{ |     which are FKs into cv_Protocol:               |
|      |     | .m |                                                   |
|      |     | ar |     -   Slide.**\_scanProtocol_key**              |
|      |     | k} |                                                   |
|      |     |    |     -   AFFYGeneChip.**\_scanProtocol_key**       |
|      |     | [  |                                                   |
|      |     | ]{ |     -   ILLUMINABeadChips.**\_scanProtocol_key**  |
|      |     | .m |                                                   |
|      |     | ar | 2.  Create the following new FK constraints:      |
|      |     | k} |                                                   |
|      |     |    |     -   cv_Protocol-Slide.\_scanProtocol_key      |
|      |     |    |                                                   |
|      |     |    |     -   cv_Protocol-AFFYGeneChip.\_scanProtocol   |
|      |     |    |         \_key                                     |
|      |     |    |                                                   |
|      |     |    |                                                   |
|      |     |    |  -   cv_Protocol-ILLUMINABeadChips.\_scanProtocol |
|      |     |    |         \_key                                     |
+------+-----+----+---------------------------------------------------+
| 124  |     | ♦  | Protocol type *bioassay_data_transformation*:     |
| 0.9h |     |    |                                                   |
|      |     | [  | 1.  Add the following new *nullable* columns,     |
|      |     | ]{ |     which are FKs into cv_Protocol:               |
|      |     | .m |                                                   |
|      |     | ar |                                                   |
|      |     | k} |    -   Slide.**\_dataTransformationProtocol_key** |
|      |     |    |                                                   |
|      |     |    |     -                                             |
|      |     |    | AFFYGeneChip.**\_dataTransformationProtocol_key** |
|      |     |    |                                                   |
|      |     |    |     -   ILLUM                                     |
|      |     |    | INABeadChips.**\_dataTransformationProtocol_key** |
|      |     |    |                                                   |
|      |     |    | 2.  Create the following new FK constraints:      |
|      |     |    |                                                   |
|      |     |    |     -   c                                         |
|      |     |    | v_Protocol-Slide.\_dataTransformationProtocol_key |
|      |     |    |                                                   |
|      |     |    |     -   cv_Proto                                  |
|      |     |    | col-AFFYGeneChip.\_dataTransformationProtocol_key |
|      |     |    |                                                   |
|      |     |    |     -   cv_Protocol-I                             |
|      |     |    | LLUMINABeadChips.\_dataTransformationProtocol_key |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add to form CVMaintenance buttons to manage       |
| 0.11 | eri |    | controlled vocabularies for new tables, and add   |
|      | ved |    | new forms identical to the existing forms         |
|      |     |    | cv_OneFieldEdit, cv_TwoFieldEdit, and             |
|      |     |    | cv_ThreeFieldEdit, that contain the two new       |
|      |     |    | fields ElementID and VocabularySource (see        |
|      |     |    | 1240.2, 3a, 4, 5, 6a, 6c, 7a, 8a, 9a).            |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Alter forms EditProject and CVMaintenance to      |
| 0.12 | eri |    | handle the experimental design (see 1240.3b).     |
|      | ved |    |                                                   |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Alter forms AddRNASample, EditRNASample, and      |
| 0.13 | eri |    | CVMaintenance to handle the material type (see    |
|      | ved |    | 1240.4) .                                         |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Alter forms AddRNASample, EditRNASample, and      |
| 0.14 | eri |    | CVMaintenance to handle the organism (see         |
|      | ved |    | 1240.5).                                          |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Alter forms AddRNASample, EditRNASample, and      |
| 0.15 | eri |    | CVMaintenance to handle mouse age **value**,      |
|      | ved |    | **unit**, and **epoch** (see 1240.6)              |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Alter form CVMaintenance to handle experimental   |
| 0.16 | eri |    | factors and experimental factor types (see        |
|      | ved |    | 1240.7)                                           |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Alter forms AddRNASample, EditRNASample, and      |
| 0.17 | eri |    | CVMaintenance to break out tissue type from cell  |
|      | ved |    | type and permit choosing of tissue and cell types |
|      |     |    | separately (see 1240.8)                           |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Form AdministrativeFunctionsForm: Remove unused   |
| 0.18 | eri |    | subroutine Start_a_Project_Click() from vb code.  |
|      | ved |    | This is the only reference to the old factors and |
|      |     |    | levels (see 1240.8)                               |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Alter form CVMaintenance to handle project and    |
| 0.19 | eri |    | sample protocols (see 1240.9, 10)                 |
|      | ved |    |                                                   |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Add new button **Publish to caArray\...** to the  |
| 0.20 | eri |    | EditProject form that creates the MAGE-TAB file   |
|      | ved |    | set for the selected project                      |
+------+-----+----+---------------------------------------------------+
| 1240 | D   | ♦  | Add new button **Project Factors\...** to the     |
| .20a | eri |    | EditProject form that permits factor and factor   |
|      | ved |    | value editing and mapping                         |
+------+-----+----+---------------------------------------------------+
| 124  | D   | ♦  | Enable controlled vocabulary source selection for |
| 0.21 | eri |    | these legacy and new tables (NOTE: some tables,   |
|      | ved |    | such as cv_GrantingAgency (button labeled         |
|      |     |    | Granting Agency), do not require vocabulary       |
|      |     |    | source selection and are thus not included here): |
|      |     |    |                                                   |
|      |     |    | > cv_Algorithm                                    |
|      |     |    | >                                                 |
|      |     |    | > cv_AmplificationMethod                          |
|      |     |    | >                                                 |
|      |     |    | > cv_CellType                                     |
|      |     |    | >                                                 |
|      |     |    | > cv_CloneManufacturer                            |
|      |     |    | >                                                 |
|      |     |    | > cv_DiseaseArea                                  |
|      |     |    | >                                                 |
|      |     |    | > cv_Epoch Unit                                   |
|      |     |    | >                                                 |
|      |     |    | > cv_ExperimentalDesign                           |
|      |     |    | >                                                 |
|      |     |    | > cv_ExperimentalFactorType                       |
|      |     |    | >                                                 |
|      |     |    | > cv_AnalysisSoftware (Labeled ImageAnalysis      |
|      |     |    | > Software)                                       |
|      |     |    | >                                                 |
|      |     |    | > cv_MaterialType                                 |
|      |     |    | >                                                 |
|      |     |    | > cv_Organism                                     |
|      |     |    | >                                                 |
|      |     |    | > cv_Protocol (button label Protocols)            |
|      |     |    | >                                                 |
|      |     |    | > cv_ProtocolType                                 |
|      |     |    | >                                                 |
|      |     |    | > cv_ResearchArea                                 |
|      |     |    | >                                                 |
|      |     |    | > cv_RNAType                                      |
|      |     |    | >                                                 |
|      |     |    | > cv_SampleType                                   |
|      |     |    | >                                                 |
|      |     |    | > cv_SlideManufacturer                            |
|      |     |    | >                                                 |
|      |     |    | > cv_SpottingMethod                               |
|      |     |    | >                                                 |
|      |     |    | > cv_StrainType                                   |
|      |     |    | >                                                 |
|      |     |    | > cv_SurfacePrep                                  |
|      |     |    | >                                                 |
|      |     |    | > cv_TechRepStage                                 |
|      |     |    | >                                                 |
|      |     |    | > cv_TimeUnit                                     |
|      |     |    | >                                                 |
|      |     |    | > cv_TissueType                                   |
|      |     |    | >                                                 |
|      |     |    | > cv_Treatment                                    |
+------+-----+----+---------------------------------------------------+

# Appendix A -- Acronym List {#appendix-a-acronym-list .unnumbered}

  -------------- -----------------------------------------------------------
  Term/\         Description
  Abbreviation   

  ASP            Active Server Pages (Microsoft IIS-based environment)

  DBA            Database Administrator

  GUI            Graphical User Interface

  IIS            Microsoft Internet Information Services

  JSP            Java Server Pages

  LIMS           Laboratory Information Management System

  MAD            Micro Array Database

  NCICB          National Cancer Institute\'s Center for Bioinformatics

  PM             Project Manager

  PMI            Project Management Interface

  RM             Requirements Manager

  RTM            Requirements Traceability Matrix

  SCM            Software Configuration Management

  SDLC           Software Development Life Cycle

  SDP            Software Development Plan

  SE             Software Engineering

  SEPG           Software Engineering Process Group

  SM             Software Manager

  SOP            Standard Operating Procedure

  SPI            Software Process Improvement

  SQA            Software Quality Assurance

  SW             Software

  TBD            To Be Determined

  TM             Test Manager

  VB             Visual Basic

  VBA            Visual Basic for Applications
  -------------- -----------------------------------------------------------

# Appendix B -- sample Mage-tab files {#appendix-b-sample-mage-tab-files .unnumbered}

MAGE-TAB files will contain data from corresponding MAD fields. Some of
these fields will be newly implemented per this document and the data
will need to be supplied to Gene Expression Services (GES) by the
investigator prior to creation of the MAGE-TAB files (or the fields will
be left blank). MAGE-TAB ADF files will be created on an as-needed
basis, only if manufacturer array design files are unavailable (MAGE-TAB
ADF files will not be needed for initial implementation and are expected
to be rarely, if ever required).

Note that some of the cells and columns are blank. This reflects the
information inherent to the individual experiment. For example, a sample
might be from organism_part, but not dissected to the cell_type. The
files are tab-delimited, but are displayed in table format for viewing
here.

**06MA-001_kdm.idf**

![](media/image1.wmf){width="7.457638888888889in"
height="4.766666666666667in"}

**06MA-001_kdm.sdrf (This illustrates a single file, with 42 headers and
2 rows of data. The file has been split to fit this page.)**

![](media/image2.wmf){width="9.594444444444445in"
height="0.4048611111111111in"}

![](media/image3.wmf){width="9.595833333333333in"
height="0.4222222222222222in"}

![](media/image4.wmf){width="9.590972222222222in"
height="0.4597222222222222in"}

![](media/image5.wmf){width="9.588888888888889in" height="0.43125in"}

![](media/image6.wmf){width="9.591666666666667in"
height="0.4305555555555556in"}

![](media/image7.wmf){width="9.594444444444445in"
height="0.4152777777777778in"}

![](media/image8.wmf){width="1.5840277777777778in"
height="0.42430555555555555in"}