otree-org/otree-docs

otree.readthedocs.io

If you know Japanese, please help contribute a translation!

1. (Optional) Send an email to [email protected] just to let me know you will be doing some translation. Maybe I can give you some advice in addition to what is written here.
2. Fork & download this repo
3. Go to locales/ and edit the .po files using poedit or simply using a text editor
4. pip install -r requirements.txt
5. If translating to Japanese: sphinx-build -b html -D language=ja source build/html/ja
6. If translating to Chinese: sphinx-build -b html -D language=zh_CN source build/html/zh_CN
7. Open the HTML files in your browser and check that they look OK
8. git commit
9. Make a pull request on GitHub.

Then, your changes will be visible at:

https://otree.readthedocs.io/ja/latest/index.html

To generate new .po files after an update to the English version, run:

sphinx-build -b gettext source build/gettext
sphinx-intl update -p build/gettext -l zh_CN -l ja 

otree-docs's Issues

Contradictions in python versions

Talk about buttons

Hi,

It would be good with an example on how to make a toggle button. I spend hours trying to get the darn checkbox inlined until it occured to me that a button was better.

However, I ended up hard-coding it in my template html file with something like:

            <button type="button" class="btn btn-default"
                    id="toggle_buy">Buy</button>

and a JS function

  // script to show/ hide the order fields, based on order type
  function toggle_display(button, label) {
      invisible = "invisible";
      color = "btn-primary";
      button.classList.toggle(color);
      e = document.getElementById(label);
      if (!e.classList.contains(invisible)){
          inputs = e.getElementsByTagName("input")
          for (input of inputs) {input.value = 0}}
      e.classList.toggle(invisible);}

  $(document).ready(function(){

  // Toggle buy box
  document.getElementById('toggle_buy').onclick = function() {
  toggle_display(this, "buyform")};
  })

This seems like something that would be quite common in an experiment...? So I think an example is appropriate for the manual. Or perhaps even a custom widget type, but I don't know how easy it is to generalize.

Edit: better version of script. Bootstrap invisible class is easier and better than display.

save not submitted variables

Hello,

Could somebody explain me how I can define that in case of timeout, whatever was written in an input is stored into that variable?

From the documentation I understood that under

timeout_submission = {'accept': True}

I can define the value of a variable. However, here I do not see how I can access what was the preliminary input.

On the other hand, in the following I accessed the preliminary input, yet there I do not see how to save this under time_out submission since it is inside a function (I tried to write it in self.player.field but nothing happens so it seems to be incorrect).

   def before_next_page(self):

        post_dict = self.request.POST.dict()
        for field in self.form_fields:
            self.player.field = post_dict[field]

Is there a straightforward way to do this?

How to change values (like payoff matrix of PD) before experiments begin.

Hi! Is there any way to change some values before session begin in the control panel?
eg. Change the payoff matrix so I can play some different version of PD experiments without creating new app.

Thanks!

A bug in source/tutorial/part1.rst : "otree\_tags" should be "otree_tags"

It would cause error "django.template.base.TemplateSyntaxError: 'otree_tags' is not a valid tag library" when I did resetdb.

Support for initial data loading

Please add support to load initial data.

I am currently setting up an experiment, which uses some large data templates and custom models. For this I would need a simple way to pre-load the data, whenever I call resetdb.

Currently I have the following methods to support such pre-loading:

• Provide the data as fixtures to be loaded initially. This method is deprecated in Django, however, in favor of migrations. Also, this would require me to define all data in a single file, which is not always suitable.

• Use migrations. However, since migrations are faked during "otree resetdb", with this approach I have to reset the migrations in the database manually and then do another call to "otree migrate", which will then pre-load the data.

Both approaches seem somewhat "hacked". It would be preferable to have a method by which not only the database structure, but also initial content can be loaded.

optional fields not working with python > 3.7.5

Improve KaTeX documentation

Hi,

At the very least the manual should mention is how to change the font type and size in KaTeX, as CM is usually not a good choice (bootstrap on my computer seems to default to a sans serif font).
It think it needs to be documented in the oTree manual as KaTeX is not as widely used as MathJax, and since the KaTeX manual isn't great (compared to MathJax at least).

