Open reynoldtan opened 5 months ago
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
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.
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.
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.
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:
TIP: Use PNG file with reduced opacity and a transparent background so as not to obstruct section of chart/graph.
To remove watermark
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
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:
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.
The Controlled Vocabulary Terms - Property/Relationship Types and Measurement Metadata
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:
NEXT
Starting with the first comment: https://github.com/TripalCultivate/docs/issues/4#issue-2089066218.
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 š
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.
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
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.
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." %}
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.
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.
@reynoldtan did these docs make it into a PR?
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
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.
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.
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.
The Tripal Cultivate Phenotypes module has been incorporated into your Drupal file system and is prepared for activation at this stage.
Enable the module.
A. Phenotypic Data API B. Phenotypic Data Collection C. Phenotypic Data Sharing
Complete! Proceed to configuration and administration pages of Tripal Cultivate Phenotypes modules.