laser.measles.mixing.competing_destinations

`laser.measles.mixing.competing_destinations`

`laser.measles.mixing.competing_destinations.CompetingDestinationsMixing(scenario=None, params=None)`

Bases: BaseMixing

Competing-destinations migration model for spatial mixing.

Extends the gravity kernel with a correction that accounts for the attractiveness of alternative destinations:

\[M_{i,j} = k \frac{p_i^{a-1} \, p_j^{b}}{d_{i,j}^{c}} \left(\sum_{k \ne i,j} \frac{p_k^{b}}{d_{ik}^{c}}\right)^{\delta}\]

When \(\delta < 0\), destinations that are surrounded by many other attractive locations receive less travel — the nearby alternatives "compete" for travellers.

Parameters:

Name	Type	Description	Default
`scenario`	`DataFrame \| None`	Patch data. `None` when the model will set it automatically.	`None`
`params`	`CompetingDestinationsParams \| None`	Model parameters.	`None`

Example:

```python
from laser.measles.mixing.competing_destinations import (
    CompetingDestinationsMixing, CompetingDestinationsParams,
)
from laser.measles.compartmental import components
from laser.measles import create_component

mixer = CompetingDestinationsMixing(
    params=CompetingDestinationsParams(k=0.01, delta=-0.5),
)
infection_params = components.InfectionParams(beta=0.8, mixer=mixer)
model.add_component(create_component(components.InfectionProcess, infection_params))
```

`laser.measles.mixing.competing_destinations.CompetingDestinationsMixing.get_migration_matrix()`

Compute the competing-destinations migration matrix.

Returns:

Type	Description
`ndarray`	Migration matrix of shape `(N, N)`.

`laser.measles.mixing.competing_destinations.CompetingDestinationsParams`

Bases: BaseModel

Parameters for the competing-destinations mixing model.

Extends the gravity kernel with a correction factor that penalises destinations surrounded by many other attractive alternatives.

Parameters:

Name	Type	Description	Default
`a`	`float`	Population source exponent.	required
`b`	`float`	Population destination exponent.	required
`c`	`float`	Distance decay exponent.	required
`k`	`float`	Average trip probability.	required
`delta`	`float`	Destination-competition exponent — negative values penalise destinations with many nearby competitors.	required

Example:

```python
from laser.measles.mixing.competing_destinations import CompetingDestinationsParams

params = CompetingDestinationsParams(a=1.0, b=1.0, c=1.5, k=0.01, delta=-0.5)
```