<div id="api_guide">
  <h2>Output Data Formats</h2>

  <div id="input_format_contents">
    <h3>Table of Contents</h3>
    <ul>
      <li><a href="#xml">XML</a>
      <ul>
        <li><a href="#xml_output">Output</a></li>
        <li><a href="#xml_errors">Errors</a></li>
      </ul>
      </li>

      <li><a href="#json">JSON</a></li>
      <ul>
        <li><a href="#json_output">Output</a></li>
        <li><a href="#json_errors">Errors</a></li>
      </ul>
    </ul>
  </div>

  <div id="xml" class="formats">
  <h3>XML</h3>

  <div id="xml_output">
  <h4>Output</h4>
    <p>
      XML can be used to format the data output by the service. With <%= link_to 'SOAP requests', {:action => 'soap'} %> this is the only option, however
      using the REST API allows the output format to be specified (see the <%= link_to 'REST section', {:action => 'rest' } %>
      of this guide).
    </p>

      <p>
        Below we give an example of a set of input parameters to the <code>find</code> API call (for both SOAP and REST)
        and show the resulting data output by the service using these parameters.</p>
        <dl>
          <dt><code>data</code></dt>
          <dd><pre>
{ "data" :
  {
    "1" : { "sources" : [1],
            "dage" : 65,
            "matches" : [ { "recipient" : 2, "score" : 3},
                          { "recipient" : 3, "score" : 1},
                          { "recipient" : 4, "score" : 2} ]},
    "2" : { "sources" : [2],
            "dage" : 45,
            "matches" : [ { "recipient" : 1, "score" : 2},
                          { "recipient" : 5, "score" : 1} ]},

    "3" : { "sources" : [3],
            "dage" : 25,
            "matches" : [ { "recipient" : 1, "score" : 1},
                          { "recipient" : 5, "score" : 1} ]},
    "4" : { "sources" : [4],
            "dage" : 55,
            "matches" : [ { "recipient" : 2, "score" : 3},
                          { "recipient" : 3, "score" : 2},
                          { "recipient" : 5, "score" : 4} ]},

    "5" : { "sources" : [5],
            "dage" : 30,
            "matches" : [ { "recipient" : 2, "score" :	1},
                          { "recipient" : 4, "score" : 2} ]},

    "6" : { "sources" : [3],
            "dage" : 25,
            "matches" : [ { "recipient" : 1, "score" : 1},
                          { "recipient" : 5, "score" : 1} ]}

  }
}
          </pre></dd>
          <dt><code>operation</code></dt>
          <dd><pre>optimal</pre></dd>
        </dl>

        <pre class="brush: xml">
