At any point in simulation, more genotypes can be imported from files
using the function load.genotypes. Similarly, alternative
genetic maps and additional sets of marker effects can be loaded at any
point in the simulation using load.map and
load.effects respectively.
Genetic map
files
The simplest genetic map file is formatted as follows:
marker chr pos
m3 3 15
m2 1 8
m1 1 5
Other valid genetic map files might include:
chr marker pos
1A 1243509 173.2
1A 2350898 462.2
1B 4360992 32.009
2A 1243556 243.5
or
gene 10 3.24
othergene 10 8.3e-1
etc 15 1.203e2
Note that genomicSimulation takes genetic maps, not physical maps.
Marker positions should be in centimorgans (and therefore correspond to
crossover probabilities), not physical base pair counts.
genomicSimulation will use these positions and the distances between
them when simulating
meiosis, to calculate the probability of recombination occurring
between markers.
The header line is optional. If there is a header line, any
permutation of the three columns “marker”, “chr”, and “pos” is allowed.
If the header is not provided, the order is assumed to be: marker name
in the first column, followed by chromosome in the second column,
followed by position in the third.
About the column “marker”, containing marker names: Genetic
markers should have names. These names can be entirely numeric. Though
genomicSimulation will run without visible errors if some markers share
names, this will cause issues when loading the genotype matrix:
non-unique marker names may cause intended genotype data to be
overwritten with alleles from a different marker with the same name, or
to be left blank because the intended data was placed at the wrong
marker. Therefore, it is recommended that marker names are unique.
About the column “chr”, containing chromosome/linkage group
names: any alphanumeric combination (of letters A-Z and digits 0-9)
may be used to denote a chromosome/linkage group, for example ‘9’ or
‘1A’. There is no limit on the number of unique chromosomes/linkage
groups in the map.
About the column “pos”, containing marker positions: should
be the position in centimorgans of each marker along its
chromosome/linkage group. (Distance of 1 cM = expected probability of
0.01 chromosomal crossovers in that range.)
Cells/table entries in the file may be separated by spaces, tabs,
commas, or any combination thereof. Cell spacers do not need to be
consistent across the file, but therefore marker names and linkage group
names cannot contain spaces, tabs, or commas.
The order in which genetic markers are presented in the file does not
matter.
Genotype matrix
files
The simplest genotype matrix file is formatted as follows:
name G01 G02 G03 G04 G05 G06
m1 TT TT TT TA TT AT
m3 TT TT TA TA TT TT
m2 AA AA AA AA CC AA
where G01, G02, …, are names of the founder genotypes; m1, m2, …, are
the genetic markers; and entries in the matrix are the alleles that the
founder genotypes have at those markers.
Other valid genotype matrix files might include:
m100, m101, m102
cand1,0,0,1
cand2,1,2,2
cand4,2,1,2
or
marker1 T/T T/T T/T T/A T/T A/T
marker3 T/- T/T T/- -/A T/T T/T
marker2 A/A A/A A/A A/A T/T A/A
The genotype matrix can be row-major or column-major (that is, the
genetic markers may be rows, or columns). genomicSimulation will guess
the orientation by attempting to match row and column headers with the
names of genetic markers extracted from the first genetic map file. If
the simulation does not yet have a list of tracked markers (that is, no
genetic map has been simultaneously or previously provided), then it
defaults to assuming that rows represent genetic markers.
The order in which genetic markers are presented in the file does not
matter. Candidate genotypes, however, will be saved internally in the
simulation in the order that they appear in the file.
Genetic marker names are required, whether they are row headers or
column headers. Candidate/genotype names are optional if candidates are
stored as columns, but genomicSimulation cannot read a gentoype matrix
with no row headers, so if candidates are stored as rows, they are
required to have names in the first column. Candidate names do not have
to be unique.
When there are both row and column headers, the first cell/corner
cell (the one that contained the value “name” in the first example
above) can contain any text, can be empty, or can not exist at all
(i.e. the header row can be one cell shorter than the other rows). In
any case, the corner cell is ignored.
The table cells in the genotype matrix file may be separated by
spaces, tabs, commas, or any combination thereof. Cell spacers do not
need to be consistent across the file. This does mean, however, that
candidate names, marker names, the value of the corner cell, and the
alleles in the table, cannot contain spaces, tabs or commas.
All cells in the body of a genotype matrix should use the same format
for storing allele pairs. There are four accepted formats for allele
pairs:
- Pairs of characters (eg. “AA”, “TA”, “nW”). Each character is an
allele. This is a format that specifies allele phase (ie. “AT” and “TA”
are different genotypes).
- Pairs of characters, separated by a forwards slash “/” character
(eg. “A/A”, “T/A”, “n/W”). The two characters either side of the slash
are the alleles. This is a format that specifies allele phase (ie. “A/T”
and “T/A” are different genotypes).
- Alternate allele counts (“0”, “1”, “2”). This is a format that does
not specify allele phase, so phase of heterozygotes will be randomised
when loaded. The counts represent the number of copies of the alternate
allele (stored inside genomicSimulation as “A”, while the reference
allele is stored as “T”). “0” then corresponds to “TT”, “2” to “AA”, and
“1” will be randomised as either “TA” or “AT”. Corresponding marker
effect files must use allele “A” consistently to represent the alternate
allele, and “T” to represent the reference. (alternatively,
change.allele.symbol can be used after loading to change T
and/or A to other symbols, to match a marker effect file.)
- (A subset of) the IUPAC encodings of DNA bases (“G”, “A”, “T”, “C”,
“R”, “Y”, “M”, “K”, “S”, “W”, “N”). This is a format that does not
specify allele phase, so phase of heterozygotes will be randomised when
loaded. See below for meanings of the IUPAC encoding symbols that
genomicSimulation can parse.
| G |
GG |
| A |
AA |
| T |
TT |
| C |
CC |
| R |
GA or AG |
| Y |
TC or CT |
| M |
AC or CA |
| K |
GT or TG |
| S |
GC or CG |
| W |
AT or TA |
| N |
\0\0 (nulls represent unknown genotype) |
If you have a genotype matrix of only “AA”, “AT”, and “TT”:
such a matrix uses “alternate allele counts”-style encoding (like format
3) but presents it in a format that looks like pairs of alleles (format
1). genomicSimulation expects allele pair encodings to include
haplotype phase, (that is, to have four possible values for genotypes of
two alleles, not three: eg. “AA”, “AT”, “TA”, and “TT” instead of just
“AA”, “AT”, “TT”). To load a dataset with non-phased “AA”/“AT”/“TT”
allele pairs, you might:
- Use haplotype phasing/haplotype inference software to infer whether
heterozygotes are “AT” or “TA”, before loading into
genomicSimulation.
- Find-and-replace “TT” with “0”, “AT” with “1”, and “AA” with “2”
before loading into genomicSimulation. genomicSimulation will then
randomise the phase of each genotype.
As may be clear from these accepted input formats, every genotype in
genomicSimulation has exactly two alleles at each marker - that is,
genomicSimulation simulates diploid genotypes.
An allele in genomicSimulation can be represented by any single
character. Specifically, this means any value that can be stored in a
char from the C programming language (one byte).
An allele can be a letter, but can also be a digit, a punctuation
mark, or an unprintable control character. Via calling
change.allele.symbol after the file is loaded, an allele
can even be a space, comma, tab or newline character (even though these
are not permitted as alleles in the input file and would make for
strange-looking output files).
This means SNP markers can be represented with the two alleles 0 and
1, or A and T, etc., according to your preference. On the other end of
the spectrum, a marker could also represent an abstracted Mendelian gene
with alleles, say, A, a, t, +, and o.
If you have missing data in your input dataset, you choose how to
represent the missing alleles in the genotype file (the letter ‘N’? the
dash ‘-’? the null character?). “Missing” alleles function identically
to other alleles, and will propagate through the generations just like
other alleles. Therefore, offspring genotypes can inherit an
unknown/missing allele from a parent.
If the format of the genotype matrix input file is detected
incorrectly by genomicSimulation, the optional format
parameter of load.data or load.genotypes can
be used to specify the correct format (see Incorrect File Format
Detection).
Marker effect
files
Loading marker effect file(s) is optional for running the simulation.
There is no need to provide marker effects if genetic breeding values
are not going to be used. The simplest marker effect file is formatted
as follows:
marker allele eff
m1 A -0.8
m2 A -0.1
m3 A 0.1
m1 T 0.9
m3 T -0.1
Other valid marker effect files might include:
marker eff allele
m1243509 0.1 A
m1243509 -0.1 T
m2350898 0.15 T
m2350898 -0.1 A
or
specialgene G 1.0
One marker effect file represents the contributions/effects of
alleles on one trait. Multiple marker effect files can be loaded to use
each to represent a different trait.
The header line is optional. If there is a header line, the three
columns “marker”, “allele”, and “eff” can appear in any order. If the
header is not provided, the order is assumed to be marker name in the
first column, followed by allele, followed by additive effect value.
The order of the rows in the file does not matter. If multiple rows
exist in the file for the same marker name/allele combination, only the
last row’s additive effect value will be saved.
About the column “marker”, containing marker names: Rows
whose marker name does not match a marker name from the primary
(first-loaded) map will be skipped and ignored.
About the column “allele”, containing the symbol representing an
allele: This column should be the allele (a non-space, non-tab,
non-comma character, eg “A”).
About the column “eff”, containing the marker effect of this
allele: This column should be a decimal representing the additive
effect value of carrying one copy of the same-row allele for the
same-row marker. It can be positive or negative or zero, and can be
represented by a decimal, a whole number, or scientific notation.
Cells may be separated by spaces, tabs, commas, or any combination
thereof. Cell spacers do not need to be consistent across the file.
