docs/source/classes.rst
Database API
============
.. module:: dallinger.models
.. _classes:
The classes involved in a Dallinger experiment are:
:class:`Network`, :class:`~Node`, :class:`~Vector`, :class:`~Info`,
:class:`~Transmission`, :class:`~Transformation`, :class:`~Participant`, and
:class:`~Question`. The code for all these classes can
be seen in ``models.py``. Each class has a corresponding table in the
database, with each instance stored as a row in the table. Accordingly,
each class is defined, in part, by the columns that constitute the table
it is stored in. In addition, the classes have relationships to other
objects and a number of functions.
The classes have relationships to each other as shown in the diagram
below. Be careful to note which way the arrows point. A :class:`~Node` is a
point in a :class:`~Network` that might be associated with a :class:`Participant`.
A :class:`Vector` is a directional connection between a :class:`Node` and another
:class:`Node`. An :class:`Info` is information created by a :class:`Node`. A
:class:`Transmission` is an instance of an :class:`Info` being sent along a
:class:`Vector`. A :class:`Transformation` is a relationship between an :class:`Info`
and another :class:`Info`. A :class:`Question` is a survey response created by a
:class:`Participant`.
.. figure:: _static/class_chart.jpg
:alt:
SharedMixin
-----------
Columns
~~~~~~~
All Dallinger classes inherit from a ``SharedMixin`` which provides multiple
columns that are common across tables:
.. autoattribute:: dallinger.models.SharedMixin.id
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.creation_time
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.property1
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.property2
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.property3
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.property4
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.property5
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.details
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.failed
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.failed_reason
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.time_of_death
:annotation:
Dynamic Properties and Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Properties, attributes and methods inherited by subclasses, and which
can be overridden:
.. autoattribute:: dallinger.models.SharedMixin.visualization_html
:annotation:
.. autoattribute:: dallinger.models.SharedMixin.failure_cascade
.. automethod:: dallinger.models.SharedMixin.json_data
Network
-------
The :class:`Network` object can be imagined as a set of other objects with
some functions that perform operations over those objects. The objects
that :class:`Network`'s have direct access to are all the :class:`Node`'s in the
network, the :class:`Vector`'s between those Nodes, Infos created by those
Nodes, Transmissions sent along the Vectors by those Nodes and
Transformations of those Infos. Participants and Questions do not exist
within Networks. An experiment may involve multiple Networks,
Transmissions can only occur within networks, not between them.
.. autoclass:: dallinger.models.Network
Columns
~~~~~~~
.. autoattribute:: dallinger.models.Network.type
:annotation:
.. autoattribute:: dallinger.models.Network.max_size
:annotation:
.. autoattribute:: dallinger.models.Network.full
:annotation:
.. autoattribute:: dallinger.models.Network.role
:annotation:
Relationships
~~~~~~~~~~~~~
.. attribute:: dallinger.models.Network.all_nodes
All the Nodes in the network.
.. attribute:: dallinger.models.Network.all_vectors
All the vectors in the network.
.. attribute:: dallinger.models.Network.all_infos
All the infos in the network.
.. attribute:: dallinger.models.Network.networks_transmissions
All the transmissions int he network.
.. attribute:: dallinger.models.Network.networks_transformations
All the transformations in the network.
Methods
~~~~~~~
.. automethod:: dallinger.models.Network.__repr__
.. automethod:: dallinger.models.Network.__json__
.. automethod:: dallinger.models.Network.calculate_full
.. automethod:: dallinger.models.Network.fail
.. automethod:: dallinger.models.Network.infos
.. automethod:: dallinger.models.Network.latest_transmission_recipient
.. automethod:: dallinger.models.Network.nodes
.. automethod:: dallinger.models.Network.print_verbose
.. automethod:: dallinger.models.Network.size
.. automethod:: dallinger.models.Network.transformations
.. automethod:: dallinger.models.Network.transmissions
.. automethod:: dallinger.models.Network.vectors
Node
----
Each Node represents a single point in a single network. A Node must be
within a Network and may also be associated with a Participant.
.. autoclass:: dallinger.models.Node
Columns
~~~~~~~
.. autoattribute:: dallinger.models.Node.type
:annotation:
.. autoattribute:: dallinger.models.Node.network_id
:annotation:
.. autoattribute:: dallinger.models.Node.participant_id
:annotation:
Relationships
~~~~~~~~~~~~~
.. autoattribute:: dallinger.models.Node.network
:annotation:
.. autoattribute:: dallinger.models.Node.participant
:annotation:
.. attribute:: dallinger.models.Node.all_outgoing_vectors
All the vectors going out from this Node.
.. attribute:: dallinger.models.Node.all_incoming_vectors
All the vectors coming in to this Node.
.. attribute:: dallinger.models.Node.all_infos
All Infos created by this Node.
.. attribute:: dallinger.models.Node.all_outgoing_transmissions
All Transmissions sent from this Node.
.. attribute:: dallinger.models.Node.all_incoming_transmissions
All Transmissions sent to this Node.
.. attribute:: dallinger.models.Node.transformations_here
All transformations that took place at this Node.
Methods
~~~~~~~
.. automethod:: dallinger.models.Node.__repr__
.. automethod:: dallinger.models.Node.__json__
.. automethod:: dallinger.models.Node._to_whom
.. automethod:: dallinger.models.Node._what
.. automethod:: dallinger.models.Node.connect
.. automethod:: dallinger.models.Node.fail
.. automethod:: dallinger.models.Node.is_connected
.. automethod:: dallinger.models.Node.infos
.. automethod:: dallinger.models.Node.mutate
.. automethod:: dallinger.models.Node.neighbors
.. automethod:: dallinger.models.Node.receive
.. automethod:: dallinger.models.Node.received_infos
.. automethod:: dallinger.models.Node.replicate
.. automethod:: dallinger.models.Node.transformations
.. automethod:: dallinger.models.Node.transmissions
.. automethod:: dallinger.models.Node.transmit
.. automethod:: dallinger.models.Node.update
.. automethod:: dallinger.models.Node.vectors
Vector
------
A vector is a directional link between two nodes. Nodes connected by a
vector can send Transmissions to each other, but because Vectors have a
direction, two Vectors are needed for bi-directional Transmissions.
.. autoclass:: dallinger.models.Vector
Columns
~~~~~~~
.. autoattribute:: dallinger.models.Vector.origin_id
:annotation:
.. autoattribute:: dallinger.models.Vector.destination_id
:annotation:
.. autoattribute:: dallinger.models.Vector.network_id
:annotation:
Relationships
~~~~~~~~~~~~~
.. autoattribute:: dallinger.models.Vector.origin
:annotation:
.. autoattribute:: dallinger.models.Vector.destination
:annotation:
.. autoattribute:: dallinger.models.Vector.network
:annotation:
.. attribute:: dallinger.models.Vector.all_transmissions
All Transmissions sent along the Vector.
Methods
~~~~~~~
.. automethod:: dallinger.models.Vector.__repr__
.. automethod:: dallinger.models.Vector.__json__
.. automethod:: dallinger.models.Vector.fail
.. automethod:: dallinger.models.Vector.transmissions
Info
----
An Info is a piece of information created by a Node. It can be sent
along Vectors as part of a Transmission.
.. autoclass:: dallinger.models.Info
Columns
~~~~~~~
.. autoattribute:: dallinger.models.Info.id
:annotation:
.. autoattribute:: dallinger.models.Info.creation_time
:annotation:
.. autoattribute:: dallinger.models.Info.property1
:annotation:
.. autoattribute:: dallinger.models.Info.property2
:annotation:
.. autoattribute:: dallinger.models.Info.property3
:annotation:
.. autoattribute:: dallinger.models.Info.property4
:annotation:
.. autoattribute:: dallinger.models.Info.property5
:annotation:
.. autoattribute:: dallinger.models.Info.details
:annotation:
.. autoattribute:: dallinger.models.Info.failed
:annotation:
.. autoattribute:: dallinger.models.Info.time_of_death
:annotation:
.. autoattribute:: dallinger.models.Info.type
:annotation:
.. autoattribute:: dallinger.models.Info.origin_id
:annotation:
.. autoattribute:: dallinger.models.Info.network_id
:annotation:
.. autoattribute:: dallinger.models.Info.contents
:annotation:
Relationships
~~~~~~~~~~~~~
.. autoattribute:: dallinger.models.Info.origin
:annotation:
.. autoattribute:: dallinger.models.Info.network
:annotation:
.. attribute:: dallinger.models.Info.all_transmissions
All Transmissions of this Info.
.. attribute:: dallinger.models.Info.transformation_applied_to
All Transformations of which this info is the ``info_in``
.. attribute:: dallinger.models.Info.transformation_whence
All Transformations of which this info is the ``info_out``
Methods
~~~~~~~
.. automethod:: dallinger.models.Info.__repr__
.. automethod:: dallinger.models.Info.__json__
.. automethod:: dallinger.models.Info._mutated_contents
.. automethod:: dallinger.models.Info.fail
.. automethod:: dallinger.models.Info.transformations
.. automethod:: dallinger.models.Info.transmissions
Transmission
------------
A transmission represents an instance of an Info being sent along a
Vector. Transmissions are not necessarily received when they are sent
(like an email) and must also be received by the Node they are sent to.
.. autoclass:: dallinger.models.Transmission
Columns
~~~~~~~
.. autoattribute:: dallinger.models.Transmission.origin_id
:annotation:
.. autoattribute:: dallinger.models.Transmission.destination_id
:annotation:
.. autoattribute:: dallinger.models.Transmission.vector_id
:annotation:
.. autoattribute:: dallinger.models.Transmission.network_id
:annotation:
.. autoattribute:: dallinger.models.Transmission.info_id
:annotation:
.. autoattribute:: dallinger.models.Transmission.receive_time
:annotation:
.. autoattribute:: dallinger.models.Transmission.status
:annotation:
Relationships
~~~~~~~~~~~~~
.. autoattribute:: dallinger.models.Transmission.origin
:annotation:
.. autoattribute:: dallinger.models.Transmission.destination
:annotation:
.. autoattribute:: dallinger.models.Transmission.vector
:annotation:
.. autoattribute:: dallinger.models.Transmission.network
:annotation:
.. autoattribute:: dallinger.models.Transmission.info
:annotation:
Methods
~~~~~~~
.. automethod:: dallinger.models.Transmission.__repr__
.. automethod:: dallinger.models.Transmission.__json__
.. automethod:: dallinger.models.Transmission.fail
.. automethod:: dallinger.models.Transmission.mark_received
Transformation
--------------
A Transformation is a relationship between two Infos. It is similar to
how a Vector indicates a relationship between two Nodes, but whereas a
Vector allows Nodes to Transmit to each other, Transformations don't
allow Infos to do anything new. Instead they are a form of book-keeping
allowing you to keep track of relationships between various Infos.
.. autoclass:: dallinger.models.Transformation
Columns
~~~~~~~
.. autoattribute:: dallinger.models.Transformation.type
:annotation:
.. autoattribute:: dallinger.models.Transformation.node_id
:annotation:
.. autoattribute:: dallinger.models.Transformation.network_id
:annotation:
.. autoattribute:: dallinger.models.Transformation.info_in_id
:annotation:
.. autoattribute:: dallinger.models.Transformation.info_out_id
:annotation:
Relationships
~~~~~~~~~~~~~
.. autoattribute:: dallinger.models.Transformation.node
:annotation:
.. autoattribute:: dallinger.models.Transformation.network
:annotation:
.. autoattribute:: dallinger.models.Transformation.info_in
:annotation:
.. autoattribute:: dallinger.models.Transformation.info_out
:annotation:
Methods
~~~~~~~
.. automethod:: dallinger.models.Transformation.__repr__
.. automethod:: dallinger.models.Transformation.__json__
.. automethod:: dallinger.models.Transformation.fail
Participant
-----------
The Participant object corresponds to a real world participant. Each
person who takes part will have a corresponding entry in the Participant
table. Participants can be associated with Nodes and Questions.
.. autoclass:: dallinger.models.Participant
Columns
~~~~~~~
.. autoattribute:: dallinger.models.Participant.type
:annotation:
.. autoattribute:: dallinger.models.Participant.worker_id
:annotation:
.. autoattribute:: dallinger.models.Participant.assignment_id
:annotation:
.. autoattribute:: dallinger.models.Participant.unique_id
:annotation:
.. autoattribute:: dallinger.models.Participant.hit_id
:annotation:
.. autoattribute:: dallinger.models.Participant.mode
:annotation:
.. autoattribute:: dallinger.models.Participant.end_time
:annotation:
.. autoattribute:: dallinger.models.Participant.base_pay
:annotation:
.. autoattribute:: dallinger.models.Participant.bonus
:annotation:
.. autoattribute:: dallinger.models.Participant.status
:annotation:
Relationships
~~~~~~~~~~~~~
.. attribute:: dallinger.models.Participant.all_questions
All the questions associated with this participant.
.. attribute:: dallinger.models.Participant.all_nodes
All the Nodes associated with this participant.
Methods
~~~~~~~
.. automethod:: dallinger.models.Participant.__json__
.. automethod:: dallinger.models.Participant.fail
.. automethod:: dallinger.models.Participant.infos
.. automethod:: dallinger.models.Participant.nodes
.. automethod:: dallinger.models.Participant.questions
Question
--------
A Question is a way to store information associated with a Participant
as opposed to a Node (Infos are made by Nodes, not Participants).
Questions are generally useful for storing responses debriefing
questions etc.
.. autoclass:: dallinger.models.Question
Columns
~~~~~~~
.. autoattribute:: dallinger.models.Question.type
:annotation:
.. autoattribute:: dallinger.models.Question.participant_id
:annotation:
.. autoattribute:: dallinger.models.Question.number
:annotation:
.. autoattribute:: dallinger.models.Question.question
:annotation:
.. autoattribute:: dallinger.models.Question.response
:annotation:
Relationships
~~~~~~~~~~~~~
.. autoattribute:: dallinger.models.Question.participant
Methods
~~~~~~~
.. automethod:: dallinger.models.Question.__json__
.. automethod:: dallinger.models.Question.fail