kep_solver.entities module

This module contains entities (such as Donors, Recipients) within a KEP, as well as the encapsulating Instance objects

exception KEPDataValidationException

Bases: Exception

An exception that is raised when invalid data requests are made. This can happen if properties (such as blood group or cPRA) are requested when they are not known, or if changes are attempted on such properties.

exception KEPSolveFail

Bases: Exception

An exception that is raised when solving fails. This should only really be happening if the user sets a solver time limit, and this time limit is reached, but this is not guaranteed.

class BloodGroup(value)

Bases: Enum

The Blood groups of a participant in a KEP.

O = 0
A = 1
B = 2
AB = 3
static all()
Return type:

ValuesView[BloodGroup]

static from_str(bloodGroupText)

Given a blood group as text, return the corresponding BloodGroup object.

Parameters:

bloodGroupText (str) – the text

Return type:

BloodGroup

Returns:

the BloodGroup

class Status(value)

Bases: Enum

A status indicator for either a donor or a recipient.

InPool = 'In Pool'
Left = 'Left'
Selected = 'Selected'
NotYetArrived = 'Not Yet Arrived'
Transplanted = 'Transplanted'
class Recipient(id)

Bases: object

A recipient in a KEP instance.

__init__(id)
status: Status

The status of this recipient.

property: dict[str, Any]

A dictionary that can store arbitrary properties related to this recipient.

longstr()

A longer string representation.

Return type:

str

Returns:

a string representation

property id: str

Return the ID of this recipient.

property age: float

The age of this recipient (in years), fractions allowed.

property cPRA: float

The cPRA of this recipient, as a value between 0 and 1.

You may have to divide by 100 if you are used to working with values from 1 to 100 inclusive.

property bloodGroup: BloodGroup

The Blood groups of this recipient.

property compatibilityChance: float

The Compatibility chance of this Recipient. In other words, what is the likelihood that this recipient will be transplant-compatible with an arbitrary donor who is ABO compatible.

inPool()

Return True if and only if this recipient is in this pool. This is true if this recipient has a status of InPool and at least one of their donors has this status too.

Return type:

bool

addDonor(donor)

Add a paired donor for this recipient.

Parameters:

donor (Donor) – The donor to add

Return type:

None

donors()

The list of donors paired with this recipient

Return type:

list[Donor]

Returns:

the list of donors

hasBloodCompatibleDonor()

Return true if the recipient is paired with at least one donor who is blood-group compatible with this recipient.

Return type:

bool

Returns:

true if the recipient has a blood-group compatible donor

pairedWith(donor)

Return true if the given donor is paired with this recipient.

Parameters:

donor (Donor) – The donor in question

Return type:

bool

Returns:

true if the donor is paired with this recipient

class Donor(id)

Bases: object

A donor (directed or non-directed) in an instance.

__init__(id)

Construct a Donor object. These are assumed to be directed, this can be changed with the NDD instance variable.

Parameters:

id (str) – An identifier for this donor.

status

The status of this donor.

property: dict[str, Any]

A dictionary that can store arbitrary properties related to this donor.

longstr()

A longer string representation.

Returns:

a string representation

property id: str

Return the ID of this donor.

property age: float

The age of the donor (in years), fractions allowed.

property bloodGroup: BloodGroup

The donor’s Blood groups

property recipient: Recipient

The recipient paired with this donor.

inPool()

Return True if and only if this donor is in this pool. This is true if this donor has a status of InPool and their recipient has this status too.

Return type:

bool

bloodGroupCompatible(recipient)

Is this donor blood-group compatible with the given recipient.

Parameters:

recipient (Recipient) – the recipient in question

Return type:

bool

Returns:

True if the donor is blood-group compatible with the given recipient

addTransplant(transplant)

Add a potential transplant from this donor.

Parameters:

transplant (Transplant) – the transplant object

Return type:

None

getTransplantTo(recipient)

Return the transplant from this donor to the given recipient.

Parameters:

recipient (Recipient) – The recipient in question.

Return type:

Transplant

Returns:

The transplant in question.

transplants()

