scicom.historicalletters.agents
===============================

.. py:module:: scicom.historicalletters.agents

.. autoapi-nested-parse::

   The agent classes for HistoricalLetters.



Classes
-------

.. autoapisummary::

   scicom.historicalletters.agents.SenderAgent
   scicom.historicalletters.agents.RegionAgent


Module Contents
---------------

.. py:class:: SenderAgent(model, geometry, crs, similarityThreshold, moveRange, letterRange)

   Bases: :py:obj:`mesa_geo.GeoAgent`


   The agent sending letters.

   On initialization an agent is places in a geographical coordinate.
   Each agent can send letters to other agents within a distance
   determined by the letterRange. Agents can also move to new positions
   within the moveRange.

   Agents keep track of their changing "interest" by having a vector
   of all held positions in topic space.


   .. py:attribute:: region_id
      :value: ''



   .. py:attribute:: activationWeight
      :value: 1



   .. py:attribute:: similarityThreshold


   .. py:attribute:: moveRange


   .. py:attribute:: letterRange


   .. py:attribute:: topicVec
      :value: ''



   .. py:attribute:: topicLedger
      :value: []



   .. py:attribute:: numLettersReceived
      :value: 0



   .. py:attribute:: numLettersSend
      :value: 0



   .. py:method:: move(neighbors)

      Agent can randomly move to neighboring positions.

      Neighbours with a higher number of received letters are
      more likely targets of a movement process. The amount of
      movement is randomly drawn.



   .. py:method:: has_letter_contacts(*, neighbors = False)

      List of already established and potential contacts.

      Implements the ego-reinforcing by allowing mutliple entries
      of the same agent. In neighbourhoods agents are added proportional
      to the number of letters they received, thus increasing the reinforcement.
      The range of the visible neighborhood is defined by the letterRange parameter
      during model initialization.

      For neigbors in the social network (which can be long-tie), the same process
      applies. Here, at the begining of each step a list of currently valid scalings
      is created, see step function in model.py. This prevents updating of
      scales during the random activations of agents in one step.



   .. py:method:: chooses_topic(receiver)

      Choose the topic to write about in the letter.

      Agents can choose to write a topic from their own ledger or
      in relation to the topics of the receiver. The choice is random.



   .. py:method:: sendLetter(neighbors)

      Send a letter based on an urn model.



   .. py:method:: step()

      Perform one simulation step.



.. py:class:: RegionAgent(model, geometry, crs)

   Bases: :py:obj:`mesa_geo.GeoAgent`


   The region keeping track of contained agents.

   This agent type is introduced for visualization purposes.
   SenderAgents are linked to regions by calculation of a
   geographic overlap of the region shape with the SenderAgent
   position.
   At initialization, the regions are populated with SenderAgents
   giving rise to a dictionary of the contained SenderAgent IDs and
   their initial topic.
   At each movement, the SenderAgent might cross region boundaries.
   This reqieres a re-calculation of the potential overlap.


   .. py:attribute:: senders_in_region


   .. py:attribute:: main_topic
      :type:  tuple


   .. py:method:: has_main_topic()

      Return weighted average topics of agents in region.



   .. py:method:: add_sender(sender)

      Add a sender to the region.



   .. py:method:: remove_sender(sender)

      Remove a sender from the region.