Agent (node)

In TTITAN, agents are individual objects that carry their own set of parameters interally allocated regardless of the process or structure that may govern those parameters. That is to say that each agent maintains their own individual values for each agent parameter even if they were assigned by a global or generalized function. As an example, the probability for testing may be globally set to 20% chance per timestep for every agent in the model, but that value is specifically assigned to each agent upon initialization rather than drawing the value from a global parameter at each testing opportunity.

Therefore, agents carry with them a suite of relationship, environmental, bahvioural, and demographical parameters, some of which are static while others are dynamic and can change.


Parameters are initially assigned to an agent upon created based on input distribtutions calculated by empirical data sources.


The following parameters are assigned upon agent creation and are statically defined (ie: cannot change over the span of a single simulation iteration)

ID                     - Agents unique identification number
parent                 - Parent of agent (for inheritence)
initAge                - Agents starting age
race                   - Race identifier for agent
gender                 - Gender of the agent
DU                     - Drug using status (NDU, NIDU, IDU)
SO                     - Agents sexual orientation
sexualRole             - Agents sexual role (inserive, receptive, versatile)

These parameters serve as agent-defining parameters that are used to influence a host of other dynamic parameters (shown below).


The following are baseline parameters that are assigned upon agent creation and are dynamic throughout the a simulation run (ie: change over the span of a single simulation iteration). They can be broken into four main categories:


Behavioral parameters influence the agents interactions with other agents. These factors include high-risk behavior, which indicate elevated exposure to “risk-acts” where transmission can occur (unprotected sex or needle sharing drug-use). They also include the agents desirable number of partners for each transmission mode, as well as the number of risk-acts per partner.

age                    - Agents instantaneous age
annual_PNtar_SE        - Target number of annual sexual partners
annual_PNtar_DU        - Target number of annual drug-use partners
annual_RAtar_SE        - Target number of annual sexual risk acts (RA) per partner
annual_RAtar_DU        - Target number of annual drug-use risk acts per partner
HR_bool                - Boolean for if agent is high-risk (HR)
HR_time                - Time agent has been high-risk
everHR_bool            - Boolean for if agent was ever high-risk during lifetime

Infection Status

These parameters include flags and times associated with various stages and types of infection. As the TITAN model is primarily HIV focused, HIV and AIDS related parameters are available for all agents.

STI_pool               - List of existing co-infection STIs
HIV_bool               - Boolean for if agent is HIV infected
HIV_time               - Time agent has been HIV infected (effects acute transmission)
AIDS_bool              - Boolean for if agent is HIV+AIDS infected
AIDS_time              - Time agent has been HIV+AIDS infected
PrEPresist_bool        - Boolean for if agent has PrEP resistant HIV infection

Treatment Cascade

The treatment parameters related to the agents interactions within the care continuum. HIV infected agents move from either HIV undiagnosed, HIV diagnosed not on treatment, or to HIV diagnosed on treatment. Additionally, HIV uninfected agents are eligible to enroll on PrEP, a preventative treatment to reduce the risk of infection per risk act.

tested                 - Boolean for if agent is positively diagnosed wiht HIV
HAART_bool             - Boolean for if agent is enrolled on ART treatment
HAART_time             - Time agent has been enrolled on ART treatment
HAART_adh              - Agents adherence to ART treatment
PrEP_bool              - Boolean for if agent is enrolled on PrEP treatment
PrEP_time              - Time agent has been enrolled on PrEP treatment
PrEP_adh               - Agents adherence to PrEP treatment
PrEP_load              - Agent instantanous PrEP serum level


All probabilites are calculated at the monthly timestep as the model runs on intervals of months. These probabilites are typically calculated from empirical data based on the agents demographical/behavioral parameters, but are often influenced by additional parameters such as their infection status or status within the treatment care continuum.

P_HIVtest              - Probability of HIV testing
P_progAIDS             - Probability of progressing to AIDS
P_HAARTenrol           - Probability of enrolling on ART treatment
P_HAARTdisc            - Probability of discontinuing HAART treatment
P_PrEPenrol            - Probability of enrolling on PrEP treatment
P_PrEPdisc             - Probability of discontinuing PrEP treatment
P_mortality            - Probability of agent dying


Partnering parameters are mostly associated with tracking active parters and relationships with those partners, as well as metrics to measure the performance of the individual agent with respect to their desired activity through both sexual and drug-use networks.

partners               - List of active agent partners
relationships          - List of active relationships with partners (injecting/sexual)
aN_SE_ptnrs            - Number of unique sexual partners in past year
aN_DU_ptnrs            - Number of unique drug-use partners in past year


The following are internally tracked agent parameters for statistical analysis reasons. Having agents store these variables independently rather than aggregated or remotely stored allows for a direct history for each agent to be pulled and analyzed.

timeAlive              - Time agent has been alive for in the model
tot_SE_acts            - Total number of sexual risk-acts performed
tot_DU_acts            - Total number of drug-use risk acts performed

Agent Creation Order of Operations

The agent population is formed upon model initialization until the desired number of total agents are created as defined by model input parameters. For each agent creation, the order of operations for agent parameters is as follows:

  1. Agent initialized and assigned unique identifier number (ID)
  2. Assign race of agent (probabalistic from demographic input params)
  3. Assign gender of agent (probabalistic from demographic input params)
  4. Assign sexual orientation and sexual role
  5. Assign drug-use status
  6. Assign initial age of agent
  7. Assign infection status (HIV_bool/HIV_time, AIDS_bool/AIDS_time)
  8. Assign location in care continuum (tested, HAART treatment status)

As these parameters are all assigned stochastically, there is variance between initial agent populations between individual simulation runs. While this functionality can be disabled and a forced random seed can be implemented to create identical initial populations, the randomness of initial conditions can play a critical role in determining model performance, and thus is left to the discretion of the user.

Set Grouping

Agents are grouped into agent sets based on heirarchal families for easier sorting and searching. Each agent set inherets froms its parent set. This means that there are never agents in subsets that are not also in the subset parent set. The benefit of this inheritence is that specialized subcategories of agents may be quickly created. One example is a sex worker class, where agents of any gender can engage in sex work behavior. While the parameters of the agent may widely remain the same, the agent could have elevated sexual frequency and condom usage. This set inheritence would allow you to include a particular agent into this sex-worker class which would appropriately adjust the relevent agent parameters.


The following are the core functions associated with an agent class.

def get_ID(self):
   #Returns agent ID
   return self._ID

def partner(self, partner):
   #Partner self agent to partner agent
   assert partner in self._partners:
   raise KeyError("Partner %s is already bonded with agent %s"%(partner.get_ID(), self._ID))

def unpartner(self, partner):
   #Removes partner from self agent partner list
       if self != agent:self._partners.remove(agent)
   except KeyError:
       raise KeyError("agent %s is not a member of agent set %s"%(agent.get_ID(), self.get_ID()))