.. _start-project:

==================
Starting a project
==================

Let's create a new project called ``myproject``. It is best to base it on the demos provided with ``psychopy_ext``, so copy the contents of the ``demos`` folder (:ref:`where is it? <where-is-demo>`) to ``myproject``.

Observe the typical structure of a project::

    myproject
    |-main           (data for the main experiment)
      |-data/        (autogenerated when you run the experiment)
      |-logs/        (autogenerated when you run the experiment)
    |-scripts/       (this is where your scripts live)
      |-__init__.py  (empty)
      |-main.py      (main experiment)
      |-twotasks.py  (another experiment)
      |-...
    |-__init__.py    (empty)
    |-run.bat        (shortcut for Windows users instead of run.py)
    |-run.py         (this is the one and only script you ever run)

Now find the ``run.py`` file, and run it (:ref:`how? <how-run-demo>`). You'll see an app appear for the *Demo Project*:

    .. image:: ../gui.png
        :width: 300px

Experiments belonging to this project are listed on the left, and options for each experiment are listed in tabs. You can choose various parameters how to run the experiment, such as entering the participant ID or determining if the experiment should run in full screen. Note that ``psychopy_ext`` generates these apps completely automatically by collecting information within your project. (For command-line ninjas, a powerful command-line interface is provided too.)

Let's have a peak into the source code to see how it's done.


---------------
``run.py`` file
---------------

The ``run.py`` file is simple -- it only calls the app generator (or the command line interpreter). You need to provide details about experiments within your project::

    from psychopy_ext import ui

    __author__ = "Jonas Kubilius"
    __version__ = "0.1"
    exp_choices = [
        ui.Choices('scripts.main',  # path to the 
                   name='Simple',
                   alias='main',  # alias to call it from CLI
                   order=['exp','analysis']),  # order of tabs in GUI
        ui.Choices('scripts.twotasks', name='Two tasks')
        ]

When all is set, you call the graphic user interface (GUI) or the command-line interpreter (CLI)::

    ui.Control(exp_choices, title='Demo Project')
    
By default, a GUI as we saw above is opened, and you can then choose options how to run the experiment and an analysis. We will see where these options come from in the :ref:`exp` section.

However, it may be faster to run your scripts using a CLI. To do so, you will have to enter options in the terminal (or the command line)::

    python run.py main exp run --subjid confsup_01 --no_output
    
Input structure:

* ``python run.py`` - Python runs the specified script
* ``main`` - alias of the module you want to call
* ``exp`` - task you want to do; in this case, you options are "exp" for running the experiment and "analysis" for analyzing data
* ``run`` - what you want to do; in this case, there is only one option ("run"), but it becomes very handy when you have multiple analyses implemented (each gets its own button then)
* ``--subjid confsup_01`` - an input variable name and a its value (meaning that the participant ID will be set to confsup_01)
* ``--no_output`` - a flag indicating that no ouput should be stored

All items with '--' are optional.

Whether you use a GUI or a CLI, the result is that the relevant Python script (via a command line input) is called.

See the next part to learn how to setup defaults for your computer: :ref:`computer`.
