dSurvey main page | Control panels | Specification files | Dynamic extensions in modules | List of documentation files

## dSurvey: a web-based tool for conducting surveys and experiments.

Contents:
  1. Introduction
     What is dSurvey
     Some basic terms
     The components of dSurvey
     Programming with dSurvey
     Some philosophy, and limitations, of dSurvey
  2. Outline
     Creating the survey instrument
     Creating a survey session
     Opening a control panel, and enrolling participants
     Displaying and controlling modules
  3. Appendix
     Advantages and disadvantages of dSurvey

Introduction
dSurvey is a flexible and powerful tool for creating and running a variety of dynamic surveys, experiments, and other forms of questionaires. dSurvey is completely web-based. This means that dSurvey requires installation on a web server.

- To administer dSurvey: /dsurvey/admin.htm
- The dSurvey home page (requires setup): /dsurvey/dsurvey.htm

Are you looking for installation instructions (and tips on file structure)?

But perhaps you want to learn more about dSurvey? Then read on...
I.1. What is dSurvey
dSurvey is a software package that facilitates the creation of dynamic surveys: where surveys refers to experiments, questionaires, open-ended public surveys, and all sorts of data gathering exercises that involve active involvment by more than one participant.

In a nutshell ...

- There are 3 actors in a dSurvey survey:
  1. The participants
  2. The administrator
  3. The web server
- Each actor uses a different component of the dSurvey software. All of it is web based: with the administrator and participant running software that requires a Mozilla (i.e.; FireFox) web browser, IE 8 or above, and the web server software specific to the type of web server software being used.

Let's clarify the above terminology -- tt will make the rest of this documentation much easier to understand if you understand how these terms are used!

Dynamic | What makes dSurvey useful is the ease of creating dynamic surveys. By dynamic, I mean surveys whose contents can change over time, and across different participants. These changes can be in real time, they can occur as directed by a survey administrator (without any action by the participant), and they can be sensitive to information provided by the participant. In other words, dynamic means that the survey instrument can be far more complex/fancy than a simple web form.
Participant / client | A human being who is taking part in the survey -- who is reading the descriptive material, reading questions, making choices, and submitting his responses. Again, in this documentation survey is a shorthand for traditional surveys, for interactive experiments, etc. etc etc. Client Client refers to the dSurvey software running on the particpant's browser. The client is responsible for changing what the participant sees on his browser. These changes include: positing new questions, providing a variety of means (textboxes, checkboxes, etc) for the participant to provide answers, and submitting this information to the administrator. Of course, all these changes will be in response to directions issued by the administator. Thus, the clients (each participant has his own client) must be in communication with the adminstrator. This communication is done through a web server.
Administrator | The administrator controls the survey -- he controls what is being displayed, when this display should be changed, and what each particpant should be seeing (and when he should be seeing it). The administrator will also gather information submitted by each participant. In addition to saving this information onto a database, the adminstrator will often process this information in real time, and use the results (of this processing) to modify just what each participant will see next. And that's a big part of what it means to be dynamic! Note that the administrator (a person) controls the survey by using a control panel -- a program that runs on his browser.
Web based | The medium that links participants and the administrator is a web-server. More precisely, it is dSurvey software running on a web server. This software will recieve `http requests` from clients, and from the administrator. Sometimes these requests contain information to be saved. Sometimes these requests are queries for information on what to do next. This means that ... The dSurvey software must know how to work with the web server. Right now, only the OS/2 SREhttp/2 web server is supported by dSurvey. By the time dSurvey is into beta, Apache will also be supported.

I.2. The components of dSurvey
So now that the actors of a dSurvey survey have been defined, lets consider the basics of a dSurvey survey.

