.. include:: imagerefs.txt .. _Traits: ====================== Trial Manager - Traits ====================== *Traits* are used in KDSmart to record (score) traits for trials and nurseries. Traits are usually phenotypic information although this is arbitrary. It is best to manage these traits from Trial Manager in KDXPlore because it serves as a central point of management, however, traits can also be managed in KDSmart. Traits can be defined with validation rules to facilitate strict data capture rules to assist in preventing recording errors. These rules can also be utilised to also make scoring more efficient by minimising the required keystrokes. The **Traits Tab** (pictured below) provides a list of all available traits and options for management of traits including importing and exporting. |br| .. only:: html |center-start| .. thumbnail:: images/TrialManager/TrialManager22.png :width: 100% :show_caption: True :alt: Traits Tab :title: Traits Tab (select to zoom) |center-end| .. only:: latex .. figure:: images/TrialManager/TrialManager22.png :scale: 100 % :alt: Traits Tab Traits Tab |br| What is a Trait? ================ Traits are the quality or characteristic being inspected, measured and recorded for the organism. Within KDSmart, traits have the following characteristics and features: - User definable; - Defined by six different data types; - Optionally lockable once scored to prevent accidental change; - Importable and exportable; - Can be grouped into bundles for easier management; and - Are either plot level or sub-plot level. A measurement is stored for each trait instance in each plot or sub-plot includes the: - Date and time when the measurement was taken; - GPS coordinates (if this is enabled); and - Value of the measurement. Some examples of traits include the height of a plant (this might be called :brown:`Plant\_Height`) or the date that a plot was irrigated (which could be called :brown:`Irrigated`). |br| .. _Trait Attributes: Trait Attributes ---------------- Each trait contains a set of attributes that define its characteristics. The following table lists the attributes of a trait: .. list-table:: Trait Attributes :widths: 18 70 :header-rows: 1 * - **Attribute** - **Description** * - **Trait Name** - Must be *unique and short* for display in the **Scoring Screen** where space is limited on smaller devices (i.e. phones). * - **Alias** - An alternative trait name, useful when the trait name is too long for the screen. * - **Description** - This is an optional longer explanation of the trait to assist in data entry. * - **Data Type** - Constrains permitted values of traits. The types available are: - CATEGORICAL; - DATE; - ELAPSED_DAYS; - INTEGER; - DECIMAL; - TEXT; and - CALC. For details refer to `Trait Data Types`_ * - **Unit** - An arbitrary term for the *unit* of the trait to assist with what value to enter when scoring (e.g. measurement in millimetres or centimetres). * - **Validation Rule** - The validation rule optionally restricts the values being entered. The nature of the rule is dependent upon the selection of a data type. .. note:: Unless specified in the CSV, traits loaded to KDSmart from CSV default to the *TEXT* data type. If the trait already exists and is not yet scored unless they have previously been loaded or defined. Once loaded you may edit the trait definition to define its data type etc. .. _Trait Data Types: Trait Data Types ---------------- The following table describes the available data types for traits: .. tabularcolumns:: |\Y{0.2}|\Y{0.2}|\Y{0.2}|\Y{0.2}| .. list-table:: Trait Data Types :header-rows: 1 :class: longtable * - **Data Type** - **Description** - **Data Entry Style** - **Example Validation Rule** * - **TEXT** - No constraint on what may be entered. - A text input field with a full keyboard. - No rule required. * - **CATEGORICAL** - Value is constrained to be one from a list of allowed values. |br| Translations to other languages are supported. - A list of the allowed values is presented and the user touches the value desired. - Example: |br| :orange:`CHOICE(BLUE|YELLOW|RED)` |br| There must be at least two values provided in the pipe separated list (such as in the example above). |br| In a later release, the format will support providing a description for each value. This will likely be of the form |br| value:description |br| To prevent future problems you should not use the colon (:) character in any current value. * - **DATE** - Value is a date. - A calendar is presented from which to choose a date. - May be left blank or specified as :orange:`date`. * - **ELAPSED_DAYS** - Value is the number of days since the trial’s planting date. |br| The range in the calendar is constrained by the start date and an optional upper limit. |br| KDSmart stores the values as a date but presents the value as a number when required. - A list of days around the current date are presented and the user selects the desired value or chooses ':orange:`Other`' to use a calendar to pick a date outside this range. |br| The choices in the list (:orange:`-3d, -2d, -1d, Today, +1d, +2d, +3d`) may be presented in different languages depending on locale support. - May be left blank or specified as |br| :orange:`elapsed_days`. |br| To enforce a maximum value, use: |br| :orange:`elapsed_days_max=NNN`. * - **INTEGER** - Integer numeric values in a range specified. |br| The range is specified as a lower and upper bound and whether or not the bounds are included in the range. - If the number of values is 'small' then the entry is similar to the categorical data type. Otherwise, a numeric keypad is presented (excluding a decimal point key). |br| The changeover from categorical style to numeric keypad may be altered in the **Settings Screen**. |br| For Example: :orange:`RERANGE(1..5)` presents as a list of choices: :orange:`1,2,3,4` but :orange:`RANGE(1..500)` presents a keypad. - Specify the range of values as: |br| :orange:`RANGE(min..max)` |br| or use `LERANGE, RERANGE, BERANGE` to exclude the left, right or both limits respectively. |br| |br| Example: :orange:`RERANGE(-1..5)` |br| means the accepted values are |br| -1, 0, 1, 2, 3, 4 |br| |br| **Note:** If you use a custom keyboard, this may affect the appearance of the numeric keypad. * - **DECIMAL** - Specify a lower and upper bound and whether or not the bounds are included in the range and the number of digits of precision that will be recorded. - Entry is done using a numeric keypad that includes the decimal point. |br| NOTE: If you use a custom keyboard, this may affect the appearance of the numeric keypad. - :orange:`RANGE(min..max)` |br| or use :orange:`LERANGE, RERANGE, BERANGE` |br| However, min and max must now contain a decimal point and at least one digit following the point. |br| So: :orange:`BERANGE(1.0..2.99)` |br| means accept values for x where :orange:`1.00 < x < 2.99` |br| (the greater number of digits after the "." for min/max is the "precision" desired). * - **CALC** - Calculated or Derived Trait. |br| |br| See `Calculated or Derived Traits`_ below for further description. - Data entry is not permitted for this type. |br| |br| Traits with this data type **cannot** be scored during data collection. - A simple calculated or derived trait is: |br| :orange:`CALC( max(PH_CM/5,1) )` |br| This calculation references a trait named :orange:`PH_CM`, dividing the value by 5 and returning the maximum of the division or :orange:`1`, whichever is the greater. So a value of :orange:`17` for :orange:`PH_CM` gives a result of :orange:`3`. |br| Alternatively, |br| :orange:`CALC( max(PH_CM/5,1) , 1 )` |br| will retain the result with one decimal place. |br| In this case the value of :orange:`17` for :orange:`PH_CM` results in :orange:`3.4`. |br| .. _Calculated_or_Derived_Traits: Calculated or Derived Traits ----------------------------- The validation rule has either one or two components (with a comma separating them if required): - The first component provides a formula that may reference other traits (by the trait name), using the operators and functions listed below. - If present, the second component indicates the number of decimal digits to retain in the computed result. The functions available are in a table below. Arithmetic operators are: :orange:`* / %` (the last is the **modulo** operation) |br| :orange:`+ -` (unary minus is also supported) |br| :orange:`^ **` (for exponentiation). .. Note:: The comparison operators: :orange:`< <= = != > >=` and the logical operators: :orange:`&& ||` evaluate to either :orange:`1` or :orange:`0` representing **true** or **false** respectively. This is relevant for the :orange:`if(cond,a,b)` function. |br| Functions Available For CALC Data Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following table describes the functions available for the CALC data type. .. tabularcolumns:: |\Y{0.2}|\Y{0.4}|\Y{0.4}| .. list-table:: Functions Available For CALC Data Type :widths: 5 40 40 :header-rows: 1 * - **Function Name(s)** - **Description** - **Example** * - :orange:`sin cos tan asin acos atan` - **Trigonometric functions** - * - :orange:`sinh cosh tanh` - **Hyperbolic functions** - * - :orange:`abs round floor ceil sqrt exp ln log sign` - **Unary mathematical functions:** |br| ROUND, FLOOR and CEIL return an integral portion of the input. |br| LN is the natural logarithm |br| LOG is the logarithm to base 10 - :orange:`round(1.5)` returns 2.0 |br| :orange:`round(1.4)` returns 1.0 |br| :orange:`floor(1.5)` returns 1.0 |br| :orange:`ceil(1.5)` returns 2.0 * - :orange:`pow min max` - **Binary mathematical functions** - :orange:`pow(2,3)` returns 8.0 |br| :orange:`pow(3,2)` returns 9.0 * - :orange:`rnd deg(radians) rad(degrees)` - **Other functions:** |br| :orange:`rnd(a)` returns the value of a multiplied by a random number satisfying the constraint :orange:`RERANGE(0..1.0)` i.e. a value :orange:`x` where: :orange:`0.0 <= x < 1.0` |br| :orange:`deg` and :orange:`rad` convert between degrees and radians. - :orange:`rnd(10)` will return a value :orange:`y` satisfying: |br| :orange:`0 <= y < 10` * - :orange:`if(expr , a , b)` - **Conditional expression:** |br| If the value of **expr** is **1**, the result is the expression **a** otherwise the result is expression **b** - :orange:`if(PH_CM <= 5 , 1 , 2)` |br| evaluates to :orange:`1` if the value of the trait :orange:`PH_CM` is 5 or less otherwise to :orange:`2` .. tip:: Why can't I import my CALC trait?! - Ensure validation rules using comma's (e.g. CALC( max(PH_CM/5,1) , 1 )) are wrapped by double quotes (e.g. "CALC( max(PH_CM/5,1) , 1 )"). Excel handles this automatically. - Ensure the number of opening and closing brackets match (It's an easy thing to miss at a glance). - Trait names that use white spaces in their names cannot be used for derived CALC traits. |br| Categorical Traits ------------------- At times during scoring, the precision level required can vary. This may be dictated by a number of factors, e.g. sheer volume of specimens, time frame for data collection, reduced/limited people to perform the scoring, etc. In these instances, the *Categorical Data Type* may prove useful. Typically *Categorical* is used for constraining the data entered to a predefined list of values, such as the following definitions: - :orange:`CHOICE(BLUE | YELLOW | RED)`; and - :orange:`CHOICE(White | Yellow | Purple | Variegated | Brown | Orange yellow | Mottled | White top | Red | Sun red | Blue | Other)`. A *categorical other* trait is one where an *other* field can be used as a text field. .. Note:: In these examples, the pipe character ‘|’ is shown with a space character either side to improve legibility. |br| Using Categorical Traits ~~~~~~~~~~~~~~~~~~~~~~~~ In some situations using a categorical data type may be more beneficial as this facilitates the use of selection ranges instead of data entry. The following table illustrates the collection of plant height using both methods: .. tabularcolumns:: |\Y{0.2}|\Y{0.4}|\Y{0.4}| .. list-table:: Comparison Scoring Integer VS Categorical Trait Type - Required Precision 5cm :widths: 10 30 30 :header-rows: 1 * - - **Trait Defined as Integer** - **Trait Defined as Categorical** * - **Entry Method** - Plant height entered by selecting a value buttons. |br| - Plant height entered by selecting a value range from a list. |br| * - **Conditions** - Trait validation with a minimum of 5 and maximum of 50 - Trait validation with six ranges defined (e.g. The unit of measure may be 5 centimetres). * - **Validation Rule** - 5 <= x <= 50 - :orange:`CHOICE(5-10 | 10-15 | 15-20 | 20-25 | 25-30 | 30++)`. * - **Key Presses** - Minimum 2 button press per sub-plot (single digit) then **Accept Button**. - Minimum 1 button press per sub-plot, unless a long condition list requires scrolling. .. Note:: For a categorical trait, the number of choices may be limited to suit the circumstances of the trial stage. |br| Trait Management ================ Traits in Trial Manager are managed from the **Traits Tab** which is outlined in the `Trial Manager - Overview `_ page. The following actions can be performed in the **Traits Tab**. - Create new traits; - Edit traits; - Delete traits; - Bundle traits; - Import traits from a CSV file; and - Export selected traits to a CSV file. |br| Creating Traits ---------------- Traits can either be created in Trial Manager or imported. Follow the instructions below to create a new trait. |br| .. only:: html |center-start| .. thumbnail:: images/TrialManager/TrialManager23.png :width: 50% :show_caption: True :alt: Creating Traits :title: Creating Traits (select to zoom) |center-end| .. only:: latex .. figure:: images/TrialManager/TrialManager23.png :scale: 50% :alt: Creating Traits Creating Traits |br| .. list-table:: Creating Tags :widths: 1 70 :header-rows: 1 * - Step - Action * - **1.** - From the **Traits Tab**, select the |add_btn| **Add Button** and then the *Add Trait* option to open the **Edit Trait Properties Window** (as pictured in the above image). * - **2.** - Enter all trait attributes for the new trait including its name, datatype, and validation rules. The above example demonstrates creating a trait called :brown:`Plant\_height` that is measured in centimetres. See the `Trait Attributes`_ section above for more information. * - **3.** - Use the checkboxes in the **Add Trait to Bundle Panel** to add the new trait to any existing trait bundles. All new traits will automatically be added to the *All Traits* bundle. * - **4.** - Select the **Save Button** to save the new trait. .. note:: Traits can also be created in KDSmart so it is not always necessary to organise traits before exporting trials to be scored. However, a trait created on a KDSmart device will then need to be imported into Trial Manager so that other KDSmart devices can utilise the trait. |br| Editing Traits --------------- Any trait in Trial Manager can also be edited. By default, trait editing is locked to ensure data integrity. Trait editing is locked if the |lock_btn| **Lock Button** appears locked. *Double+click* the button See the below information for instruction on editing traits: |br| .. only:: html |center-start| .. thumbnail:: images/TrialManager/TrialManager24.png :width: 50% :show_caption: True :alt: Editing Traits :title: Editing Traits (select to zoom) |center-end| .. only:: latex .. figure:: images/TrialManager/TrialManager24.png :scale: 50% :alt: Editing Traits Editing Traits |br| .. list-table:: Editing Traits :widths: 1 70 :header-rows: 1 * - Step - Action * - **1.** - From the **Traits Panel**, ensure that trait editing is not locked. If it is, select the |lock_btn| **Lock Button** and to unlock editing. * - **1.** - *Double+click* a trait to be edited. This will open the **Edit Trait Properties Window**. * - **2.** - The **Edit Trait Properties Window** will be the same as when creating a trait except the trait name will be disabled as it is not possible to change a trait name. Any other trait attributes can be edited. * - **3.** - After editing all required fields, select the **Save Button**. The trait will now be updated. .. note:: Be careful with editing traits that are currently being used to score trials. |br| Deleting Traits --------------- Traits that are not needed can be deleted. One or more traits can also be deleted at once. See the instructions below for more information: |br| .. only:: html |center-start| .. thumbnail:: images/TrialManager/TrialManager25.png :width: 70% :show_caption: True :alt: Deleting Traits :title: Deleting Traits (select to zoom) |center-end| .. only:: latex .. figure:: images/TrialManager/TrialManager25.png :scale: 70% :alt: Deleting Traits Deleting Traits |br| .. list-table:: Deleting Traits :widths: 1 70 :header-rows: 1 * - Step - Action * - **1.** - From the **Traits Panel**, select one or more traits to be deleted and select the |delete_btn| **Delete Button** (as in the above image). * - **2.** - Select the *Delete Traits* option. * - **3.** - There will be a confirmation dialogue which will ask for confirmation to delete the selected trait/s Either select the **Yes Button** to confirm the deletion or the **No Button** to cancel deletion of the traits. |br| Trait Bundle Management ======================= Traits can be grouped into bundles to assist with management. Trait bundles can be created in Trial Manager and imported/exported from other devices as well. There will always be a bundle that is automatically created called *All Traits*. The image of the **Traits Panel** below contains trait bundles such as *Grapes* and *Plant dimensions*. |br| .. only:: html |center-start| .. thumbnail:: images/TrialManager/TrialManager26.png :width: 70% :show_caption: True :alt: Trait Bundle Example :title: Trait Bundle Example (select to zoom) |center-end| .. only:: latex .. figure:: images/TrialManager/TrialManager26.png :scale: 70% :alt: Trait Bundle Example Trait Bundle Example |br| See the sections below for trait bundle management. |br| Creating Trait Bundles ---------------------- The steps below are an example of how to create a new trait bundle: |br| .. only:: html |center-start| .. thumbnail:: images/TrialManager/TrialManager17.png :width: 100% :show_caption: True :alt: Creating Trait Bundles :title: Creating Trait Bundles (select to zoom) |center-end| .. only:: latex .. figure:: images/TrialManager/TrialManager17.png :scale: 100% :alt: Creating Trait Bundles Creating Trait Bundles |br| .. list-table:: Creating Trait Bundles :widths: 1 70 :header-rows: 1 * - Step - Action * - **1.** - Select the |add_btn| **Add Button** from the **Traits Panel** and choose the *Add Trait Bundle* option to open the **Add/Edit Trait Bundle Window** as pictured above. * - **2.** - To add a trait to the new bundle, either *double-click* a trait or select it with a *single-click* then select the |arrow_right_btn| **Add To Bundle Button**. *Click+drag*, *shift+click*, or *ctrl+click* to select multiple traits. * - **3.** - Enter a name for the bundle in the field at |circle1|. * - **4.** - Ensure that all necessary traits have been added and then select the **Save Button**. |br| Editing Trait Bundles --------------------- Trait bundles can also be edited to change the bundle name and add or remove traits from the bundle. |br| .. only:: html |center-start| .. thumbnail:: images/TrialManager/TrialManager28.png :width: 100% :show_caption: True :alt: Editing Trait Bundles :title: Editing Trait Bundles (select to zoom) |center-end| .. only:: latex .. figure:: images/TrialManager/TrialManager28.png :scale: 100% :alt: Editing Trait Bundles Editing Trait Bundles |br| .. list-table:: Editing Trait Bundles :widths: 1 70 :header-rows: 1 * - Step - Action * - **1.** - From the **Traits Panel**, select a trait bundle to be edited and then select the |edit_btn| **Edit Button**. This will open the **Add/Edit Trait Bundle Window** * - **2.** - To remove traits from a bundle, select one or more traits from the bundle (listed in the **Traits In Bundle Panel**) to be deleted and select the |backspace_btn| **Remove Button** to confirm the edit. * - **3.** - More traits can also be added to the bundle. To add traits, select one or more traits from the **Traits From Bundle Panel** and then the |arrow_right_btn| **Add To Bundle Button** to confirm the edit. |br| Deleting Trait Bundles ---------------------- Trait bundles that are not needed can be deleted from Trial Manager in a similar way to deleting individual traits. |br| .. only:: html |center-start| .. thumbnail:: images/TrialManager/TrialManager29.png :width: 70% :show_caption: True :alt: Deleting Trait Bundles :title: Deleting Trait Bundles (select to zoom) |center-end| .. only:: latex .. figure:: images/TrialManager/TrialManager29.png :scale: 70% :alt: Deleting Trait Bundles Deleting Trait Bundles |br| .. list-table:: Deleting Trait Bundles :widths: 1 70 :header-rows: 1 * - Step - Action * - **1.** - From the **Traits Panel**, select a trait bundle to be deleted and select the |delete_btn| **Delete Button** (as in the above image). * - **2.** - Select the *Delete Trait Bundles* option. * - **3.** - There will be a confirmation dialogue which will ask for confirmation to delete the selected trait/s Either select the **Yes Button** to confirm the deletion or the **No Button** to cancel deletion of the traits. |br|