Writing Software Project Requirements

Introduction

It is important to carefully consider the proposed program and the experiment, before making a formal request for the program. This ensures that the program is developed as quickly as possible, and does exactly what is required.

When requesting a program, the client should think in terms of what they want, and ignore what they think the computer can do. The client should give an ideal-world list of their requirements, then, the programmer can advise on what is, and what is not, possible.

Misunderstandings between the client and the programmer can be frequent and wasteful. Therefore, it is essential to be clear about what is required of the program. Discussions between the client and programmer are valuable, and should start as early as possible. It is important that the programmer can contact the client at short notice to clarify any issues, and offer prototypes for testing and feedback. Also, it is usual for several prototypes to be produced, so that the client has a better idea of what the final product will look like. It is likely that experimental procedures and parameters will be changed as pilot runs are conducted. This is natural and need not be a problem, providing that the factors most likely to change are identified early in the design.

This develop-demonstrate-develop cycle is known as "rapid prototyping" and is a very useful strategy in a research environment. Whilst it avoids having to predict vague and abstract (or simply unknown) features, it should not be seen as a replacement for careful planning. However, it requires the client to provide feedback to the programmer. Note that if the client is unavailable and no requirements have been given, development may be stopped until the client is available.

Software Features

• Pseudo-random numbers can be generated repetitively (all participants get the same sequence of `random' stimuli), or they can be different for each participant. The sequence can be controlled so that, although different for each participant, the exact sequences can be repeated.
• The stimuli may be of any appropriate nature, although stimulus presentation devices requiring high electrical power (e.g. mains lighting) require extra hardware, which takes extra time to produce.
• It is usually possible to time stimulus events (as opposed to responses) with equal accuracy and resolution. There are several ways of presentating stimuli, the most obvious being the monitor screen. Monitors are not suitable for presentations requiring a high degree of resolution and accuracy because they display images for multiples of a specific duration (about 15 ms). This value is quite stable but can vary between PCs. For applications where the presentation time is critical, LED's are recommended as they can be controlled with a precision of 1 ms. However, Producing high-resolution images with LEDs is not possible.
• External events (e.g. decision and movement times) can be timed to a resolution of 1 ms with an accuracy of +/- 1 ms.
• The computer is able to control a maximum of 40 inputs/outputs at any time.
• Error handling and user-friendliness are important features of a program but usually make a substantial impact upon program complexity and development time.
• A statistical package such as SPSS can be used for all statistical analysis. The experimental results can be saved in plain text (flat ASCII) format. Statistical analysis cannot be included within our programs.
• It is possible to design the program to operate automatically with no user intervention (other than the participant's, presumably). This is called batch mode. For instance, you may require a program to reformat data files. If you have data files for many subjects, it would be tedious to run the program manually for each participant's data file. This can be avoided by telling the computer to process, say, all files in the current directory. The command to filter all files ending with .DAT might look like this: C:\STROOP\DATA>FILTER *.DAT
• Command line parameters are simply letters and filenames that you type along with the command. These parameters can be used to modify the program's behaviour, and work similarly to the user-prompts you normally use (such as "enter the participant's age, ID, sex", etc.). If you don't want to enter these one-by-one, they can be entered all at once on the command line. If you don't want to enter any such details, a single parameter could tell the computer to skip the questions. See below.

Specification Changes

• It is important that the program is fully evaluated prior to use in real research. Every effort is taken to avoid bugs but these may still occur, especially during the initial uses of the program. Should any errors occur, they will be dealt with as a priority initially. After a reasonable amount of use, support will be offered on a lower priority. For this reason, it is important to test the program thoroughly as soon as possible.
• If a major change to the software is necessary, the original release of the program will be replaced by a new version. If the experimenter feels that they may still require the old release please inform the programmer. Following the release of new versions, technical support will have a higher priority until the new version is clearly reliable.
• Major changes to the software may have to be undertaken as a new 'job'. This means that the 'job' will have to wait its turn, while other jobs are completed. This can give rise to long delays so again planning is important.
• While it can be difficult to predict changes, it is possible to speculate reliably about their likelihood and nature. By foreseeing changes, we can build-in the ability to accommodate them, saving time and effort, and giving greater control over experimental conditions from the very outset (the experimenter need not wait for software changes to be made).
• Software changes fall into two categories: changes to the process, and changes to the data. Data changes are usually harder to implement than changes to process so the program's data (and its format) should receive special attention.
• It is important to understand the significance of version numbers. Their main purpose is to enable the tracking of various releases of the same program. It helps to ensure that the correct version of a program is being used. Numbers before the decimal point represent major changes, while numbers after the decimal point indicate minor changes. Some examples of version numbers are 0.23 (a development version - not yet released for official use); 1.0 (first official release); 1.2, (two slight feature changes since first release); 2.0 (major change from version 1.x).
• When a program is in the development stage, the number will be 0.xx. with the digits represented by xx increasing as the program develops. Thus, version 0.17 will be the seventeenth step in the development of the software. Development versions are for testing purposes only, and should not be used for official data collection. Testing of the data measures usually occurs in the last stages of development. When the program is first released for official participant testing, the version number will become 1.0 and you can trust the results.
• New versions developed only to repair a bug are indicated by a letter (for example, 1.1 to 1.1a). A planned change (no bugs were involved) from 1.1a would take the version number to 1.2 (not 1.1b or 1.2a).

Glossary

Subject Details (Name; Age; Sex; Date of birth)

Indicate all input requirements and the format they should take (i.e. date of birth may be in dd/mm/yy, name may be limited to n characters)

Experiment Details (Experimenter name; Date; Time)

If required, the system clock can set the date and time automatically, or by default (if the user presses a specific button at the prompt).

Other User Prompts (Instructions; Stimulus or results filenames)

If the participant is to be shown a set of instructions, the computer can display these from a text file. This has the advantage that the experimenter is able to change the file without contact with the programmer.

Test Parameters (Number of trials; Number of trial-blocks)

It is usually most convenient to have the test (and trial) parameters read from a stimulus file. The program can request a filename. If none is given the program can abort, or use a random (or pre-defined) set of parameters. The use of a stimulus file enables the experimenter to alter the test without recourse to the programmer. It is helpful to specify minimum and maximum possible values for all parameters early in the design stage.

Test Structure (Practice session; Trials arranged linearly or in blocks)

The computer can present trials in a straight sequence or arranged in blocks of a certain number (e.g. where conditions are being varied between blocks). Also, a practice session can be added, which is merely a number of trials whose results are not saved.

Stimuli Type (Words; Sounds; Images)

The experimenter can specify words, or images to be presented on screen, or sounds to be produced by the PC's speaker. Graphics stimuli are limited to simple line drawings and 2-dimensional shapes (2D representations of 3D can be too complex and slow for reaction-time experiments). Define images in terms of their colour and shape by drawings, etc. They should also have their screen size specified, along with the Inter-Stimulus Interval (ISI). Sounds should have their pitch defined. Text should have its on-screen size defined. All these items must have their duration defined and can be defined from a stimulus file. Note that the best possible resolution for stimulus screen duration is about 15 ms, so a stimulus presentation's duration will be a multiple of this value (which can vary between PCs).

Event Timing (Stimulus presentation times, Reaction times)

The experimenter must specify the events to be timed. Decision time and movement time are the usual measures. Decision time is the time taken from onset of the stimulus, to first reaction of the participant (for example, release of a 'home' button). Movement time is the time taken from the release of the 'home' button to the press of a response button. Reaction time is the addition of these two. Where a 'home' button is not available, reaction time is the only recorded measure. It is necessary to specify the units of the results (seconds, milliseconds).

Additional Hardware (Response buttons, Stereo headphones)

Where stereo (bi-lateral) auditory presentations are required, stereo headphones will be used. Where a specific response button layout is required, a button-pad will be constructed. It should be borne in mind that the keyboard is not ideal as a reaction pad from the psychologist's and programmer's points-of-view. Also, where the duration of graphical stimuli has to be closely controlled, it may not be possible to use the screen. Graphics hardware is not readily available, so such stimuli are limited to on/off indications, though simple 2-dimensional stimuli can be presented with a crude matrix of lights. If the structure of the device is important (position of buttons or stimuli, etc.) then a simple construction diagram giving dimensions should be drawn.

Output Format (Results filename; Data format; On-screen summary)

The computer can prompt the user for a filename in which to store the results from the experiment. The data will be saved in ASCII (text) format is compatible with any editor or word-processor (and SPSS). Specify the SPSS format (fixed or free) general format (for example one line per trial) and the structure of each individual item (for example leading zeros, minimum number of digits). Also specify the meaning of the data items. For instance, if you have a data item indicating whether the correct button was pressed, would you want it to be written in the results file as 'correct/wrong', 'yes/no', or '1/0'. We recommend avoiding the use of correct/incorrect as they look too similar and can be confused when reading long printouts. Also, when specifying what data is to be saved, always err on the generous side. It is always better to have too much information than too little. Any unused information can be easily ignored. Excessive quantity of data is not really a problem as even floppy disks are capable of holding over one hundred files of average size (say 10 KB). Each participant's data files will probably not exceed 20 KB (as a very rough estimate) in size.

Data Analysis (Descriptive statistics, 3S.D. stripping)

Due to pressure of time, we can no longer produce programs to calculate statistics other than simple means. As the results will be in ASCII format, any statistics should be performed with a separate statistics package.

Program Options (Command-line options)

It is possible to add command-line options to tailor the operation of the program. This feature is especially useful for running a program automatically (using batch file programs for instance). These options might include making the program ask for a participant number instead of name, or to skip certain user-prompts such as results filename, age/sex, etc. This allows the programmer to make the program as versatile as possible, while allowing the experimenter to turn off irrelevant features to simplify the participant testing procedure.

Content last updated: 2002-11-06