Skip to content

Knowledge

name: str

Name of exposure in the params file. Also used to name the attribute in Agent

stats: List[str]

Knowledge collects the following stats:

  • knowledge_aware - number of agents with active knowledge

convert(self, model)

Make an agent aware, stochastically make knowledge aware if their opinion meets the threshold.

Parameters:

Name Type Description Default
model model.TITAN

The running model

required
Source code in titan/exposures/knowledge.py
def convert(self, model: "model.TITAN"):
    """
    Make an agent aware, stochastically make knowledge aware if their opinion meets the threshold.

    args:
        model: The running model
    """
    params = self.agent.location.params.knowledge
    self.active = True  # type: ignore[attr-defined]
    if (
        self.opinion > params.opinion.threshold  # type: ignore[attr-defined]
        and model.run_random.random() < params.feature.prob
    ):
        agent_attr = getattr(self.agent, params.feature.name)
        agent_attr.initiate(model, force=True)

expose(model, interaction, rel, num_acts) staticmethod

Expose a relationship to the exposure for a number of acts for a specific interaction type. Typically, this determines if the exposure can cause conversion/change in one of the agents, then if so, determines the probability of that and then converts the succeptible agent.

If transmission stochastically occurs, either convert the unaware agent, or if both agents aware, have the higher influence agent influce their partner.

Parameters:

Name Type Description Default
model model.TITAN

The running model

required
interaction str

The type of interaction (e.g. sex, injection)

required
rel ag.Relationship

The relationship where the interaction is occuring

required
num_acts int

The number of acts of that interaction

required
Source code in titan/exposures/knowledge.py
@staticmethod
def expose(
    model: "model.TITAN",
    interaction: str,
    rel: "ag.Relationship",
    num_acts: int,
):
    """
    Expose a relationship to the exposure for a number of acts for a specific interaction type.  Typically, this determines if the exposure can cause conversion/change in one of the agents, then if so, determines the probability of that and then converts the succeptible agent.

    If transmission stochastically occurs, either convert the unaware agent, or if both agents aware, have the higher influence agent influce their partner.

    args:
        model: The running model
        interaction: The type of interaction (e.g. sex, injection)
        rel: The relationship where the interaction is occuring
        num_acts: The number of acts of that interaction
    """
    assert (
        model.params.model.network.enable
    ), "Network must be enabled for knowledge exposure"

    # agent/partner ordering is irrelevant at this point for knowledge transmission
    p = rel.agent1.knowledge.get_transmission_probability(  # type: ignore[attr-defined]
        model, interaction, rel.agent2, num_acts
    )

    if model.run_random.random() < p:
        agent1_aware = rel.agent1.knowledge.active  # type: ignore[attr-defined]
        agent2_aware = rel.agent2.knowledge.active  # type: ignore[attr-defined]

        if agent1_aware and agent2_aware:
            influence(model, rel)
        elif agent1_aware:
            rel.agent2.knowledge.convert(model)  # type: ignore[attr-defined]
        elif agent2_aware:
            rel.agent1.knowledge.convert(model)  # type: ignore[attr-defined]

get_transmission_probability(self, model, interaction, partner, num_acts)

Get the probability of knowledge/opinion transmission in this relationship

Parameters:

Name Type Description Default
model model.TITAN

The running model

required
interaction str

The interaction type (e.g. pca)

required
partner ag.Agent

The agent's partner

required
num_acts int

The number of interactions the agents had

required

Returns:

Type Description
float

the probability of knowledge/opinion transmission

Source code in titan/exposures/knowledge.py
def get_transmission_probability(
    self,
    model: "model.TITAN",
    interaction: str,
    partner: "ag.Agent",
    num_acts: int,
) -> float:
    """
    Get the probability of knowledge/opinion transmission in this relationship

    args:
        model: The running model
        interaction: The interaction type (e.g. `pca`)
        partner: The agent's partner
        num_acts: The number of interactions the agents had

    returns:
        the probability of knowledge/opinion transmission
    """
    if not interaction == "pca":
        return 0.0

    if self.active and partner.knowledge.active:  # type: ignore[attr-defined]
        p = model.params.knowledge.opinion.prob
    else:
        p = model.params.knowledge.prob

    return utils.total_probability(p, num_acts)

init_agent(self, pop, time)

Initialize the agent for this exposure during population initialization (Population.create_agent). Called only on exposures that are enabled per the params.

Stochastically make agent aware, if aware, set the opinion from the params.

Parameters:

Name Type Description Default
pop population.Population

the population this agent is a part of

required
time int

the current time step

required
Source code in titan/exposures/knowledge.py
def init_agent(self, pop: "population.Population", time: int):
    """
    Initialize the agent for this exposure during population initialization (`Population.create_agent`).  Called only on exposures that are enabled per the params.

    Stochastically make agent aware, if aware, set the opinion from the params.

    args:
        pop: the population this agent is a part of
        time: the current time step
    """
    knowledge_params = self.agent.location.params.knowledge
    if pop.pop_random.random() < knowledge_params.init:
        self.active = True

    # Initialize all agents with some opinion, may or may not be active
    self.opinion = utils.get_cumulative_bin(
        pop.pop_random, knowledge_params.opinion.init
    )

set_stats(self, stats, time)

Update the stats dictionary passed for this agent. Called from output.get_stats for each enabled exposure in the model.

The stats to be updated must be declared in the class attribute stats to make sure the dictionary has the expected keys/counter value initialized.

Parameters:

Name Type Description Default
stats Dict[str, int]

the dictionary to update with this agent's feature statistics

required
time int

the time step of the model when the stats are set

required
Source code in titan/exposures/knowledge.py
def set_stats(self, stats: Dict[str, int], time: int):
    if self.active:
        stats["knowledge_aware"] += 1

update_agent(self, model)

Update the agent for this exposure for a time step. Called once per time step in TITAN.update_all_agents.

If the knowledge start_time has happened, stochastically convert agents.

Parameters:

Name Type Description Default
model model.TITAN

the instance of TITAN currently being run

required
Source code in titan/exposures/knowledge.py
def update_agent(self, model: "model.TITAN"):
    """
    Update the agent for this exposure for a time step.  Called once per time step in `TITAN.update_all_agents`.

    If the knowledge start_time has happened, stochastically convert agents.

    args:
        model: the instance of TITAN currently being run
    """
    knowledge_params = self.agent.location.params.knowledge
    if (
        model.time >= knowledge_params.start_time
        and not self.active
        and model.run_random.random() < knowledge_params.prob
    ):
        self.convert(model)