Page History

This section includes the following topics.

...

AnchorRTF32393339353a204368617074RTF32393339353a204368617074Creating a New Study
This chaptersection chapter describes the processes for creating and managing studies in caIntegrator.
Topics in this chaptersection include:

...

Creating a

...

Study – Overview

study:creatingYou You can create a caIntegrator study by importing subject annotation study data, genomics data and imaging data, using a combination of spreadsheet/files and existing caGrid applications as source data. Each instance of caIntegrator can support multiple studies. As the manager creating a study, it is important that you understand the study well and that the data you wish to aggregate has been submitted to the applications whose data can be integrated in caIntegrator.

• study:subject annotation description;subject annotation:data forSubject Subject Annotation – Subject annotation data refers to pre-subject annotation, phenotypic, subject annotation, pathology or any other annotations associated with a subject.The subject annotation data should be available in CSV files, with a unique patient identifier in one column, one patient per row. Other relevant data can be supplied in other columns to be identified as annotations in the file from within caIntegrator. You, as the study creator, must have access to the subject annotation data file, as the file does not come from a caBIG^® repository.
• study:genomic data, description;genomic data:for studyGenomic Genomic – To use caIntegrator to integrate array data, the data should be imported into caArray, either locally or in the CBIIT installation, using that system's data file import functionality. You must also have a mapping file in CSV format. This file indicates correlations between array files and the subjects in the subject annotation data files.
• study:imaging data, description;imaging data:for studyImaging Imaging – Imaging data should have been submitted to the NBIA grid node as public data, either locally or as part of the CBIIT installation. Image annotations, which includes information about images provided by radiologists or other researchers can include such information as tumor size, tumor location, etc. It must be in CSV format, with unique image series IDs in one column (required) and annotation IDs in the second column. caIntegrator can map the images automatically or alternatively, you can upload an image mapping file in CSV format. This file indicates correlations between subject annotation subjects or images in NBIA and subjects in the subject annotation data files.

As you create the study, you define its structure in the process, identifying the data sources and mapping the data between different source data. After the study has been created and deployed, the study can then be used to you can perform analyses .
AnchorRTF34353236333a204865616469RTF34353236333a204865616469of the data in the study.

Configuring and Deploying a Study

When you create a study:creating;creating:study;deploying studystudy, you must specify different data-types (subject annotation, array, image, etc), data sources (caGrid applications – caArray and NBIA) and map the data, (patient to sample, image series, etc.).

To create a new study, follow these steps:

1. In the Study Management section of the left sidebar, click Create New Study.
2. In the Create New Study dialog box that opens, provide a name and description for the study you are creating (). Image Modified

• Anchor
  RTF39303134393a204361707469 RTF39303134393a204361707469

  Create Study page

1. Click Save.

This opens an Edit Study page where you can add identify data files for your study. See .

Creating/Editing a

...

Study

creating:study;study:creatingThe The Edit Study page, as described shown in the following figure, displays the Name and Description that you entered for a new study, or for an existing study that you are editing (). Image Modified

...

To continue creating a study or to modify a study, on the Edit Study page complete these steps:

1. Enter or change(if editing) the name and/or description, if you choose.
2. Check the checkbox to make the study publicly available, if appropriate.
3. For the study log feature, click View Log or Edit Log. See for details about the log.
4. Click Save.

...

1. Info
   title Note

...

1. You can save the study at any point in the process of creating it. You can resume the definition and deployment process later.

2. If you choose to add a logo for the study, click the Browse button corresponding to Logo File. Navigate for the file, then click Upload Now. Once you save the study (or its edit), the logo displays in the center of the page (). On the home page for the study, the logo displays in the upper left, above the sidebar. Image Modified

...

To continue, you can add subject annotation data sources, genomic data sources or imaging data sources.
AnchorRTF39323832313a204865616469RTF39323832313a204865616469

Viewing/Editing a Log

log, viewing or editingOn On the Edit Study page, as a study manager you can open a detailed log for the study.

1. Click View Log on the Edit Study page to simply review an existing log. The log records all steps comprising activity in the study, with the most recent displaying at the top of the log.
2. To edit a log, click Edit Log on the Edit Study page.
3. Add an appropriate description/annotations to the individual log entries.
4. Check the Update box next to the description, then click Save to save the edits. The descriptions will now be available when any user views the log.

