The Kidney Data Analysis Toolkit is a software tool that allows you to run multiple kidney exchange matching runs each with a different set of constraints. The results are then collated into a table to be viewed online or downloaded as a csv file. The layout of this help is as follows:

- How to perform a matching run
- Input parameters
- How to add/remove a matching run
- How to add/remove a constraint
- Description of the output data
- Short hand notation for describing constraints
- Downloading the data

On navigating to the homepage you are presented with a screen that looks similar to the following:

The page contains the section "Data" where the data to be used for the matching run is specified
- the format of the data is described here.

The section entitled "Run Data" contains the details of the matching runs to take place and the constraints involved
in a particular matching run. In the screenshot above two matching runs have been scheduled to take place. The first will find a solution
where the maximum cycle size is 2 (i.e. the solution will contain only pairwise
exchanges), the altruistic donors are allowed only in short chains (as the altruistic chain is set to involve one pair), and
we are enforcing a single constraint that simply maximises the total number of transplants. The second matching run
shown has a maximum cycle size of 3 (i.e. we want a solution that is made up of both 3-way and pairwise exchanges),
altruistic donors are allowed to be involved in long chains (as the altruistic chain is set to involve two pairs), and the solution
output is subject to two constraints, the first maximises the total number of transplants and
subject to this the second then maximises the overall weight of the solution.

Also in the "Run Data" section are the links containing a red cross like so .
The cross at the top right allows you to remove a matching run. The second cross (shown in matching run two next to the second constraint)
allows you to remove a particular constraint from a matching run. Similarly the "Add constraint" link allows you to add a
constraint to a matching run with the "Add matching run" link enabling you to add another matching run.

Any runs and their constraints set up in the "Run Data" section will be automatically saved when you hit the "Run" button. This means that if you choose to
you reload the page (F5) at any time in the future the last set of runs that were constructed will
be shown in "Run Data". At any point you can revert back to the original set of matching runs and constraints that
came pre-programmed by pressing the "Reset to default matching runs" link.

Once you have copied in the data to be used for the matching runs, and constructed the required runs you then
press the "Run" button which will run each matching run in turn reporting the data back to the screen as each
matching run completes.

Below we give a brief overview of the parameters that can be specified in the UI of the data analysis toolkit

- Data
- This is the input data to be used for each of the matching runs. The various formats that this can take are described here. Note: if you wish to include altruistic donors you must use either JSON or XML as the input format.
- Maximum cycle size
- This is the maximum length of the largest cycle to be output as part of a solution. For example, a value 2 indicates only pairwise exchanges should be considered, a value of 3 indicates that the solution can contain both pairwise exchanges and 3-cycles, and a value of 4 indicates the solution can contain pairwise exchanges, 3-cycles and 4-cycles.
- Altruistic chain length
- This is the number of pairs in the middle of an altruistic chain. If the value is set to 1 it means any altruistic chains that form part of a solution can involve only one pair (i.e. a solution can contain only short chains) and a value of 2 indicates that altruistic chains that form part of a solution may involve one or two pairs (i.e. a solution can contain both short and long chains). The value can also be set to 0 which indicates that the solution should contain no altruistic chains - this is effectively saying ignore the altruistic donors in the input data.
- Constraints
- These are a list of the constraints that should be applied to the matching run. At times a short-hand notation will be used to describe these constrains, an overview of this notation can be found here.

A matching run is represented in the UI as a grey box containing the parameters for setting the maximum cycle
size, the (maximum) altruistic chain length and the set of constraints to be used in the run. To add a new matching run
you simply click the "Add another matching run" button at the bottom of the "Run Data" section. This will add
a new box to the bottom that can be populated with the required values.

To delete a matching run you simply click the in the top right-hand side of the matching
run box. As there must be at least one matching run it is not possible to delete the first one. If the first matching
run in the UI needs to be updated you can just change the values and add/remove constraints as required.

Clicking the "Add constraint" button will add a new constraint represented by a select box containing a list of
available constraints. An example of adding and selecting a new constraint is show below.

To remove a constraint you simply click the remove icon next to the constraint
that you wish to remove. Each matching run must have a minimum of one constraint.

After pressing "Run" on the homepage you will be directed to a screen that contains a table with 16 columns. A brief
description of each column is given below:

- Run number
- This corresponds to the number next to the matching run on the data entry page. If you hover over this number a tooltip will be displayed that contains a description of the matching run that took place. This description includes the maximum cycle size, the altruistic chain length and the constraints used. The constraints are described in a short form as described in the following section.
- Total transplants
- The total number of transplants identified, this is
`2*num_2_ways + 3*num_3_ways + 2*num_short_chains + 3*num_long_chains`

- Total paired transplants
- The number of paired transplants is calculated to be the total number of transplants minus the number of transplants from chains involving altruistic donors
- Total transplants involving altruistic donors
- The number of altruistic donors that were used
- Number of unused altruistic donors
- This is the number of altruistic donors to be sent to the DDWL
- Number of 2-ways
- Number of 2-cycles in the solution that do not contain an altruistic donor
- Number of 3-ways
- Number of 3-cycles in the solution that do not contain an altruistic donor, but including the 3 ways with a embedded two-way
- Number of 3-ways with embedded
- This holds the number of 3-ways described in the previous column that have an embedded 2-way
- Number of 4-ways
- The number of 4-ways
- Number of short ADCs
- The number of short altruistic donor chains in the solution
- Number of long ADCs
- The number of long altruistic donor chains in the solution
- Effective pairwise
- The number of 2-ways plus the number of 3-ways plus the number of short and long chains
- Weight
- The total weight of the solution
- Pairs
- A link that when clicked displays the set of pairwise exchanges and short chains that belong to the solution. Each pair is represented by the following notation
`[patient_1(donor_1),patient_2(donor_2)]`

. For example,`[2(2),3(4)]`

states that donor with id 2 belonging to patient 2 gives their kidney to patient with id 3 and patient 3's donor with id 4 gives their kidney to patient 2. We note that entries that involve an altruistic donor will not contain a patient id for that donor. For example if donor with id 5 is an altruistic donor and they donate their kidney to patient 3 then the list would include the pair`[(5),3(4)]`

. - 3-ways
- A link that when clicked displays the set of 3-way exchanges and long chains that belong to the solution. The notation is similar to that described for "Pairs" above.
- 4-ways
- A link that when clicked displays the set of 4-way exchanges that belong to the solution. The notation is similar to that described for "Pairs" above.

- size
- Maximise the total number of transplants
- effective
- Maximise the effective number of pairwise exchanges
- altruistic
- Maximise the number of altruistic donors used
- 3way
- Minimise the number of 3-ways
- backarc
- Maximise the number of backarcs
- weight
- Maximise the overall weight

When all the matching runs are complete a button will appear on the screen that says "Save to disk" - shown below.
Clicking this button allows you to download the results from the matching runs to a CSV file. The CSV file contains columns
that are identical to those described in the section "Description of output data" the only difference being that
the first column is named "Description" rather than "Run number" and contains a string with the details of the
particular matching run - it's similar to the information found in the tooltip displayed.

**Note: ** If the "Save to disk" button does not appear then it is likely that you need to upgrade your versio
of Adobe Flash to the most recent version.