File: xmlinput.html

package info (click to toggle)
lamarc 2.1.10.1%2Bdfsg-3
links: PTS, VCS
area: main
in suites: buster
size: 77,052 kB
sloc: cpp: 112,339; xml: 16,769; sh: 3,528; makefile: 1,219; python: 420; perl: 260; ansic: 40
file content (1166 lines) | stat: -rw-r--r-- 56,635 bytes
parent folder | download | duplicates (3)
<!-- header fragment for html documentation -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>

<META NAME="description" CONTENT="Estimation of population parameters using genetic data usi
ng a maximum likelihood approach with Metropolis-Hastings Monte Carlo Markov chain importanc
e sampling">
<META NAME="keywords" CONTENT="MCMC, Markov chain, Monte Carlo, Metropolis-Hastings, populat
ion, parameters, migration rate, population size, recombination rate, growth rate, maximum likelihood">

<TITLE>LAMARC Documentation: XML data description</title>
</HEAD>


<BODY BGCOLOR="#FFFFFF">
<!-- coalescent, coalescence, Markov chain Monte Carlo simulation, migration rate, effective
 population size, recombination rate, maximum likelihood -->

<P>(<A HREF="converter_cmd.html">Previous</A> | <A
HREF="index.html">Contents</A> | <A HREF="menu.html">Next</A>)</P>

<H2>XML Input Format for LAMARC</H2>

<P> You will probably not need to directly look at or edit LAMARC's XML
input files, because these are generated for you by our file conversion
programs.  However, in rare cases, you may need or want to write or edit
these files by hand.  Here is the necessary information for doing so.</P>

<P> We are not currently supporting all the nice abilities that would
really justify using XML, but we hope to do so in the future.</P>

<P> <B>Please</B> be careful not to save the XML file in Microsoft Word or
another word processor format.  This will fill it with invisible
editing characters, and it will not work.  Always use the "save
as plain text" option of your word processor.  If a previously
successful input file stops working, check whether you
have accidentally saved it as formatted text.  This is the #1
cause of input-file problems in both PHYLIP and LAMARC today.</P>

<P> Also, be aware that some word processors (including at least
one version of MS Word) will automatically parse XML text, reducing your
input data file to a disorganized heap of data.  If this happens,
you can try giving your file an extension of .txt.  If that doesn't
work, we have no suggestions other than using a different word processor. </P>

<H3> Index</H3>

<UL>
<LI><A HREF="xmlinput.html#overview">Overview</A></LI>
<LI><A HREF="xmlinput.html#data">Data Section</A></LI>
<LI><A HREF="xmlinput.html#datamodel">Data Models</A></LI>
<LI><A HREF="xmlinput.html#forces">Evolutionary Forces</A></LI>
<LI><A HREF="xmlinput.html#chains">Chain Control</A></LI>
<LI><A HREF="xmlinput.html#options">User Options</A></LI>
<LI><A HREF="xmlinput.html#mapping">Trait Mapping</A></LI>
</UL>

<H3><A NAME="overview"> Overview:</A></H3>
<P> XML is a very simple minded language, so you have to be methodical as it is easily confused. Best approach is to start with a functioning script, either the one generated for you by LAMARC or one of examples included in this web site. (If you find one that doesn't work, <A HREF="MAILTO:lamarc@u.washington.edu">
please tell us</A>. We've tested them, but they're easily broken.) Starting from an appropriate script, incrementally modify it to your needs, testing as you go.</p>

<p>Looking at our examples, you'll note that each level of tag is indented 4 spaces further than the next higher level tag. This not required by the XML compiler (it ignores all those spaces) but is invaluable when trying to debug a malfunctioning script. <u>We highly recommend</u> you follow this convention. It will save you many hours of pain (don't ask how we know that :-).  One thing to particularly avoid is XML that is indented differently from its meaning. This leads to exceptionally hard-to-find errors. </p>

<p>If you are unfortunate enough to start with an XML script that is not properly indented, it is worth your time to go through and indent it properly. Not only will you understand it better, the indenting it will make modifications much easier.</p>

<p>Each bit of information in the input file is surrounded by
a beginning and ending tag.  For example, the whole input
file is surrounded by &lt;lamarc&gt; and &lt;/lamarc&gt;, and the data
section is surrounded by &lt;data&gt; and &lt;/data&gt;.  Tags must
come in &lt;tag&gt; &lt;/tag&gt; pairs and must be strictly nested, so
these are legal:</P>

<P> <font color="#0000FF">&lt;blue&gt; </font> <font color="#FF0000">&lt;red&gt; &lt;/red&gt; </font> <font color="#0000FF">&lt;/blue&gt;</font></P>

<P> <font color="#FF0000">&lt;red&gt; &lt;/red&gt; </font><font color="#0000FF"> &lt;blue&gt; &lt;/blue&gt;</font></P>

<P> but this is illegal:</P>

<P><font color="#0000FF"> &lt;blue&gt; </font><font color="#FF0000">&lt;red&gt; </font><font color="#0000FF">&lt;/blue&gt; </font><font color="#FF0000">&lt;/red&gt;</font></P>

<P> The symbol "&lt;!--" starts a comment, and the symbol "--&gt;" ends
it.  Anything inside a comment is ignored.  You can use comment
symbols to temporarily remove parts of your input file that you
don't want, as long as what remains is legal.  </P>

<P> Some tags require additional information, such as the name of
a population.  This is done with "attributes":</P>

<P> &lt;population name="Washington DC"&gt;</P>

<P> The quotes are required.</P>

<H3><A NAME="data"> Data section </A></H3>

<P> The data section contains your actual molecular data, and additional
information used to interpret it.  It is required to be present,
and is enclosed in &lt;data&gt; tags.</P>

<P> LAMARC divides molecular data into "regions".  A region is all the
available genetic information that is closely linked on the same 
chromosome and has a known map.  
Use a single region for data which is one contiguous stretch, so that
it would be meaningful to calculate recombination rates along it.
Use multiple regions for data composed of several
disconnected bits or bits whose connections are not known.  Regions
are enclosed in the &lt;region&gt; tag, and at least one must be present.
The region's name can be added in an optional name attribute.</P>

<P> The optional tag &lt;effective-popsize&gt; may be used to specify
a different relative effective population size for each &lt;region&gt;.
For example, data from nuclear chromosomes of a diploid organism reflect
an effective population size four times larger than data from the
mitochondrion of the same organism. Data from sex chromosomes also have
unique effective population sizes--the relative effective population size
ratios for a non-sex chromosome to an X chromosome to a Y chromosome is
4:3:1. Be aware that the parameter estimates produced by LAMARC will be
scaled proportional to an effective population size of 1.  That is, if
you tell LAMARC that you have two regions, one with an effective population
size of 4 and one with an effective population size of 3, your final
overall estimate of &Theta; will be lowered to correspond to an
effective population size of 1.  If you are combining mitochondrial
and autosomal data in diploids into a joint analysis, set your
relative effective population sizes to 0.25 and 1, respectively,
if you want the joint &Theta; estimate to be reported using the
autosomal scale; otherwise, set these to 1 and 4, respectively,
to obtain &Theta; using the mitochondrial scale.</P>