See also on page 12.

Working with Annotations – An Overview

One of the most important factors in creating a study in caIntegrator is in properly annotating the data. Because the process can be relatively complex, you might want to review the steps for working with annotations.
Annotation workflow summary:

1. Add an annotation group. This optional step is for users who have a rigid data dictionary of all annotations relevant to the study. This step can also be helpful in cases where a study has many annotations. For more information, see .
2. Add subject annotation data. This consists of multiple sub-steps.
3. Add a new subject annotation data sources file. This step uploads the file and starts the workflow for assigning uploaded data definitions. See , step .
   1. Edit the annotations. This step opens the Define Fields for Subject Data page. See , step .
   2. In the Define Fields for Subject Data page, review possible definitions in the annotation group associated with this study. See .
   3. Assign the visibility of each annotation definition. See , step .
   4. Locate and verify the assignment as "identifier" for one annotation. See .
   5. Review, verify and assign definitions for each annotation. You can do this in one of four ways:
      --Accept existing default definitions as described in the associated annotation group. See .
      --Create or manage definitions manually. See .
      --Search for and use definitions existing in other caIntegrator studies. see .
      --Search for and use definitions from caDSR. see .
4. Load the Subject Annotation Source. Up until this point, you can periodically save your work with the annotations, but before you can deploy the study, you must complete this step.
5. Deploy the study. See .

...

Adding An Annotation Group

This topic opens from both the Create Annotation Group page and the Edit Annotation Group page. If you plan to create a group, continue with this topic. If you plan to edit an annotation group, see .
annotation group:adding;adding:annotation groupAn annotation group is a group of annotation definitions configured in a CSV file. This feature is primarily meant for the Study Manager who knows that they have tightly restricted vocabulary definitions that are relevant to a study. In this optional step, you can review the uploaded Group Definition Source file before assigning the appropriate definition for your study.
To add an annotation group, follow these steps:

...

...

1. On the Edit Study page for a study, Annotation Groups section, click the Add New button.
2. On the Edit Annotation Group page that opens, enter a name for the annotation group.
3. Enter a description (optional).
4. Browse for the Group Definition Source CSV file.
   The CSV file must include columns with these column headers in the first row: File Column Name, Field Type, Entity Type, CDE ID, CDE Version, Annotation Def Name, Data Type, Permissible, and Visible. Subsequent rows in the file define each subject annotation column in the subject annotation file.
   1. If a subject annotation is defined by a CDE Public ID, values for the following columns are required: File Column Name, Field Type, Entity Type, CDE ID, and Visible; a value for CDE Version is optional.
      – OR –
   2. If a subject annotation definition is not defined by a CDE Public ID, values for the following columns are required: File Column Name, Field Type, Entity Type, Annotation Def Name, Data Type (String, Date, Numeric), Permissible (Yes or No), and Visible (Yes or No).
5. Click Save. This uploads the file, whose name now displays on the Edit Study page under Annotation Groups.

When you open the Define Fields for Subject Data page (see ), the annotation definitions in the file you uploaded display on the page, available for assignment in the study. Additionally, you can view the definitions by viewing the annotation group listed in the first column of the matrix.

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

Image Modified

...

...

1. For the column (PatientID) that you choose to be the one and only Identifier column, in the Column Type drop-down list, select Identifier.
2. Click Save to save the identifier. This returns you to the Define Fields for Subject Data page where the Identifier is noted in the Field Definition

...

1. column.
2. After you have defined which field is the Identifier, you must ensure that ALL other fields also have a field definition assignment. For those fields without a Field Definition assignment or for those whose Annotation Definition you want to review, click Change Assignment.
3. In the Assign Annotation Definition for Field Descriptor dialog box, select Annotation in the drop-down list.

As you select the column type, you can work with column headers in one of four ways in this dialog box.

• You can accept existing default definitions (those that are inherent in the data file you selected). See Step .
• You can create and/or manage your own definitions manually. See Step .
• You can search for and use definitions in other caIntegrator studies. See .
• You can search for and use definitions found in caDSR. See . AnchorRTF31363630373a204e756d6265RTF31363630373a204e756d6265

1. Review the current

...

1. annotation definition in the Assign Definition page, Current Annotation Definition section. Click Cancel to return to the Define Fields... page.

