Tripal Cultivate Phenotypes Installation, Setup and Configuration (DRAFT)

[reynoldtan]

NOTE: A description of adding a module through Composer is available in Installation. This is an alternative, a manual installation.

Manually downloading Tripal Cultivate Phenotypes Module.

Go to Tripal Cultivate Phenotypes Module Github Repository by clicking the link below:

https://github.com/TripalCultivate/TripalCultivate-Phenotypes

1. Click on the <>Code button located in the upper right corner of the summary table, indicated as No. 1 in the screenshot above, to reveal the expanded view.

2. Choose the Download ZIP option, identified as No. 2, to start the file download. Take note of the destination directory where the file is saved, as it will be necessary for the subsequent steps. In most computers the file is save in /Downloads directory.

3. With the appropriate administrative permissions to install modules, select the Extend menu option indicated as No. 1 in the screenshot below, in your Drupal and Tripal site portal.

4. Once in the Extend page, click + Add New Module as indicated by No. 1 in the screenshot below.

5. Utilize the file upload field by selecting the browse button (No. 1 in the screenshot below) and locate the downloaded file in the file browser window (No. 2). Once you confirm the correct ZIP file, use the open button (No. 3) to load the file into the designated field. To initiate the installation of the module, click the Continue button (No. 4).

The Tripal Cultivate Phenotypes module has been incorporated into your Drupal file system and is prepared for activation at this stage.

Enable the module.

1. Click the link Enable newly added modules in the Drupal Modules Update Manager window as shown in the screenshot above (marked No. 1). This will bring you to a listing of modules shown below.

3. Scroll down to module container titled Tripal Cultivate: Phenotypes (marked No. 1) and check all 3 items

A. Phenotypic Data API
B. Phenotypic Data Collection
C. Phenotypic Data Sharing

4. Click Install button to enable the modules.

Complete! Proceed to configuration and administration pages of Tripal Cultivate Phenotypes modules.

[reynoldtan]

Configure Tripal Cultivate Phenotypes Module

Getting to configuration menu:

With the appropriate permission, click on Tripal -> Extensions menu in the top main menu as shown in the screenshot above (marked No. 1). All Tripal 4 compatible modules will be listed in this page. Locate and click the link Tripal Cultivate Phenotypes Configuration (marked No. 2) to load a detailed listing of configuration pages available.

Configuration Menu

1. R TRANSFORMATION RULES
   Tripal Cultivate Phenotypes supports R language for statistical computing by providing syntactically valid version of trait or values. Use R Transformation Rules configuration page to define standard transformation rules to apply to trait or string when converting to R version.

2. WATERMARK CHART
   Every diagram generated by Tripal Cultivate Phenotypes can be superimposed with personalized logo or text logo to ensure proper credit and indicate authenticity. Use Watermark Chart configuration to set watermarking scheme of modules.

3. ONTOLOGY TERMS
   Tripal Cultivate Phenotypes require that phenotypic traits be housed in a Controlled Vocabulary (CV) and pre-define terms used throughout the various processes. Use Ontology Terms configuration to setup terms that best support your data.

Switch to configuration pages

Navigate from one configuration to another by using the top tabs as shown in the screenshot below (marked No. 1).

---

CONFIGURING R TRANSFORMATION RULES

The R Transformation Rules configuration page simplifies the conversion of trait/terms into names compatible with R language, by emulating the language's variable names transformation methods. This is achieved by specifying words and/or special characters to exclude, along with a specific word replacement.

The configuration is preloaded with predefined values.

To update values.

NOTE: Each value must be separated by a comma symbol.

1. Enter words to remove into List of words to remove field (marked No. 1 in the screenshot above).
2. Enter special characters to remove into List of special characters to remove field (marked No. 2).
3. Enter pair of word/characters delimited by an = sign where the character in the left will be searched and replaced with the character on the right (marked No. 3)
4. Click Save Configuration button to save. Each of the three fields can be individually edited, but remember to save your changes afterwards.

---