<P> Within a region there may be several "contiguous segments."  Segments
are stretches of genetic information which are linked to one another
but need separate handling.  For instance, if we have a stretch of
DNA (modelled by a nucleotide substitution model) and an adjacent
microsatellite (modelled by a stepwise model) they need to be in the
same region as they are linked, but cannot be in the same segment as
they require different mutational models.  Information about the
relative position of segments is placed in a &lt;spacing&gt; tag.</P>

<P>  Each segment is indicated by a &lt;block&gt; tag, which can
also give information about the position of the segment itself,
and (particularly for non-contiguous markers such as SNPs and
microsatellites) the positions of the markers within the segment.</P>

<P> Within &lt;block&gt;, the &lt;length&gt; tag indicates the total length 
of the segment.  This is important for SNPs in particular
because correct interpretation of the
markers requires knowledge of how many non-markers were surveyed.
The &lt;map-position&gt; tag gives the position of this segment on
an overall map of the region.  The map position is the point at which
sequencing or scanning began, even if that is not the zero point of
your segment's internal numbering.  For example, if you sequenced
a gene from upstream position -45 to downstream position 500,
your map position should tell where position -45 is on the overall
map of the region.
The &lt;locations&gt; tag
encloses a list of marker positions within the region; for example,
the tag &lt;locations&gt; -10 7 18 22 &lt;/locations&gt; indicates
that the four markers are at positions -10, 7, 18 and 22 with respect
to the segment's numbering system.  The &lt;offset&gt; tag
gives the origin of the segment's numbering system with respect
to the boundaries of the region.  For example, if you began sequencing
at position -45 with regard to your chosen numbering system (perhaps
you have begun your numbering at a gene's start codon but obtained 
upstream sequence), your &lt;offset&gt; would be -45.  If no offset
is given, the offset is assumed to be zero.  </P>

<P> Within each region you can list various populations.  If you list
&lt;population&gt; tags under more than one region, they will be matched 
by means of their name attributes, so the names are not optional.
Use of good names here will also make your output much
easier to interpret!</P>

<a name="panel-xml">
<P> If a <a href="panels.html">SNP panel</a> was used to generate your
input data, the panel size will be specified under the &lt;population&gt; tags.
Panel members are represented as additional tips in the coalescence tree that have unknown data. 
All that is needed is the number of tips, though optionally one can name the panel. 
Here is a fragment that shows the panel correction information for one of two populations.
</p></a>
<P><PRE>
&lt;lamarc&gt;
  ...
  &lt;data&gt;
    &lt;region name="Alcohol dehydrogenase"&gt;
      &lt;population name="Seattle"&gt;
        &lt;panel name="adhpanel"&gt;
          &lt;panel-size&gt; 6 &lt;/panel-size&gt;
        &lt;/panel&gt;
        &lt;individual&gt; ... &lt;/individual&gt;
        ...
      &lt;/population&gt;
      &lt;population&gt;
        ...
      &lt;/population&gt;
    &lt;/region&gt;
  &lt;/data&gt;
</PRE>
</P>

<P> Within each population you can list various individuals.  An
individual represents all the data for that region that comes from
a single biological individual, which may be one, two, or more
sets of data depending on how you obtained your data.  For
example, an individual might consist of one mtDNA sequence, or
two nuclear DNA sequences.  Individuals can have a name attribute,
but it is optional; the &lt;individual&gt; tag itself is required.</P>

<P> Within each individual, you can have one or more &lt;sample&gt; tags
indicating the actual sequences.  For example, an individual
with one mtDNA sequence would have a single &lt;sample&gt; tag for it,
which would contain this sequence.  An individual with
two nuclear DNA sequences would contain two &lt;sample&gt; tags.
While the two sequences are treated as separate tips of the
tree, their identity as a single individual is important if haplotypes
are to be considered. </P>

<A NAME="phase"><P> Optionally, an individual can have a &lt;phase&gt; tag, indicating
uncertainty about the phase of certain sites.  For example, if you
have only genotypic data, you will want to indicate uncertainty
about the phase of all sites.  The &lt;phase&gt; tag has an obligatory
attribute, "type," which can be either "known" or "unknown."  If
the type is "known," the list of sites which follows is the list
of all sites whose phase is known, and therefore need not be 
reconsidered during the run.  If the type is "unknown," the list
which follows is the list of all sites whose phase is unknown,
and thus should be reconsidered.  A simple way to code a sequence
of genotypic data with no phase information is &lt;phase type="known"&gt; 
&lt;/phase&gt;.
It is not necessary to specify homozygous sites as to their
phase-known or phase-unknown status, as they will not be reconsidered
anyway.</P>

<P>Valid values for the phase tag are site numbers between the value of the
offset for that segment (which defaults to 1) and the length of the segment
plus the offset.  If the segment is longer than the number of markers you
have (as is the case for SNP data), valid values here are the same values
used for the 'locations' tag in the 'block' section (above).  (Note that
versions of LAMARC prior to 2.1 did not use this numbering scheme, and
instead required you to indicate the particular marker number, starting from
0, that was phased or unphased.  Old LAMARC infiles will give errors or fail
to run properly using the 2.1 system.)</P>

<P> The sequences themselves are enclosed in &lt;datablock&gt; tags,
one per segment per sample.
Currently we support DNA, RNA, SNP, and microsatellite data.
Each datablock must have an attribute indicating the type of data 
it contains.  Use type="DNA" for full DNA or RNA sequences,
type="SNP" for SNP sequences, and type="Microsat" for microsatellites.
Please do not mislabel SNPs as full DNA, because the estimates of
population size will become vastly overblown. </P>

<P> Sequence data must be aligned and of the same length for all
samples within a region.  "Unknown nucleotide" codes (X, N or -) can
be used to fill in missing or unknown sequence.  There is no point
in including individuals for whom the entire sequence is unknown,
as they add nothing to the analysis (and will slow it down).
The full IUPAC nucleotide ambiguity code is available, and DNA and
RNA are both accepted (and treated identically).  Upper- and lowercase
nucleotide symbols are treated equivalently.  Deletions should be
coded as unknown, and will be treated as unknown; no attempt is made to
model the insertion/deletion process.</P>

<P> Here is a minimal DNA data block describing a single region, 
a single segment, a
single population, and two individuals with a single haplotype each.
Note that while the two blocks of data are differently formatted,
they contain the same number of bases; this is required since all
blocks corresponding to a single segment must contain the same
number of markers.  If your
sequences for a given segment are of different lengths, they must be padded out with
unknown-nucleotide codes.</P>

