Demonstration of a Blaise Demonstration of a Blaise Instrument Documentation System Instrument Documentation System

“BlaiseDoc”“BlaiseDoc”

Gina-Qian Cheung

May 25, 2005

Institution for Social Research

University of Michigan

2

AgendaAgenda

• Introduction

• BlaiseDoc Design

• Blaise Questionnaire Generator Demo

• BlaiseDoc Codebook Demo

• Some outstanding issues and next step

4

Current ApproachCurrent Approach

BlaiseDoc(Interface program)

TEXTRTF

HTMLQuestionnaire

TEXTRTF

HTMLCodebook

UM SRC BlaiseDoc Flow

DDIxForm(transforms XML)

DDIGen(Produces XML)

Support DB

SAS Frequency

DB *.xml(one XML per

language)

XSL Stylesheets Scripts

Config.xml(location of file &

record of selections)

Blaise datamodelExternal lookupsSAS ODBC link

Word processor / browser Interprets

Four keycomponents

Systemproduces

Your previousselectionsare saved

E.g., QxQ’s, Resp. Booklet

5

DDIGenDDIGen Creates eXtended Markup Creates eXtended Markup Language (XML) OutputLanguage (XML) Output

• Creates tagged elements (e.g., variable or question) from Blaise datamodel metadata (information about survey instrument variables, e.g., name, question text, code frame, etc.) Tags

• Bracket elements (examples follow)• Comply with Data Documentation Initiative (DDI)

Hierarchical tree structure• Generates comprehensive metadata about all Blaise

survey instrument variables Opens possibility of using XML metadata in many

ways, by many systems, and customizing display of those metadata to meet many needs

6

DDIxFormDDIxForm Transforms XML, Based Transforms XML, Based on XSL Stylesheet Scriptson XSL Stylesheet Scripts

• eXtended Stylesheet Language Transformation (XSLT) uses stylesheet scripts (*.XSL) to traverse XML tree, looking for elements and generating formatted outputs (e.g., HTML, TXT, RTF, PDF, etc.) HTML (HyperText Markup Language) is used

for commands an internet browser interprets to decide how to display information

7

Examples of Elements, Attributes, & Examples of Elements, Attributes, & Data in Blaise XMLData in Blaise XML

• Elements codeBook var (variable element) qstn (question element within var) qstnlit (question text, element within qstn) varGrp (block)

• Attributes name (variable name, attribute of var) var ID (attribute of var and varGrp)

• Data Actual question text Actual short variable name (Blaise Field Name)

8

Example of XML Output Based on Example of XML Output Based on Blaise DatamodelBlaise Datamodel

DDIGen captures Blaisescreen formatting charac-teristics, e.g., bold, blue, special characters, etc.

9

Basic HTML Stylesheets AvailableBasic HTML Stylesheets Available

QNaireHTML1.XSL Field names, Q text with fills, code frames/other Q types, lookups, universes

QNaireHTML2.XSL … plus constructed variables, preload variables, interviewer consistency checks

QNaireHTML3.XSL … plus “goto’s” with links to target questions, internal consistency checks

QnaireHTML4.XSL … plus links to respondent booklet & help (QxQs)

CodebookHTML1.XSL Field names, Q text with fills, code frames/other Q types, lookups, constructed variables, preload variables, universes

CodebookHTML2.XSL … plus frequencies

CodebookHTML3.XSL … plus links to respondent booklet & help (QxQs)

10

View ResultsView Results

DDIGen captures Blaise screen characteristics, e.g., blue for text not read to respondent

11

• Elements of questionnaire Question identifier Question text and fills Response options for code frame / other Q types Lookup (e.g., for states) Goto’s (optional) Preload variables (optional) Constructed variables (optional) Interviewer consistency checks (optional) Internal checkpoints (optional) Supplemental information (e.g., QxQ’s and

respondent booklets, optional)

Elements of QuestionnairesElements of Questionnaires

12

Elements of CodebooksElements of Codebooks

• Elements of codebook Question identifier Question Response options for code frame / other Q type Lookup (e.g., states) Preload variables Constructed variables Universes (respondents for whom Q’s asked)

• E.g., Females over 65 Frequencies and Percents (optional) Variable characteristics (in this case for SAS,

assuming Blaise instrument; if freqs, thus optional) Supplemental information (e.g., QxQ’s and

respondent booklets, optional)

13

• What you see is what you specify and what gets programmed Fonts, upper and lower case, interviewer instructions,

goto’s, etc.

Elements of Questionnaires & Elements of Questionnaires & CodebooksCodebooks

Example specification

SRO is developing Blaise specification,screen design, and programmingGuidelines.

Field NameField Tag

Field Description

14

Codebook without UniverseCodebook without Universe

15

Codebook with UniverseCodebook with Universe

Difference between codebook & qnaire:Universe vs. “goto”

16

Editing StylesheetsEditing Stylesheets

• DDIxFORM opens the XML file and applies an XSL stylesheet script against it grabs data, adds text, and produces text output

• In addition to XSL commands, XSL file contains HTML commands that DDIxForm does not interpret, but are copied with other text These commands are then interpreted by the user’s

browser or text processor to control formatting and display

Can edit XSL and HTML commands to change the display of documentation

We’re going add HTML commands to a stylesheet to change the format of a questionnaire

17

Edit Stylesheet and Generate Edit Stylesheet and Generate Revised DocumentationRevised Documentation

18

Exercise 3: Edit Stylesheet and Exercise 3: Edit Stylesheet and Generate Revised DocumentationGenerate Revised Documentation

19

Exercise 3: Edit Stylesheet and Exercise 3: Edit Stylesheet and Generate Revised DocumentationGenerate Revised Documentation

• [Click] on the File menu and Save the file

• [Double click] on the Refresh Questionnaire shortcut on the computer Desktop

20

• From

Exercise 3: View ResultsExercise 3: View Results

21

• To

Exercise 3: View ResultsExercise 3: View Results

22

Uses of BlaiseDocUses of BlaiseDoc

• Documentation of Blaise Instrument IRB documentation Qnaire or codebook documentation of final data

collection instrument or dataset Testing

• Can generate current documentation of instrument for use by testers at any point in development process

• Check question text, fills, goto’s, universes, etc.

• Developing program to read post-processed SAS dataset against original Blaise datamodel and generate XML for final codebook SASToSAS--similar to BlaiseToSAS Creates new datamodel for use with BlaiseDoc

23

SummarySummary

• BlaiseDoc Documents Blaise survey instruments and data

• Questionnaires• Codebooks

• SRC has standard stylesheet scripts that provide options for what appears in documentation

• These can be modified to produce additional stylesheets to meet specific client requirements

• Quality of output dependent on original Blaise survey instrument specifications and programming Need to think about questionnaire and data documentation

requirements during instrument specification• You can use BlaiseDoc throughout instrument

development cycle, to “test” the instrument and check question wording and fills, skip logic (goto’s), including DK / RF skip logic, etc.

24

““BlaiseDoc” is a Work in ProgressBlaiseDoc” is a Work in Progress

• We are using beta version• Expect release of final system within next few

months Move to .NET Modifications to handle grids, rosters and fills better Additions of other features requested by users Updated interface Integration of programs (DDIGen, DDIxFORM, and

BlaiseDoc interface) Updated documentation

• Encourage you to use system and provide feedback (to Gina Cheung) See slide 4 for location of installation program and user guide Work with your Blaise programming and data operations team members to get the

results you need and expect

25

Discussion / QuestionsDiscussion / Questions