&lt;data&gt;
&lt;algorithm&gt;Optimal set of exchanges with respect to the optimality criteria&lt;/algorithm&gt;
&lt;output&gt;
  &lt;all_cycles&gt;
    &lt;cycle id="0" backarcs="0" weight="11.05" alt=""&gt;
      &lt;pair&gt;&lt;p&gt;1&lt;/p&gt;&lt;d&gt;1&lt;/d&gt;&lt;tb&gt;0.025&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;3&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;2&lt;/p&gt;&lt;d&gt;2&lt;/d&gt;&lt;tb&gt;0.025&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="1" backarcs="0" weight="2.018" alt="2"&gt;
      &lt;pair&gt;&lt;p&gt;1&lt;/p&gt;&lt;d&gt;1&lt;/d&gt;&lt;tb&gt;0.009&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;3&lt;/p&gt;&lt;d&gt;3&lt;/d&gt;&lt;tb&gt;0.009&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="2" backarcs="0" weight="2.018" alt="1"&gt;
      &lt;pair&gt;&lt;p&gt;1&lt;/p&gt;&lt;d&gt;1&lt;/d&gt;&lt;tb&gt;0.009&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;3&lt;/p&gt;&lt;d&gt;6&lt;/d&gt;&lt;tb&gt;0.009&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="3" backarcs="0" weight="8.0605" alt=""&gt;
      &lt;pair&gt;&lt;p&gt;2&lt;/p&gt;&lt;d&gt;2&lt;/d&gt;&lt;tb&gt;0.03025&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;5&lt;/p&gt;&lt;d&gt;5&lt;/d&gt;&lt;tb&gt;0.03025&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="4" backarcs="0" weight="6.0405" alt=""&gt;
      &lt;pair&gt;&lt;p&gt;4&lt;/p&gt;&lt;d&gt;4&lt;/d&gt;&lt;tb&gt;0.02025&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;4&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;5&lt;/p&gt;&lt;d&gt;5&lt;/d&gt;&lt;tb&gt;0.02025&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="5" backarcs="1" weight="16.097" alt=""&gt;
      &lt;pair&gt;&lt;p&gt;1&lt;/p&gt;&lt;d&gt;1&lt;/d&gt;&lt;tb&gt;0.036&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;4&lt;/p&gt;&lt;d&gt;4&lt;/d&gt;&lt;tb&gt;0.036&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;3&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;2&lt;/p&gt;&lt;d&gt;2&lt;/d&gt;&lt;b&gt;0&lt;/b&gt;&lt;tb&gt;0.025&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="6" backarcs="1" weight="8.061" alt="7"&gt;
      &lt;pair&gt;&lt;p&gt;1&lt;/p&gt;&lt;d&gt;1&lt;/d&gt;&lt;tb&gt;0.036&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;4&lt;/p&gt;&lt;d&gt;4&lt;/d&gt;&lt;tb&gt;0.016&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;3&lt;/p&gt;&lt;d&gt;3&lt;/d&gt;&lt;b&gt;1&lt;/b&gt;&lt;tb&gt;0.009&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="7" backarcs="1" weight="8.061" alt="6"&gt;
      &lt;pair&gt;&lt;p&gt;1&lt;/p&gt;&lt;d&gt;1&lt;/d&gt;&lt;tb&gt;0.036&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;4&lt;/p&gt;&lt;d&gt;4&lt;/d&gt;&lt;tb&gt;0.016&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;3&lt;/p&gt;&lt;d&gt;6&lt;/d&gt;&lt;b&gt;2&lt;/b&gt;&lt;tb&gt;0.009&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="8" backarcs="2" weight="12.0865" alt=""&gt;
      &lt;pair&gt;&lt;p&gt;2&lt;/p&gt;&lt;d&gt;2&lt;/d&gt;&lt;b&gt;3&lt;/b&gt;&lt;tb&gt;0.03025&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;5&lt;/p&gt;&lt;d&gt;5&lt;/d&gt;&lt;b&gt;4&lt;/b&gt;&lt;tb&gt;0.02025&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;4&lt;/p&gt;&lt;d&gt;4&lt;/d&gt;&lt;&lt;tb&gt;0.036&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;3&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="9" backarcs="1" weight="8.0785" alt="10"&gt;
      &lt;pair&gt;&lt;p&gt;3&lt;/p&gt;&lt;d&gt;3&lt;/d&gt;&lt;tb&gt;0.04225&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;5&lt;/p&gt;&lt;d&gt;5&lt;/d&gt;&lt;b&gt;4&lt;/b&gt;&lt;tb&gt;0.02025&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;4&lt;/p&gt;&lt;d&gt;4&lt;/d&gt;&lt;tb&gt;0.016&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
    &lt;cycle id="10" backarcs="1" weight="8.0785" alt="9"&gt;
      &lt;pair&gt;&lt;p&gt;3&lt;/p&gt;&lt;d&gt;6&lt;/d&gt;&lt;tb&gt;0.04225&lt;/tb&gt;&lt;dif&gt;3&lt;/dif&gt;&lt;s&gt;1&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;5&lt;/p&gt;&lt;d&gt;5&lt;/d&gt;&lt;b&gt;4&lt;/b&gt;&lt;tb&gt;0.02025&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
      &lt;pair&gt;&lt;p&gt;4&lt;/p&gt;&lt;d&gt;4&lt;/d&gt;&lt;tb&gt;0.016&lt;/tb&gt;&lt;dif&gt;0&lt;/dif&gt;&lt;s&gt;2&lt;/s&gt;&lt;/pair&gt;
    &lt;/cycle&gt;
  &lt;/all_cycles&gt;
          
  &lt;exchange_data&gt;
    &lt;entry weight="14.1045"
	       two_way_exchanges="1"
		   total_transplants="5"
		   three_way_exchanges="1"&gt;
	  &lt;description&gt;(COIN) Optimal set of exchanges&lt;/description&gt;
	  &lt;exchanges&gt;&lt;cycle&gt;1&lt;/cycle&gt;&lt;cycle&gt;8&lt;/cycle&gt;&lt;/exchanges&gt;
	&lt;/entry&gt;
  &lt;/exchange_data&gt;