As I need to solve this anyway, I'll look into it. But feel free to beat me to it.

Rasmus

video in Safari

It seems to be the case (unless I'm doing something wrong) that video does not work in Safari.

This code...
<video width="320" height="240" controls="true"> <source src="{% static "playground/movie.mp4" %}" type="video/mp4"> Your browser does not support the video tag. </video>
...works in Chrome but not Safari.

If I replace the src path with a link, such as 'http://clips.vorwaerts-gmbh.de/VfE_html5.mp4' then it does work.

postgresql notes

Hi,

The notes on how to get otree to work with a "proper" sql server are a bit confusing if one is not acquainted with web deployment (and indeed I failed when I tried to follow them). Also, I'm not sure it's good to use the postgresql user for the database.

Since most social scientists are probably not terribly invested in server deployment it might be nice with some more hand-holding.

I did the following (on wheezy),

$ aptitude install postgresql postgresql-contrib
$ sudo su - postgres
$ createuser -P
Enter name of role to add: otree_db
Enter password for new role: 
Enter it again: 
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n

In the settings.py I used,

if gethostname().lower() == 'remote':
    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.postgresql_psycopg2',
            'NAME': 'otree_data',
            'USER': 'otree_db',
            'PASSWORD': 'psk',
            'HOST': 'localhost',
            'PORT': ''}}
else:
    DATABASES = {
        'default': dj_database_url.config(
            default='sqlite:///' + os.path.join(BASE_DIR, 'db.sqlite3'))}

the database is then synced with otree syncdb and my update script calls su - postgres -c "dropdb otree_data ; createdb otree_data".

Rasmus

"For an example, see the oTree sample ultimatum game"

The doc on dynamic form field points at the ultimatum game for an example of the use of get_form_field().

I've looked it up and could not find get_form_field() used there. If you could be more specific about where it is used that would be great.

Thanks in advance.

FileNotFoundError while calling heroku run “otree resetdb”

Hello guys,

so I receive a FileNotFoundError: [Errno 2] No such file or directory error. The error occurs when I try to deploy an oTree experiment with heroku and git after command heroku run "otree resetdb". Operating system is Windows 10. I honestly don't know what to do since the file is certainly there

Full error message:
Running otree resetdb on ⬢ otreeexperimentna... up, run.5607 (Free)
Traceback (most recent call last):
File "/app/.heroku/python/lib/python3.7/site-packages/otree_startup/__init__.py", line 227, in do_django_setup django.setup()
File "/app/.heroku/python/lib/python3.7/site-packages/django/__init__.py", line 24, in setup apps.populate(settings.INSTALLED_APPS)
File "/app/.heroku/python/lib/python3.7/site-packages/django/apps/registry.py", line 114, in populate app_config.import_models()
File "/app/.heroku/python/lib/python3.7/site-packages/django/apps/config.py", line 211, in import_models self.models_module = import_module(models_module_name)
File "/app/.heroku/python/lib/python3.7/importlib/__init__.py", line 127, in import_module return _bootstrap._gcd_import(name[level:], package, level)
File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
File "<frozen importlib._bootstrap>", line 983, in _find_and_load
File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
File "<frozen importlib._bootstrap_external>", line 728, in exec_module
File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
File "/app/experimentMusic/models.py", line 21, in <module> class Constants(BaseConstants):
File "/app/experimentMusic/models.py", line 26, in Constants
with open('D:\Experiment\oTreeproject\oTreeonlineshop-master\shop\oTree\experimentMusic\products.json', 'r', encoding='utf-8') as jsonfile: FileNotFoundError: [Errno 2] No such file or directory: 'D:\\Experiment\\oTreeproject\\oTreeonlineshop-master\\shop\\oTree\\experimentMusic\\products.json'

I also tried a version of code with normal slashes and with double backslashes and still received the same error. Next I tried to rewrite the path in models.py using Path from pathlib as follows:

from pathlib import Path
with open(Path('D:/Experiment/oTreeproject/oTreeonlineshop-master/shop/oTree/experimentMusic/products.json'), 'r', encoding='utf-8') as jsonfile:
data=jsonfile.read()
shoppinglist = json.loads(data)

