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:

BloodGroup

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:

BloodGroupGenerator

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:

DonorCountGenerator

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 donor

  • recipient_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:

Donor

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:

DonorGenerator

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:

FloatGenerator

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:

CompatibilityChanceGenerator

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 recipients

  • compatible_generator (Optional[FloatGenerator]) – A generator of cPRA to be used for recipients with an ABO compatible donor

  • incompatible_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:

CPRAGenerator

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:
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:

Recipient

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:

RecipientGenerator

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 use

  • ndd_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:

Instance

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:

InstanceGenerator