Getting Started

As an application, PsychoPy has two main views: the Builder view, and the Coder view. It also has a underlying API that you can call directly.

1. Builder. You can generate a wide range of experiments easily from the Builder using its intuitive, graphical user interface (GUI). This might be all you ever need to do. But you can always compile your experiment into a python script for fine-tuning, and this is a quick way for experienced programmers to explore some of PsychoPy’s libraries and conventions.

   

2. Coder. For those comfortable with programming, the Coder view provides a basic code editor with syntax highlighting, code folding, and so on. Importantly, it has its own output window and Demo menu. The demos illustrate how to do specific tasks or use specific features; they are not whole experiments. The Coder tutorials should help get you going, and the API reference will give you the details.

   

The Builder and Coder views are the two main aspects of the PsychoPy application. If you’ve installed the StandAlone version of PsychoPy on MS Windows then there should be an obvious link to PsychoPy in your > Start > Programs. If you installed the StandAlone version on macOS then the application is where you put it (!). On these two platforms you can open the Builder and Coder views from the View menu and the default view can be set from the preferences. On Linux, you can start PsychoPy from a command line, or make a launch icon (which can depend on the desktop and distro). If the PsychoPy app is started with flags —-coder (or -c), or —-builder (or -b), then the preferences will be overridden and that view will be created as the app opens.

For experienced python programmers, it’s possible to use PsychoPy without ever opening the Builder or Coder. Install the PsychoPy libraries and dependencies, and use your favorite IDE instead of the Coder.

Builder

When learning a new computer language, the classic first program is simply to print or display “Hello world!”. Lets do it.

A first program

Start PsychoPy, and be sure to be in the Builder view.

• If you have poked around a bit in the Builder already, be sure to start with a clean slate. To get a new Builder view, type Ctrl-N on Windows or Linux, or Cmd-N on Mac.

• Click on a Text component

  

  and a Text Properties dialog will pop up.

  

• In the Text field, replace the default text with your message. When you run the program, the text you type here will be shown on the screen.

• Click OK (near the bottom of the dialog box). (Properties dialogs have a link to online help—an icon at the bottom, near the OK button.)

• Your text component now resides in a routine called trial. You can click on it to view or edit it. (Components, Routines, and other Builder concepts are explained in the Builder documentation.)

• Back in the main Builder, type Ctrl-R (Windows, Linux) or Cmd-R (Mac), or use the mouse to click the Run icon.

  

Assuming you typed in “Hello world!”, your screen should have looked like this (briefly):

If nothing happens or it looks wrong, recheck all the steps above; be sure to start from a new Builder view.

What if you wanted to display your cheerful greeting for longer than the default time?

• Click on your Text component (the existing one, not a new one).
• Edit the Stop duration (s) to be 3.2; times are in seconds.
• Click OK.
• And finally Run.

When running an experiment, you can quit by pressing the escape key (this can be configured or disabled). You can quit PsychoPy from the File menu, or typing Ctrl-Q / Cmd-Q.

Getting beyond Hello

To do more, you can try things out and see what happens. You may want to consult the Builder documentation. Many people find it helpful to explore the Builder demos, in part to see what is possible, and especially to see how different things are done.

A good way to develop your own first PsychoPy experiment is to base it on the Builder demo that seems closest. Copy it, and then adapt it step by step to become more and more like the program you have in mind. Being familiar with the Builder demos can only help this process.

You could stop here, and just use the Builder for creating your experiments. It provides a lot of the key features that people need to run a wide variety of studies. But it does have its limitations. When you want to have more complex designs or features, you’ll want to investigate the Coder. As a segue to the Coder, lets start from the Builder, and see how Builder programs work.

Builder-to-coder

Whenever you run a Builder experiment, PsychoPy will first translate it into python code, and then execute that code.

To get a better feel for what was happening “behind the scenes” in the Builder program above:

• In the Builder, load or recreate your “hello world” program.

• Instead of running the program, explicitly convert it into python: Type F5, or click the Compile icon:

  

The view will automatically switch to the Coder, and display the python code. If you then save and run this code, it would look the same as running it directly from the Builder.

It is always possible to go from the Builder to python code in this way. You can then edit that code and run it as a python program. However, you cannot go from code back to a Builder representation.

To switch quickly between Builder and Coder views, you can type Ctrl-L / Cmd-L.

Coder

Being able to inspect Builder-generated code is nice, but it’s possible to write code yourself, directly. With the Coder and various libraries, you can do virtually anything that your computer is capable of doing, using a full-featured modern programming language (python).

For variety, lets say hello to the Spanish-speaking world. PsychoPy knows Unicode (UTF-8).

If you are not in the Coder, switch to it now.

• Start a new code document: Ctrl-N / Cmd-N.

• Type (or copy & paste) the following:

  from psychopy import visual, core
  
  win = visual.Window()
  msg = visual.TextStim(win, text=u"\u00A1Hola mundo!")
  
  msg.draw()
  win.flip()
  core.wait(1)
  win.close()
  

• Save the file (the same way as in Builder).

• Run the script.

Note that the same events happen on-screen with this code version, despite the code being much simpler than the code generated by the Builder. (The Builder actually does more, such as prompt for a subject number.)

Coder Shell

The shell provides an interactive python interpreter, which means you can enter commands here to try them out. This provides yet another way to send your salutations to the world. By default, the Coder’s output window is shown at the bottom of the Coder window. Click on the Shell tab, and you should see python’s interactive prompt, >>>:

PyShell in PsychoPy - type some commands!

Type "help", "copyright", "credits" or "license" for more information.
>>>

At the prompt, type:

>>> print u"\u00A1Hola mundo!"

You can do more complex things, such as type in each line from the Coder example directly into the Shell window, doing so line by line:

>>> from psychopy import visual, core

and then:

>>> win = visual.Window()

and so on—watch what happens each line::

>>> msg = visual.TextStim(win, text=u"\u00A1Hola mundo!")
>>> msg.draw()
>>> win.flip()

and so on. This lets you try things out and see what happens line-by-line (which is how python goes through your program).