Interact

Magellan.Surveyor Documentation

David Heise
Indiana University
heise@indiana.edu

Magellan is an ongoing research project in which dictionaries of affective meaning are being collected around the world. Surveyor is a Java applet that measures affective meaning in indigenous languages, and that archives data in the U.S.A. via the Internet, or else archives data on field computers used to interview respondents.

The Surveyor Program

Surveyor is a Java applet that runs in World Wide Web (WWW) browsers and collects data from respondents. Surveyor has the following features.

Java source for the Surveyor2 applet is available online.

Magellan Projects

Using Surveyor to obtain a dictionary of affective meanings in a culture requires the following steps.

Once dictionaries are available, a second phase of culture exploration can be undertaken: estimating impression-formation equations. Surveyor can be used for data collection in this work, too.

Currently, the Internet part of a project must be implemented through David Heise at Indiana University who maintains the World Wide Web location supporting Magellan research: www.indiana.edu/~socpsy/surveyor2/. You provide

as described below. Then Dr. Heise will

A flowchart offers some perspective on these processes. It appears in a separate window so you can compare it to the texts above.

This document provides details on topics that you must understand in order to submit required materials to Dr. Heise.

Translating the Surveyor Interface Texts

This section is relevant only if you need to make Surveyor operate in a language that Surveyor has not used previously. The file described here need not be provided if you will operate in one of the available Surveyor languages: English, simplified Chinese, Japanese, German, Arabic.

Translating Surveyor into a new language has two aspects: dealing with the texts that define Surveyor's bipolar rating scales, and providing indigenous texts for the rest of Surveyor's user interface.

The texts for scales and user interface are defined in a Java file named Messages.java. You copy that file and put translations into it for compilation into the Surveyor program.

Scales

Surveyor measures affective meaning on the dimensions of Evaluation, Potency, and Activity. Here is an English version of Surveyor's Evaluation scale:

A translation has to convert all of the words defining the scale into the indigenous language. For example, here is the Japanese version.

The anchors defining the ends of scales in non-English languages are not mere translations of the adjectives defining the scales in English. Rather, the non-English adjectives come from prior research indicating how each dimension of affective meaning is best defined indigenously. This is discussed in detail in a book by David Heise, Surveying Cultures (Wiley-Interscience, 2010). Research has been done in 31 different societies/languages, and scale definitions in these languages should make use of the prior research. Translation of scale anchors into societies/languages other than the 31 already studied listed should be informed by studying prior research on related languages. For example, German scales were defined by considering the scale definitions in Dutch and English. Languages that are very different than those already studied may require new scale-development research.

The English adverbs slightly, quite, extremely define approximately equal intervals along the rating scale, and infinitely defines somewhat longer intervals at the ends of a scale (D. Heise. 1969. "Some methodological issues in semantic differential research." Psychological Bulletin, 72:. 406-22. D. Heise, 1978, Computer-Assisted Analysis of Social Action, Chapel Hill, N.C.: Institute for Research in Social Science). Lacking research on magnitude effects of adverbs in other languages, these English adverbs should be translated as precisely as possible.

The following table shows definitions for scales in English on the left, and definitions for scales in German on the right.

Translations often will require specifying special characters with unicodes, as detailed below.

User Interface

Surveyor has a variety of prompts and messages, and Surveyor provides a tutorial on how to use its computerized scales. The texts of the prompts, messages, and instructions must be translated to the indigenous language in order to be intelligible to indigenes.

For example, Surveyor uses a Cancel button in one of its dialogs, and the English text for this button is defined as follows in Messages_en_US.java.

{ "cancelSkipButton", "Cancel" },

The German language version of Surveyor has to give a German name to the button in Messages_de_DE.java, as follows.

{ "cancelSkipButton", "Abbrechen" },

The complete set of texts that require translation are given in the following table. Notes for translators follow the table.

Surveyor reads definitions of scales and messages from a single file called Messages.java. If you are translating Surveyor to a new language, then download Messages.java, and modify that file. Messages.java is a text-only file and should be saved with the same name, specifying it as being simple text. Afterwards you may have to change the extension from "txt" back to "java". (Heise will elaborate the file name with proper insertions when he compiles the Java file; e.g., the German version of Messages.java becomes "Messages_de_DE.java".)

Creating Stimuli Files