You can still initiate a search for another annotation definition in the Search for an Annotation Definition section if you choose to change the definition (). See . Click Save to retain any changes. Image Modified

...

...

1. To enter a new name annotation, or any other information about the annotation definition, click the New button and enter the information described in the following table.

   Annotation Field	Field Description
   Name	Enter the name for the annotation.
   Definition	Enter the term(s) that define the annotation.
   Keywords	Insert keyword(s) that can be used to find the annotation in a search, separated by commas.
   Data Type	Select a string (default), numeric, or date.
   Apply Max Number Mask	This field is available only for numeric-type annotations, or when a new definition is created. This feature is unavailable when permissible values are present. Select the box and enter a maximum number for the mask, such as "80" for age. When you query results above the value of the mask, then the system displays the mask and not the actual age. Note: If you enter masks of both "max number" and "range", caIntegrator applies both masks at the same time. The Data Dictionary page now has a Restrictions column that shows restrictions whenever a mask has been applied.
   Apply Numeric Range Mask	This field is available only for numeric-type annotations, or when a new definition is created. This feature is unavailable when permissible values are present. Select the box and enter a width of range for the mask, such as "5" representing blocks of 5 years. For example, if you enter a width of 5, the query only allows age blocks of 0-5, 6-10, 11-15, etc. When you query results above the value of the mask, then the system displays the mask and not the actual age ranges. Note: If you enter masks of both "max number" and "range", caIntegrator applies both masks at the same time. The Data Dictionary page now has a Restrictions column that shows restrictions whenever a mask has been applied.
   permissible value, annotation definition;annotation definition:permissible valuesannotation definition:field definition entriesPermissible/Non-permissible Values	Note: The first time you load a file, before you assign annotation definitions (), these panels may be blank. If the column header for the data is already "recognizable" by caIntegrator, the system makes a "guess" about the data type and assigns the values to the data type in the newly uploaded file. They will display in the Non-permissible values sections initially. Use the Add and Remove buttons to move the values shown from one list to the other, as appropriate. When you select or change annotation definitions by selecting matching definitions (described in ), this may add (or change) the list of non-permissible values in this section. If you leave all values for a field in the Non-permissible panel, then when you do a study search, you can enter free text in the query criteria for this field. If there are items in the Permissible values list, then the values for this annotation are restricted to only those values. When you perform a study search, you will select from a list of these values when querying this field. If there are no items in the permissible values list then the field is considered free to contain any value. To edit a field's permissible values, you must change the annotation definition. You can do this even after a study has been deployed. Note: You cannot edit permissible values in an existing annotation definition. To change permissible values, you must create a new annotation.

...

...

...

Searching for Annotation Definitions

annotation:searching for definitions;searching:annotation definitionsAn alternative to creating a new definition is to search for annotation definitions already present in caIntegrator studies or in caDSR.

1. Enter search keyword(s) in the Search text box on the Assign Annotation Definition page. Click Search or click Enter to launch the search. After a few moments, the search results display on the page

...

1. shown in the following figure. Image Modified

...

...

1. Wiki Markup
   To view the definitions corresponding to any of the "Matching Annotation Definitions", which are those currently found in other caIntegrator studies, click the \[term\], such as "age", hypertext link. The definition then appears in the Current Annotation Definition segment of the page just above.

In summary, when you click the link, that assigns the definition to the Define Fields for Subject Data page, and it also closes the Annotation Definition page.

You can modify any portion of the definition, as described in .

1. The matches from caDSR display some of the details of the search results. To view more details of a match, such as permissible values, click View, which opens caDSR to the term. If you click Select, the caDSR definition automatically replaces the annotation definition for this field with which you are working.
   

...