CONFIGURING WATERMARK CHART

In Watermark Chart configuration, you can establish a configuration for watermarking charts as a means to acknowledge the data sources used in visualizations.

NOTE: Users with advanced HTML/CSS knowledge will be able to remove the watermark image. Please take additional steps to protect your data if you are concerned.

To watermark charts:

1. Under Choose which chart to watermark radio buttons, select Watermark all charts as shown by the screenshot above (marked No. 1).
2. A file field will become available to allow for upload of a watermark image file (PNG file). Click browse and navigate to the file and click open in the file browser window (marked No. 2 and No. 3).
3. Click Save configuration to set the watermark to the file. If a watermark file was previously uploaded, this will be replaced with the new file.
4. Once the file is uploaded a preview of the watermark will appear in the gray area.

TIP: Use PNG file with reduced opacity and a transparent background so as not to obstruct section of chart/graph.

To remove watermark

1. Select Do not watermark any charts under Choose which chart to watermark radio buttons.
2. Click Save configuration.

---

[reynoldtan]

CONFIGURE ONTOLOGY TERMS

The Tripal Cultivate Phenotypes module utilizes a specific set of controlled vocabulary as metadata to establish connections and determine configuration values. Furthermore, the module organizes phenotypic data based on genus and experiment.

NOTE: This module requires that Drupal/Tripal site has records in the organism table.

WARNING: Once Phenotypic Data has been uploaded for a genus, these vocabularies CANNOT be changed! Please take the time to read the descriptions below and ensure to select terms applicable in your research.

Configurre Trait Ontologies - Trait Vocabulary, Associated Database and Crop Ontology

1. Click the the title Trait Ontologyes - Trait Vocabulary, Associated Databse and Crop Ontology as shown in the screenshot above (marked No. 1).

The Trait Ontologies Configuration
Set the Controlled Vocabulary (CV), Database (DB) and Crop Ontology to be used when creating phenotypic trait, method and unit under an organism (genus).

To configure a genus:

1. Each genus will be set up to include Trait Vocabularies, an Associated Database, and Crop Ontology. The details for each configuration entry are outlined in the description area (top region), as indicated in the screenshot above (marked No. 1).
2. Genus from the organism table is presented in the summary table (marked No.2) where each configuration entry is linked to a selection box that corresponds to a specific configuration.
3. Set the Controlled Vocabulary under Trait Vocabularies column to specify the Trait, Method and Unit.
4. Set the Database selection box under Associated Database column.
5. Set the Crop Ontology selection box under Crop Ontology column.
6. Specify, for all genus configurations, whether to permit the saving of newly detected traits in the phenotypic importer or not. Setting this option to TRUE (checked) will enable data collector to include new traits, method and unit in the data file (marked No. 3).

NOTE: Setting "Allow new traits to be added during upload" option to FALSE (unchecked), a validation error will be triggered when an unrecognized trait is detected in the data file.

7. Click Save configuration button (marked No. 4) to save all configuration values for a genus.

The Controlled Vocabulary Terms - Property/Relationship Types and Measurement Metadata

1. Click the the title Controlled Vocabulary Terms - Property/Relationship Types and Measurement Metadata (marked No. 2 in the main configuration page screenshot).

The Tripal Cultivate Phenotype module comes with pre-installed Controlled Vocabulary Terms, providing predefined terms to facilitate the initiation of data collection after installation. However, the terms can be reconfigured to another term that best support your data and project setup.

WARNING: Once Phenotypic Data has been uploaded for a genus, these vocabularies CANNOT be changed! Please take the time to read the descriptions below and ensure to select terms applicable in your research.

To alter a term:

1. Ensure that vocabulary term is created in cvterm table prior to changing a value.
2. Select a field corresponding a term to modify and clear the field value.
3. Once the field is clear, begin typing the term name and inspect the terms suggested matching the characters entered so far, as shown in the screenshot below (marked No. 1).

4. When an exact match of the target term is found, click the term to set the field value.
5. Click Save configuration to save.

