How to Use the AlloMate Tool for Mate Allocation

Learn how to effectively utilize the AlloMate platform to manage breeding programs and optimize mate selection. This guide provides a walkthrough for uploading your data, configuring essential parameters, and downloading the finalized results.

Arlyn Ackerman
24 steps
3 minutes

Shinyapps

127.0.0.1

Launching Allomate

Navigate to <https://bi-science.shinyapps.io/AlloMate/>, this will launch the shiny.io version of AlloMate in your browser.

While using shinyapps.io is the easiest way to launch AlloMate, launching locally via R gives you the most up-to-date version and makes the best use of your device's resources, which matters most for larger datasets. To launch via R, follow the instructions under "**Installation and Running the App**" on the[GitHub page](https://github.com/Breeding-Insight/AlloMate), then return here for usage instructions.

Optional: Download Tutorial Data

Click the "Help" section in the sidebar.

Home page with help in left hand menu highlighted.

Click "Download Tutorial Data"

Download Tutorial data button highlighted

Calculate Kinship with A/G/H Matrices

Click "Matrix Builder"

Matrix Builder on the left hand menu highlighted

Click **"Browse..."** and upload genotype data as a **.csv or .txt table with one row per individual and one column per marker**.

Browse option highlighted under "upload marker/dosage file"

*Adhere to the following format to ensure the successful conversion of **G and H Matrices**:* - **Header row:** the first column holds individual IDs (any column name works). Each other column is one marker, named by its marker ID. - **Values:** numeric allele dosage, meaning the number of copies of one chosen allele. Use 0, 1 or 2 for diploids, or 0 up to the ploidy for polyploids (e.g. 0–4 for tetraploids). Count the same allele for every individual. - **Missing genotypes:** enter `NA`, or leave the cell empty in a CSV. - **Separators:** commas, tabs or spaces all work. **Before uploading, check:** - **Letter calls (AA, A/T, AB) must be converted to numbers first.** AlloMate treats them as missing and doesn't warn you. - Each individual appears only once. - The **Ploidy** box matches how your dosages are coded. - For an **H matrix**, every genotyped ID must also appear in the pedigree file, spelled exactly the same.

