Project Data Entry: Introduction to Interactive Reader Creation Tool

Last Updated: Apr 03, 2019 02:36PM PDT

Summary: An introduction to using the ScienceCloud Project Data Entry interactive reader creation tool.

Covered Topics

The following topics are covered in this article. Clicking a link will scroll the page to the relevant section.


The interactive reader creation tool enables you to define custom readers that will read and interpret you chemistry and assay result registration files. Specifically, if you have registration files that utilize consistent field headers, creating a reader will enable you to map your registration file's fields to ScienceCloud fields so that ScienceCloud can interpret your data. You only need to create the reader one time, after which you can register data from registration files with the same fields, without having to spend time converting every file to utilize ScienceCloud naming conventions in each field header.

The reader that you create will be available for use to all members of your current ScienceCloud team. Only the original creator of a reader can modify or delete that reader. Other team members can use that reader or create a new reader from your reader.

There is no limit to the number of readers that you may create.

How to Access

For chemistry:
  1. From the ScienceCloud home page, go to Project Data Entry.
  2. Click the Register entities link.
  3. Click the From file link.
  4. Next to the Reader menu, click on Interactive Reader Creation.

For assay results:

  1. From the ScienceCloud home page, go to Project Data Entry.
  2. Click the Add data to entities link.
  3. Click the From file link.
  4. Next to the Reader menu, click on Interactive Reader Creation.

Create a Reader

To create a new reader, after clicking on the Interactive Reader Creation link you will see under the header "Upload Registration File Template" a Choose File upload button (ignore the Choose Reader menu - which is only visible when your ScienceCloud team has existing readers) menu unless you want to create a new reader from an existing reader). From your computer, select an Excel file that you can use as a registration file template for a custom reader. Be careful to use a registration file template with fields that you will use consistently in all the registration files that you will use to register data to ScienceCloud using this new reader.

After your registration file template is uploaded and you click the Continue button, the interactive reader creation tool will read your registration file template's fields and display them as column headers, which you can then map to the appropriate ScienceCloud field selected from a menu of choices. If any of the registration file template's fields already match the name of a ScienceCloud field, that registration file template field will be automatically mapped to the ScienceCloud field. You can change that field's mapping if desired.

Every field in your uploaded registration file template must be mapped to some ScienceCloud field, or mapped to **ignore**. Any field mapped to **ignore** will be disregarded when you upload registration files using this reader. Additionally, if you upload a registration file to ScienceCloud Project Data using this reader and your registration file has fields that were not mapped when creating the custom reader, those fields will be ignored.

With the exception of **ignore** and custom property fields, ScienceCloud fields cannot be selected more than once for any one result set. Result sets are explained in the next section, and are applicable only to assay result readers.

To save your reader, type a name in the Reader Name field. The reader name must be unique within your ScienceCloud team. If you select the Overwrite an existing reader instead checkbox, you can choose from a list of existing readers that you have previously created (if you have created any previously), and your new reader will overwrite the existing reader that you select.

Optionally, type a Purpose and Description for your reader: this information will be displayed when users select your reader and click the Information link.

Result Sets Explained

Custom readers for chemistry (entities) can process flat files: one batch per row of your registration file. Custom readers for assay result registrations can process files that contain result sets: multiple result sets per row. For example, if you have a registration file template in Excel format with one batch per row and multiple assay results per row, each assay result can be considered a result set. When creating a custom reader using the interactive reader creation tool, you can configure the reader to recognize which field identifies a result set. For each result set, you can specify what are the assay result objects for each result set, such as: assay, assay paramater, result type, test unit, dose, dose unit, timepoint, timepoint unit, test date, screener, trial ID, and group ID.

In the example above, there are two rows in the registration file: two batches. The NUM_VALUE field records the assay result value from testing IC50 of fibroblast toxicity. Each row has two other assay results to account for: the fields "Chagas - TcruziLacZ Score" and "Edema". Three assay results per row is the equivalent of saying there are three result sets per row of this registration file.

Result Set "All" Explained

When creating a custom reader, your registration file template's fields are mapped by default to result set "All". This means that the mapping will apply to all records in your registration file (unless overridden later by default values specified for specific result sets, explained in the next section).

For example, if your registration file has a field "assay_name" which maps to ScienceCloud field "assay_name", and your reader is configured to keep Result Set = "All" for field "assay_name", then the assay identified in the assay_name field of your registration file for each row will be applied to all result sets in that row: whether there is only one result set or whether there are several result sets.

