Help center

How to format your phenotype file (three layouts)

The three phenotype file layouts CacaoIQ reads, and the columns each one needs.

Your phenotype file doesn’t have to match a fixed template. CacaoIQ finds the header row, suggests what each column is, and you confirm or change every column role before anything runs.

Prerequisites

  • A CSV file or an Excel workbook (.xlsx) with one header row. In a workbook with several sheets, you choose the sheet at upload.
  • One column that identifies each tree (or clone or accession). Two if your trial has several trees per clone (see below).
  • One column per trait, holding numbers or scores.

Step 1: Pick one of three layouts

Layout A: one row per tree

One row per tree, clone or accession. CacaoIQ uses it as it is.

Tree Block pod_count wb_index
T001 1 24 2.5
T002 1 31 1.0

Layout B: one row per record, with a Year column

One row per tree and year (often called long format). The Year column is recognized and fitted as a fixed effect, so differences between year means are removed. Several years of one tree are repeated measurements of that tree.

Tree Year Block pod_count
T001 2022 1 18
T001 2023 1 24
T002 2022 1 27
  • Harvest-period labels such as 2017-I, 2016-II, 2017 A or 2016/17 in a Harvest, Season or Year column also work. Each period is a level of the time effect, so main-crop and mid-crop means are adjusted for.
  • If your main crop runs across the new year (for example October to March), add a Year column holding the crop year. A Year column is always used before a date.
  • Two rows of one tree in the same year, with no Month or Date column, are treated as replicates (for example several trees of one clone). The data check says so.

Layout C: one column per year

One column per trait and year, with names such as yield2018, yield_2018, yield.2018 or 2018_yield.

Tree Block yield2018 yield2019 yield2020
T001 1 1.8 2.4 2.1

CacaoIQ notices that these columns look like one trait measured in different years and offers to combine them as one trait (the box is ticked by default). Combined, the trait has one record per tree and year, with the year as a fixed effect. Untick the box to analyze each column as a separate trait.

Step 2: Add monthly records only if you have them

A Month or Date column (Excel dates included), or columns such as yield_Jan2019 or yield_2019_01, are fine. When a tree has several records in one year, the data check asks how to combine them for each trait:

  • Sum: the year’s total, suggested for counts and yields (pods harvested, kg wet beans per tree).
  • Average: a typical value, suggested for sizes, scores and indexes (pod length, bean weight, a disease index).
  • Ratio of sums: for a percentage or ratio whose counts are in the file (% infected pods, pod index).
  • Keep separate: the records stay as they are; the results carry a caution.

Confirm the choices with Use these choices before running.

A file with only a Month column (no year) stops the run with an explanation. Add a Year column. Each date column is read with one date order for the whole column; check the order CacaoIQ shows in the column mapping.

Step 3: Set up clonal trials with several trees per clone

Give the clone and the tree their own columns, and mark both as Identifier. The ramets of a clone are then replicates of that clone. In Gene Discovery, the models use the ID column that matches your genotype file; the run panel says which one. In Phenotypic Modeling, choose Clonal copies to get broad-sense H².

Step 4: Mark the design columns

  • Block, replicate, plot and field columns are trial-design factors: tick Trial-design factor (adjust for it) in the column mapping. It is ticked automatically only when the column name clearly says block, rep, plot or field.
  • Row and column positions get the role Field position.
  • Leave plant traits such as pod shape or a flower-color score unticked. Adjusting for a plant trait would remove real genetic signal.
  • A Treatment or Site column is analyzed one level at a time, each in its own run. Differences between treatments or sites are not tested in this version.

Step 5: Code missing values clearly

  • Leave the cell empty, or use a common code: ., -, NA, N/A, NaN, NULL, missing, none, no data, sin dato. In a column of numbers, ND, NR and SD are read as blank too. The data check lists every code it found.
  • Score a dead or missing tree as a blank cell (or a word such as dead), never as 0. A typed 0 looks like a real measurement.
  • Values such as -9999 are left out by default; the data check lists them, and you can untick them. Other unusual values (-9, 999, values far from the rest) are listed in the data check with the trees they are on, so you can decide.
  • Optionally, set a plausible range for each trait under Change column roles (for example Percentage 0 to 100) to catch typing slips.

Before you upload: checklist

  • One header row, and IDs written the same way as in your genotype file. See Fix: tree IDs don’t match between phenotype and genotype files.
  • Each trait in its own column, with numbers only. Text in a number column (such as dead or lost) is read as missing.
  • A Year column if your records come from several years.
  • Measurements recorded as whole numbers with many different values (height in cm, harvest day) are currently analyzed as counts. See Known issue: whole-number traits read as counts.
  • Decide whether each trait is a raw measurement or already a BLUP. See Should I upload raw measurements or BLUPs?

Check that it worked

After Confirm columns and check data, the data check shows identifier issues, blank-cell codes it recognized, negative values and outliers, and strongly skewed traits with a suggested transform. Nothing is dropped or changed unless you accept it, apart from the codes listed as left out by default, which you can untick. Each run’s README lists what was left out.

Not supported in this version

  • Several sites or treatments in one model (genotype × environment, treatment tests).
  • The month as its own effect in the model (it is only used to combine records within a year).
  • Splitting a harvest-period label into year and period.
  • A random year effect, or pedigree-based models.

Still stuck? Write to support@scilytics.ai with your system and what you see on screen. Don’t attach data files. The first reply comes within 2 business days.