<P>
<PRE>
&lt;data&gt;
  &lt;region name="Alcohol dehydrogenase"&gt;
    &lt;population name="Seattle"&gt;
      &lt;individual name="Mary"&gt;
        &lt;sample&gt;
          &lt;datablock type="DNA"&gt;
            CTTGTAACCTAATGGCTTCCGAGATGGACTAGTGAGCCGCTTTCTC
            TACACCAACGCAGCACATGACGGTCTTACATGCGGAGCCCGCTCAA
          &lt;/datablock&gt;
        &lt;/sample&gt;
      &lt;/individual&gt;
      &lt;individual name="Jon"&gt;
        &lt;sample&gt;
          &lt;datablock type="DNA"&gt;
            CTTGTAACCTAATGGCTTCCGA
            GATGGACTAGTGAGCCGCTTTCTC
            TACACCAACGCAGCACATGACG
            GTCTTACATGCGGAGCCCGCTCAA
          &lt;/datablock&gt;
        &lt;/sample&gt;
      &lt;/individual&gt;
    &lt;/population&gt;
  &lt;/region&gt;
&lt;/data&gt;
</PRE> </P>

<P>Microsatellite data are coded as the number of repeats, with "?"
standing for unknown data.  Successive microsatellites within the
same region are separated by blank spaces.  Here is a microsatellite
data block which also illustrates the use of multiple samples per
individual.  In this example, "Mary" is a heterozygote for the
second microsatellite and a homozygote for the other five.</P>

<P><PRE>
&lt;data&gt;
  &lt;region name="Alcohol dehydrogenase"&gt;
    &lt;population name="Seattle"&gt;
      &lt;individual name="Mary"&gt;
        &lt;sample&gt;
          &lt;datablock type="Microsat"&gt;
              7 8 14 7 9 21
          &lt;/datablock&gt;
        &lt;/sample&gt;
        &lt;sample&gt;
          &lt;datablock type="Microsat"&gt;
              7 9 14 7 9 21
          &lt;/datablock&gt;
        &lt;/sample&gt;
      &lt;/individual&gt;
      &lt;individual name="Jon"&gt;
        &lt;sample&gt;
          &lt;datablock type="Microsat"&gt;
              7 9 14 7 10 23
          &lt;/datablock&gt;
        &lt;/sample&gt;
        &lt;sample&gt;
          &lt;datablock type="Microsat"&gt;
              8 9 13 7 ? 23
          &lt;/datablock&gt;
        &lt;/sample&gt;
      &lt;/individual&gt;
    &lt;/population&gt;
  &lt;/region&gt;
&lt;/data&gt;
</PRE> </P> 


<H3><A NAME="datamodel"> Data Model</A> </H3>

<P> A &lt;region&gt; can contain models &lt;model&gt; to be used to interpret its
data.  One model should be provided per segment within the region,
in the same order that the segments are listed.
You can also provide a global &lt;model&gt; (inside the &lt;lamarc&gt;
tag) which will be used for any region that does not provide
its own models.  Only models in these two locations will be used by the program;
if both are present, the regional models will
be used in preference to the global one.  The model chosen must
be appropriate for the data type chosen.  If no model
is provided, then a default model of the appropriate datatype will be used by
the program--nucleotides use the Felsenstein '84 model, and microsatellites
use the Brownian motion model.
</P>

<P> Several tags are common to all models.  </P>

<P>  The &lt;relative-murate&gt; tag is used to specify segment-specific
mutation rates.  This is essential if very different data types are
combined in one analysis.  For example, including DNA and microsat
data without taking account of the fact that microsats mutate
thousands of times more rapidly than the single-base substitution
rate will lead to a nonsense overall estimate.  If all of your
segments have the same expected mutation rate, this tag is not
needed.  When it is needed, you should chose some data type as
the standard and set its relative rate to 1, and give all other
data types in relation to that standard.  The estimated parameters
will then also be in terms of your standard.</P>

<P> Be aware that the parameter
estimates produced by LAMARC will be scaled proportional to a
segment of relative mutation rate 1, even if no such segment is
included in the data.  That is, if you tell LAMARC that you have 
two segments, one with a relative mutation rate of 5 and the other 
with a relative mutation rate of 50, your final estimate of &Theta;
will describe a fictional segment with a relative mutation rate
of 1, and you will need to multiply by 5 or 50 to find the
&Theta; of your actual segments.</P>

<P> If you believe that your segments vary in mutation rate
according to a gamma distribution, you may wish to use the
gamma-estimation facilities of LAMARC instead of the 
&lt;relative-murate&gt; tag.  Relative mutation rate is designed
for the case where different segments or regions fall into
clearly distinct groups, known in advance, such as DNA versus
microsats or introns versus exons. </P>
 
<P> The &lt;categories&gt; tag encloses information about variable rate
categories per site (or microsat).  Within it, &lt;num-categories&gt; gives 
the number of rate categories, &lt;rates&gt; gives the relative mutation
rate of each category, and &lt;probabilities&gt; gives the probability
that a site is in each category.  The &lt;probabilities&gt; must add
up to 1.0, and there must be a rate and a probability for each
category.  The &lt;autocorrelation&gt; tag encloses information about the
average length of a run of sites (or microsats) with the same rate.  For
example, if you believe your data consists of runs averaging
100 sites with the same rate, you would set it to 100.0.
If you wish to assume that there is no autocorrelation of rates,
set this value to 1.0.  (We expect 1.0 to be an appropriate
value for microsatellites in most cases.) </P>

<A NAME="normalize"><P> The &lt;normalize&gt; tag </a> controls internal
normalization of data likelihood values.  Data likelihoods can be extremely
small, and may be subject to underflow (that is, rounded down to zero,
resulting in a loss of information).  Normalization attempts to buffer
them against underflow at the cost of making the program run more slowly.
Versions 1.2 and above of LAMARC turn on normalization automatically if they encounter 
underflow, so this tag should almost always be set to "false," and we may
remove it in a future version.  If you are sure your data set will need
normalization (extremely polymorphic data, especially microsatellites, or
extremely large data sets), then there is no harm in turning it on 
to free the program from the task of diagnosing the need for normalization.</P>


<P> The remaining tags are specific to the particular data model.  The
current selection of models is described below. </P>

<H4> Nucleotide models </H4>

<P> Lamarc offers a choice of two mutational models for DNA, RNA, and
SNP data.  The simpler (and slightly quicker) model is the model
of Felsenstein 1984 (F84), which allows differing nucleotide frequencies
and differing rates of transition versus transversion.  The more
general model is the General Time-Reversible model (GTR), which allows
every pair of nucleotides to have a characteristic mutation rate, as
well as allowing differing nucleotide frequencies.<P>

<P>Simpler models such as Jukes-Cantor or Kimura Two-Parameter 
can be obtained by correct choice of parameters to the two models
given.  If a model can be expressed as a simplification of F84, it
will run faster than the same model expressed as a simplification
of GTR.<P>

<P> The difference between F84 and GTR is that F84 expresses its
mutation rate information as a single parameter, the ttratio (ratio
of transitions to transversions) whereas GTR uses six parameters
(relative mutation rates between each pair of bases).

<P> Here is a sample F84 data model, which could appear either globally
or within a region.</P>