1. An actual working survey is called a survey session.
2. Each survey session is created from a survey instument
3. There can be many survey sessions based on a single survey instrument.
4. Information submitted by participants, and results computed by the administrator, are specific to session
5. In other words, a survey instrument is a template that is used to create a survey session.
6. Participants join a survey session. The do not join an instrument.
7. An administrator manages a survey session using a control panel that is specific to this survey session.
8. What each particpant sees (the descriptions, questions, and input areas) is controlled by session-specific parameters. Some of these parameters are the same across all participants. Some are different for each participant. Some of these parameters may be changed throughout the course of the survey; changes that can influence what descriptions are shown, and the details of what questions are asked. And these changes can vary across participants. Furthermore, these changes can be based on information submitted by the participant.
9. A survey is often divided into rounds. For example, in experiments there are often repetitions of the same (or slightly modified) questions -- each repetition would be a round. More generally, a round can be thought of as a new beginning -- with new parameters being applied at the beginning of a round, and a round ending when all participants have answered their questions, and after all the submitted information has been processed. In fact, typically a round will start by reporting the results of the prior round, results which are computed by the administrator (more likely, custom functions that are accessed by the control panel) using "submitted information" of a prior round.

With these basics in mind, we can define several components of a dSurvey survey. For any survey, one must create these three components in a systematic fashion -- since each component uses, or is used by, the other components.

The survey instrument
  The survey instrument contains the the descriptions, questions, and input fields that a participant views and uses.
  The survey instrument has several pieces:
  - Parameters that describe basic features of the survey instrument are stored in a instrument descriptor file.
  - For maximum flexibilty, dSurvey uses modules to implement a survey instrument. Modules contain the actual HTML code used to display the survey's contents. They also contain special dynamic extensions to basic HTML -- these extensions are used to specify the display of information that can vary across time and across participants.
    They are also used to setup input fields that participants use to respond to questions
  - A module specification file is used to control which modules to display when. Basically, the specification file (the SPEC file) tells the client what to ask the web-server for, and what to do with responses from the web server (for example, which modules to show next).
    Anticipating discussion below, we designed the structure of SPEC files so that they are fairly easy to write -- though they do require learning a set of commands. Soon (12 Nov 2009), we will create a web interface that can assist the creation of SPEC files!
The parameter files
  The parameter files specify session specific, and participant specific, parameters.
  - The session descriptor is created from the instrument descriptor file. It contains basic information on the survey session.
  - The session specific parameters (which do not vary across participants) are used to customize the survey -- so that within a single session one can display a variety of descriptions and questions. Typically, before the start of a new round a new variation of the survey is devised by selectively changing these parameters.
  - Participant specific parameters are used to specify the attributes of each participant. For example, in an experiment these attributes may be the endowments and opportunities avaiable to each participant. In other words, these are parameters that will vary across each participant, in a fashion controlled by the survey designer & administrator. Typically, these parameters do not change across rounds of a session -- though which parameters are used in a given round is completely subject to change.
The control panel
  The control panel is used to manage the survey session. Control panels are specified by a control-panel program. These control-panel program are fairly easy to write, offering design features that simplify the specification of how the administrator controls a survey session.
  - Each survey instument has its own control panel program.
  - Thus, each session uses its own copy of its instrument's control panel program.

I.3. Programming with dSurvey
So, to create a working survey, you need to create the various components of dSurvey (the descriptor files, modules, etc.).

These are written with three different `languages`: XHTML, XML, and JavaScript.

- Modules are written using dynamic XHTML.
  By specifying special attributes (within XHTML elements), the content displayed can be be influenced by parameters (both session and participant specific).
- Parameter files, and descriptor files, are written in using XML (the exact syntax is described below).
- Module specification files and control panel programs are also written using XML (the exact syntax is described below).

Lying behind these components is JavaScript code -- code that will interpret the specification files and the control panel programs. Furthermore, there are several places where custom javascript procedures can be called.