It also didn't work, with similar error message.

What could be the problem? The file products.json is there and is not empty, so I have no clue why it doesn't work. I also tried to run the experiment on my local server and it works perfectly fine, so I guess the problem is the deployment on heroku. Any advice is welcome, thanks so much!

Best, Lina

Versions of the documentation

When one is not using the very last version of otree-core, he should be able to read the corresponding documentation.

It looks that it is very easy if you create git tags of documentation when you create git tags of otree-core: http://read-the-docs.readthedocs.io/en/latest/features.html#versions

Or at least one branch by major version?

Initial value of payoff

Cf. oTree-org/otree-core#337 it might be good to mention that payoff is None (as opposed to say c(0)), initially. Feel free to use the patch below:

From 08ded8d2d20c8de8f518275aac09baba9ad003e8 Mon Sep 17 00:00:00 2001
From: Rasmus <[email protected]>
Date: Mon, 22 Jun 2015 14:27:56 +0200
Subject: [PATCH 1/2] money.rst: Add note on inital value of payoff

---
 source/money.rst | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/source/money.rst b/source/money.rst
index 0625a70..6f4abd0 100644
--- a/source/money.rst
+++ b/source/money.rst
@@ -23,7 +23,17 @@ but when you pass them to an HTML template, they are automatically
 formatted as currency. For example, if you set
 ``player.payoff = c(1.20)``, and then pass it to a template, it will be
 formatted as ``$1.20`` or ``1,20 €``, etc., depending on your
-``REAL_WORLD_CURRENCY_CODE`` and ``LANGUAGE_CODE`` settings.
+``REAL_WORLD_CURRENCY_CODE`` and ``LANGUAGE_CODE`` settings.  The
+initial value of the ``payoff`` field is ``None``.  Before adding a
+value to ``payoff`` you should therefore check the whether the current
+value is ``None``, as in this example:
+
+
+.. code:: python
+
+    for p in self.get_players():
+            x = c(1.20)
+            p.payoff = x if p.payoff is None else p.payoff + x

 Note: instead of using Python's built-in ``range`` function, you should
 use oTree's ``currency_range`` with currency values. It takes 3
-- 
2.4.4

Double colons cause incorrect code block start

In the tutorial page for Public goods game, double colons in "Create the app" section is causing the code block to start in an incorrect position.

https://otree.readthedocs.io/en/latest/tutorial/part1.html

I've create d a pull request at #34

Improve Highchart documentation

Hi,

The highchart section does not even mention that high chart is how to add graphics to oTree. It should at the very least repeat the blob on page 10 of the oTree.pdf paper.