<P>
<PRE>
&lt;model name="F84"&gt;
  &lt;base-freqs&gt; 0.25 0.25 0.25 0.25 &lt;/base-freqs&gt;
  &lt;per-base-error-rate&gt; 0.001 &lt;/per-base-error-rate&gt;
  &lt;ttratio&gt; 2.0 &lt;/ttratio&gt;
  &lt;categories&gt;
    &lt;num-categories&gt; 2 &lt;/num-categories&gt;
    &lt;rates&gt; 1.0 10.0 &lt;/rates&gt;
    &lt;probabilities&gt; 0.8 0.2 &lt;/probabilities&gt;
    &lt;autocorrelation&gt; 5.0 &lt;/autocorrelation&gt;
  &lt;/categories&gt;
  &lt;normalize&gt; false &lt;/normalize&gt;
&lt;/model&gt;
</PRE> </P>

<P> To change this to a GTR model, remove the ttratio, change the model 
name, and add a line for the mutational rates.  We recommend using
an external tool such as PAUP* with Modeltest to estimate appropriate
GTR rates.</P>

<P>
<PRE>
&lt;model name="GTR"&gt;
  &lt;base-freqs&gt; 0.25 0.25 0.25 0.25 &lt;/base-freqs&gt;
  &lt;per-base-error-rate&gt; 0.001 &lt;/per-base-error-rate&gt;
  &lt;gtr-rates&gt; 5.4050 147.7765 4.2745 3.5801 96.3678 1.0 &lt;/gtr-rates&gt;
  &lt;categories&gt;
    &lt;num-categories&gt; 2 &lt;/num-categories&gt;
    &lt;rates&gt; 1.0 10.0 &lt;/rates&gt;
    &lt;probabilities&gt; 0.8 0.2 &lt;/probabilities&gt;
    &lt;autocorrelation&gt; 5.0 &lt;/autocorrelation&gt;
  &lt;/categories&gt;
  &lt;normalize&gt; false &lt;/normalize&gt;
&lt;/model&gt;
</PRE></P>

<P> The &lt;base-freqs&gt; tag sets the frequencies of the nucleotides
A, C, G, and T (or U) in that order.  They must be strictly greater than zero,
and must add to 1.  Alternatively, instead of four frequencies, you can 
enter the keyword "calculated," which will cause the program to calculate 
nucleotide frequencies based on your input data.  This will not work if 
one or more nucleotides are missing from your input data; you must explicitly 
set four non-zero frequencies in such cases.  We also recommend that
you always set the base frequencies explicitly when using the GTR model. </P> 

<P> The &lt;per-base-error-rate&gt; tag gives the rate at which each individual
nucleotide should be assumed to have been miss-called. A value of 0 indicates
that all were sequenced correctly. A value of 0.001 indicates one in one
thousand is incorrect. 
If not present, the value is assumed to be 0.
This functionality is in beta test as of December, 2009.
</P>

<P> The &lt;ttratio&gt; tag (F84 model only) gives the ratio of 
transitions to transversions.
The Jukes-Cantor model (no transition bias) would correspond
to a &lt;ttratio&gt; of 0.5, but due to a limitation in the algorithm
this (and lower) values are illegal.  If you wish to
use a Jukes-Cantor model, set &lt;ttratio&gt; to a very slightly
larger number such as 0.500001.</P>

<P> The &lt;gtr-rates&gt; tag (GTR model only) gives the 
relative mutation rate of each
pair of nucleotides, in the order AC, AG, AT, CG, CT, GT.  Only relative
values are important.  These are rates as output by PAUP*, before
consideration of nucleotide frequencies. </P>

<H4> Microsatellite models </H4>

<P>For microsatellite data we offer four models: the stepwise model of
Beerli and Felsenstein (1999), the Brownian model of Beerli and Felsenstein
(in preparation), a simple K-Allele model similar in concept to the
Jukes-Cantor DNA model but for arbitrary K>1, and a mixed K-Allele/Stepwise
model where both stepwise and K-Allele-type mutations are allowed at a
relative ratio.</P>

<P>The stepwise model assumes that microsatellites evolve
via stepwise changes and are constrained not to go below one repeat.
This model currently has no unique user-settable parameters; it deduces
its required number of bins from the data, and always considers a
window of 10 steps on either side of the most extreme data elements
unless this is found to overlap zero.</P>

<P>Here is a sample data model which could appear either globally
or within a region:</P>

<P><PRE>
&lt;model name="Stepwise"&gt;
  &lt;categories&gt;
    &lt;num-categories&gt; 2 &lt;/num-categories&gt;
    &lt;rates&gt; 1.0 10.0 &lt;/rates&gt;
    &lt;probabilities&gt; 0.8 0.2 &lt;/probabilities&gt;
    &lt;autocorrelation&gt; 1.0 &lt;/autocorrelation&gt;
  &lt;/categories&gt;
  &lt;normalize&gt; false &lt;/normalize&gt;
&lt;/model&gt;
</PRE></P>

<P>The Brownian model assumes that the changes in microsatellite
length can be approximated by a continuous distribution (we use a Normal).
This model currently has no unique user-settable parameters.  It
is much faster than the stepwise model, and appears to work well,
except for genealogies with very short branches (such as those
associated with very small population sizes) on which it shows a significant
upward bias.  When using this model, be on the lookout for data
log-likelihoods of zero in the runtime reports (these are labelled
"Data lnL").  If many of these
appear, they are an indication that your population sizes are too
small for safe use of the Brownian approximation.</P>

<P><PRE>
&lt;model name="Brownian"&gt;
  &lt;categories&gt;
    &lt;num-categories&gt; 2 &lt;/num-categories&gt;
    &lt;rates&gt; 1.0 10.0 &lt;/rates&gt;
    &lt;probabilities&gt; 0.8 0.2 &lt;/probabilities&gt;
    &lt;autocorrelation&gt; 1.0 &lt;/autocorrelation&gt;
  &lt;/categories&gt;
  &lt;normalize&gt; false &lt;/normalize&gt;
&lt;/model&gt;
</PRE></P>

<P> The K-Allele model assumes that the observed alleles represent
all possible alleles and that mutation is equally likely among any
pair of alleles.  It is probably not appropriate for most microsatellite
data, and is provided mainly for its ability to handle data types
otherwise not analyzable with Lamarc, such as elecrophoretic or
indel data.
The K-Allele model can also
be used to assess how severe an effect violation of the Stepwise
model's assumptions might have on the results, since it is essentially
the opposite of the Stepwise model.  If both have similar results,
the results are probably quite insensitive to the details of the
microsatellite mutational process.</P>

<P> A K-Allele model block looks just like the Brownian one with
a different name:</P>

<P><PRE>
&lt;model name="KAllele"&gt;
  &lt;categories&gt;
    &lt;num-categories&gt; 2 &lt;/num-categories&gt;
    &lt;rates&gt; 1.0 10.0 &lt;/rates&gt;
    &lt;probabilities&gt; 0.8 0.2 &lt;/probabilities&gt;
    &lt;autocorrelation&gt; 1.0 &lt;/autocorrelation&gt;
  &lt;/categories&gt;
  &lt;normalize&gt; false &lt;/normalize&gt;
&lt;/model&gt;
</PRE></P>


