kep_solver.generation module
Generation of KEP instances.
- class BloodGroupGenerator(dist)
Bases:
object
Generates Blood groups based on a given distribution.
- __init__(dist)
Constructor for BloodGroupGenerator.
- Parameters:
dist (
dict
[BloodGroup
,float
]) – A mapping from BloodGroup to the proportion of said blood group in a given population. Note that the sum of these proportions, across all four blood groups, must equal one.
- draw()
Draw a random blood group from the generator.
- Return type:
- Returns:
A randomly-chosen blood group, chosen with probabilities proportional to the distribution given when the generator was constructed.
- config()
The configuration of this BloodGroupGenerator: a dictionary of expected relative proportion of blood group drawn.
- Return type:
dict
[str
,float
]
- classmethod from_json(json_obj)
Create a BloodGroupGenerator from a JSON object. The JSON object should be a dictionary of key, value pairs where each key is a string representing a blood group, and the corresponding value is the proportion of people in a given population with that blood group.
- Return type:
- class DonorCountGenerator(dist)
Bases:
object
- __init__(dist)
Constructor for DonorCountGenerator.
- Parameters:
dist (
dict
[int
,float
]) – A mapping from a potential number of donors, to the expected likelihood of a recipient being paired with that many donors. Note that the sum of these proportions must equal one.
- draw()
Draw a random random number of donors.
- Return type:
int
- config()
The configuration of this DonorCountGenerator: a dictionary of expected relative proportion of recipients paired with the given number of donors.
- Return type:
dict
[int
,float
]
- classmethod from_json(json_obj)
Create a DonorCountGenerator from a JSON object. The JSON object should be a dictionary of key, value pairs where each key is a is an integer, and the corresponding value is the proportion of recipients with that number of donors.
- Return type:
- class DonorGenerator(bloodgroup_generator, *, recipient_o_generator=None, recipient_a_generator=None, recipient_b_generator=None, recipient_ab_generator=None)
Bases:
object
Generates Donors. Note that it is possible to configure such a generator so that the blood group is drawn from different distributions depending on the blood group of a paired recipient.
- __init__(bloodgroup_generator, *, recipient_o_generator=None, recipient_a_generator=None, recipient_b_generator=None, recipient_ab_generator=None)
Construct a DonorGenerator object. Note that the donor distributions that depend on the recipient BloodGroup must be specified by parameter name to avoid mis-matching.
- draw(name, recipient_bg=None)
Draw a donor from this generator.
- Parameters:
name (
str
) – A name (or ID) for this donorrecipient_bg (
Optional
[BloodGroup
]) – The blood group of the paired recipient. This may be used to adapt the distribution of donor blood group based on the blood group of the paired recipient.
- Return type:
- config()
Returns the configuration of this DonorGenerator.
- Return type:
dict
[str
,dict
[str
,float
]]- Returns:
a dictionary with keys that are either “Generic”, or one of “O”, “A”, “B”, or “AB”. The entry for each key gives the distribution of BloodGroup for donors, across all donors if the key is “Generic” or otherwise dependent on the recipient BloodGroup.
- classmethod from_json(json_obj)
Create a DonorGenerator from a JSON object. The JSON object should be a dictionary of key, value pairs where each key is a a string (one of “Generic”, “O”, “A”, “B”, or “AB”) and the corresponding value is the configuration of a BloodGroupGenerator that generates blood groups. The “Generic” blood group is required, but the other generators are optional.
- Return type:
- class FloatGenerator(*, bands=None, bandString=None)
Bases:
object
A FloatGenerator generates floating point values in the range [0, 1] based on a pre-defined distribution amongst a population. In particular, the range [0, 1] is split up into bands, each of which is either a singular value or a range of values. Each such band has an associated probability of occuring amongst the designated population.
These can represent either distributions of cPRA amongst recipients, or alternatively the distribution of compatibility chance amongst a population.
- __init__(*, bands=None, bandString=None)
Construct a FloatGenerator object.
Note that exactly one of bands or bandStrings must be passed to the constructor, and it must be passed by parameter name
- Parameters:
bands (
Optional
[dict
[tuple
[float
,float
],float
]]) – A set of bands.bandString (
Optional
[str
]) – A string representing a set of bands. This parameter exists for compatibility with other software.
- draw()
Draw a value from this set of bands. The band is chosen based on the probability of each band occuring using a uniform distribution. If the band is a singular value, then that value is returned, otherwise a value in the band is chosen uniformly at random and returned.
Note that in particular, the returned value will lie in the range [0, 1].
- Return type:
float
- Returns:
a floating point value in the range [0, 1]
- config()
Returns the configuration of this FloatGenerator.
- Return type:
list
[list
[Union
[list
[float
],float
]]]- Returns:
a list of the bands that define this FloatGenerator. Each list must have two elements. The first is a list containing either [low, high] values or one exact [value], and the second is the probability, such that the chance of the cPRA being either exactly value, or drawn uniformly between low and high, is given by said probability.
- classmethod from_json(json_obj)
Create a FloatGenerator from a JSON object. The JSON object should contain a list of bands, where each band is itself a list containing two items. The first of these is another list with either one or two items. If it contains only one item, this band only corresponds to one floating point value, but if it contains two, it corresponds to the range between the first and second item. The second item in each band is the probability that this band is selected.
- Return type:
- class CompatibilityChanceGenerator(*, dists)
Bases:
object
This class represents a generator for Compatibility chance. The distributions can be distinct for different cPRA values.
- __init__(*, dists)
Constructor for CompatibilityChanceGenerator.
- Parameters:
dists (
list
[tuple
[float
,float
,Union
[FloatGenerator
,Callable
[[float
],float
]]]]) – A set of distributions of compatibility chance. Each distribution is a tuple (low, high, generator) where low and high are floating values such that if the cPRA is in the range [low, high) (i.e., cPRA >= low and cPRA < high), generator will be used to generate compatibility chance. Generator itself is either a FloatGenerator object, or a function that takes as input a cPRA value and returns a corresponding compatibility chance. Note that there must be one, and exactly one, distribution to cover each cPRA in the range [0, 1]. In particular, since the upper range of an individual distribution has a strict upper bound, it must have an upper limit strictly above 1.0.
- draw(pra)
Draw a compatibility chance.
- Return type:
float
- config()
Returns the configuration of this CompatibilityChanceGenerator.
Note that this will fail if this CompatibilityChanceGenerator uses a function.
- Return type:
list
[tuple
[float
,float
,list
[list
[Union
[list
[float
],float
]]]]]- Returns:
a list of [low, high, generator] lists such that if the recipient cPRA is between low and high, then generator is a configuration for a FloatGenerator that will generate the compatibility chance for this recipient.
- classmethod from_json(json_obj)
Create a CompatibilityChanceGenerator from a JSON object. The JSON object should be a list of (low, high, config) tuples such that if the recipient cPRA is between low and high, then config is either the configuration for a FloatGenerator that will generate the compatibility chance for this recipient, or a function that will generate the compatibility chance for this recipient.
Currently, only linear functions can loaded from JSON.
- Return type:
- class CPRAGenerator(*, generic=None, compatible_generator=None, incompatible_generator=None)
Bases:
object
Generates cPRA values for a recipient based upon the configured distribution of cPRA. This can be configured either with one single distribution of cPRA for all recipients, or two distinct distributions dependent on whether the recipient has a bloodgroup compatible donor.
- __init__(*, generic=None, compatible_generator=None, incompatible_generator=None)
Construct a generator object from some FloatGenerator objects. To construct, either the generic generator (which will be used for all requests to draw a CPRA value) must be passed in, or both a compatible_generator and an incompatible_generator must be passed in. This allows the use of two distinct distributions of cPRA values - one for those recipients who do have an ABO compatible donor, and a second for those that don’t.
- Parameters:
generic (
Optional
[FloatGenerator
]) – A generator of cPRA to be used for all recipientscompatible_generator (
Optional
[FloatGenerator
]) – A generator of cPRA to be used for recipients with an ABO compatible donorincompatible_generator (
Optional
[FloatGenerator
]) – A generator of cPRA to be used for recipients without an ABO compatible donor
- draw(hasABOCompatibleDonor=None)
Draws a cPRA value for a given recipient, depending on whether the recipient has an ABO compatible donor.
- Parameters:
hasABOCompatibleDonor (
Optional
[bool
]) – True if and only if the target recipient has a ABO-compatible donor. Can only be left as None if a generic cPRA band has been provided to the generator in the initialiser.- Return type:
float
- Returns:
a cPRA value
- config()
Returns the configuration of this CPRAGenerator.
- Return type:
dict
[str
,list
[list
[Union
[list
[float
],float
]]]]- Returns:
a dictionary with a subset of [“Generic”, “Compatible”, and “Incompatible”] as keys, such that the value for each is a FloatGenerator configuration that corresponds to the distribution of cPRA amongst all recipients, recipients with an ABO compatible donor, and recipients without an ABO compatible donor respectively. Note that the dictionary will either only contain “Generic”, or will only contain “Compatible” and “Incompatible”
- classmethod from_json(json_obj)
Create a CPRAGenerator from a JSON object. The JSON object should be a list of (low, high, bands) tuples such that if the recipient cPRA is between low and high, then bands is a FloatGenerator that will generate the compatibility chance for this recipient.
- Return type:
- class RecipientGenerator(recipient_bloodgroup_generator, donor_count_generator, donor_generator, cpra_generator, compatibility_chance_generator)
Bases:
object
A generator for recipients. This class will generate a blood group, an integer N such that this recipient will have N donors, the N donors themselves, as well as both the cPRA and compatibility chance of a recipient.
- __init__(recipient_bloodgroup_generator, donor_count_generator, donor_generator, cpra_generator, compatibility_chance_generator)
Constructs a RecipientGenerator.
- Parameters:
recipient_bloodgroup_generator (
BloodGroupGenerator
) – A generator for the blood group for recipientsdonor_count_generator (
DonorCountGenerator
) – A generator for number of donors a recipient is paired withdonor_generator (
DonorGenerator
) – A donor generatorcpra_generator (
CPRAGenerator
) – A cPRA generatorcompatibility_chance_generator (
CompatibilityChanceGenerator
) – A generator for a recipient’s chance of compatibility
- draw(id_, donor_id_function=<function _donor_id_gen>)
Generate a Recipient.
- Parameters:
id – An identifier for this Recipient.
donor_id_function (
Callable
[[Recipient
],str
]) – A function that takes as input this recipient, and returns an identifier for the next donor for this recipient. The default is, given a Recipient with identifier “RX”, to use the identifier “RX_DY” where Y is an integer that starts at 1 and increases for additional donors.
- Return type:
- config()
Returns the configuration of this RecipientGenerator.
- Return type:
dict
[str
,Union
[dict
[str
,float
],dict
[int
,float
],dict
[str
,dict
[str
,float
]],dict
[str
,list
[list
[Union
[list
[float
],float
]]]],list
[tuple
[float
,float
,list
[list
[Union
[list
[float
],float
]]]]]]]- Returns:
a dictionary with the following keys and corresponding configurations for the respective generators: * RecipientBloodGroupGenerator * DonorCountGenerator * DonorGenerator * CPRAGenerator * CompatibilityChanceGenerator
- classmethod from_json(json_obj)
Create a RecipientGenerator from a JSON object. The JSON object should be a dictionary with the following keys containing corresponding configurations for the respective generators: * RecipientBloodGroupGenerator * DonorCountGenerator * DonorGenerator * CPRAGenerator * CompatibilityChanceGenerator
- Return type:
- class InstanceGenerator(recipient_generator, ndd_bloodgroup_generator=None)
Bases:
object
A class for generating Instances. Uses a RecipientGenerator to generate Recipients, and also takes a BloodGroupGenerator that can be used to generate non-directed donors.
- __init__(recipient_generator, ndd_bloodgroup_generator=None)
Constructor for InstanceGenerator.
- Parameters:
recipient_generator (
RecipientGenerator
) – The RecipientGenerator to usendd_bloodgroup_generator (
Optional
[BloodGroupGenerator
]) – The BloodGroupGenerator to use for non-directed donors.
- draw(numRecipients, numNonDirectedDonors=0, *, weightFn=<function _defaultWeight>, donor_id_function=<function _donor_id_gen>, recipient_id_function=<function _recip_id_gen>, ndd_id_function=<function _ndd_id_gen>)
Create a random instance with the given number of recipients and non-directed donors. Note that the number of directed donors is determined through the RecipientGenerator as it decides how many donors to pair with each recipient.
- Parameters:
numRecipients (
int
) – The number of recipients to generate.numNonDirectedDonors (
int
) – The number of non-directed donors to generate.weightFn (
Callable
[[Donor
,Recipient
],float
]) – A function that takes as input a Donor and a Recipient (not paired), and returns the score that should be used for a potential transplant between the Donor and Recipient. The default is to give each transplant a score of 1.0.
- Return type:
- config()
Returns the configuration of this InstanceGenerator.
- Return type:
dict
[str
,Union
[dict
[str
,Union
[dict
[str
,float
],dict
[int
,float
],dict
[str
,dict
[str
,float
]],dict
[str
,list
[list
[Union
[list
[float
],float
]]]],list
[tuple
[float
,float
,list
[list
[Union
[list
[float
],float
]]]]]]],dict
[str
,float
]]]- Returns:
a dictionary with the following keys and corresponding configurations for the following generators: * RecipientGenerator * NDDBloodGroupGenerator
- classmethod from_json(json_obj)
Create a RecipientGenerator from a JSON object. The JSON object should be a dictionary with the following keys containing corresponding configurations for the following generators: * RecipientGenerator * NDDBloodGroupGenerator
- Return type:
- class DynamicGenerator(recipient_arrival_rate, recipient_attrition_function, recipient_temporary_departure_function, recipient_positive_crossmatch_function, ndd_arrival_rate, ndd_attrition_function, ndd_temporary_departure_function)
Bases:
object
A generator of dynamic instances. These are instances that also include details on arrival and departure rates and temporary departure periods for participants, as well as a list of transplants that will have a positive laboratory crossmatch. Note that periods are arbitary, the user can think of each period as a week, or a month, or any suitable time period.
- __init__(recipient_arrival_rate, recipient_attrition_function, recipient_temporary_departure_function, recipient_positive_crossmatch_function, ndd_arrival_rate, ndd_attrition_function, ndd_temporary_departure_function)
Create a dynamic generator.
- Parameters:
recipient_arrival_rate (
float
) – The expected number of recipient arrivals per period.recipient_attrition_function (
Callable
[[Recipient
],float
]) – A function that takes a Recipient and returns the chance that the given recipient will leave in any period.recipient_temporary_departure_function (
Callable
[[Recipient
,int
],float
]) – A function that takes a Recipient and the length of their current temporary departure and returns the chance of this recipient being ill in any periodrecipient_positive_crossmatch_function (
Callable
[[Recipient
,Donor
],bool
]) – A function that takes as input a recipient and a donor, and returns the chance of a positive laboratory crossmatch between the recipient and donor.ndd_arrival_rate (
float
) – The expected number of non-directed donors arrivals per period.ndd_attrition_function (
Callable
[[Donor
],float
]) – A function that takes a non-directed donor and the length of their current temporary departure and returns the chance that this donor will leave in any period.recipient_temporary_departure_function – A function that takes a non-directed donor and returns the chance of this donor being ill in any period
- generate(instance, periods)
Generate a dynamic instance. A dynamic instance is a regular instance that also includes information on when recipients and non-directed donors arrive, leave, or are ill. Directed (paired) donors are assumed to always be present when their recipient is present.
- Parameters:
instance (
Instance
) – The (regular) Instance in questionperiods (
int
) – For how many periods will the dynamic simulator run
- Return type:
- Returns:
A dynamic instance