As of this writing, dSurvey has been tested with FireFox (version 3.x) and Internet Explorer 8). Unfortunately, prior to version 8, Internet Explorer lacked adherence to Javascript standareds. Thus, Internet Explorer 7 (and earlier versions) can not be used with dSurvey.
I.4. Some dSurvey philosophy & limitations
Perhaps what you have just read seems convoluted. Perhaps you have read what follows and found that even more convoluted. Perhaps you are asking why such troublesome complications are necessary?
The key design goal of dSurvey is to expedite the efficient construction of complex, dynamic surveys that are web-based... and that require minimal commitment of server resources. This means that the choice of which page to display next, and what the contents of this page are, should not require a lot of server processing.

In contrast, one could design survey software where the server handles the workload -- the server decides which page each participant should get whenever a new page is needed. More importantly, for each participant the server customizes each page, inserting participant-specific values (say, a participant specific cost variable).

There are several shortcomings to a server-centric approach:

1. If the number of participants is large, and the pace of decision making is quick, server load may be substantial. In particular, if many participants submit information at nearly the same time, and are then given customized web page -- the server load can lead to significant response delays, or worse (i.e.; server hangs).

   > For example, 20 people participating in an auction experiment, where each round of the auction lasts 30 seconds. And where the choice facing each participant changes between rounds, based on their success or failure in the prior round.

   Moreover, the more the customization, the greater the load; since customization of web pages tends to be much more demanding (on server CPU resources) than merely transfering a file whose contents do not change.
2. Programs running on the server need to be written to handle the customization. Although not onerous, this does impose extra work on the survey designer. To the extent this work can be simplifed, using commonly used browser tools, the easier design becomes.

dSurvey, with its modular design and support for dynamic extensions, addresses these shortcomings by moving as much work as possible to each participant's machine. In addition, dSurvey uses XML and javascript scripting tools to implement the dynamic presentation of the potentially numerous (and often cyclically displayed) web pages that comprise a survey instrument. And it is likely that competence in XML (and javascript) is more widespread than knowledge of server-side programming tools (such as PHP).

#### Limitations

dSurvey has limitations. If you aren't willing to wrestle with these limitations, you may wish to investigate other tools.

- As of this writing, dSurvey contains few tools and utilities.This means ...
- You really should understand the basics of HTML coding. You should be mildly comfortable with XML syntax. And while it is not necessary, if you want to get fancy (say, computing intermediate results that are used to change what participants see in later rounds), a working understanding of JavaScript is recommended.
- Many of the the various files that are required (the module files, etc) must be written by you -- the survey designer -- using your favorite text editor. It may be possible, even easy, to configure HTML creation software to construct the XML files that define a dSurvey survey. However, at this writing, we can not provide any hints.
- There are now several utilties, accessed through dSurvey's main adminstrative page that can be used to create several of these files (such as the session and participant specific parameters files.
- We may create XML style sheets for each of these various types of file.
- As of span this writing, dSurvey uses a javascript dialect that is not fully supported by versions Internet Explorer prior to version 8. You should use FireFox 3.0 (or later), or Internet Explorer 8.0 (or later).
- As a web-based product, a dSurvey can be taken by people spread across the Internet. This is quite convenient, but since the web is far from 100% robust, this can also can be treacherous -- disconnections and other noise can interfere with communications between participants, the administrator, and the web-server. And such interfences can lead to loss of data, and to worse (such as being dropped from the survey). As noted above, the distributed nature of dSurvey is largely driven by the desire to minimize such problems. Nevertheless, it still is an issue.
- Furthermore, as a web based design, extremely speedy throughput can not be guaranteed. If you need response times on the order of fractions of a second, dSurvey may not be right for you.
- As a web based product, dSurvey is naturally vulnerable to malicious attack. dSurvey is not designed with high security requirements -- to protect dSurvey, you will have to use whatever security protocols are provided by your web server.

  Actually, it is worse than that. To save throughput and processing time, dSurvey often sends extra information to participants. This "extra" information often includes data on what other respondents have done. In many cases, this data could be used by an unscrupulous participant to gain advantage. Such use would not be technically easy: information retrieval and storage is all done by javascript programs, so is never visible to the participant's eyeballs. Nevertheless, it is a potential weakness.