<P> The Mixed K-Allele/Stepwise considers both Stepwise mutational
possibilities and K-Allele mutational possibilities.  The
relative weight of the two types of mutation is given by the
parameter 'percent_stepwise'.
The allele range considered for the K-Allele changes is the
same as that for the Stepwise model (that is, all alleles within
a certain range of any observed allele) and will therefore
include some alleles never observed in the data.  
The
initial percent_stepwise is set by the user, and if the 'optimize' option
is set, it is reset at the end of every chain to its optimum
value based on the final genealogy of that chain,
as calculated using the bisection approach.</P>

<P>Because this model incorporates both a K-Allele and Stepwise approach,
it should only be used for data for which both of those models are
legal, namely microsatellite data.</P>

<P> A Mixed K-Allele/Stepwise model block includes two new tags, 'alpha' 
(meaning the percent_stepwise parameter),
and 'optimize', which should be on the same level as 'categories' and
'normalize'.</P>

<P><PRE>
&lt;model name="MixedKS"&gt;
  &lt;categories&gt;
    &lt;num-categories&gt; 2 &lt;/num-categories&gt;
    &lt;rates&gt; 1.0 10.0 &lt;/rates&gt;
    &lt;probabilities&gt; 0.8 0.2 &lt;/probabilities&gt;
    &lt;autocorrelation&gt; 1.0 &lt;/autocorrelation&gt;
  &lt;/categories&gt;
  &lt;normalize&gt; false &lt;/normalize&gt;
  &lt;alpha&gt; 0.3 &lt;/alpha&gt;
  &lt;optimize&gt; false &lt;/optimize&gt;
&lt;/model&gt;
</PRE></P>



<H3><A Name="forces"> Evolutionary Forces</A></H3>

<P> The &lt;forces&gt; tag encloses information about each evolutionary force
to be considered in the analysis.  The &lt;forces&gt; section should not
specify forces that make no sense--for example, migration is not
allowed if there is only one population, and recombination is not
allowed if there is only one site.
</P>

<P> The force tags are &lt;coalescence&gt;, &lt;migration&gt;, &lt;recombination&gt;,
&lt;growth&gt;, &lt;gamma-over-regions&gt; and the pair &lt;divergence-migration&gt; and &lt;divergence&gt;. In this version of Lamarc.
&lt;coalescence&gt; is required, the others are optional (though if multiple populations
are specified, either &lt;migration&gt; or the  &lt;divergence-migration&gt;, &lt;divergence&gt; pair is required). 
</P>

<P>The gamma-over-regions "force" may only be applied
to data spread over multiple, unlinked genomic regions.  This "force" assumes the
relative mutation rates over unlinked genomic regions are gamma-distributed, and
causes Lamarc to simultaneously infer the shape of the gamma distribution which best fits
the data.  More information about this can be found <A HREF="gamma.html">here</A>.
Please note that Lamarc is unable to co-estimate the shape of the gamma distribution
and population growth rates.  Lamarc will accept input files containing either the
tag &lt;growth&gt; or the tag &lt;gamma-over-regions&gt;, but not both.
</P>

<P> Divergence can only be defined if there are two or more populations in the data. If the user wishes to estimate Divergence, they must define the relationships between the populations in the input data by defining parents. This is most easily done in the <a href="converter.html">data file converter</a>, but can be done directly in the XML as shown <A HREF="xmlinput.html#divergence">below</A>.
</P>

<P>For each force tag, the following information can be included:
</P>

<P> &lt;start-values&gt; contains a space-delimited list of the starting
values of the parameters for that force.  For example, in a
3-population case, you would provide 3 starting values for population
Thetas, and 9 starting values for immigration rates.  In the migration
case, diagonal entries (meaningless values for migration from
a population to itself) can be indicated with dashes instead of
zeros, if desired.
</P>

<P> &lt;method&gt; indicates the algorithms for computing starting values for
each parameter.  This can be "User," meaning that the user-specified
values should be used.  Other options are "FST" to set migration
parameters using the <i>F<sub>ST</sub></i> algorithm, and "Watterson" to set Thetas using
the method of Watterson, We do not currently provide algorithms to
estimate starting recombination or growth rates, or a starting value
for the single parameter of the gamma-over-regions "force."  (None of the available
algorithms seemed to perform well enough to be helpful.)  If you are
going to specify any methods, you need to specify one for each parameter.
</P>

<P> It is sometimes helpful to set certain parameters to "User" even if
you mainly intend to use FST and Watterson.  FST, in particular,
will fail in certain cases.  We use an arbitrary default value when
FST fails, but you may be able to provide a better value than this
default.
</P>

<P> &lt;max-events&gt; gives a maximum for the number of events in the
tree that are generated by this force.  For example, for the
migration force it gives the maximum total number of migrations.
If a tree violates any of these maxima, that tree will be discarded.
Discarded trees are noted in the runtime reports and, if verbose
output is requested, in the output file.  This option is not useful
(though it is harmless) for coalescence, growth, and gamma-over-regions.</P>

<P> You may wish to set the maxima relatively low if the program is
running out of space or slowing down tremendously.  However, if the
maxima are encountered often (look at the runtime report to check),
the estimate of parameters for that force will tend to be biased
downward.</P>

<P> &lt;profiles&gt; gives the type of profile likelihood to be computed for
each parameter.  The options are "percentile," which will compute
profile likelihoods at selected percentiles of the distribution;
"fixed," which will compute profile likelihoods at fixed multiples
of the maximum-likelihood parameter value; and "none," which will
compute no profiles.  The profiles of a given run may be a mix
of "percentile," "fixed," and "none," but you cannot
use both "percentile" and "fixed" percentiles for the same force.</P>

<P> In a likelihood analysis, percentile profiles are very time-consuming. 
If you are not interested in a particular parameter, consider turning off
its profiling, and if the overall run is still too slow, consider fixed
rather than percentile profiles.  If you are only interested in the 95%
support interval, you may also change the output file <A
HREF="#verbosity">verbosity</a> to 'concise', which causes only those
intervals to be calculated and output (decreasing the time spent profiling
by approximately a factor of 5). In a Bayesian analysis, profiling is simply a matter
of reading off values from the produced posterior probability curve, so the
more-informative percentile profiles should be the profile type of choice
for most users.</P>

<P> The profile line, if present, must have one entry per parameter for
that force (for example, a three-population case must have nine
entries for migration profiling).  It does not matter what profile
type you specify for the "diagonal" migration rates.</P>

<P> An example &lt;forces&gt; block for a case with two populations and migration:</P>

<P>
<PRE>
&lt;forces&gt;
  &lt;coalescence&gt;
    &lt;start-values&gt; 0.01 0.03 &lt;/start-values&gt;
    &lt;method&gt; Watterson Watterson &lt;/method&gt;
    &lt;profiles&gt; fixed fixed &lt;/profiles&gt;
  &lt;/coalescence&gt;
  &lt;migration&gt;
    &lt;start-values&gt; - 1.2 1.8 - &lt;/start-values&gt;
    &lt;method&gt; - FST User User - &lt;/method&gt;
    &lt;max-events&gt; 1000 &lt;/max-events&gt;
    &lt;profiles&gt; - none fixed - &lt;/profiles&gt;
  &lt;/migration&gt;
  &lt;recombination&gt;
    &lt;start-values&gt; 0.04 &lt;/start-values&gt;
    &lt;method&gt; User &lt;/method&gt;
    &lt;max-events&gt; 1000 &lt;/max-events&gt;
    &lt;profiles&gt; none &lt;/profiles&gt;
  &lt;/recombination&gt;
