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 Status(value)

Bases: Enum

A status indicator for either a donor or a recipient.

InPool = 'InPool'

Left = 'Left'

NotYetArrived = 'NotYetArrived'

Transplanted = 'Transplanted'

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.

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.

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

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

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

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

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

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

donor(id)

Return a donor by ID:

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

transplants()

Return type:: list[Transplant]

writeFile(filename, file_format)

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

Return type:

None

writeFileXml(filename)

Write the instance to an XML file

Parameters:: filename (str) – The name of the file to write
Return type:: None

writeFileJson(filename, write_recipients=False)

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

Return type:

None

writeFileYaml(filename)

Write the instance to a YAML file

Parameters:: filename (str) – The name of the file to write
Return type:: None

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