More discussion of the strengths and weaknesses of dSurvey
II. Outline
With the introduction firmly in mind, let's outline what needs to be done to create a dSurvey session.
The links in the first column will bring up detailed documentation on the topic!
Links and descriptions in this kind of box point to useful dSurvey utilties.
Note: These dSurvey utilties are meant to specify options that almost all survey/instrument designers are likely to use. That is, a number of the more advanced options can not be set by these utilties (default values are used).
Thus, advanced and technically proficient dSurvey users may find these utilties inconvenient (or, only useful as a starting point).

Creating the survey instrument First, one must create the survey instrument. This entails creating: An instrument descriptor file One or more module files (the modules containing XHTML code with dSurvey's dynamic extensions) An instrument specification file A survey control panel program Parameter files The base home page
Instrument Descriptor File | The instrument descriptor specifies the basics of a survey instrument, such as its name, where module files are stored, the names of parameter files, and some access control (username/password) parameters. You can use the Create an instrument utility to create a new instrument, or to modify files associated with an existing instrument. This utility will allow you to specify (or change) almost all of the variables in an instrument's descriptor file
Modules & dynamic extensions | A dSurvey survey is based on modules. This means that a survey instrument is built using discrete blocks of extended XHTML code -- each of these blocks is what we call a module. Building a survey instrument with these modules is, at a first approximation, a matter of listing what modules comprise each page of the survey instrument, and when and how to display each of these modules. While the ability to selectively choose the order and sequence of module display is a powerful capability, it is rather coarse. Often, fine-detail control of the contents of a web page is useful -- such as the ability to display a participant-specific value of some parameter (say, a cost variable in an auction experiment). dSurvey uses extensions to provide this fine control. Moreover, these extensions are used to control a number of actions; such as the submission of participant-specified information, and when to display a new page (built from a new set of modules). If you create an instrument using the Create an instrument utility, then a genericModules module file will be created. This genericModule module file is designed to implement a set of startup screens that will be seen by the participant.
SPECification file | As discussed above: at a coarse level, a dSurvey survey proceeds by display of different modules. The control of which modules to display, and when, is a principal means of introducing dynamics in to a session. Specification files (SPEC files) are used to achieve this control. If you create an instrument using the Create an instrument utility, then a basic SPEC file will be created. This basic SPEC file is designed to implement the startup screens seen by the client. Note that the basic SPEC file is designed to work with the genericModule module file (that is mentioned above). The hope is that by using this basic SPEC file as a starting point, the chore of creating one's SPEC file will be easier.
Control panel program | During the course of a survey, the administrator may have to take a variety of actions. This includes dictating what the participants should be seeing, changing parameters that control the details of the survey, saving or computing results from information submitted by the participants. While there are other means of controlling your session, the preferred mechanism is via the use of control panel programs. Control panel programs are structured as XML files, with special tagnames and attributes that implement a simple scripting language understood by dSurvey. These tagnames and attributes allow you to specify tasks. These tasks allow you automate many administrative actions, some of which may be relatively complicated, with a small amount of coding. However, this power comes at a cost: you have to write a control panel program for your instrument. Besides having to learn the syntax, one must be sure to coordinate with the SPEC files, and with the XHTML extensions used in the modules -- the control panel program should be modifying variables that the SPEC files, and the extensions, work with! Within a control panel programs there are two classes of options. Generic options: these are accessed via drop down menus, using a menubar at the top of the screen. Generic options are meant to be used by proficient administrators. Tasks: tasks are specific to an instrument, and are specified by the creator of the instrument's control panel program. The expectation is that the designer will use specify a complete set of tasks: at set of tasks that does everything a session administrator will need to do. Since there are a number of generic tasks that are likely to be used in a wide variety of instruments, dSurvey provides a basic control panel. This basic control panel implements a set of generic tasks that take one from session startup to display of the introductory page of an instrument.. If you use the Create an instrument utility., a basic control panel program for this instrument will automatically be created. As noted above,this basic control panel implements several generic tasks that control the startup of a session (such as a task that controls whether new participants can join the session). Note that this basic control panel program is designed to work with the basic SPEC file (that is noted above). You can view a template of these control panels. The hope is that by using this basic control panel as a starting point, the chore of creating one's control panel program will be easier.
Parameter files | Parameter files are used to store parameters that influence the details of the survey. They are also used to store parameters that specify attributes assigned to each participant. In the instrument descriptor file, you can specify instrument specific parameter files. Often, two parameter files are specified, one that specifies general parameters (that apply to all participants), and one that specifies reference data, that is used to assign participant-specific values. You can use the create, or modify, other instrument files utility to create & modify the general and reference parameter files.
The survey's base web page | The `base home page` is a file that a participant loads to actually start the survey. The base home page is specific to an instrument. That means that all sessions based on a given instrument will start by loading the same file (parameters included in the request to load this file are used to forge a link to the desired session). The base home page is actually quite generic: in most cases you can use the example without any changes. Though you might want to change its name, making sure it matches the `HOME_PAGE` variable in the instrument descriptor file. If you create an instrument using the Create an instrument utility, a base web page will automatically be created. You will not have to edit it! the web pages viewed by the participant will have a basic architecture.
Creating a survey session Second, one must create the a survey session, modify it, and open a control panel.
Creating a session | Each session is identified by a name you chose. This name must be unique -- no other existing session can have this name (even if it is a session that is based on a different instrument). Remember: a dSurvey session is based on a dSurvey instrument. You can have many active dSurvey sessions based on the same instrument. Use the new session utility to create a new session.
Modifying the session-specific parameter files | Before participants have joined, or while participants are joining but before the session actually starts, you can modify the session-specific administrative parameter files. Once you start the session, client-accessible parameter files, that incorporate these modifications, can be retrieved by the clients (and used to control which modules are displayed, etc). You can use the Modify general parameters file a and the Modify reference data file utilties to modify a session's general and reference parameter files.
Open a control panel | The control panel is used by the administrator to... control the session! Basically, there are three broad sets of actions the control panel can do: Changing parameter values (and informing participants of these new values by modifying the client-accessible parameter files) Changing server variables. Computing results, given information submitted by participants. Note that all control panels have generic options, and will contain tasks that are explicitily specified using the control panel program for this session. If the instrument uses the basic control panel program, a set of generic tasks will be specified. You should use the Open a control panel for a survey-session utility to open a control panel for a session. If you create an instrument using the Create an instrument utility, a generic control panel is created that has the following architecture.
Opening a control panel, and enrolling participants Third, using the control panel: allow participant so join, generate client-accessible parameter files, and start the session.
Allow participants to join | Once a session has been created, the administrator must permit participants to join. This is done within the control panel (either with a generic option, or with an option that is part of the control panel program). Once all participants have joined (note that the current list of participants can be readily displayed using a generic control panel option), you may end enrollment (using a generic control panel option). It is possible to keep a session open -- to allow participants to join at any time. It is also possible to allow clients to rejoin a session -- such as if their browser crashes. Though dSurvey is designed for groups of individuals who participate together, you can use dSurvey to implment open-ended sessions (sessions that are always open to new participants, even if prior participants have left).
Create control panel databases & generate client-accessible parameter files | This is done using tasks in the control panel program. The control panel databases are what the control panel works with. These databases include a list of participants, and the variables & parameters assigned to these participants. Using these internal databases, client-accessible parameter files can be created. Remember: client-accessible parameter files can contain general and client-specific parameters -- the control panel program is used to determine just what parameters to include. Note that reading internal databases is usually done just once: after all the participants have joined. That's why letting participants join at any time can be complicated -- you have to reconstruct the internal databases.
Start the session | Once all particpants have joined, and you have created internal database (& generated client accessible parameter files), you can start the session (say, by using one of the basic control panel) tasks. Starting the session means instructing all the participants to start following the instructions in the SPECification file -- to load modules files, and to show the first section.
Displaying and controlling modules Once the session starts, the clients (the javascript program running on the particpants' browsers) become active.
Loading the SPECification file | Once the session starts, participants must first load the base home page. The base-home page will then load the specification file for this instrument. The specification file is what controls the presentation of the survey; determining when and what modules are displayed, as well as processing the dynamic XHTML extensions the modules. may contain. Note that a session's (one or more) module files belong to the instrument -- so all sessions based on an instrument will retrieve the same modules files from the server.
Loading modules and starting the first section | Based on instructions in the init section of your SPEC file, the client will retrieve module files. Then, the first group in the first section will be loaded, processed, and displayed.
Display new modules | Based on events specifed in the SPEC file, the client will display new modules. Events include expiration of a timer, the participant clicking an appropriately configured button, or by an action of the administrator. Which module is displayed will be determined by the SPEC file, which typically uses parameters provided in the client-accessible parameter files, or through server variables retrieved by the client on-the-fly.
Submitting data | Using submit event action, the client will submit results to the server. The server will add these client (and round) specific results result to a session-specific submitted data database.
processing results and starting a new section | Once all (or enough) of the participants have responded, the administrator can process the results. This may be as simple as noting they have been recorded. Or it can be complex, with individual results computed based on what all the participants have chosen. After processing, the administrator (via the control panel) will communicate the results back to the client. This is done by modifying the client accessible parameter files, and informing the clients to start a new section. At the start of a new section, each client will retrieve this file, and extract his data. This new data, both general and client-specific, can be used to chose which module to display, and to modify the XHTML dynamic extensions within the chosen module.

Appendix
Advantages and disadvantages of dSurvey

- A advantage of "dSurvey" is that it is fully webbed. Which means, conceivably, you can run an experiment from anywhere-all you need are computers with web access.

  A disadvantage of "dSurvey" is that it is fully webbed. Which means that if one's connections are slow, or if the distant server has problems, you are SOL.
- An advantage of "dSurvey" is its use of an XHTML syntax to specify screens, which includes extensions (tag names) that make it fairly easy to specify dynamic content (content whose value depends on participant specific data and on data that changes over the course of time). And this specification requires little or no understanding of how client-server communications are structured.

  A disadvantage of "dSurvey" is its use of a "proprietary" XHTML syntax, one that is more-or-less unique to "dSurvey". This means the instrument designer must learn a unique syntax, for which there are not readily available GUI tools. In other words, one must hand code the content (although starting with a good HTML editor and tweaking it afterwards might work. Note that dSurvey does include some tools to help program its various components, but they are fairly primitive.
- An advantage of "dSurvey" is it use of javascript. This means that results calculations can be programmed in a well known language. Furthermore, a number of functions are provided that make it relatively easy to retrieve and save parameters (including participant specific parameters), data submitted by participants, and the results of prior calculations. And it is straightforward to communicate the results of these calculations to participants and to the administrator

  A disadvantage of "dSurvey" is its dependence on javascript to do serious calculations. Some calculations can be done by dSurvey's built in features, but for anything slightly complex the easiest approach is to use javascript functions created by the instrument designer. While use of external software (i.e. excel) is supported, it requires a moderately convoluted approach (saving data, running the external software, reading the data, further processing of the data). Thus, effective use of dSurvey is enhanced by a familiarity with javascript.
- An advantage of "dSurvey" is it use client-centric structure. The broad outline of a survey session is specified in XML "specification files" that allow for a dynamic set of treatments (that can be changed mid-session). This reduces server load, and provides a moderately intuitive structured mechanism.

  A disadvantage of "dSurvey" is it use of a proprietary means of specifying how treatments are presented. Itsa XML "specification files" requires hand-coding, as there are no style sheets (XSLT) or schema to validate or otherwise assist in their design. While providing flexibility, the syntax of these specification files is unique to dSurvey

18 March 2011. Daniel Hellerstein (danielh@crosslink.net);