&lt;/forces&gt;
</PRE> </P>

<H4><A Name="divergence">Divergence</A></H4>
<P> Divergence introduces population divergence into migration, so things get much more complex. The populations are combined pairwise, so if there are three measured populations, there will be two ancestors. Once the first ancestor is defined, migration cannot happen between the two populations subsumed into that ancestor and the third population, as those two populations no longer exist. This is shown graphically on the <a href="divergence.html">Divergence</a> page. As a result you need to define two forces &lt;divergence&gt; and &lt;divergence-migration&gt;. </P> 

<P>Besides all the standard force tags &lt;divergence&gt; also specifies how the measured populations and their ancestors are related. This is done creating the &lt;population-tree&gt; which explicitly defines, using &lt;epoch-boundary&gt; tags, a pair of  &lt;new-populations&gt; and their &lt;ancestor&gt;. That &lt;ancestor&gt; name can then be used as a &lt;new-populations&gt; member for an earlier  &lt;ancestor&gt;.</P>

<P>&lt;divergence-migration&gt; defines the migrations between the populations and ancestors (it has exactly the same format as  &lt;migration&gt; but is, of course, much larger because of the additional rows and columns required to specify migration to and from the ancestor populations). Below is the XML for the 3 population example on the <a href="divergence.html">Divergence</a> page. </P>

<P> Note that in the example both &lt;divergence&gt; and  &lt;divergence-migration&gt; have a &lt;prior&gt; defined. This is because Divergence only functions in Bayesian analysis currently. Likelihood analysis is not available.
</P> 
<P>
<PRE>
&lt;divergence&gt;
    &lt;prior type="linear"&gt;
        &lt;paramindex&gt; default &lt;/paramindex&gt;
        &lt;lower&gt; 0.0 &lt;/lower&gt;
        &lt;upper&gt; 0.01 &lt;/upper&gt;
    &lt;/prior&gt;
    &lt;method&gt; USER USER &lt;/method&gt;
    &lt;start-values&gt;  0.002000  0.004000 &lt;/start-values&gt;
    &lt;population-tree&gt;
        &lt;epoch-boundary&gt;
            &lt;new-populations&gt; North South &lt;/new-populations&gt;
            &lt;ancestor&gt; Parent_1 &lt;/ancestor&gt;
        &lt;/epoch-boundary&gt;
        &lt;epoch-boundary&gt;
            &lt;new-populations&gt; East Parent_1 &lt;/new-populations&gt;
            &lt;ancestor&gt; Parent_2 &lt;/ancestor&gt;
        &lt;/epoch-boundary&gt;
    &lt;/population-tree&gt;
&lt;/divergence&gt;
&lt;divergence-migration&gt;
    &lt;start-values&gt; 0 50.000000 50.000000 0 0 50.000000 0 50.000000 0 0 
    50.000000 50.000000 0 50.000000 0 0 0 50.000000 0 0 0 0 0 0 0 &lt;/start-values&gt;
    &lt;method&gt; USER USER USER USER USER USER USER USER USER USER USER 
    USER USER USER USER USER USER USER USER USER USER USER USER USER USER &lt;/method&gt;
    &lt;max-events&gt; 10000 &lt;/max-events&gt;
    &lt;profiles&gt; None None None None None None None None None None None 
    None None None None None None None None None None None None None None &lt;/profiles&gt;
    &lt;constraints&gt; Invalid Unconstrained Unconstrained Invalid Invalid 
    Unconstrained Invalid Unconstrained Invalid Invalid Unconstrained Unconstrained 
    Invalid Unconstrained Invalid Invalid Invalid Unconstrained Invalid Invalid 
    Invalid Invalid Invalid Invalid Invalid &lt;/constraints&gt;
    &lt;prior type="linear"&gt;
        &lt;paramindex&gt; default &lt;/paramindex&gt;
        &lt;lower&gt; 0.0 &lt;/lower&gt;
        &lt;upper&gt; 100.0 &lt;/upper&gt;
    &lt;/prior&gt;
&lt;/divergence-migration&gt;
</PRE> 
</P>

<H3><A NAME="chains"> Chain Control </A></H3>

<P> The &lt;chains&gt; tag contains information controlling the search
strategy, such as number and length of chains, sampling interval,
heating, and rearrangement strategy.  For details on selecting a
search strategy, see the file "Search Strategies." </P>

<P> Chains come in two kinds, "initial" and "final;" the program will
run the requested number of initial chains, and then the requested
number of final chains.  It is often useful to make the initial
chains shorter, giving a quick-and-dirty estimate which the
final chains can refine, but the program does not dictate any
particular relationship between initial and final.</P>

<P> The &lt;initial&gt; and &lt;final&gt; tags lay out parameters for the two
chain types.  Within them, &lt;number&gt; is the number of chains of
that type, &lt;samples&gt; is the number of genealogies that will be
sampled for parameter estimation, &lt;interval&gt; is the number of
genealogies generated for each one that is sampled, and &lt;discard&gt;
is the length of the burn-in period before any genealogies are
sampled.  For example, if &lt;samples&gt; is 35, &lt;interval&gt; is 10, and
&lt;discard&gt; is 200, the program will first produce and discard
200 genealogies, and then produce 350 more, sampling every 10th
one for a total of 35 sampled genealogies.</P>

<P> If you wish, for some reason, to run only one chain, you can set
the samples of the other chain type to zero.  For likelihood-based
parameter estimation we believe that one chain is always too few.
One chain is a reasonable choice for Bayesian analysis, however.  (If only
one chain is run, burn-in should probably be quite long.)
</P>

<P> Note that this convention for indicating how many genealogies to
sample is the same as the one used in MIGRATE, but different from
the one used in COALESCE, FLUCTUATE, and RECOMBINE.  The latter
three programs take the total number of genealogies to be produced,
not the number to be sampled.  Be careful of this point when comparing
runs of the different programs.</P>

<P> The &lt;replicates&gt; tag gives the number of replications for each
chain (one or more).  If more than one replicate is requested,
a joint parameter estimate over all replicates will be produced.</P>

<P> The &lt;heating&gt; tag controls the heating strategy.  It must contain
two tags.  &lt;temperatures&gt; gives a list of temperatures for the
various searches (the number of entries in this tag determines the
number of searches that will be run).  The lowest temperature should
always be 1.0.  (We know of no use for a chain colder than that.)
The &lt;swap-interval&gt; tag gives the number of chain steps that will
pass between each attempt to swap trees among the different
temperatures.  1 is a reasonable default; higher values may run a
little faster, but are less effective.</P>