&lt;/output&gt;
&lt;/data&gt;
       </pre>
      <p>The <code>&lt;algorithm&gt;</code> element contains a description of the algorithm that was run. In this
      case, as we ran the algorithm with <code>operation optimal</code>, the text states that we have returned an optimal
      matching as defined in the <%= link_to 'optimality criteria', {:action => 'optimality'} %> section.</p>

      <p>Next, <code>&lt;all_cycles&gt;</code> contains the set of all possible cycles for this data set. An
      individual cycle is represented by a <code>&lt;cycle&gt;</code> element. For example:
        <pre class="brush: xml">
&lt;cycle id="6" backarcs="1" weight="8.061" alt="7"&gt;
  &lt;pair&gt;
    &lt;p&gt;1&lt;/p&gt;
    &lt;d&gt;1&lt;/d&gt;
    &lt;tb&gt;0.036&lt;/tb&gt;
    &lt;dif&gt;3&lt;/dif&gt;
    &lt;s&gt;2&lt;/s&gt;
  &lt;/pair&gt;
  &lt;pair&gt;
    &lt;p&gt;4&lt;/p&gt;
    &lt;d&gt;4&lt;/d&gt;
    &lt;tb&gt;0.016&lt;/tb&gt;
    &lt;dif&gt;0&lt;/dif&gt;
    &lt;s&gt;2&lt;/s&gt;
  &lt;/pair&gt;
  &lt;pair&gt;
    &lt;p&gt;3&lt;/p&gt;
    &lt;d&gt;3&lt;/d&gt;
    &lt;b&gt;1&lt;/b&gt;
    &lt;tb&gt;0.009&lt;/tb&gt;
    &lt;dif&gt;0&lt;/dif&gt;
    &lt;s&gt;3&lt;/s&gt;
  &lt;/pair&gt;
