django-scientific-survey 0.3.4

A django survey app for conducting scientific surveys, based on "django-survey-and-report" by Pierre Sassoulas.

Django scientific survey

A django survey app for conducting scientific surveys, based on "django-survey-and-report" by Pierre Sassoulas. The package supports integration only with Django between versions 2.2 and up to and including 3.2.16. Supporting Django 4 is on the agenda, but not a top priority as of right now.

The following changes were made to the original app to accommodate scientific use cases:

• Introduced answer groups for the use cases when a datapoint should be evaluated using multiple different aspects. For instance, for a given text, you might want to evaluate its naturalness on the scale from 1 to 5, its fluency on the scale from 1 to 10 and its coherence on the scale from 1 to 4.
• Added the possibility to use numerical rating scales by prodiving prefix and suffix for an answer group. See example of how this looks below.

• Added a field called "extra" to the Question model to carry out some extra question-specific information. This information will be invisible to the end user and will be simply transfered to the exported survey results for easier analysis later. For instance, this can hold the information about the model that has generated the text.
• Added the possibility of using external redirect on finishing the survey, which is useful for integrating with crowdsourcing platforms frequently used for human evaluation, such as Prolific.
• Changed import and export format from CSV to JSON and added the answer groups and the "extra" field to this format.
• Added the possibility to randomize the order of questions for each survey participant.
• Added the possibility to import surveys from a JSON file.
• [New in v0.1.2] Added the possibility to add ranges (sliders) as question types, distinguishing between integer ranges (range_int) and float ranges (range_float). It is possible to specify min, max and step for the range by re-using the already existing choices field.
• [New in v0.2.0] Categories can be treated as independent sub-surveys! This is useful if one wants to create a number of batches all of which are aimed at answering the same research question, but the experimental design requires each participant to see their own batch of questions. Additionally, one can control a number of responses per batch (1 by default).
• [New in v0.3.0] Added the possibility to specify and save template layouts for questions. Changed JSON to YAML when importing surveys to enable multiline layouts.

Recognizing that these changes are not necessarily useful for the users of the original "django-survey-and-report" app (and that the code became more different from the original than expected initially), it was decided to create a separate package "django-scientific-survey" to acommodate these changes.

Table of contents

• Language available
• Getting started
• Making a survey
  • Manually through admin UI
  • Importing configuration from a JSON file
• Contributing as a developer
  • Development environment
  • Committing code
    • Launching tests
    • Adding test data
    • Launching coverage
    • Applying Lint
• Translating the project
  • As a developer
  • As a translator
• Credit

Language available

The software is developed in English.

Full translation is available for these languages (in alphabetical order):

• Russian thanks to Vlad M. and Dmytro Kalpakchi
• Ukrainian thanks to Dmytro Kalpakchi

Partial translation (due to the contributions to the original "django-survey-and-report") are available for these languages (in alphabetical order):

• Brazilian-Portuguese thanks to Rafael Capaci
• Chinese thanks to 朱聖黎 (Zhu Sheng Li)
• French thanks to Pierre Sassoulas
• German thanks to Georg Elsas
• Indonesian thanks to Dhana Dhira
• Japanese thanks to Nobukuni Suzue
• Polish thanks to Daniel Horner
• Spanish thanks to Javier Ordóñez

Getting started

Add django-scientific-survey to your requirements and get it with pip.

echo 'django-scientific-survey' > requirements.txt
pip install -r requirements.txt

Add bootstrapform and survey in the INSTALLED_APPS in your settings :

INSTALLED_APPS = [
	# Your own installed apps here
]

...

INSTALLED_APPS += [
	'bootstrapform',
	'scientific_survey'
]

Add an URL entry to your project’s urls.py, for example:

from django.conf import settings
from django.conf.urls import include, url

urlpatterns = [
    # Your own url pattern here
]

if 'scientific_survey' in settings.INSTALLED_APPS:
    urlpatterns += [
        url(r'^survey/', include('scientific_survey.urls'))
    ]

Note: you can use whatever you wish as the URL prefix.

You can also change some other options:

# The separator for questions (Default to ",")
CHOICES_SEPARATOR = "|"

# What is shown in export when the user do not answer (Default to "Left blank")
USER_DID_NOT_ANSWER = "NAA"

To uninstall django-scientific-survey, simply comment out or remove the scientific_survey line in your INSTALLED_APPS.

Making a survey

Manually through admin interface

Using the admin interface you can create surveys, add questions, give questions categories, define multiple answer groups per question, mark them as required or not, etc.

For instance, if you want the respondents to read a text and define its sentiment, you might want to ask "How would you define a sentiment of a text you just read?". This question can be created via the admin interface as shown below.

Now if you wanted to give participants 3 options: "Positive", "Neutral" and "Negative", you could do that via the admin interface as well by adding an answer group, as shown below.

The front-end survey view then automatically populates based on the questions that have been defined and published in the admin interface. We use bootstrap3 to render them.

Submitted responses can be viewed via the admin backend and exported in the JSON format.

By importing configuration from a JSON file

You can also create a survey by importing it from a JSON file, which is very handy for large surveys containing hundreds of questions. You can do this via the admin interface using "Import from JSON" button in the "Surveys" menu.

The format of the import file is self-explanatory and some examples of such files can be found here.

Contributing as a developer

Development environment

This is the typical command you should do to get started:

python -m venv venv/ # Create virtualenv
source venv/bin/activate # Activate virtualenv
pip install -e ".[dev]" # Install dev requirements
pre-commit install # Install pre-commit hook framework
python manage.py migrate # Create database
python manage.py loaddata survey/tests/testdump.json # Load test data
python manage.py createsuperuser
python manage.py runserver # Launch server

Please note that pre-commit will permit to fix a lot of linting error automatically and is not required but highly recommended.

Committing code

Launching tests

NOTE: Test overhaul is in progress

python manage.py test survey

Adding test data

If you want to dump a test database after adding data to it, this is the command to have a minimal diff :

python manage.py dumpdata --format json -e contenttypes -e admin -e auth.Permission
-e sessions.session -e sites.site --natural-foreign --indent 1
-o survey/tests/testdump.json

Launching coverage

coverage run --source=survey --omit=survey/migrations/* ./manage.py test
coverage html
xdg-open htmlcov/index.html

Applying Lint

We're using pre-commit, it should take care of linting during commit.

Translating the project

Django-scientific-survey is available in multiple languages. Your contribution would be very appreciated if you know a language that is not yet available.

As a developer

If your language do not exists add it in the LANGUAGE variable in the settings, like here. Do not forget to credit yourself like in the header seen here

In order to add translation files you first need to run for your own locale (change -l flag to the locale of your choice, e.g. 'ru', 'es', 'fr', etc.).

python manage.py makemessages --no-obsolete --no-wrap --ignore venv -l uk

Then run the server, as usual (python manage.py runserver) and access http://localhost:8000/admin to login. Then go to http://localhost:8000/rosetta to translate

Afterwards addd your translations to GitHub and create a pull request for them to be merged.

git add survey/locale/

If your language is not yet available in rosetta, according to this stack overflow question should work even for languages not handled by django.

As a translator

If you're not a developer, open an issue on github and ask for a .po file in your language. I will generate it for you, so you can edit it with an online editor. I will then create the .po and commit them, so you can edit them with your github account or integrate it myself if you do not have one. You will be credited here.

Credits

Based on django-survey-and-report by Pierre Sassoulas, which is, in turn is based on jessykate's django-survey, and contributions by jibaku, joshualoving, and ijasperyang in forks of jessykate's project.