===============================================================================
DiHabs Django Application
===============================================================================

DiHabs is a `Django`_ application for conducting online interviews about
information disclosure behavior within social interactions.

.. _Django: https://www.djangoproject.com/

Software and data related to DiHabs is hosted at the `Open Science Repository`__
of the Computer Science Department at Rostock University.

.. __: http://opsci.informatik.uni-rostock.de/index.php/DiHabs

-------------------------------------------------------------------------------
Deployment
-------------------------------------------------------------------------------

The Django project's `online documentation`__ is very comprehensive and
generally describes how to set up and run a Django site project. As these steps
are very generic they are not repeated at this place. However, the basic steps
in setting up a Django site using DiHabs are:

1. make the DiHabs application available in ``PYTHONPATH``,
2. create a new Django site project,
3. configure its settings to use the DiHabs application,
4. initialize the session database, and
5. run the server (either in standalone mode or integrated into a web server).

.. __: https://docs.djangoproject.com/en/1.2/intro/

-------------------------------------------------------------------------------
Settings
-------------------------------------------------------------------------------

The DiHabs application expects the following configuration options:

``DIHABS_INTERVIEW``:
    Path to an interview specification file.

``DIHABS_RESULTS``:
    Path to a file to store completed interviews in.

``DIHABS_SESSION_DEBUG`` (optional):
    If `True`, certain debug features are enabled.

``DIHABS_TESTMODE`` (optional):
    If `True`, interviews are flagged as tests (which excludes them from a
    later analysis).

-------------------------------------------------------------------------------
Interviews
-------------------------------------------------------------------------------

Interviews are defined as plain Python dictionaries which must have the the
following items:

``name``:
    Name of the interview.

``npersons_min`` and ``npersons_max``:
    Minimum and maximum number of persons a participant has to name when asked
    for her social environment.

``npersons_max_sample``:
    Maximum number of persons to actually use for generating person groups.

``ngdups``:
    Number of person group duplicates (to check for conflicting disclosures).

``groups``:
    Either a precompiled list of groups (where a group is a tuple of person
    index numbers) or a list specifying how much groups to generate for different
    group sizes (i.e. the value ``groups[i]`` specifies the number of groups of
    size ``i+1``).

``messages``:
    A dictionary of messages used in page templates. Each message is
    interpreted as markdown_  formatted text.

    ``title``:
        Global page title.
    ``start``:
        Welcome page content.
    ``start_ack``:
        Label for the button acknowledging the start page.
    ``privacy``:
        A privacy declaration to be shown when participants provide person names
        and personal information items.
    ``setnames_title``:
        Title headline for the page where participants enter person names.
    ``setnames_intro``:
        Introduction text for the page where participants enter person names.
    ``setnames_needmore``:
        Error message to show when not enough person names have been given.
    ``setvalues_title``:
        Title headline for pages where participants enter personal information
        items.
    ``setvalues_needmore``:
        Error message to show when not enough information items have been given.
    ``disclosure_title``:
        Title headline for pages of the 3rd part of the interview, where
        participants decide information disclosure in face of certain person groups.
    ``disclosure_persons``:
        Explanation text for the persons listed on a disclosure page.
    ``badstep``:
        Error text when interview steps is done twice.
    ``badstep_okay``:
        Label for the button acknowledging the previous error message.

``itypes``:
    A list of dictionaries, each specifying a particular information type
    respectively situation where participants are supposed to decide
    disclosures for.

    ``name`` and ``plotname``:
        Name of the information type (``plotname`` should be a short name to be
        used in plots).
    ``nvalues_min`` and ``nvalues_max``:
        Minimum and maximum number of information items participants must
        provide.
    ``desc_input``:
        Description of the information items participants are supposed to
        provide.
    ``desc_select``:
        Description of the information type and situation where the disclosure
        of information items have to be decided. This description must include
        the social context and modalities of information disclosure.

.. _markdown: http://daringfireball.net/projects/markdown/

-------------------------------------------------------------------------------
Analysis
-------------------------------------------------------------------------------

Survey results are stored in a `Python shelve`_ database (mapping participant
session IDs to corresponding interview data). The DiHabs application provides a
script to analyze results in such a database.  Supposed the DiHabs
application's Python module is available in ``PYTHONPATH``, it can be run as
follows::

    $ python -m dihabs.analyze

The ``--help`` option shows a summary of this script's functionality.

.. _`Python shelve`: http://docs.python.org/library/shelve.html

List Results
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A list of all results in a survey results database is shown when using the
``--list`` option::

    $ python -m dihabs.analyze --results=results.db --list
      0: 69c48713... (2010-09-07 09:39:31.107497, 7ea0be9a..., Demo)
      1: 1dd50bff... (2010-09-07 09:47:48.395140, 7ea0be9a..., Demo)
      2: 3e269763... (2010-09-09 12:49:35.249546, 7ea0be9a..., Demo)
      3: 6246deab... (2010-09-09 12:49:48.900607, 7ea0be9a..., Demo)
      4: fb1776cf... (2010-09-09 12:49:51.995939, 7ea0be9a..., Demo)
    ...

For each participant, this shows the participant's session ID, the interview
start-time, and the interview ID and name. Especially the session ID is needed
to select individual results for further analysis.

Inspect a Specific Result
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The data related to a specific participant can be shown using the ``--dump``
option::

    $ python -m dihabs.analyze --results=results.db --usid 69c48713... --dump
    usid: 69c487130a3a4869b97725247b19761f:wq
    interview: {'templates': {}, 'npersons_max': 20, 'name': 'September', 'messages ..
    start: 2010-09-07 09:39:31.107497
    end: 2010-09-07 10:14:34.895914
    npersons: 12
    groups: [92, 8, 12, 6, 14, 46, 158, 152, 2, 20, 28, 16, 4]
    nvalues: [10, 5, 3, 9, 8]
    test: False
    disclosures: [{'group': 92, 'values-per-type': [262, 10, 1, 328, 7], 'values': 10 ..

A textual summary of detected disclosure patterns can be retreived similarly
using the ``--analyze`` option (instead of ``--dump``).

Render Order-Mapping Graphs for a Specific Result
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In order to inspect order-mappings in the disclosure behavior of a specific
participant, the analyzer script may render graphs which illustrate the
order-mappings of situation pairs where the information receiver person groups
are comparable with each other::

    $ python -m dihabs.analyze --results=results.db --usid 69c48713... --graph \
             --dest exampleplots/

.. image:: exampleplots/graph.png
   :name: graph

This renders graphs for each information type found in a result. Figure graph_
shows an example graph.  Here the circles represent disclosure situations while
the binary numbers represent the presence of persons (information receiver) in
a situation, i.e.  the number `000011` indicates that persons `5` and `6` were
present (i.e. part of information receiver group) whole persons `1` to `4` were
not present. The arrows show *is-superset-of* relations concerning the person
groups. The colors indicate the type of order mapping. Green arrows reflect
*order-reserving*, orange *order-preserving*, blue *order-ignoring*, and dashed
purple arrows indicate *order-loosing* mappings. Order-mapping relations are
transitive except when two nodes are connected directly.

Render Pattern Usage Plots for All Results
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The options ``--plot`` and ``--plot2`` may be used to render plots which
illustrate the occurrence of certain information disclosure patterns, including
order-mapping types.