&lt;/cycle&gt;
        </pre>

      <p>Here we have a three-way exchange (as the cycle element contains three <code>&lt;pair&gt;</code> elements), and this
      cycle has a (group) <code>id</code> of 6. The id here is used to uniquely identify the cycle.  The cycle also
      has a single backarc (<code>backarcs="1"</code> attribute) and has weight 8.061 (<code>weight="8.061"</code> attribute). The final
      attribute of the <code>&lt;cycle&gt;</code> element is <code>alt</code>: this holds a comma separated list of alternative
      cycles to this one. An alternative cycle is a cycle with the the same set of patients, but contains
      at least one different donor (this can only happen if at least one of the patients has multiple donors). In
      the example, there is only one alternative cycle to 6, which is the cycle with id 7. If there were multiple
      choices of alternative cycles then the attribute would take the form <code>alt="5,9,10"</code>.</p>

      <p>The final attribute that may be included with a <code>&lt;cycle&gt;</code> element is <code>altruistic</code>. This
      attribute holds a boolean value that indicates whether the cycle contains an altruistic donor. If the attribute is not
      specified then we take this to mean that there are no altruistic donors in the cycle.</p>

      <p>The <code>&lt;pair&gt;</code> elements that form the content of <code>&lt;cycle&gt;</code> hold
      information about the participants in a cycle, whether it contains an embedded pairwise exchange (and if so specifies
      the id of the embedded exchange ) or if any of the donors are altruistic
      (the order of the <code>&lt;pair&gt;</code> elements indicate the direction of the cycle).
      In our example above the cycle with id 4 is a three-way exchange involving patients 1, 4 and 3. We identify the
      patients by inspecting the value of each <code>&lt;p&gt;</code> element of a <code>&lt;pair&gt;</code>. A patient's
      respective donor is found in the sibling element <code>&lt;d&gt;</code> of the patient. Furthermore,
      we can establish if a backarc exists between two (donor,patient) pairs by checking for the existence of the <code>&lt;b&gt;</code>
      element of a pair. If a <code>&lt;pair&gt;</code> element contains a <code>&lt;b&gt;</code> tag this indicates
      that an embedded two-way exists between this (donor,patient) pair and the next pair in the list
      (or the first in the case where the last <code>&lt;pair&gt;</code> contains the <code>&lt;b&gt;</code> element).
      The value stored in this <code>&lt;b&gt;</code> element holds the group id of the embedded pairwise exchange.
      We note that the embedded pairwise exchange need not be between the donors who make up the three-way exchange.
      If it is indeed not made up of donors from the three-way exchange it will hold the id of the pairwise exchange
      with the largest score. The final three items in the <code>&lt;pair&gt;</code> element hold the tie breaker
      calculation (<code>&lt;tb&gt;</code>), the donor-to-donor age difference points (<code>&lt;dif&gt;</code>), and the
      original score passed into the algorithms (<code>&lt;s&gt;</code>) between
      this (donor, patient) pair and the next (donor,patient) pair on the list. So in the example above we have that
      the donor-to-donor age difference points between the first two pairs in the three-cycle (that is, the pairs containing donors
      1 and 4) is 3 and the tie breaker score between these pairs is 0.036 with the original score passed into the algorithms
      between these two (donor,patient) pairs being 2.<p>

      <p>So looking at cycle 6 above we have that donor 1 for patient 1 gives a kidney to patient 4, patient 4's
      donor with id 4 then gives a kidney to patient 3, whose donor with id 3 gives a kidney to patient 1, completing
      the three-way exchange. We note that in the final <code>&lt;pair&gt;</code> element <code>&lt;b&gt;</code> has the
      value 1, this indicates that there exists an embedded two-way between patient 1 and patient 3 and this embedded
        two-way has id 2.</p>

    <p>It is also possible that a <code>&lt;pair&gt;</code> element may contain a child element <code>&lt;a&gt;</code>.
    An example is shown below:</p>

    <pre class="brush: xml">
&lt;cycle id="15" backarcs="1" weight="12.0845" alt="" altruistic="true"&gt;
  &lt;pair&gt;
    &lt;d&gt;12&lt;/d&gt;
    &lt;b&gt;false&lt;/b&gt;
    &lt;a&gt;true&lt;/a&gt;
    &lt;tb&gt;0.04225&lt;/tb&gt;
    &lt;dif&gt;3&lt;/dif&gt;
    &lt;s&gt;3&lt;/s&gt;
  &lt;/pair&gt;
  &lt;pair&gt;
    &lt;p&gt;4&lt;/p&gt;
    &lt;d&gt;4&lt;/d&gt;
    &lt;tb&gt;0.04225&lt;/tb&gt;
    &lt;dif&gt;3&lt;/dif&gt;
    &lt;s&gt;3&lt;/s&gt;
  &lt;/pair&gt;