1. {note:title=cautionTake care before you add a caDSR definition that it says exactly what you want. caDSR definitions can have minor nuances that require specific and limited applications of their use.

   Note

2. Once you have settled on an appropriate field definition for the annotation, click Save. This returns you to the Define Fields for Subject Data page.

   Info
   title Note
   If you have not clicked Select for alternate definitions in this dialog box, then click Save to return to the Define Field...dialog box without making any definition changes.

3. From the Define Fields for Subject Data page, be sure and designate the data types for each field in the file. Click Save on each page to save your entries or click New to clear the fields and start again. You will not be able to proceed until every field definition entry on the Fields for Subject Data screen has an entry, one as the unique Identifier and the remainder as annotations.

The Data From File columns on the page display the column header values of the first three rows you designated as "annotations".

The Edit Study page now displays a "Not Loaded" status for the file whose annotations (column headers) you have defined (). Image Removed

...

. An example of a file whose annotations have been defined but not yet loaded is shown in the following figure. Image Added

Status definitions:

• Definition Incomplete – An annotation definition or definitions must be modified on the Define Fields for Subject Data page. This status may be displayed because an identifier has not been selected. See .
• Not Loaded – The annotation definitions must be loaded before a study can be deployed. If an error appears after attempting to load a subject annotation source, cick the Edit Annotations button which takes you to the Define Fields for Subject Data page where the problematic annotations will appear in red. See .
• Loaded – The annotation definitions are properly loaded.

1. Click the Load Subject Annotation Source button in the Action section to load the data file you have configured, The Deploy Study button, to this point has been unavailable, but this step activates the button.

   Info
   title Note
   You can add as many files as are necessary for a study. Patients 1-20 in first file, 21-40 in second file, or many patients in first file and annotations in second file, etc. As long as IDs are defined correctly, it works.

• Click Deploy Study. caIntegrator now loads data from the file to the caIntegrator database, and the file status changes to "Loaded".

  Info
  title Note
  You can change assignments even after the study is deployed, using the Edit feature. For more information, see .

The Manage Studies page opens when the study is deployed. The Deployed status is indicated on the Manage Studies page as well as the Edit Study page. For more information, see .
You can continue to perform other tasks in caIntegrator while deployment is in process.
See also .

...

Defining Survival Values

survival values, defining;defining survival valuesSurvival value is the length of time a patient lived. If you plan to analyze your caIntegrator data to create a Kaplan-Meier (K-M) Plot, then during the Annotation Definition process described above in , you should do one of two things:

1. Make sure that you have defined at least three fields set to the "date" Data Type. These will be matched to the following three properties during Survival Value definition.

• Survival Start Date
• Death Date
• Last Followup Date

  Info
  title Note
  Setting survival values is optional if you do not plan to use the K-M plot analysis feature or if you do not have this kind of data (survival values) in the file.

1. It is also possible to generate KM plots if an Annotation Field Descriptor such as DAYSTODEATH has been set to Data Type 'numeric'. See .

For some applications, such as REMBRANDT and I-SPY, survival values are pre-defined in the databases when you load the data. In caIntegrator, however, you can review and define survival value ranges in a data set you are uploading to a study. To be able to do so, you need to understand the kind of data that can comprise the survival values.
To set up survival values, follow these steps:

• On the Edit Study page, click Edit Survival Values. This opens the Survival Value Definitions dialog box (). Image Modified AnchorRTF36333830353a204361707469RTF36333830353a204361707469
• Survival Value Definition dialog box_

1. Click New to enter new survival value definitions.

• OR -
  Click Edit to edit existing survival value definitions.

1. The dialog box extends, now displaying radio buttons and three drop-down lists that show column headers for date metadata in the spreadsheet you have uploaded. displays survival value ranges that have already been added to a study. Image Modified

...

...

Survival

...

Survival values can be defined by Date or by Length of time in study. Select the radio button for the category that defines your survival data.

In the drop-down lists, select the appropriate survival value definitions for each field listed. You might want to refer to the column headers in the data file itself. Dates covered by the definitions are already in the data set. You cannot enter specific dates.

...

See also on page 82.
Updated the Edit Survival Value Definitions page, now has a radio button and 2 different types of ways to define survival values.
AnchorRTF32383738323a204865616469RTF32383738323a204865616469

Adding/Editing Genomic Data

genomic data:adding to study;adding:genomic data;study:adding genomic dataOnce Once you have loaded subject annotation data and identified patient IDs, you can add either one or more sets of array genomic sample data from caArray, which caIntegrator maps by sample IDs to the patient IDs in the subject annotation data, covered in this section, or you can load imaging files from NBIA, also mapped by IDs to the patient data, covered in . You can also edit genomic data information that you have already added to the study. Genomic sample data and imaging data are independent of each other, so neither is required before loading the other.

It is essential that you are well acquainted with the data you are working with--the subject annotation data, and the corresponding array data in caArray.

caIntegrator supports a limited number of array platforms. For more information, see .

To add genomic data to your caIntegrator study, follow these steps:

1. On the Edit Study page where you have selected and added the subject annotation data, click the Add New button under Genomic Data Sources. You can upload genomic data only from caArray.

This opens the Edit Genomic Data Source dialog box. Enter the appropriate information in the fields (). This fields are described

Image Removed

...

 below. !worddav946e5d24c73cdc9a7c76170b895e5e66.png|vspace=4, alt="!

• caArray Web URL – Enter the URL for the caArray to be used for Edit Genomic Source dialog box"the genomic data sources. This will enable a user to link to the referenced caArray experiment from the study summary page.
• caArray Host Name – Enter the hostname for your local installation or for the CBIIT installation of caArray, If you misspell it, you will receive an error message.
• caArray JNDI Port – Enter the appropriate server port. See your administrator for more information. Example: For the CBIIT installation of caArray, enter 8080.
• caArray Username and caArray Password – If the data is private, you must enter your caArray account user name and password; you must have permissions in caArray for the experiment. If the data is public, you can leave these fields blank.
• caArray Experiment ID – Enter the caArray Experiment ID which you know corresponds with the subject annotation data you uploaded. Example: Public experiment "beer-00196" on the CBIIT installation of caArray (). If you misspell your entry, you will receive an error message.
• Vendor – Select either Agilent or Affymetrix
• Data Type – Select Expression or Copy Number.
• Platform – If appropriate, select the Agilent or Affymetrix platform.

  Info
  title Note
  Because you can add more than one set of genomic data to a study, a study can also have multiple platforms, one for each set of genomic data.

• Central Tendency for Technical Replicates – If more than one hybridization is found for the reporter, the hybridizations will be represented by this method.
• Indicate if technical replicates have high statistical variability – If more than one hybridization is found, checking this box will display a ** in the genomic search results when a reporter value has high statistical variability.
• Standard Deviation Type - When the checkbox for indicating if technical replicates have high statistical variability is checked, this parameter becomes available. Select in the drop-down the calculation to be used to determine whether or not to display a ** (see previous bullet point).
  --Relative{*}, which calculates the Relative Standard Deviation in percentage value
  --Normal{*}, which calculates the Standard Deviation in numeric value
• Standard Deviation Threshold – When the checkbox for indicating if technical replicates have high statistical variability is checked, this parameter becomes available. This is the threshold at which the Standard Deviation Type is exceeded and the reporter is marked with a **.

1. Click Save.

caIntegrator goes to caArray, validates the information you have entered here, finds the experiment and retrieves all the sample IDs in the experiment. Once this finishes, the experiment information displays on the Edit Study page under the Genomic Data Sources section ().

• Anchor
  RTF39303336373a204361707469 RTF39303336373a204361707469

  Genomic Data Sources section of the Edit Study page

1. If you want to redefine the caArray experiment information, you can edit it. Click the Edit link corresponding to the Experiment ID. The Edit Genomic Data Source dialog box reopens, allowing you to edit the information.

...

...

Mapping Genomic Data to Subject Annotation Data

genomic data:mapping to subject annotation data;study:mapping genomic data to subject annotation;mapping genomic to subject annotation dataBecause Because the goal of caIntegrator is to integrate data from subject annotation, genomic and imaging data sources, data from uploaded source files must be mapped to each other. Mapping files can map to caArray genomic data of two types: "imported and parsed" and that stored in supplemental files. AnchorRTF35393935313a204865616469RTF35393935313a204865616469

Creating a Mapping File

You, as the caIntegrator study manager, must create a Subject to Sample mapping file before following the actual mapping steps. This file provides caIntegrator with the information for mapping patients to caArray samples.

1. Start with the 6-column mapping file template, described as follows:

• * All platforms – Raw (level 1) data cannot be mapped; only normalized, processed (level 2) data is acceptable.
• The required six-column file format uses the following columns:
• Subject ID
• Sample ID
• Name of supplemental file (if appropriate, as attached to the experiment in caArray)
• Probe Header – Name of column header (in the supplemental file) which contains the probe IDs.
• Value Header – Name of column header (in the supplemental file) which holds the level 2 data.
• Sample Header – Name of column header (in the supplemental file) which holds the level 2 data.
• Only one of the last 2 columns is used: a single sample per file uses the Value Header column; multiple samples per file used Sample Header column. Unused columns are blank.

...