*Adhere to the following format to ensure the successful conversion of **A and H Matrices**:* - **Header row:** `id`, `male_parent`, `female_parent` (capitalization doesn't matter). Extra columns, such as family, are ignored. - **Every parent needs its own row.** List founders too, with both parents set to `0`. - **Unknown parents:** enter `0`. Don't use `NA` or an empty cell. - **Row order doesn't matter.** Parents can appear before or after their offspring. - **Separators:** commas, tabs or spaces all work. **Before uploading, check:** - Each ID appears in the `id` column only once. If an ID repeats, only its first row is kept. - Each parent appears in only one parent column. If an ID is a male parent in one row and a female parent in another, AlloMate can't tell its sex and treats it as an unknown parent everywhere. This includes selfs (the same ID in both columns). - The **Ploidy** box matches your species. - For an **H matrix**, IDs must match the genotype file exactly.

Click "Build Matrix" to calculate kinship.

The viewing window will show the successfully calculated A/G/H matrix.

Viewing window showing successfully calculated A/G/H matrix

Click "Download Matrix (.csv)" to download the resulting A/G/H matrix and use for subsequent processes.

Running OCS to Generate a Mating Plan

To begin performing **Optimum Contribution Selection**, click "Mate Allocation".

Home page of AlloMate with Mate Allocation highlighted

Upload Your Input Files

AlloMate requires a minimum of three input files to complete its analysis, which can be uploaded in **.csv, .tsv, or .txt** **format**: - A list of prospective **candidates** - The **pedigree** information for those candidates - **Trait** data — one file per trait Trait data performs best when supplied as estimated breeding values (EBVs)\ rather than phenotypes from a single observation window.

If you would like to experiment with tutorial data, you can download these files from the **Help** section on the sidebar.

All inputs and parameters live in the **Inputs Box** on the left side of the\ screen.

Under inputs, option of "browse" to select a file is highlighted

The **Inputs Box** is organized into four sections, top to bottom, that follow the\ order of the analysis: - **Core Data Inputs** — upload your candidate list and pedigree file, and set the maximum kinship allowed between mates. - **Weighted EBVs** — add one trait at a time, uploading an EBV file and assigning each trait a weight. - **Optimum Contribution Selection** — set your desired inbreeding rate and number of offspring, then click Run OCS. - **Export Results** — download everything as a single zip once the analysis has finished.

First, upload the prospective candidate list of viable parents. If using tutorial data, this file is [[candidates.txt]].

Browse button selected under upload list of candidates

Next, upload the corresponding pedigree file. In this scenario, we will use a pedigree file and compute an A matrix within the workflow. If using tutorial data, the file name is [[pedigree.txt]] .

Browse button highlighted under upload pedigree file

The pedigree information does not need to be subset or filtered to match the candidate list; AlloMate will automatically handle that upon upload.\ \ If your pedigree file needs to be cleaned further, see [**Familia**](https://github.com/Breeding-Insight/familia), a Breeding Insight app for pedigree validation and ancestry assessment.

Clicking "**+ Add trait**" after uploading a trait file will wipe the previous trait files that were already uploaded.

Next upload traits. First, select "**+ Add trait**" for as many traits will be uploaded.

Upload EBVs for all empty trait files. In this case we are using two traits: [[length_ebvs.txt]] and [[width_ebvs.txt]] .

Browse button highlighted under EBVs for trait 1

Upload EBVs for all empty trait files.

Browse button highlighted under EBVs for trait 2

Next upload traits. First, select "**+ Add trait**" for as many traits will be uploaded.

Add trait + button highlighted to show where to add traits

Upload EBVs for all empty trait files.

Browse highlighted showing where to load EBV file.

While trait data from a single observation window can be used, we suggest using preprocessed EBVs.

Analysis Configuration

Set the maximum permitted inbreeding rate for the prospective population.

Desired inbreeding rate adjuster button highlighted and set at 0.05

Elect a desired number of off spring.

AlloMate has multiple advanced metrics that can be activated by the check boxes. Selection can be made based off of user preference. - **Enforce per pair kinship ensures that the mating plan:** Implements mate allocation as opposed to being limited to optimum contribution selection, in other words, enforcing inbreeding rate at a mate level rather than a population level. - **Use greedy mating (browser-safe):** Greedy mating circumvents OptiSel and implements combinations that may well exceed the desired inbreeding rate while maintaining it at a population level. - **Bypass quadprog (heuristic contributions):** Eliminates most dependencies for a lightweight methodology. Results will be correct, but not as optimal with this option checked.

Results and Export

After all preferred selections have been chosen, click "Run OCS".

Some combinations of the maximum inbreeding rate and the desired number of offspring may not be attainable in a given population. In this case, update the parameters and try again.

The viewer allows the user to view kinship and predicted EBVs, as well as the mating plan in the Optimum Contribution Selection Tab.

Click "Download Results" to download all results in a cohesive zip file.

For further assistance, select the "Help Button".

Your analysis is now finished and you are ready to "allocate mates"! For additional assistance please reach out to us at [bi-science-team@ufl.edu.](mailto:bi-science-team@ufl.edu)

How to Use the AlloMate Tool for Mate Allocation

Arlyn Ackerman
24 steps
3 minutes

Shinyapps

127.0.0.1

Launching Allomate

Navigate to <https://bi-science.shinyapps.io/AlloMate/>, this will launch the shiny.io version of AlloMate in your browser.

Optional: Download Tutorial Data

Click the "Help" section in the sidebar.

Click "Download Tutorial Data"

Calculate Kinship with A/G/H Matrices

Click "Matrix Builder"

Click **"Browse..."** and upload genotype data as a **.csv or .txt table with one row per individual and one column per marker**.

Click "Build Matrix" to calculate kinship.

The viewing window will show the successfully calculated A/G/H matrix.

Click "Download Matrix (.csv)" to download the resulting A/G/H matrix and use for subsequent processes.

Running OCS to Generate a Mating Plan

To begin performing **Optimum Contribution Selection**, click "Mate Allocation".

Upload Your Input Files

If you would like to experiment with tutorial data, you can download these files from the **Help** section on the sidebar.

All inputs and parameters live in the **Inputs Box** on the left side of the\ screen.

First, upload the prospective candidate list of viable parents. If using tutorial data, this file is [[candidates.txt]].

Next, upload the corresponding pedigree file. In this scenario, we will use a pedigree file and compute an A matrix within the workflow. If using tutorial data, the file name is [[pedigree.txt]] .

Clicking "**+ Add trait**" after uploading a trait file will wipe the previous trait files that were already uploaded.

Next upload traits. First, select "**+ Add trait**" for as many traits will be uploaded.

Upload EBVs for all empty trait files. In this case we are using two traits: [[length_ebvs.txt]] and [[width_ebvs.txt]] .

Upload EBVs for all empty trait files.

Next upload traits. First, select "**+ Add trait**" for as many traits will be uploaded.

Upload EBVs for all empty trait files.

While trait data from a single observation window can be used, we suggest using preprocessed EBVs.

Analysis Configuration

Set the maximum permitted inbreeding rate for the prospective population.

Elect a desired number of off spring.

Results and Export

After all preferred selections have been chosen, click "Run OCS".

Some combinations of the maximum inbreeding rate and the desired number of offspring may not be attainable in a given population. In this case, update the parameters and try again.

The viewer allows the user to view kinship and predicted EBVs, as well as the mating plan in the Optimum Contribution Selection Tab.

Click "Download Results" to download all results in a cohesive zip file.

For further assistance, select the "Help Button".

Your analysis is now finished and you are ready to "allocate mates"! For additional assistance please reach out to us at [bi-science-team@ufl.edu.](mailto:bi-science-team@ufl.edu)