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:
- 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)
-
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
- 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
- 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:
- 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 weight: float
- 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 recipientcreate (
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:
- 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:
- 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 writefile_format (
OutputFormat
) – The file format to use. Currenly only JSON is supportedcompressed (
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 writecompressed (
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 writewrite_recipients (
bool
) – If True, also write the recipient data to the filecompressed (
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 writecompressed (
bool
) – Should the file saved as a compressed file (using LZMA compression as a .xz file)
- Return type:
None
- __init__(donors=<factory>, recipients=<factory>)
-
donors:
- 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 arriverecipient_departures (
MutableMapping
[str
,int
]) – A mapping from recipient IDs to the period in which they departrecipient_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 arrivendd_departures (
MutableMapping
[str
,int
]) – A mapping from non-directed donor IDs to the period in which they departndd_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.