[reynoldtan]

NEXT

• Uploading Trait, Method and Unit in Bulk using Tripal Cultivate Phenotypes Trait Importer
• Install will create a Tripal Job - explain how to execute this job

[laceysanderson]

Starting with the first comment: #4 (comment).

Manually downloading Tripal Cultivate Phenotypes Module.

We do not want to mention the UI way to install a module as it will cause them version management issues later 🙈 So let's stick to the original composer instructions.

That said, if you want to put the current install instructions you have on their own separate page that is not in the menu and then put a link after the existing composer instructions mentioning that if they do not have command line access, here is an alternative approach but that it is not recommended as it makes keeping track of versions and straightening out dependencies during site upgrades in the future more difficult.

Enable the module.

Your instructions starting at the Enable module part are good 👍

[laceysanderson]

R TRANSFORMATION RULES
Tripal Cultivate Phenotypes supports R language for statistical computing by providing syntactically valid version of trait or values. Use R Transformation Rules configuration page to define standard transformation rules to apply to trait or string when converting to R version.

Might be more clear as:

R TRANSFORMATION RULES
Tripal Cultivate Phenotypes can transform trait names or values for easy use in R (both in R Studio or R Shiny applications) for statistical computing. Use this configuration page to define standard transformation rules to apply to trait or string values when formatting them for use in R.

[reynoldtan]

That said, if you want to put the current install instructions you have on their own separate page that is not in the menu and then put a link after the existing composer instructions mentioning that if they do not have command line access, here is an alternative approach but that it is not recommended as it makes keeping track of versions and straightening out dependencies during site upgrades in the future more difficult.

Sounds good, @carolyncaron started the composer way just need to add for collect and share (the enable part).

https://tripalcultivate.github.io/docs/docs/administration/installation

[laceysanderson]

ONTOLOGY TERMS
Tripal Cultivate Phenotypes require that phenotypic traits be housed in a Controlled Vocabulary (CV) and pre-define terms used throughout the various processes. Use Ontology Terms configuration to setup terms that best support your data.

The "pre-defined terms" part is ambiguous as it could mean that trait/method/unit terms need to be predefined. Maybe reword as

ONTOLOGY TERMS
Tripal Cultivate Phenotypes is designed to house phenotypic traits, methods and units in genus-specific Controlled Vocabularies (CV). You need to use this configuration page to set these for your genus before uploading data. You can also indicate if you want to allow insert of trait, methods and units as they are used in the phenotypic data importers or restrict insert to the Trait Importer for greater control. Additionally, we allow you to indicate the terms used to describe specific types and relationships in your data. We have default terms configured but this page also allows you to choose specific terms that best support your data.

[laceysanderson]

In the instructions for the R transformation rules config page, it would be really good to have an example to show how these rules are used. So something like:

For example, if you have a trait name "Days till 50% of plants have at least one open flower" and you want the R transformed version to be Days.50percent.1openflower then these are the transformation rules that you will need: [list them or show a screenshot].

It would also be good to add a warning note box that reminds them these rules are applied to all trait, method, unit names during transformation. So something like

{% include alert.html type="warning" title="The rules you configure here will be applied to all trait, method and unit names when formatting for use with R. As such, remember to keep them generic and more universally applicable." %}

[laceysanderson]

Note: I'm using the 👀 emoji reaction on the comment to show that I'm done with suggestions for that particular block of documentation :-)

I'm currently complete up to the end of the watermark configuration page documentation.

[laceysanderson]

The ontology term configuration could use some rewording so it's not as technical... but lets put it in the docs in it's current form as it's much easier for me to suggest small working changes once it's in code.

With that, I'm calling this review/feedback session Done ✅ Feel free to add these to the docs directly as soon as you get the chance.

Also, reminder, specialized formatting instructions are available here: https://vsoch.github.io/docsy-jekyll/docs/getting-started including the note example that I gave above to show a warning.

[laceysanderson]

@reynoldtan did these docs make it into a PR?