Different projects ask respondents to answer different background questions and to rate different stimuli. Whatever the content, however, questions and stimuli must be incorporated into Surveyor using a standard format, shown in the following table.

The line containing "|Are you:|Female|Male|", "|Are you:|Female|Male|", illustrates how to format a background question. The duplication is not an error. The first entry in quotes is the text of the question in the indigenous language, for presentation to respondents. The second quoted entry on the line is the text of the question in English, for use in archiving the data. In this example, the indigenous language is English, so the two entries are identical, but in general the two entries will be in different languages.

Here are considerations to keep in mind when incorporating questions into Surveyor files.

Stimuli for EPA rating follow the questions. The example in the table has six stimuli. Some considerations regarding stimuli follow.

Stimuli files are named Word_1.java, Word_2.java, etc. The number of the file should match the number of the class in line three of the file. Stimuli files are text-only files, and should be saved as simple text files, even though they must end up with a "java" extension.

One method of building randomly selected subsets of stimuli. Suppose you have 1,500 stimuli in column B of an Excel worksheet, and you want to divide this list into 15 randomly selected subsets. Enter this formula in the cells of column A: =CEILING(15*RAND(),1). Random numbers between 1 and 15 appear in column A defining the subset for each stimulus. Copy the two columns to a new worksheet, paste as values, and sort on column A. The stimuli now are organized into 15 sets. The randomly-drawn sets have varying number of stimuli, so you have to randomly shift some stimuli from overly-large sets into overly-small sets in order to even out all sets to 100 stimuli each.

Another method of building randomly selected subsets of stimuli. Suppose you have 1,500 stimuli in the SPSS data editor, the actual stimuli in a string variable named "stimulus" and the English translation in a string variable named "key". Chose Data / Select Cases / Random Sample / Exactly 100 from the first 1500 to get the first sample of one hundred. Transform the "filter_$" variable produced by SPSS to a new variable called "sample", and sort on that variable. Then select another random sample of 100 from the first 1400 cases, and continue the procedures repeatedly until all 15 random samples of 100 stimuli are defined.

Unicode

This section is relevant only if you need to make Surveyor operate in a language that Surveyor has not used previously, and that language does not use Latin characters.

Most non-European languages use non-Latin characters in their printed renditions. Texts in these languages must be expressed in Unicode (\udddd notation) in order to be usable in Surveyor. Unicode is an internationally supported system providing a standardized number for each character in every written language. Charts for converting characters to unicodes are provided by the Unicode Consortium.

For example, here is how the Japanese evaluation scale shown previously gets defined in Surveyor (\u signals that the next four characters are a unicode in the form of a hexadecimal number).

{ "Pos_1_1", "\u3088\u3044" },
{ "Pos_1_2", "\u308a\u3063\u3071\u306a" },
{ "Pos_1_3", "\u6109\u5feb\u306a" },
{ "Pos_1_4", " " },
{ "Pos_1_5", " " },

{ "Neg_1_1", "\u60aa\u3044" },
{ "Neg_1_2", "\u3072\u3069\u3044" },
{ "Neg_1_3", "\u4e0d\u5feb\u306a" },
{ "Neg_1_4", " " },
{ "Neg_1_5", " " },

Punctuation characters !()-[]:;',.? may be entered between unicodes in their Latin form. Quotation marks within text have to be preceded with a backslash \" to distinguish them from quotes used in the Java program.

A program for Windows called native2ascii.exe (Native-to-ASCII) transforms native-language texts into unicode. First, a file is created with text in the native language, created on a computer that routinely operates in the native language. Then native2ascii.exe is used to create a new file in which native-language characters are converted to unicode. (The native2ascii.exe program leaves Latin characters in their native form.)

For example, suppose you wrote just this one line on a Japanese computer with Shift-JIS encoding

and saved it in a file called source.txt in the same directory as the native2ascii.exe program. Then you run the conversion program with the following command from the MS-DOS prompt:
native2ascii -encoding SJIS source.txt output.txt
and you get a new file in the same directory called output.txt which contains the one line:

{ "Pos_1_1", "\u3088\u3044" },

This is the first line of Surveyor's definition of the Japanese evaluation scale. Similarly, translations throughout Surveyor's Messages.java file could be defined in native Japanese, and then the whole file could be converted to unicode with native2ascii.exe. The same procedure can be used with stimuli files.

The native2ascii.exe program is included in the bin directory of the standard edition of the Java platform, which can be downloaded without charge from Sun Microsystems. Documentation for Native-to-ASCII also is available from Sun on the web.