I will try to improve this section later, as I need to learn about graphing anyway. [I won't be using Highchart cf. next post].

Rasmus

loading pictures

Hi,

I am new to otree and I would like some help on importing graphics.

I followed the documentation creating a static folder and so on.
In the top of my template I included the line
'{% load staticfiles otree_tags %}'
However, this gives me an unresolved library 'staticfiles'
Subsequently loading the html the picture fails to load.

Can someone explain me what I did wrong?

formfield and loop example

Hi,

I would appreciate an example on how to combine { %for ...} loops and {% formfield ...}.

In my case I'm trying to do the following.

1. In views.py I have get_form_fields which dynamically makes a list of fields to modify in the Player table based on the current round and total rounds. In addition I create a list of lists in vars_for_template with contains string names of the fields I want to modify plus other stuff. Called it fields:

fields = [[int-a-ID, 'form_field_a1', 'form_field_a2']' [int-b-ID2, 'form_field_b1', 'form_field_b2']]

1. In my django html file I want to to add an input box for each element. I tried something like

{% for id, left, right in fields %}
<div class="panel-row">
  <div class="col-md-4">
    {{ id }}
  </div>
  <div class="col-md-4">
    {% formfield {{ left }} with label="" %}
  </div>
  <div class="col-md-4">
    {% formfield {{ righ }} with label="" %}
  </div>
</div>
{% endfor %}

This produces an error, where the backtrace contains

django.template.base.TemplateSyntaxError: formfield's second argument must be 'with'.

suggesting some sort of escaping is needed.

In general I don't understand how fields in e.g. the player table work together with view.py. I mean, I set a table and a list of fields. Some magic happens, and I end up (hopefully) populating the right field. But I only gave a string, not an actual field...

Further, when I search for django and %formfield I don't find much documentation. Is it relying on some 3rd party packages? E.g. someone must surely have had the problem of escaping such fields before, but I simply don't know the vocabulary needed to inform myself.

Thanks,
Rasmus

PS: Is there a (gmane-enabled) mailing list or IRC?

Add example of how to add columns dynamically to group and player

The manual talks about how to add fields that a particular view dynamically.

However, it would also be great to be able to add columns to e.g. the Player table dynamically.

E.g. I have something like this, which is asking for trouble.

    f1  = models.CurrencyField(initial=None, blank = True)
    ⋮
    f30  = models.CurrencyField(initial=None, blank = True)

E.g. is there something like a user "self.assign" for otree.models.BasePlayer?

Randomizing page sequence via rounds link broken

https://github.com/oTree-org/otree-snippets/tree/master/random_page_order does not work.

The link appears on https://otree.readthedocs.io/en/latest/pages.html#randomizing-page-sequence

Typo "beginneng" in otree-snippets

Not sure where to report this, since otree-snippets does not seem to be on GitHub (which would have let me submit this as a pull request). Anyway..

The typo "beginneng" appears twice on this page: https://www.otreehub.com/code/

class Transaction(ExtraModel):
    group = models.Link(Group)
    buyer = models.Link(Player)
    seller = models.Link(Player)
    price = models.CurrencyField()
    seconds = models.IntegerField(doc="Timestamp (seconds since beginneng of trading)")

interactive shell

Hi,

As Juan taught me, the way to get an interactive shell is not obvious for non-Djangoers cf. oTree-org/otree-core#338. I would at least not have been able to guess this myself, so perhaps it would be useful to note this. The below patch adds a subsection to debugging part of trying_your_app.rst:

From 10a6a558c8c16dd4fb754282a71b8aa78671d191 Mon Sep 17 00:00:00 2001
From: Rasmus <[email protected]>
Date: Mon, 22 Jun 2015 14:28:38 +0200
Subject: [PATCH 2/2] trying_your_app.rst: Notes on interactive session

---
 source/trying_your_app.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/source/trying_your_app.rst b/source/trying_your_app.rst
index 9fba7ff..6b12ce5 100644
--- a/source/trying_your_app.rst
+++ b/source/trying_your_app.rst
@@ -47,3 +47,14 @@ line by line.

 More on the PyCharm debugger
 `here <http://www.jetbrains.com/pycharm/webhelp/debugging.html>`__.
+
+Debugging and testing with the shell
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes it may be useful to test parts of the program from an
+interactive python shell.  You can start an interactive session using
+
+.. code:: shell
+
+    $ python otree shell
+
-- 
2.4.4

otree-core, oTree and virtualenv

Hi,

As python3 is the default in my distro, I want to install oTree via virtualenv. But I don't understand the relationship between the otree-core repo and oTree repo. When following the plain instructions I'm instructed to both install the otree-core (via pip) and clone oTree. E.g. otree binary of oTree repo seems to be necessary starting oTree.

As such, I would like clearer instructions in the Plain install part on how to setup with virtualenv.

Thanks,

mention how to debug errors in runproductionserver

hi,

I get a funny 500 error when I try to initialize a new session under gunicorn. It's not there when I use the developer server. Nothing useful is printed to stdout, perhaps because the error happens with a worker.
Perhaps the default Procfile should log to some file? Or perhaps the documentation should mention how to debug errors with gunicorn.

This is not the most structured bug; sorry.

Thanks,

MySQL (<= 5.7) documentation for python3

I managed to make oTree (almost, there is still some issue during the process) working with MySQL, but it was not an easy task for a non-python programmer.

It would be nice to improve the documentation. Here is what I did.

Be sure you have Python 3 installed:

# python --version
Python 3.5.1

Add the following line to requirements.txt:

https://cdn.mysql.com/Downloads/Connector-Python/mysql-connector-python-2.1.3.tar.gz

Then install the requirements:

pip install -r /app/sources/games/requirements.txt

It will install the official mysql driver, compatible with MySQL up to 5.7, and python 3.

Configure the database in settings.py:

DATABASES = {
        'default': {
            'HOST': 'localhost',
            'PORT': '3306',
            'ENGINE': 'mysql.connector.django',
            'NAME': 'otree_dev',
            'USER': 'otree',
            'PASSWORD': 'pass'
        }
    }

Finally, run the migration:

otree migrate

At this time, there is also an issue with the length of session._anonymous_code: https://github.com/oTree-org/otree-core/issues/453

formfield and loop example with label depending on forloop.counter

This is somewhat of a follow up question on #2.

The answer to #2 is very helpful and would definitely be worth adding to the doc.

Along the same lines, it would be nice if the doc explained how to have the forms' labels depend on the forloop.counter. I have tried using what I thought was a standard construct in Django template, namely

`{% for field in form %}

{% formfield field with label="blablabla {{ forloop.counter }}" %}

{% endfor %}`

but got {{forloop.counter}} appears as is in the label, instead of it being replaced by its value.

Also posted a question at http://stackoverflow.com/questions/32615979/parsing-forloop-counter-in-forms-label-in-django and tried the suggestion there got an error:

Could not parse the remainder: 's" }}?"' from '"blablabla {{ forloop.counter|stringformat:"s" }}?"' (Request Method: GET, Exception Type: TemplateSyntaxError, Django Version: 1.8.4)

Weirdly enough, the person who answered on Stackoverflow was not able to reproduce the error on his machine.

Deployment and Environement variables

Hi,

I deployed oTree to my Debian VM with apache2 and this was fairly straight forward. I wrote some step by step instructions, if that's useful.

However, I'm confused about some of the environment variables and parts of settings.py.

• OTREE_PRODUCTION: From the settings.py it seems this variable controls whether debug info is shown.
• IS_OTREE_DOT_ORG: Do I need to care about this variable at all?
• OTREE_ADMIN_PASSWORD, OTREE_SECRET_KEY: Looks like variables I should care about, but not in manual. What's the difference between KEY and PASSWORD?
• OTREE_AUTH_LEVEL: In the manual, I'm told to set it to DEMO when I want to use my server for production.... What does it do?
• ACCESS_CODE_FOR_DEFAULT_SESSION: What exactly is the purpose of this variable? Is that what users have to put in?
• On database setup: you mention complicated stuff on PostgreSQL. When I downloaded my copy of oTree.git I got something like the following, which Just Work™. Reading the manual, I don't understand if I have to dig further into setting up databases, or whether the default setup is fine.

DATABASES = {
    'default': dj_database_url.config(
        default='sqlite:///' + os.path.join(BASE_DIR, 'db.sqlite3'))}

Edit: The point of this issue is of course, that I think it would be helpful to have slightly better documentation on the deployment step.

Translating experiment to other language

Hi,

The oTree paper pp. 10 mentions localization. Yet I don't see any information on how to actually do this in the manual (I searched for localization, local and translate but didn't see anything immediately useful). A short introduction to this, or at least a link to the corresponding django documentation should be part of the manual imo.

Rasmus

Missing information on oTree Studio pricing

I note https://otree.readthedocs.io/en/latest/studio.html says:

oTree Studio is a point-and-click interface for building oTree apps.

We recommend for new users to start with oTree Studio instead of a text editor (like PyCharm), because it has makes learning oTree much easier and has a free 30-day trial.

The site itself has nothing about pricing, just login and register links - even the top level oTree Hub page says just:

oTree Hub

oTree Hub is the central place to build, launch, and monitor your oTree experiments.

• Design your experiment in oTree Studio, a visual interface for building oTree apps.
• Deploy and manage oTree servers on Heroku
• Browse public oTree projects

What is the pricing model, and could the documentation point at this information please?

Something is wrong with the stylesheet on readmydoc

This is what the readmydoc manual looks like when my screen is constrained to half of my screen (== 720px). This is using Firefox. It looks fine when it can use the entire width (1440px).