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.

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 Recipient(id)

Bases: object

A recipient in a KEP instance.

__init__(id)

longstr()

A longer string representation.

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.

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.

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.

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

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 Instance

Bases: object

A KEP instance.

__init__(): Create a new KEP instance.

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

recipients()

Return a list of all recipients.

Return type:: ValuesView[Recipient]
Returns:: a list of recipients

addTransplant(transplant)

Add a potential transplant to this instance.

Parameters:: transplant (Transplant) – The transplant
Return type:: None

donors()

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

donor(id)

Return a donor by ID:

Parameters:: id (str) – a donor ID
Return type:: Donor
Returns:: the donor

transplants()

Return type:: list[Transplant]

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