&lt;/cycle&gt;
    </pre>

    <p>The element <code>&lt;a&gt;</code> in the first <code>&lt;pair&gt;</code> element above
    indicates that donor 12 is an altruistic donor. We note that since the donor is altruistic, the <code>&lt;pair&gt;</code>
      need not contain a <code>&lt;p&gt;</code> element.</p>

      <p>The set of exchanges returned by the service can be found within <code>&lt;exchange_data&gt;</code>.
      This element consists of a single item named <code>entry</code> that has four attributes. The first
      attribute, <code>weight</code>, holds the total weight of the set of cycles that make up this exchange set.
      The attributes <code>two_way_exchanges</code> and <code>three_way_exchanges</code> hold the number
      of two-way and three-way exchanges in this set of exchanges respectively. The attribute <code>total_transplants</code>
      holds the total number of transplants that would take place if each of the two-way and
      three-way exchanges were to go ahead - it does not include the number of unmatched altruistic donors.</p>

      <p>The first child element (<code>&lt;description&gt;</code>) of <code>&lt;entry&gt;</code> contains information about the
        algorithm that was run - in the example above the COIN Integer Programming algorithm was used to find the optimal
        set of exchanges. The ids of the cycles that make up the optimal set of exchanges
        are found in the <code>&lt;cycle&gt;</code> elements of <code>&lt;exchanges&gt;</code>. We therefore have in the
        example above that the set of exchanges consists of one pairwise and one 3-way exchange, the pairwise exchange has
        id 1 (line 56) and the 3-way exchange has id 8 (line 57). That is, the pairwise consists of patients 1 and 3
        with donors 1 and 3 respectively, and the 3-way consists of patients 2, 5, and 4 with donors 2, 5 and 4
        respectively. The pairwise has weight 2.018 and the 3-way has weight 12.0865 with two embedded pairwise exchanges
        (with ids 3 and 4 respectively). </p>

    </div>

    <div id="xml_errors">
    <h4>Errors</h4>
     <p>If an error occurs during the processing of a request then an error message is normally sent back to the
     user. A sample error message is shown below:</p>

      <pre class="brush: xml">
&lt;data&gt;
  &lt;algorithm&gt;
        Optimal set of exchanges
  &lt;/algorithm&gt;
  &lt;error&gt;
    Unrecognised operation passed to program, must be one of optimal,
    maxcard, or pairs.
  &lt;/error&gt;