The European set of numeric digits is not used in all languages. You assure that digits will be shaped properly for indigenes in your study by giving the unicode character for the indigenous zero digit in a line at the top of the Messages.java file.

{ "UnicodeZero", "\u0030"},

The unicode value shown above is for European digits. To provide digits shaped for Arabic, for instance, you would replace \u0030 with \u0660.
 

Applet Web Page

The Surveyor applet is presented on a web page that has to be set up by the researcher and provided to Heise as a file for uploading. The file should be saved as a text file, with a name like surveyor.txt, even though the extension then will have to be changed from "txt" to "htm". Do not save as an HTML file from a word processor, because word processors like Word bloat HTML files with unnecessary code that makes Heise's job harder.

The text in the file should be identical to the text shown in the box below except for the values of the parameters.

Data Format

Data obtained with stimulus set Words_X.java are appended to an archive file named Data_X.dat. The archive file is created if it does not yet exist. For example, suppose that a first respondent answers the questions and does the ratings of stimuli in your Words_3.java stimuli file. When this respondent's data are stored, a file named Data_3.dat is created in your project directory, and the first respondent's data is saved in it. Later when a second respondent answers the questions and does the ratings of stimuli in Words_3.java, the second respondent's data are appended at the end of Data_3.dat.

In an Internet project, you can examine the data files at any time with a WWW browser by visiting the URL:

where YourDirectory is the name of your project directory at Indiana University. An index is displayed showing all of the files in your directory, and you may click on the name of a data file to examine its contents.

You can download a data file by right-clicking on the name in the index and selecting "Save link as". (This is a Windows procedure; comparable procedures are available in browsers running on other platforms.)

Data from a respondent constitute one record. Respondent records are separated by two blank lines.

Each record in a data file is structured as follows:

The total number of variables is: 5 on the first line, plus 2 times the number of background questions, plus four times the number of stimuli. For example, with three background questions and 100 stimuli, there will be 410 variables in the dataset.

A data file can be imported directly into SPSS by specifying the number of variables per record (500 maximum) and indicating that fields are comma-delimited. SPSS will treat end-of-line as a field delimiter, without user specification. (This works only if stimuli do not contain embedded commas.)

Data also can be imported into SPSS using a syntax file, and this approach allows more than 500 variables per record. For example, the following syntax file reads a data file that contains answers to questions about sex, race, geographic origin, and marital status. The syntax file then gets stimulus text and respondent EPA ratings for 100 stimuli. Then the syntax file sets missing-data values for the EPA ratings. Stimuli texts are read using A format, and the specified length of the stimulus field (e.g., A35) must be greater than the number of characters in any stimulus.

Saving Data Locally

Occasions arise when it would be desirable to use Surveyor apart from an immediate connection to the Internet: for example, when using a laptop or tablet computer as an interviewing tool. However, that would require that data be saved directly to the computer's hard drive rather than being archived at Indiana University, and applets like Surveyor ordinarily are not allowed to write files on the computers running them.

The restriction can be circumvented on a specific computer as follows.

1. Create a directory to contain Surveyor, and another directory to receive the data. Surveyor expects the first directory to be C:\Surveyor, and the second to be C:\Surveyor\Data. Setting up other directories would require changing code inside of Surveyor.
2. Heise will provide a file named surveyor_all.jar containing the applet, the localized Messages file, and all Words files. The file should be put into the C:\Surveyor directory.
3. The applet web page (TheWebPage.html) also should be put in the C:\Surveyor directory. The applet web page is the same as discussed above except for the ARCHIVE line which now should read ARCHIVE="surveyor_all.jar", and the InternetSave parameter which now should be set as follows: <PARAM NAME=InternetSave VALUE=false>.
4. The Java permissions file, C:\Program Files\Java\jre6\lib\security\java.policy, must be changed by appending the following line at its bottom (note that all slashes are forward rather than backward in this line):
   
   permission java.io.FilePermission "C:/Surveyor/Data/-", "write";
   

With these changes, the Surveyor applet can be run by using one's Internet browser to open file C:\Surveyor\TheWebPage.html. Data from completed sessions will be stored in directory C:\Surveyor\Data. The dat files have exactly the same format as those archived at Indiana University.

URL: www.indiana.edu/~socpsy/ACT/SurveyorDocumentation.htm