Agent

This class constructs and represents an agent within the population

__init__(self, sex_type, age, race, drug_use, location, id=None) special

Initialize an agent based on given properties

Parameters:

Name	Type	Description	Default
id	Optional[int]	Unique agent ID	None
sex_type	str	Name of defined sex type (e.g. MSM) [params.classes.sex_types]	required
age	int	Agents initialization age	required
race	str	Race of agent [params.classes.races]	required
drug_use	str	Drug use flag [params.classes.drug_types]	required

Source code in titan/agent.py

def __init__(
    self,
    sex_type: str,
    age: int,
    race: str,
    drug_use: str,
    location: Location,
    id: Optional[int] = None,
) -> None:
    """
    Initialize an agent based on given properties

    Args:
        id: Unique agent ID
        sex_type: Name of defined sex type (e.g. MSM) [params.classes.sex_types]
        age: Agents initialization age
        race: Race of agent [params.classes.races]
        drug_use: Drug use flag [params.classes.drug_types]
    """
    # self.id is unique ID number used to track each person agent.
    if id is not None:
        self.id = id
    else:
        self.id = self.next_agent_id

    self.update_id_counter(self.id)

    # agent properties
    self.sex_type = sex_type
    self.age = age
    self.race = race
    self.drug_type = drug_use
    self.location = location
    self.component = "-1"  # updated after relationships created

    self.sex_role = "versatile"

    # agent-partner params
    self.relationships: Set[Relationship] = set()
    self.partners: Dict[str, Set] = {}
    self.mean_num_partners: Dict[str, int] = {}
    self.target_partners: Dict[str, int] = {}

    # agent exposures params
    # model features
    for exposure in exposures.BaseExposure.__subclasses__():
        setattr(self, exposure.name, exposure(self))

    # model features
    for feature in features.BaseFeature.__subclasses__():
        setattr(self, feature.name, feature(self))

__repr__(self) special

Repr formatting of agent object

Returns:

Type	Description
str	agent ID as str

Source code in titan/agent.py

def __repr__(self) -> str:
    """
    Repr formatting of agent object

    returns:
        agent ID as str
    """
    return str(self.id)

__str__(self) special

String formatting of agent object

Returns:

Type	Description
str	String formatted tab-deliminated agent properties

Source code in titan/agent.py

def __str__(self) -> str:
    """
    String formatting of agent object

    returns:
        String formatted tab-deliminated agent properties
    """
    return (
        f"\t{self.id}\t{self.age}\t{self.sex_type}\t{self.drug_type}\t"  # type: ignore[attr-defined]
        f"{self.race}\t{self.hiv.active}\t{self.prep.active}"  # type: ignore[attr-defined]
    )

get_num_partners(self, bond_types=None)

Get the number of partners an agent has, optionally filtered by bond type

Parameters:

Name	Type	Description	Default
bond_types	Optional[Iterable[str]]	list of bond types which will filter the partners, otherwise total number of partners returned	None

Returns:

Type	Description
int	the number of partners the agent has

Source code in titan/agent.py

def get_num_partners(self, bond_types: Optional[Iterable[str]] = None) -> int:
    """
    Get the number of partners an agent has, optionally filtered by bond type

    args:
        bond_types: list of bond types which will filter the partners, otherwise total number of partners returned

    returns:
        the number of partners the agent has
    """
    return len(self.get_partners(bond_types))

get_partners(self, bond_types=None)

Get all of an agents partners or those with specific bond types

Parameters:

Name	Type	Description	Default
bond_types	Optional[Iterable[str]]	list of bond types which will filter the partners, otherwise all partners returned	None

Returns:

Type	Description
Set[Agent]	set of agent's partners

Source code in titan/agent.py

def get_partners(self, bond_types: Optional[Iterable[str]] = None) -> Set["Agent"]:
    """
    Get all of an agents partners or those with specific bond types

    args:
        bond_types: list of bond types which will filter the partners, otherwise all partners returned

    returns:
        set of agent's partners
    """
    if bond_types:
        partners = set()
        for bond in bond_types:
            partners.update(self.partners[bond])
    else:
        partners = {partner for partner in self.iter_partners()}

    return partners

has_partners(self)

Determine whether an agent has any partners

Returns:

Type	Description
bool	whether an agent has at least one partner

Source code in titan/agent.py

def has_partners(self) -> bool:
    """
    Determine whether an agent has any partners

    returns:
        whether an agent has at least one partner
    """
    return any(self.iter_partners())

is_msm(self)

Determine whether an agent is a man who can have sex with men

Returns:

Type	Description
bool	if agent is MSM

Source code in titan/agent.py

def is_msm(self) -> bool:
    """
    Determine whether an agent is a man who can have sex with men

    returns:
        if agent is MSM
    """
    sex_dict = self.location.params.classes.sex_types
    if sex_dict[self.sex_type].gender != "M":
        return False

    for sex_type in sex_dict[self.sex_type].sleeps_with:
        if sex_dict[sex_type].gender == "M":
            return True
    return False

iter_partners(self)

Get an iterator over an agent's partners

Returns:

Type	Description
Iterator[Agent]	iterator of agent partners

Source code in titan/agent.py

def iter_partners(self) -> Iterator["Agent"]:
    """
    Get an iterator over an agent's partners

    returns:
        iterator of agent partners
    """
    for partner_set in self.partners.values():
        for partner in partner_set:
            yield partner