&lt;/data&gt;
      </pre>

      <p>The <code>&lt;algorithm&gt;</code> element will provide a description of the algorithm being run. More
      important is the <code>&lt;error&gt;</code> element which provides a text-based description of the
      actual error that took place.</p>
  </div>
 </div>

  <div id="json" class="formats">
    <h3>JSON</h3>
    <p>
      In addition to XML, the REST API also supports JSON as an output format. JSON provides a more concise way
      of modelling the output data and can save a significant number of bytes especially for large datasets.
    </p>
    <div id="json_output">
    <h4>Output</h4>
      <p>
        Below we give an example of a set of input parameters to the <code>find.json</code> REST API call
        and show the resulting data output by the service using these parameters.</p>

      <dl>
        <dt><code>data</code></dt>
        <dd><pre>
{ "data" :
  {
    "1" : { "sources" : [1],
            "dage" : 65,
            "matches" : [ { "recipient" : 2, "score" : 3},
                          { "recipient" : 3, "score" : 1},
                          { "recipient" : 4, "score" : 2} ]},
    "2" : { "sources" : [2],
            "dage" : 45,
            "matches" : [ { "recipient" : 1, "score" : 2},
                          { "recipient" : 5, "score" : 1} ]},

    "3" : { "sources" : [3],
            "dage" : 25,
            "matches" : [ { "recipient" : 1, "score" : 1},
                          { "recipient" : 5, "score" : 1} ]},

    "4" : { "sources" : [4],
            "dage" : 55,
            "matches" : [ { "recipient" : 2, "score" : 3},
                          { "recipient" : 3, "score" : 2},
                          { "recipient" : 5, "score" : 4} ]},

    "5" : { "sources" : [5],
            "dage" : 30,
            "matches" : [ { "recipient" : 2, "score" :	1},
                          { "recipient" : 4, "score" : 2} ]},

    "6" : { "sources" : [3],
            "dage" : 25,
            "matches" : [ { "recipient" : 1, "score" : 1},
                          { "recipient" : 5, "score" : 1} ]}

  }
}
        </pre></dd>
        <dt><code>operation</code></dt>
        <dd><pre>optimal</pre></dd>
      </dl>

        <pre class="brush: js">
{ "algorithm" : "Optimal set of exchanges with respect to the optimality criteria",
  "output" :
    { "all_cycles": {
        "0": {"cycle": [{"p": 1,"d": 1,"tb": 0.025,"dif": 3,"s": 3},
                        {"p": 2,"d": 2,"tb": 0.025,"dif": 3,"s": 2}],
              "backarcs": 0,
              "weight": 11.05,
              "alt": []},

        "1": {"cycle": [{"p": 1,"d": 1,"tb": 0.009,"dif": 0,"s": 1},
                        {"p": 3,"d": 3,"tb": 0.009,"dif": 0,"s": 1}],
              "backarcs": 0,
              "weight": 2.018,
              "alt": [2]},

        "2": {"cycle": [{"p": 1,"d": 1,"tb": 0.009,"dif": 0,"s": 1},
                        {"p": 3,"d": 6,"tb": 0.009,"dif": 0,"s": 1}],
              "backarcs": 0,
              "weight": 2.018,
              "alt": [1]},

        "3": {"cycle": [{"p": 2,"d": 2,"tb": 0.03025,"dif": 3,"s": 1},
                        {"p": 5,"d": 5,"tb": 0.03025,"dif": 3,"s": 1}],
              "backarcs": 0,
              "weight": 8.0605,
              "alt": []},
          
        "4": {"cycle": [{"p": 4,"d": 4,"tb": 0.02025,"dif": 0,"s": 4},
                        {"p": 5,"d": 5,"tb": 0.02025,"dif": 0,"s": 2}],
              "backarcs": 0,
              "weight": 6.0405,
              "alt": []},

        "5": {"cycle": [{"p": 1,"d": 1,"tb": 0.036,"dif": 3,"s": 2},
                        {"p": 4,"d": 4,"tb": 0.036,"dif": 3,"s": 3},
                        {"p": 2,"d": 2,"b": 0,"tb": 0.025,"dif": 3,"s": 2}],
              "backarcs": 1,
              "weight": 16.097,
              "alt": []},

        "6": {"cycle": [{"p": 1,"d": 1,"tb": 0.036,"dif": 3,"s": 2},
                        {"p": 4,"d": 4,"tb": 0.016,"dif": 0,"s": 2},
                        {"p": 3,"d": 3,"b": 1,"tb": 0.009,"dif": 0,"s": 1}],
              "backarcs": 1,
              "weight": 8.061,
              "alt": [7]},

        "7": {"cycle": [{"p": 1,"d": 1,"tb": 0.036,"dif": 3,"s": 2},
                        {"p": 4,"d": 4,"tb": 0.016,"dif": 0,"s": 2},
                        {"p": 3,"d": 6,"b": 2,"tb": 0.009,"dif": 0,"s": 1}],
              "backarcs": 1,
              "weight": 8.061,
              "alt": [6]},

        "8": {"cycle": [{"p": 2,"d": 2,"b": 3,"tb": 0.03025,"dif": 3,"s": 1},
                        {"p": 5,"d": 5,"b": 4,"tb": 0.02025,"dif": 0,"s": 2},
                        {"p": 4,"d": 4,"tb": 0.036,"dif": 3,"s": 3}],
              "backarcs": 2,
              "weight": 12.0865,
              "alt": []},

        "9": {"cycle": [{"p": 3,"d": 3,"tb": 0.04225,"dif": 3,"s": 1},
                        {"p": 5,"d": 5,"b": 4,"tb": 0.02025,"dif": 0,"s": 2},
                        {"p": 4,"d": 4,"tb": 0.016,"dif": 0,"s": 2}],
              "backarcs": 1,
              "weight": 8.0785,
              "alt": [10]},
          
        "10": {"cycle": [{"p": 3,"d": 6,"tb": 0.04225,"dif": 3,"s":: 1},
                         {"p": 5,"d": 5,"b": 4,"tb": 0.02025,"dif": 0,"s": 2},
                         {"p": 4,"d": 4,"tb": 0.016,"dif": 0,"s": 2}],
               "backarcs": 1,
               "weight": 8.0785,
               "alt": [9]}},

      "exchange_data": [
          { "description": "(COIN) Optimal set of exchanges",
            "exchanges": [1,8],
            "weight": 14.1045,
            "two_way_exchanges": 1,
            "total_transplants": 5,
            "three_way_exchanges": 1 } ]
     }
 }