<P> A third, optional tag &lt;adaptive&gt; can be used to turn on or
off "adaptive" heating, in which the program will adjust the temperatures
in use so as to try to optimize acceptance rates.  Adaptive heating is
off by default.  If you enable it (&lt;adaptive&gt; true &lt;/adaptive&gt;), 
keep a close eye on your searches
to make sure that they are performing well.  In theory adaptive
heating should be superior to fixed-temperature heating, but we have
little experience with it so far.</P>

<P>The &lt;strategy&gt; tag indicates the rearrangement strategy.   It contains
a relative frequency (a number between 0 and 1) for use of this
particular strategy; the frequencies of all strategies should add
up to 1.</P>

<P>In version 2.0, four strategies are possible.  </P>

<P>The &lt;resimulating&gt; strategy
rearranges the genealogy.  Every run must have a &lt;resimulating&gt;
strategy, since only this strategy allows free movement through the
genealogy search space.  Its frequency should always be fairly
high; we recommend at least 80% in a likelihood run, and at least
40% in a Bayesian run.</P>

<P>The &lt;haplotyping&gt; strategy reconsiders 
haplotype assignments.  This is only useful if you have some phase-unknown
sites in your data, and will be silently disabled, even
if you specify it, on data with no phase-unknown sites.  A
reasonable frequency for it, if it is needed, might be around 20%.</P>

<P>The &lt;bayesian&gt; strategy allows a Bayesian analysis to
search the space of population parameters.  It is only useful in
a Bayesian run (including a Bayesian arranger will turn the
run into a Bayesian run).  We have found setting its frequency
equal to the resimulating arranger's frequency to be satisfactory.
Please note that a Bayesian run with a 50/50 resimulating/Bayesian
arranger strategy will have to take twice as many steps to 
consider as many trees as a pure likelihood run, and probably
should.  Bayesian rearrangements are relatively quick, so this will
not slow the program inordinately.</P>

<P> The &lt;trait-arranger&gt; strategy is useful only when trying
to map a trait to a location on the chromosome using the "jumping"
algorithm.  It allows the search to reconsider the location of the
trait, and should probably have a high frequency such as 30-50%.  
It will be silently turned off if not needed.</P>

<P> Here is a sample search-strategy block.</P>

<P>
<PRE>
&lt;chains&gt;
  &lt;replicates&gt;1&lt;/replicates&gt;
  &lt;heating&gt;
    &lt;temperatures&gt;1.0&lt;/temperatures&gt;
    &lt;swap-intervals&gt;1 1&lt;/swap-intervals&gt;
  &lt;/heating&gt;
  &lt;strategy&gt;
    &lt;resimulating&gt; 1.0 &lt;/resimulating&gt;
  &lt;/strategy&gt;
  &lt;initial&gt;
    &lt;number&gt;5&lt;/number&gt;
    &lt;samples&gt;50&lt;/samples&gt;
    &lt;discard&gt;100&lt;/discard&gt;
    &lt;interval&gt;20&lt;/interval&gt;
  &lt;/initial&gt;
  &lt;final&gt;
    &lt;number&gt;1&lt;/number&gt;
    &lt;samples&gt;100&lt;/samples&gt;
    &lt;discard&gt;100&lt;/discard&gt;
    &lt;interval&gt;20&lt;/interval&gt;
  &lt;/final&gt;
&lt;/chains&gt;
</PRE> </P>

<H3><A NAME="options"> User options</A> </H3>

<P> The &lt;format&gt; tag encloses various options for formatting and
detail level of results, as well as the random number seed.</P>

<P>The &lt;convert-output-to-eliminate-zero&gt; tag indicates whether you
think of your data in terms of it having a 'site 0' or not.  The traditional
biologist assumption is that 'site 1' is right next to 'site -1', with
nothing inbetween.  As you might imagine, such a scheme would cause no end
of trouble computationally, so a LAMARC input file scoots all such negative
numbers up by one such that 'site -1' becomes 0, 'site -2' become -1, and so
on.  (The converter lam_conv does not make this assumption, but produces
LAMARC input files that do.)  If you are using the mapping option, you will
see numbers for sites in both the menu and in the output file; this option
can be toggled ('true' or 'false') by hand here so that the data output will
match your expectations.  See <A HREF="troubleshooting.html#Q14">"Does
LAMARC use 'site 0'?"</a> in the FAQ.</P>


<A NAME="verbosity"></a><P> The &lt;verbosity&gt; tag indicates how lengthy the output report should
be; options are concise, normal, and verbose.  When in doubt, try
verbose--you can always discard unneeded parts later.</P>

<P> Similarly, the &lt;progress-reports&gt; tag indicates what kind of feedback
should be given while the program is running.  Options are none,
concise, normal and verbose.  For exploratory runs, we strongly
recommend verbose.</P>

<P> The &lt;seed&gt; tag initializes the random number generator.  The
number provided should be an integer of the form 4N+1, such
as 101 or 105.  If the program is run twice with the same
parameters, data, and seed, it will produce the same results.</P>
If no &lt;seed&gt; tag is given and no seed is set from the menu,
the program will try to use the system clock to seed the random
number generator.  If your system is peculiar enough to have
no system clock, you'll want to prevent this by always specifying
a seed.</P>

<P> &lt;results-file&gt; gives the name of the file which will receive the
output report when the program finishes (destroying any previous
contents).</P>

<P> &lt;use-in-summary-file&gt; can be set to either "true" (if data reading
from a summary file is desired) or "false" (if not).  
&lt;in-summary-file&gt; gives the name of the file from which to read in
data from a previous run of LAMARC.</P>

<P> &lt;use-out-summary-file&gt; can be set to either "true" (if data
writing to a summary file is desired) or "false" (if not).  
&lt;out-summary-file&gt; gives the name of the file which will contain
the output summary file.</P>

<P> &lt;use-curvefiles&gt; can be set to "true" in a Bayesian run for
which curvefiles should be saved, or "false" otherwise.  
&lt;curvefile-prefix&gt; gives a prefix which will form the first part
of the name of all such curvefiles (the remainder of the name is
formed from the name of the parameter whose curve is being recorded).</P>

<P> &lt;use-reclocfile&gt; can be set to "true" if you want to dump
out the locations of all recombination events in sampled trees in
the last final chain. This is &quot;false&quot; by default since
the files can be quite large.
&lt;reclocfile-prefix&gt; gives a prefix which will form the first
part of the name of all recombination location files.</P>

<P> &lt;use-tracefile&gt; can be set to "true" if Tracer-readable
summaries of the run are desired, or "false" otherwise.  
&lt;tracefile-prefix&gt; gives a prefix which will form the first
part of the name of all Tracer files.</P>

<P> &lt;use-newicktreefile&gt; can be set to "true" if trees from
this run should be written out in Newick format, or "false"
otherwise.  &lt;newicktreefile-prefix&gt; gives a prefix which
will form the first part of the name of all Newick-format tree
files.</P>

<P> &lt;out-xml-file&gt; gives the name of the file which will receive a
copy of the input file, as modified by options selected in the menu.</P>

