Help

Overview

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:


  1. How to perform a matching run
  2. Input parameters
  3. How to add/remove a matching run
  4. How to add/remove a constraint
  5. Description of the output data
  6. Short hand notation for describing constraints
  7. Downloading the data

How to perform a matching run

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.

Input Parameters

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.

How to add/remove a matching run

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.

How to add/remove a constraint

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.

Description of the output data

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.


Short hand notation for describing constraints

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


Downloading the data

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.