ʻOhana
Population structure, admixture history, and selection using learning methods.
nemeco/jade.main.cpp
1 /* -------------------------------------------------------------------------
2  Ohana
3  Copyright (c) 2015-2020 Jade Cheng (\___/)
4  Jade Cheng <info@jade-cheng.com> (='.'=)
5  ------------------------------------------------------------------------- */
6 
7 #include "jade.optimizer.hpp"
8 #include "jade.version.hpp"
9 
10 namespace
11 {
12  char const * const usage = R"(USAGE
13  nemeco [options] <g-matrix> <f-matrix>
14 
15 ARGUMENTS
16  g-matrix the path to a genotype matrix
17  f-matrix the path to the frequency matrix
18 
19 OPTIONS
20  --ain,-ai indicates the next argument is the path to the
21  admixture graph input file; this option cannot
22  be specified with the --cin or --tin options
23  --cin,-ci indicates the next argument is the path to the
24  initial covariance matrix; this option cannot
25  be specified with the --ain or --tin options
26  --cout,-co indicates the next argument is the path to the
27  [k-1 x k-1] output covariance matrix
28  --epsilon,-e indicates the next argument is the epsilon
29  value; i.e. the minimum difference between
30  likelihood; this value must be greater than or
31  equal to zero
32  --f-epsilon,-fe indicates the next argument is the epsilon used
33  to clamp values of the allele frequency matrix
34  between (0 + fe) and (1 - fe); if unspecified,
35  this value defaults to 1.0e-6; the value must
36  be greater than 0.0 and less than 0.1
37  --help,-h shows this help message
38  --max-iterations,-mi indicates the next argument is the maximum
39  number of iterations to execute the algorithm;
40  this value must be greater than zero
41  --max-time,-mt indicates the next argument is the maximum time
42  in seconds to execute the algorithm; this value
43  must be greater than or equal to zero
44  --tin, -ti indicates the next argument is the path to the
45  file that defines the input tree structure; the
46  file is in Newick format; this option cannot
47  be specified with the --ain or --cin options
48  --tout, -to indicates the next argument is the path to the
49  output file containing the tree structure; the
50  file is in Newick format; this option cannot be
51  specified without the --tin option
52 
53 DESCRIPTION
54  Models the joint distribution of the allele frequencies as a variant of a
55  multivariate Gaussian and infers its covariance matrix using the Nelder-Mead
56  optimization method.
57 
58  [Notation]
59 
60  K := Number of Components
61  This value must be greater than or equal to one.
62 
63  I := Number of Individuals
64  This value must be greater than or equal to one.
65 
66  J := Number of Markers
67  This value must be greater than or equal to one.
68 
69  G := [I x J] Discrete or Likelihood Genotype Matrix
70  dgm consists of integer values ranging from 0 to 3, inclusive.
71  0 := major-major allele
72  1 := major-minor allele
73  2 := minor-minor allele
74  3 := missing allele information
75  lgm with three floating-point value matrices in the following order.
76  n x m matrix, values 0.0 to 1.0 for minor-minor
77  n x m matrix, values 0.0 to 1.0 for major-minor
78  n x m matrix, values 0.0 to 1.0 for major-major
79 
80  F := [K x J] Frequency Matrix
81  This matrix consists of floating-point values ranging from 0 to 1.
82 
83  C := [K-1 x K-1] Rooted Covariance Matrix
84  This matrix consists of floating-point values. It is a symmetric and
85  positive semidefinite matrix.
86 
87  [Admixture Graph Input File Format]
88 
89  An Admixture Graph Input (AGI) file is an ASCII file that specifies parameter
90  names for branch lengths, parameter names for admixture proportions, a number
91  of components, and expressions that are evaluated to compose the rooted
92  covariance matrix. At least one branch length parameter and at least one
93  proportion parameter must be defined, but not all parameters must be used in
94  the expressions. For example, the following represents an admixture graph
95  with three components, one admixture event, and rooted at component A:
96 
97  # f/ \
98  # / \g
99  # /\ \
100  # / d\ /\
101  # a/ \ /e \
102  # / <-p |b \c
103  # A B C
104  #
105  # Branch length parameters, range: [0, inf)
106  a b c d e f g
107 
108  # Admixture proportion parameters, range: [0, 1]
109  p
110 
111  # K value
112  3
113 
114  # Matrix entries, total number should be: K*(K-1)/2
115  # They map to a C matrix, e.g. K=3 it maps to:
116  # 0 1
117  # 1 2
118  (1 - p) * (b + e + g + f + a) + p * (b + d + a)
119  p * a + (1 - p) * (g + f + a)
120  c + g + f + a
121 
122 EXAMPLES
123  $ nemeco -mi 3 -e 0 -co ./cout.matrix g.matrix f.matrix
124  iter duration delta-log log-likelihood
125  1 0.005124 0.000000e+00 -6.190334e+04
126  2 0.000044 0.000000e+00 -6.190334e+04
127  3 0.000042 0.000000e+00 -6.190334e+04
128 
129  log likelihood = -61903.3
130  Writing C matrix to ./cout.matrix
131 
132 BUGS
133  Report any bugs to Jade Cheng <info@jade-cheng.com>.
134 
135 Copyright (c) 2015-2020 Jade Cheng
136 )";
137 }
138 
139 ///
140 /// The main entry point of the program.
141 /// \param argc The argument count.
142 /// \param argv The argument values.
143 /// \return EXIT_SUCCESS or EXIT_FAILURE.
144 ///
145 int main(const int argc, const char * argv[])
146 {
147  try
148  {
149  jade::args args (argc, argv);
150 
151  if (args.read_flag("--help", "-h"))
152  {
153  std::cout << ::usage;
154  return EXIT_SUCCESS;
155  }
156 
157  if (args.read_flag("--version", "-v"))
158  {
159  jade::version::write("nemeco", std::cout);
160  return EXIT_SUCCESS;
161  }
162 
163  typedef double value_type;
164  typedef jade::basic_settings<value_type> settings_type;
165  typedef jade::basic_optimizer<value_type> optimizer_type;
166 
167  const settings_type settings (args);
168  optimizer_type::execute(settings);
169 
170  return EXIT_SUCCESS;
171  }
172  catch (const std::exception & e)
173  {
174  std::cerr << e.what() << std::endl;
175  return EXIT_FAILURE;
176  }
177 }
jade::basic_settings
A template for a class encapsulating the settings provided to the optimizer.
Definition: cpax/jade.settings.hpp:22
jade::basic_args
A template for a class that helps process command-line arguments.
Definition: jade.args.hpp:19
jade::basic_version::write
static void write(char_type const *const title, ostream_type &out)
Writes the string displayed to the user.
Definition: jade.version.hpp:29
jade::basic_optimizer
A template for a class that optimizes the Q and F matrices.
Definition: cpax/jade.optimizer.hpp:21