<P> There is no entry for the name of the input data file, since
that's the file this XML is in.</P>

<P> Here is a sample &lt;format&gt; block: </P>

<P>
<PRE>
&lt;format&gt;
  &lt;verbosity&gt;verbose&lt;/verbosity&gt;
  &lt;progress-reports&gt;normal&lt;/progress-reports&gt;
  &lt;seed&gt;1005&lt;/seed&gt;
  &lt;use-in-summary-file&gt;false&lt;/use-in-summary-file&gt;
  &lt;in-summary-file&gt;insumfile.xml&lt;/in-summary-file&gt;
  &lt;use-out-summary-file&gt;false&lt;/use-out-summary-file&gt;
  &lt;out-summary-file&gt;outsumfile.xml&lt;/out-summary-file&gt;
  &lt;out-xml-file&gt;menusettings_infile.xml&lt;/out-xml-file&gt;
&lt;/format&gt;
</PRE> </P>

<H3><A NAME="mapping"> Trait Mapping </A></H3>

<P> Trait mapping is enabled by presence of a &lt;traits&gt;
block nested within a &lt;region&gt;.  Within it there
should be a &lt;trait&gt; block for each trait being mapped.
Although you are unlikely to need it, if you have multiple traits that map
to the same genomic region, you may map them simultaneously by giving each a
'trait' tag.  The trait is assumed
to be located somewhere in this region; LAMARC will not
consider the possibility that it is elsewhere.</P>

<P> The trait is given a name with a &lt;name&gt; block,
and the type of analysis (floating or jumping) is given
with an &lt;analysis&gt; block whose legal values are
"float" or "jump".</P>

<P> If information is available about possible locations for
the trait, they can be indicated in a &lt;possible-locations&gt;
block containing one or more &lt;range&gt; blocks.  Each
&lt;range&gt; should contain a &lt;start&gt; and an &lt;end&gt;
block giving the starting and ending sites of the range,
numbering the first site of the region as 1.  At least one
site must be a legal location for the trait (and really, it is
silly to attempt mapping unless more than one site is legal).</P>

<P> The trait block may also contain an appropriate data model for trait
allele mutations, which must (at present) be a K-Allele model.  It is
inappropriate to have multiple categories for a trait allele (since the
categories involve differences in mutation rate among markers, and there
will always be exactly one marker for trait alleles), and normalization can
usually be ignored, but you may want to input a relative mu rate.  For
example, if you believe your alleles are the result of a dysfunctional gene,
and you are working with SNP data, you might estimate that there are
approximately 500 sites in an average gene that lead to that gene's
disruption, and observed SNPs approximately one every 100 sites, so you
would tell LAMARC that the relative mutation rate of your trait allele is 5
times more than that for your SNP data.  (If you had DNA data instead, you
would put in '500' as the relative mutation rate.)    
 </P>

<P>As an example, here is XML input for the trait 'funny-nose', which we
know might be mappable to site 1 or somewhere within sites 35-68, and which
has a relative mutation rate of 5:
<PRE>
&lt;data&gt;
  &lt;region name="Region1"&gt;
    &lt;traits&gt;
      &lt;trait&gt;
        &lt;name&gt; funny-nose &lt;/name&gt;
        &lt;analysis&gt; float &lt;/analysis&gt;
        &lt;possible-locations&gt;
          &lt;range&gt;
            &lt;start&gt; 1 &lt;/start&gt;
            &lt;end&gt; 1 &lt;/end&gt;
          &lt;/range&gt;
          &lt;range&gt;
            &lt;start&gt; 35 &lt;/start&gt;
            &lt;end&gt; 68 &lt;/end&gt;
          &lt;/range&gt;
        &lt;/possible-locations&gt;
        &lt;model name="KAllele"&gt;
          &lt;normalize&gt;false&lt;/normalize&gt;
          &lt;categories&gt;
            &lt;num-categories&gt;1&lt;/num-categories&gt;
            &lt;rates&gt; 1&lt;/rates&gt;
            &lt;probabilities&gt; 1&lt;/probabilities&gt;
            &lt;autocorrelation&gt;1&lt;/autocorrelation&gt;
          &lt;/categories&gt;
          &lt;relative-murate&gt;5&lt;/relative-murate&gt;
        &lt;/model&gt;
      &lt;/trait&gt;
    &lt;/traits&gt;
</PRE>
<P> Additionally, within the &lt;individual&gt; tag of each
individual from whom data was sampled, you will need to include
a &lt;genotype-resolutions&gt; block specifying the possible
genotypes which could correspond to that individual's phenotype.
The first block within the &lt;genotype-resolutions&gt; block
should be a &lt;trait-name&gt; matching the name given earlier
for the trait.  This is followed by a collection of 
&lt;haplotypes&gt; blocks which give each haplotype possible
for that individual, and the penetrance.  Be careful with
these penetrances!  The penetrance of a haplotype is the
chance that, if the individual has this haplotype, they will
show the phenotype they did in fact show; it is <b>not</b>
the chance that the individual has this haplotype.  Only
haplotypes which the individual could have should be listed.
The penetrance, which should be a number greater than 0 and
less than or equal to 1, goes in a &lt;penetrance&gt; tag
and the two alleles, in order, which make up the haplotype
go in a &lt;alleles&gt; tag.</P>

<P> Here is an example from an individual whose nose is bent.  Based on our
previous analysis of this trait, we know that 100% of individuals who are
homozygous for the 'broken' allele have a bent nose, that 50% of individuals
who are heterozygous and have one 'broken' allele and one 'normal' allele
have a bent nose, and that no individual who is homozygous for the 'normal'
allele has a bent nose:
</P>

<P>
<PRE>
  &lt;individual name="Mary"&gt;
    &lt;genotype-resolutions&gt;
      &lt;trait-name&gt; funny-nose &lt;/trait-name&gt;
         &lt;haplotypes&gt;
            &lt;penetrance&gt; 1 &lt;/penetrance&gt;
            &lt;alleles&gt; broken broken &lt;/alleles&gt;
         &lt;/haplotypes&gt;
         &lt;haplotypes&gt;
            &lt;penetrance&gt; 0.5 &lt;/penetrance&gt;
            &lt;alleles&gt; normal broken &lt;/alleles&gt;
         &lt;/haplotypes&gt;
         &lt;haplotypes&gt;
            &lt;penetrance&gt; 0.5 &lt;/penetrance&gt;
            &lt;alleles&gt; broken normal &lt;/alleles&gt;
         &lt;/haplotypes&gt;
       &lt;/genotype-resolutions&gt;
</PRE></P>

<P>Note that we must include both 'normal broken' as well as 'broken normal'
for the heterozygote.</P>

<P> Every individual will require such a block giving all
possible haplotype resolutions of the trait data.</P>

<P>(<A HREF="converter_cmd.html">Previous</A> | <A
HREF="index.html">Contents</A> | <A HREF="menu.html">Next</A>)</P>

<!--
$Id: xmlinput.html,v 1.55 2012/05/29 18:59:45 ewalkup Exp $
-->
</BODY>
</HTML>