...Web Development‎ > ‎jQuery, YAML‎ > ‎

Documentation

Code

Source Code
The working copy of source code is hosted at http://github.com/yiwang/titration

Deployment URL
parameter 'lang' is to specify language
If language not specified, default is lang=en

JavaScript code
survey.js for the main logic, it does the heavy lifting to substitute $BASE_VALUE and $VAL_VALUE with correct numbers based on user interaction and the corresponding Transition Matrix.
entry.js for data structure at client side.

PHP code
survey-header.php for linking *.js libraries and transforming *.yaml question files to JSON format.
survey.php for constructing major viewable elements (<div> etc.) in survey page.
survey-save.php for handling POST data and save user's respond to server

Question files in 'question' foler
Each question file is named as ID.yaml, where ID is integer, i.e. 1, 2, 3 ...
$BASE_VALUE and $VAR_VALUE mark variable locations and will be substituted with actual number at run time.

Configuration
Refer to file config.yaml

Libraries
spyc is used to convert *.yaml question files to JSON in JavaScript to be embedded in survey.php
'lib/js' folder contains JavaScript libraries (jQuery) used in this project

Transition Matrix (tm)

Description of Transition Matrix (tm), the table-like representation of the schema for '$VAR_VALUE' generation based on user's each choice within one question (group) sharing the same textual description.

basedc
b
a



c.i
b.i
1234567


Decision Tree

Suppose we have the above base/var/sub scenario (bvs_array=[0 (for exit and Infinite), base, d, c, c.i, b, b.i, a] in code), one (of possible multiple) Transition Matrix based on user's each choice may be generated as below:



var atuser's
choice
var
transition
to
user's var
preference
range LOW
user's var
preference
rang HIGH
a77 (0 in code)517

71exit (0 in code)7Infinite (0 in code)
b55 (0)315

51657
b.i66 (0)exit (0)56

61exit (0)67
c33 (0)213

31435
c.i44 (0)exit (0)34

41exit (0)45
d22 (0)exit (0)12

21exit (0)23


Note var transition to 'exit' denotes exiting the choice question (which is ctype0 in code) and leading to the filling blank question (which is ctype1 in code).
tm.js in code implements Transition Matrixes. "tm-index" field in each YAML question file specify the index of Transition Matrix pertaining to the specific question.
Note the number (0-7) is actually the index of elements in bvs_array.


YAML question file format specification

A template to specify the format of YAML question files.

---
#line starting with '#' is comment, does not harm the file format, but only for human readability, the above '---' line is needed.

# Section title here, for easier relating to the location in the paper.

# Choose one TYPE from below and DELETE OTHERS, just for easier to identify the type later.

1#Environmental: usage x gain
2#Environmental: usage x loss
3#Environmental: existence x loss
4#Environmental: existence x gain
5#Monetary: luck x gain
6#Monetary: luck x loss
7#Monetary: self-earned/inflicted x gain
8#Monetary: self-earned/inflicted x loss
9#Health: risk x gain
10#Health: risk x loss
11#Health: condition x loss
12#Health: condition x gain
13#Environmental: permanent x loss
14#Environmental: temporary x loss
15#Environmental: permanent x gain
16#Environmental: temporary x gain
17#Monetary: house x gain
18#Monetary: earned x gain
19#Monetary: house x loss
20#Monetary: earned x loss
21#Health: severe x gain
22#Health: severe x loss
23#Health: mild x gain
24#Health: mild x loss

# tm-index specifies the index of Transition Matrix pertaining to this specific question
tm-index: 1

# pattern for 'var' and 'sub'
#  d      c                 b               a     for 'var'
#                   c.i             b.i             for 'sub'
# 22  - 30 -  (37) - 44 - (55) - 65

# 'var' has EXACTLY 4 numbers in it, 'sub' has EXACTLY 2 numbers in MONOTONICALLY INCREASING order.
# DO have one WHITE SPACE after ',' between each number

base: 21
var: [22, 30, 44, 65]
sub: [37, 55]

desc:
  en:>
    Start paragraph here with 4 WHITE SPACES padding in the begining, use $BASE_VALUE  and $VAR_VALUE to represent numbers
  zh:>
    Start paragraph here, use $BASE_VALUE  and $VAR_VALUE to represent numbers
   
ans:
  en:
    - start sentence here with one WHITE SPACE from '-' $BASE_VALUE
    - $VAR_VALUE
  zh:
    - $BASE_VALUE
    - $VAR_VALUE
# note, only for ctype = 0, the selection question
note:
  en: #start sentence here with one WHITE SPACE from ':', if there is no note, leave this blank
  zh: 

Response Data Specification

when one instance of survey is finished, an entry (entry.js in code) is generated and written to data file in CSV format as one appending line.
for example:
en,Z,Mon Jan 11 2010 04:46:47 GMT-0600 (CST),1263206807163,1263206824929,17.8,ID8,23,300,10000,3.166,5.991,,,,ID22,23,150,200,2.185,2.054,1.572,2.798,,SEQ,22,8
as an entry in CSV files means:
language                               [0] => en
set, which contains ID8 and ID22       [1] => Z
survey start time in string            [2] => Mon Jan 11 2010 04:46:47 GMT-0600 (CST)
survey start time in ms                [3] => 1263206807163
survey end time in ms                  [4] => 1263206824929
duration=[4]-[3] in second             [5] => 17.8
[6]~[14] are data for ID8 question
first question ID                      [6] => ID8
user's input for "equally attractive"  [7] => 23
user's preference range: (300,10000)
range LOW value                         [8] => 300
range HIGH value                        [9] => 10000
[10]~[14] are intervals in second
of user's actions for ID8 question
                                        [10] => 3.166
                                        [11] => 5.991
12~14 are empty place holders
                                        [12] => 
                                        [13] => 
                                        [14] => 
[15]~[23] are data for ID22 question    
                                        [15] => ID22
                                        [16] => 23
                                        [17] => 150
                                        [18] => 200
                                        [19] => 2.185
                                        [20] => 2.054
                                        [21] => 1.572
                                        [22] => 2.798
                                        [23] => 
SEQ Separator                           [24] => SEQ
the order of randomized ID sequence
(the order user answers the questions)
is ID22 first, then ID8
                                        [25] => 22
                                        [26] => 8
Note 23-15 = 14-6, thus each ID occupies the same number of tokens.
The response data ([6] ~ [23]) for IDs are sorted by their ID integer value in ascending order (8<22) for alignment.

Question Divisions

Question Divisions


Comments