If your registration file template has more than one result set on any row, you must utilize changing the Result Set to some unused number for the field in which the assay result value is stored (you do not have to use Result Set 1 for the first result set and number result sets sequentially, but doing so makes your reader easier to understand). For example, in the registration file template shown in the previous screenshot where there were up to three result sets per row, you must associate the field pertaining to the first result set with a Result Set number not already in use: perhaps Result Set 1 for the first result set, Result Set 2 for the second result set, and Result Set 3 for the third result set.

Enforcing Default Values

You can configure and enforce default values for assay result data properties, even if those properties do not have a corresponding field in your registration file. Default values are configured on result sets in the "Defaults for Result Sets" section of the interactive reader creation tool.

For example, if you want to specify that the screener was yourself for all the assay results you are uploading, in the row for Result Set "All" you would choose your username from the Screener menu.

If you want to specify a default for a specific result set, you would make a selection in the row for the appropriate Result Set number. Using the example of the registration file shown in a previous screenshot, if you did not make any default value selections for result set 2 (field "Chagas - TcruziLacZ Score" in your registration file template), that second result set would be associated with the assay identified in the file's assay_name and assay_type fields, the assay parameter identified in the assay_parameter_name and assay_parameter_description fields, and the assay result identified in the file's assay_result_type_name field. To associate the assay result in result set 2 with the Chagas in vitro assay, an assay parameter "T. cruzi", and result type Score, select those values from the menus in the row for Result Set 2 in the "Defaults for Result Sets" section.

In the following screenshot, those values have been selected for Result Set 2. Additionally, for Result Set 3 (mapped to registration file field "Edema") an assay, assay parameter, and result type have been selected. Result Set 1 does not have any default values selected, and therefore will utilize the assay from the the registration file's assay_name field that was mapped to Result Set "All" in the Map Fields section.

Default values configured for a ScienceCloud property for a specific Result Sets other than "All" will always override any default values configured for Result Set "All" and will override any values for that same ScienceCloud property coming from your registration file if that ScienceCloud property was mapped to a field in your registration file.

The menus in the "Defaults for Result Sets" section are populated based on your ScienceCloud team's dictionaries. For example, if you select an assay from Assay menu, the Assay Parameter menu will be re-populated showing only the assay parameters associated with the chosen assay in your ScienceCloud team's assay dictionary.

Help From Tooltips

Most elements on the interactive reader creation page have tooltips, which display helpful information about the element if you hover over that element with your pointer.

How To Modify an Existing Reader

To modify an existing reader, go to the interactive reader creation tool and select from the Choose Reader menu the reader you wish to modify from the Choose Reader menu. You can only modify an existing reader if you were the original creator of that reader.

If you wish to modify an existing reader with a new registration template, upload your registration file template and then click Continue.

The next screen will pre-populate the Map Fields section and the Default for Result Sets section with the mappings and defaults already existing on the reader.

After making the desired changes to the field mappings and the default values, in the Reader Name section select the Overwrite an existing reader instead checkbox, which will automatically populate the Reader Name field with the reader that you chose in the first step. Click the Save button.

If you had not selected an existing reader at the first step and were instead creating a fresh new reader, you could still choose to update an existing reader by selecting the Overwrite an existing reader instead checkbox and choosing the existing reader name from the Reader Name menu.

How To Build a New Reader From an Existing Reader

To build a new reader from an existing reader, the process is the same as for modifying an existing reader with the exception that instead of selecting the Overwrite an existing reader instead checkbox, you will type in a Reader Name that is not already in use in your ScienceCloud team, and then click the Save button.

Next Steps

After a custom reader has been created, the reader can be used from the Project Data Entry application. In any of the "From File" registration options, you can upload a registration file with the data to be registered and choose the appropriate custom reader from the Reader menu.

When you select a custom reader from the Reader menu, several helpful links will appear next to the Reader menu:

  1. Information: click this to view the reader's purpose and description, and to see the field mappings and any default values and result set information.
  2. Download Template: click this to download a template pre-populated with fields identified in the reader's field mapping. If you did not already have a registration file populated with data, you can populate your data into this downloaded template and then upload the file in the Registration File field.
  3. Delete Reader: if you are the creator of the chosen reader, you will see this link which enables you to delete a custom reader.
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found