Return the list of transplants associated with this Donor.

Return type:

list[Transplant]

Returns:

A list of transplants

class Transplant(donor, recipient, weight)

Bases: object

A potential transplant.

__init__(donor, recipient, weight)
property donor: Donor
property recipient: Recipient
property weight: float
class OutputFormat(value)

Bases: Enum

An enumeration.

JSON = 1
XML = 2
YAML = 3
class Instance(donors=<factory>, recipients=<factory>)

Bases: object

A KEP instance.

donors: MutableMapping[str, Donor]

A mapping (dictionary) from donor IDs to the donors in this instance.

recipients: MutableMapping[str, Recipient]

A mapping (dictionary) from recipient IDs to the recipients in this instance.

property transplants: list[Transplant]

Return all transplants relevant for this instance.

activeTransplants()

Return all transplants relevant for this instance.

Return type:

list[Transplant]

addDonor(donor)

Add a donor to the instance.

Parameters:

donor (Donor) – The Donor being added

Return type:

None

recipient(id, create=True)

Get a recipient from the instance by ID. If the recipient does not exist, create one with no details.

Parameters:
  • id (str) – the ID of the recipient

  • create (bool) – If True, will create recipient if it doesn’t exist. If False, and the recipient does not exist, will raise an exception.

Return type:

Recipient

Returns:

the recipient

addRecipient(recipient)

Adds an already-constructed Recipient to this instance. If a recipient with the same ID already exists, this will throw an exception. This will also add the paired donors of the recipient to this instance.

Parameters:

recipient (Recipient) – The recipient to add.

Return type:

None

allRecipients()

Return a list of all recipients.

Return type:

ValuesView[Recipient]

Returns:

a list of recipients

activeRecipients()

Return a list of the recipients in the instance. These recipients must have the status InPool and so must at least one of their donors.

Return type:

list[Recipient]

Returns:

a list of donors

hasRecipient(recipient)

Return True if the given Recipient is in this instance.

Parameters:

recipient (Recipient) – The recipient in question.

Return type:

bool

Returns:

True if and only if the recipient is in this instance.

addTransplant(transplant)

Add a potential transplant to this instance.

Parameters:

transplant (Transplant) – The transplant

Return type:

None

allDonors()

Return a generator object that can iterate through donors in a list-like fashion. Note that this list cannot itself be modified.

Return type:

ValuesView[Donor]

Returns:

a list of donors

allNDDs()

Return an iterable over all non-directed donors in this instance.

Return type:

list[Donor]

Returns:

An iterable of non-directed donors

activeDonors()