</pre>
      
      <p>As we can see the <code>algorithm</code> element contains a description of the algorithm that was run. In this
      case as we ran the algorithm with <code> operation optimal</code>, the text indicates that we have returned a set of optimal
      exchanges as defined in the <%= link_to 'optimality criteria', {:action => 'optimality'} %> section.</p>

      <p>Next, <code>all_cycles</code> contains the set of all possible cycles for this data set. Each key in this
        object corresponds to a group id for the cycle, and this id is used to uniquely identify a cycle. In the example
        output above we can see that the first element in <code>all_cycles</code> represents a cycle with id 0. At this
        node we hold information about cycle 0, in particular we can see the (donor,patient) pairs that are involved in
        a cycle (the <code>cycle</code> key), the number of backarcs in the cycle (the <code>backarcs</code> key),
        the weight of the cycle (the <code>weight</code> key)
        and whether there are any cycles that are alternatives to this one (the <code>alt</code> key). The contents of both
        the <code>backarcs</code> and <code>weight</code> keys are obvious, therefore we concentrate on the
        <code>cycle</code> and <code>alt</code> keys.</p>

      <p>The <code>cycle</code> key holds information about the patients (the <code>p</code> key) and their corresponding donors
      (the <code>d</code> key) that are involved in a cycle. Taking the cycle with id 5 as an example, we can see that cycle 5 is
      a 3-way exchange, as the <code>cycle</code> array consists of three elements, and involves patients 1, 4 and 2 - as these
        are the values stored against each key <code>p</code> in the array. The order that the (donor,patient) pairs appear
        in the array is important and indicates the direction of the exchange. Furthermore, we observe that each <code>p</code> element
      has a sibling <code>d</code> that holds the id of their donor. If the cycle is a 3-way exchange then the object
      may also contain a <code>b</code> element. This element indicates the presence of an embedded two-way. As an example
        of the use of the keys <code>d</code> and <code>b</code> we use cycle 5 again above.
        Here we can see that the donors for patients 1, 4, and 2 are donors with ids 1, 4 and 2 respectively 
        (the donor ids need not be the same as the
        patient ids, they just happen to be in this example). Cycle 5 also contains an embedded pairwise exchange between
        (donor,patient) pairs (1,1) and (2,2). This can be seen in the output by observing the fact that the last
        element in the cycle array has the value 0 for <code>b</code>. This means that there exists an embedded pairwise exchange
        between the corresponding (donor,patient) pair in the array and the next (donor,patient) pair in the array, or in this case
        as this is the last pair, it's between the final pair and the first. In particular, we can identify the embedded
      pairwise exchange from the value stored in <code>b</code>, so for cycle 5 we have that the embedded pairwise
      exchange has id 0. We note that an embedded pairwise exchange need not contain any of the donors from the original
      cycle. The final three elements in the objects that make up the cycle array are <code>tb</code>, <code>dif</code> and <code>s</code>
      The value held against the <code>tb</code> key holds the tie breaker calculation between this element and the
      next in the array, similarly <code>dif</code> holds the donor-to-donor age difference points between these two
      elements. Finally <code>s</code> holds the original score between this element and the next in the array, this is the
      same score that was passed in as part of the input data.
      As in the case of key <code>b</code>, the values of <code>tb</code>, <code>dif</code> and <code>s</code> for the last
      element in the array describe the tie breaker calculation and donor-to-donor age difference between the final
      element and the first.</p>


        <p>Each cycle also contains the key <code>alt</code> that holds an array of ids. These integers correspond to the
          ids of other cycles within the <code>all_cycles</code> structure that are an alternative to this one. That is,
          there exists an alternative where the same set of patients are involved in the exchange, but the alternative contains
          at least one different donor (this can only happen if at least one of the patients has multiple donors). This
          information is useful if, say, a donor becomes ill and cannot provide a kidney for transplantation.
          To find an alternative donor (or in fact cycle) we need only look at the <code>alt</code> array to see if
          there are any possible alternatives to the current cycle.</p>

      <p>It may be the case that the cycle is tagged with the <code>altruistic</code> key as shown below.</p>

      <pre class="brush: js">
"15": {"cycle": [{"d": 12,"a": true,"tb": 0.02025,"dif": 0,"s": 2},
                 {"p": 3,"d": 3,"tb": 0.02025,"dif": 0,"s": 1}],
      "backarcs": 0,
      "weight": 2.018,
      "altruistic": true,
      "alt": [2]},
      </pre>

      <p>The <code>altruistic</code> key on the object above indicates that the cycle with id 15
      contains an altruistic donor. We can identify this altruistic donor by inspecting the <code>cycle</code>
      object and observing the the first object in the array now includes a key <code>a</code> with value true. In general,
      if the donor is not altruistic then there will be no <code>a</code> key in the object; similarly if the cycle does
      not contain an altruistic donor, then the <code>altruistic</code> key will not be present.
      Therefore looking at the example above, we can see that
      the donor with id 1 is an altruistic donor (note there is no <code>p</code> element here) whereas donor 3
      is just a regular donor. We now describe the actual set of exchanges returned by the service.</p>

      <p>The calculated set of exchanges are returned as part of the <code>exchange_data</code> array - at the moment this array will
        only consist of a single object. In the example above this object provides a <code>description</code> of
        the optimality criteria used, the total weight of the exchange set (<code>weight</code>), the number of pariwise exchanges
        (<code>two_way_exchanges</code>), the number of 3-way exchanges(<code>three_way_exchanges</code>),
        and the total number of transplants (<code>total_transplants</code>) that would take place
        if all pairwise and 3-way exchanges were to go ahead - it does not include the number of unmatched altruistic donors. The final member of this object holds the key
        information about the optimal set of cycles. In the example above, we can see that <code>exchanges</code>
        contains the array <code>[1,8]</code>. This means that for this dataset there are two cycles in the optimal
        set of exchanges, namely the cycle with id 1 and the cycle with id 7. Looking at the information on the cycles held in the
        <code>all_cycles</code> object, we can see that the cycle with id 1 is a pairwise exchange and contains patients 1 and 3 with donors 1 and 3 respectively.
        There is an alternative to this cycle, cycle 2, that contains donors 1 and 6 for patients 1 and 3 respectively.
        Cycle 8 is a 3-way exchange that contains patients 2, 5 and 4 and donors 2, 5 and 4 respectively. Here donor 2 for patient
        2 gives a kidney to patient 5, patient 5's donor with id 5 gives a kidney to patient 4, and patient 4's donor
        with id 4 gives a kidney to patient 2.
    </div>

    <div id="json_errors">
    <h4>Errors</h4>
     <p>If an error occurs during the processing of a request then an error message is normally sent back to the
     user. A sample error message is shown below:</p>
      <pre class="brush: js">
        { "algorithm" : "Set of all possible exchanges from pairwise up to the optimal solution",
          "output" : "Unrecognised operation passed to program, must be one of optimal,
                      maxcard, or pairs" }
      </pre>

      <p>The <code>algorithm</code> element provides a description of the algorithm being run. More
      important is the <code>error</code> value, this will provide a text based description of the
      actual error that took place</p>
    </div>
 </div>
</div>