Return a list of the donors who are in the pool (according to their status, and possibly the status of their paired recipient if they are a directed donor.

Return type:

list[Donor]

Returns:

a list of donors

hasDonor(donor)

Return True if the given Donor is in this instance.

Parameters:

donor (Donor) – The donor in question.

Return type:

bool

Returns:

True if and only if the donor is in this instance.

donor(id)

Return a donor by ID:

Parameters:

id (str) – a donor ID

Return type:

Donor

Returns:

the donor

writeFile(filename, file_format, compressed=True)

Write the instance to a file of the given format.

Parameters:
  • filename (str) – The name of the file to write

  • file_format (OutputFormat) – The file format to use. Currenly only JSON is supported

  • compressed (bool) – Should the file saved as a compressed file (using LZMA compression as a .xz file)

Return type:

None

writeFileXml(filename, compressed)

Write the instance to an XML file

Parameters:
  • filename (str) – The name of the file to write

  • compressed (bool) – Should the file saved as a compressed file (using LZMA compression as a .xz file)

Return type:

None

writeFileJson(filename, write_recipients=False, compressed=True)

Write the instance to a JSON file, where recipient data (e.g., blood types and cPRA of recipients) are included only if the parameter write_recipients is True

Parameters:
  • filename (str) – The name of the file to write

  • write_recipients (bool) – If True, also write the recipient data to the file

  • compressed (bool) – Should the file saved as a compressed file (using LZMA compression as a .xz file)

Return type:

None

writeFileYaml(filename, compressed)

Write the instance to a YAML file

Parameters:
  • filename (str) – The name of the file to write

  • compressed (bool) – Should the file saved as a compressed file (using LZMA compression as a .xz file)

Return type:

None

__init__(donors=<factory>, recipients=<factory>)
class InstanceSet(instances)

Bases: object

A set of instances that can be analysed for statistical properties.

__init__(instances)

Constructor for InstanceSet.

Parameters:

instances (list[Instance]) – The set of instances.

donor_details()

Extract a table of donor properties from this set.

Return type:

DataFrame

Returns:

A pandas DataFrame with the following table headers. donor_id donor_bloodgroup paired_recipient_bloodgroup is_ndd

recipient_details(calculate_compatibility=True)

Extract a table of donor properties from this set.

Parameters:

calculate_compatibiltiy – If True (default), this function will calculate the compatibility chance for each recipient. Otherwise, each recipient must have compatibility chance already determined.

Return type:

DataFrame

Returns:

A pandas DataFrame with the following table headers. * recipient_id * recipient_bloodgroup * cPRA * compatibility_chance * num_donors * has_abo_compatible_donor

class DynamicInstance(donors=<factory>, recipients=<factory>, recipient_arrivals=<factory>, recipient_departures=<factory>, recipient_temporary_departures=<factory>, ndd_arrivals=<factory>, ndd_departures=<factory>, ndd_temporary_departures=<factory>, failing_transplants=<factory>)

Bases: Instance

A dynamic KEP instance, that includes when participants arrive, depart, or are ill, as well as which transplants will pass a virtual crossmatch but fail a laboratory-based crossmatch.

Parameters:
  • recipients (MutableMapping[str, Recipient]) – The recipients in the instance.

  • donors (MutableMapping[str, Donor]) – The non-directed donors in the instance.

  • transplants – The transplants in the instance.

  • recipient_arrivals (MutableMapping[str, int]) – A mapping from recipient IDs to the period in which they arrive

  • recipient_departures (MutableMapping[str, int]) – A mapping from recipient IDs to the period in which they depart

  • recipient_temporary_departures (MutableMapping[str, list[int]]) – A mapping from recipient IDs to a list of periods in which said recipient is ill.

  • ndd_arrivals (MutableMapping[str, int]) – A mapping from non-directed donor IDs to the period in which they arrive

  • ndd_departures (MutableMapping[str, int]) – A mapping from non-directed donor IDs to the period in which they depart

  • ndd_temporary_departures (MutableMapping[str, list[int]]) – A mapping from non-directed donor IDs to a list of periods in which said donor is ill.

  • failing_transplants (list[Transplant]) – A list of the transplants which will fail a laboratory crossmatch.

__init__(donors=<factory>, recipients=<factory>, recipient_arrivals=<factory>, recipient_departures=<factory>, recipient_temporary_departures=<factory>, ndd_arrivals=<factory>, ndd_departures=<factory>, ndd_temporary_departures=<factory>, failing_transplants=<factory>)
recipient_arrivals: MutableMapping[str, int]

A mapping from recipient IDs to the period in which they arrive.

recipient_departures: MutableMapping[str, int]

A mapping from recipient IDs to the period in which they depart.

recipient_temporary_departures: MutableMapping[str, list[int]]

A mapping from recipient IDs to a list of periods in which said recipient is ill.

ndd_arrivals: MutableMapping[str, int]

A mapping from non-directed donor IDs to the period in which they arrive.

ndd_departures: MutableMapping[str, int]

A mapping from non-directed donor IDs to the period in which they depart.

ndd_temporary_departures: MutableMapping[str, list[int]]

A mapping from non-directed donor IDs to a list of periods in which said donor is ill.

failing_transplants: list[Transplant]

A list of the transplants which will fail a laboratory crossmatch.

is_available(participant, period)

Return either an empty string if the participant is available, or a string containing the reason why the participant is not available if they are not available.

Parameters:
  • participant (Donor | Recipient) – The participant in question#

  • period (int) – The period in which we are querying.

Return type:

str