1 @node SPSS Viewer File Format
2 @chapter SPSS Viewer File Format
4 SPSS Viewer or @file{.spv} files, here called SPV files, are written
5 by SPSS 16 and later to represent the contents of its output editor.
6 This chapter documents the format, based on examination of a corpus of
7 about 500 files from a variety of sources. This description is
8 detailed enough to read SPV files, but probably not enough to write
11 SPSS 15 and earlier versions use a completely different output format
12 based on the Microsoft Compound Document Format. This format is not
15 An SPV file is a Zip archive that can be read with @command{zipinfo}
16 and @command{unzip} and similar programs. The final member in the Zip
17 archive is a file named @file{META-INF/MANIFEST.MF}. This structure
18 makes SPV files resemble Java ``JAR'' files (and ODF files), but
19 whereas a JAR manifest contains a sequence of colon-delimited
20 key/value pairs, an SPV manifest contains the string
21 @samp{allowPivoting=true}, without a new-line. (This string may be
22 the best way to identify an SPV file; it is invariant across the
25 The rest of the members in an SPV file's Zip archive fall into two
26 categories: @dfn{structure} and @dfn{detail} members. Structure
27 member names begin with @file{outputViewer@var{nnnnnnnnnn}}, where
28 each @var{n} is a decimal digit, and end with @file{.xml}, and often
29 include the string @file{_heading} in between. Each of these members
30 represents some kind of output item (a table, a heading, a block of
31 text, etc.) or a group of them. The member whose output goes at the
32 beginning of the document is numbered 0, the next member in the output
33 is numbered 1, and so on.
35 Structure members contain XML. This XML is sometimes self-contained,
36 but it often references detail members in the Zip archive, which are
40 @item @file{@var{prefix}_table.xml} and @file{@var{prefix}_tableData.bin}
41 @itemx @file{@var{prefix}_lightTableData.bin}
42 The structure of a table plus its data. Older SPV files pair a
43 @file{@var{prefix}_table.xml} file that describes the table's
44 structure with a binary @file{@var{prefix}_tableData.bin} file that
45 gives its data. Newer SPV files (the majority of those in the corpus)
46 instead include a single @file{@var{prefix}_lightTableData.bin} file
47 that incorporates both into a single binary format.
49 @item @file{@var{prefix}_warning.xml} and @file{@var{prefix}_warningData.bin}
50 @itemx @file{@var{prefix}_lightWarningData.bin}
51 Same format used for tables, with a different name.
53 @item @file{@var{prefix}_notes.xml} and @file{@var{prefix}_notesData.bin}
54 @itemx @file{@var{prefix}_lightNotesData.bin}
55 Same format used for tables, with a different name.
57 @item @file{@var{prefix}_chartData.bin} and @file{@var{prefix}_chart.xml}
58 The structure of a chart plus its data. Charts do not have a
61 @item @file{@var{prefix}_pmml.scf}
62 @itemx @file{@var{prefix}_stats.scf}
63 @item @file{@var{prefix}_model.xml}
64 Not yet investigated. The corpus contains few examples.
67 The @file{@var{prefix}} in the names of the detail members is
68 typically an 11-digit decimal number that increases for each item,
69 tending to skip values. Older SPV files use different naming
70 conventions. Structure member refer to detail members by name, and so
71 their exact names do not matter to readers as long as they are unique.
74 * SPV Structure Member Format::
75 * SPV Light Detail Member Format::
76 * SPV Legacy Detail Member Binary Format::
77 * SPV Legacy Detail Member XML Format::
80 @node SPV Structure Member Format
81 @section Structure Member Format
83 Structure members' XML files claim conformance with a collection of
84 XML Schemas. These schemas are distributed, under a nonfree license,
85 with SPSS binaries. Fortunately, the schemas are not necessary to
86 understand the structure members. To a degree, the schemas can even
87 be deceptive because they document elements and attributes that are
88 not in the corpus and do not document elements and attributes that are
91 Structure members use a different XML namespace for each schema, but
92 these namespaces are not entirely consistent. In some SPV files, for
93 example, the @code{viewer-tree} schema is associated with namespace
94 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
95 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
96 additional @file{viewer/}). Under either name, the schema URIs are
97 not resolvable to obtain the schemas themselves.
99 One may ignore all of the above in interpreting a structure member.
100 The actual XML has a simple and straightforward form that does not
101 require a reader to take schemas or namespaces into account.
103 The elements found in structure members are documented below. For
104 each element, we note the possible parent elements and the element's
105 contents. The contents are specified as pseudo-regular expressions
106 with the following conventions:
119 Grouping multiple elements.
124 @item @var{a} @math{|} @var{b}
125 A choice between @var{a} and @var{b}.
128 Zero or more @var{x}.
132 For a diagram illustrating the hierarchy of elements within an SPV
133 structure member, please refer to a PDF version of the manual.
137 The following diagram shows the hierarchy of elements within an SPV
138 structure member. Edges point from parent to child elements.
139 Unlabeled edges indicate that the child appears exactly once; edges
140 labeled with *, zero or more times; edges labeled with ?, zero or one
142 @center @image{dev/spv-structure, 5in}
146 * SPV Structure heading Element::
147 * SPV Structure label Element::
148 * SPV Structure container Element::
149 * SPV Structure text Element (Inside @code{container})::
150 * SPV Structure html Element::
151 * SPV Structure table Element::
152 * SPV Structure tableStructure Element::
153 * SPV Structure dataPath Element::
154 * SPV Structure pageSetup Element::
155 * SPV Structure pageHeader and pageFooter Elements::
156 * SPV Structure pageParagraph Element::
157 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
160 @node SPV Structure heading Element
161 @subsection The @code{heading} Element
163 Parent: Document root or @code{heading} @*
164 Contents: @code{pageSetup}? @code{label} (@code{container} @math{|} @code{heading})*
166 The root of a structure member is a @code{heading}, which represents a
167 section of output beginning with a title (the @code{label}) and
168 ordinarily followed by content containers or further nested
169 (sub)-sections of output.
171 The document root heading, only, may also contain a @code{pageSetup}
174 The following attributes have been observed on both document root and
175 nested @code{heading} elements.
177 @defvr {Optional} creator-version
178 The version of the software that created this SPV file. A string of
179 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
180 e.g.@: @code{21000001} is version 21.0.0.1. Trailing pairs of zeros
181 are sometimes omitted, so that @code{21}, @code{210000}, and
182 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
183 three of those forms).
187 The following attributes have been observed on document root
188 @code{heading} elements only:
190 @defvr {Optional} @code{creator}
191 The directory in the file system of the software that created this SPV
195 @defvr {Optional} @code{creation-date-time}
196 The date and time at which the SPV file was written, in a
197 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
198 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
199 December 5, 2014 5:00:19 o'clock PM EST}.
202 @defvr {Optional} @code{lockReader}
203 Whether a reader should be allowed to edit the output. The possible
204 values are @code{true} and @code{false}, but the corpus only contains
208 @defvr {Optional} @code{schemaLocation}
209 This is actually an XML Namespace attribute. A reader may ignore it.
213 The following attributes have been observed only on nested
214 @code{heading} elements:
216 @defvr {Required} @code{commandName}
217 The locale-invariant name of the command that produced the output,
218 e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
221 @defvr {Optional} @code{visibility}
222 To what degree the output represented by the element is visible. The
223 only observed value is @code{collapsed}.
226 @defvr {Optional} @code{locale}
227 The locale used for output, in Windows format, which is similar to the
228 format used in Unix with the underscore replaced by a hyphen, e.g.@:
229 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
232 @defvr {Optional} @code{olang}
233 The output language, e.g.@: @code{en}, @code{it}, @code{es},
234 @code{de}, @code{pt-BR}.
237 @node SPV Structure label Element
238 @subsection The @code{label} Element
240 Parent: @code{heading} or @code{container} @*
243 Every @code{heading} and @code{container} holds a @code{label} as its
244 first child. The root @code{heading} in a structure member always
245 contains the string ``Output''. Otherwise, the text in @code{label}
246 describes what it labels, often by naming the statistical procedure
247 that was executed, e.g.@: ``Frequencies'' or ``T-Test''. Labels are
248 often very generic, especially within a @code{container}, e.g.@:
249 ``Title'' or ``Warnings'' or ``Notes''. Label text is localized
250 according to the output language, e.g.@: in Italian a frequency table
251 procedure is labeled ``Frequenze''.
253 The corpus contains one example of an empty label, one that contains
256 This element has no attributes.
258 @node SPV Structure container Element
259 @subsection The @code{container} Element
261 Parent: @code{heading} @*
262 Contents: @code{label} (@code{table} @math{|} @code{text})?
264 A @code{container} serves to label a @code{table} or a @code{text}
267 This element has the following attributes.
269 @defvr {Required} @code{visibility}
270 Either @code{visible} or @code{hidden}, this indicates whether the
271 container's content is displayed.
274 @defvr {Optional} @code{text-align}
275 Presumably indicates the alignment of text within the container. The
276 only observed value is @code{left}. Observed with nested @code{table}
277 and @code{text} elements.
280 @defvr {Optional} @code{width}
281 The width of the container in the form @code{@var{n}px}, e.g.@:
285 @node SPV Structure text Element (Inside @code{container})
286 @subsection The @code{text} Element (Inside @code{container})
288 Parent: @code{container} @*
289 Contents: @code{html}
291 This @code{text} element is nested inside a @code{container}. There
292 is a different @code{text} element that is nested inside a
293 @code{pageParagraph}.
295 This element has the following attributes.
297 @defvr {Required} @code{type}
298 One of @code{title}, @code{log}, or @code{text}.
301 @defvr {Optional} @code{commandName}
302 As on the @code{heading} element. For output not specific to a
303 command, this is simply @code{log}. The corpus contains one example
304 of where @code{commandName} is present but set to the empty string.
307 @defvr {Optional} @code{creator-version}
308 As on the @code{heading} element.
311 @node SPV Structure html Element
312 @subsection The @code{html} Element
314 Parent: @code{text} @*
317 The CDATA contains an HTML document. In some cases, the document
318 starts with @code{<html>} and ends with @code{</html}; in others the
319 @code{html} element is implied. Generally the HTML includes a
320 @code{head} element with a CSS stylesheet. The HTML body often begins
321 with @code{<BR>}. The actual content ranges from trivial to simple:
322 just discarding the CSS and tags yields readable results.
324 This element has the following attributes.
326 @defvr {Required} @code{lang}
327 This always contains @code{en} in the corpus.
330 @node SPV Structure table Element
331 @subsection The @code{table} Element
333 Parent: @code{container} @*
334 Contents: @code{tableStructure}
336 This element has the following attributes.
338 @defvr {Required} @code{commandName}
339 As on the @code{heading} element.
342 @defvr {Required} @code{type}
343 One of @code{table}, @code{note}, or @code{warning}.
346 @defvr {Required} @code{subType}
347 The locale-invariant name for the particular kind of output that this
348 table represents in the procedure. This can be the same as
349 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
350 @code{Case Processing Summary}. Generic subtypes @code{Notes} and
351 @code{Warnings} are often used.
354 @defvr {Required} @code{tableId}
355 A number that uniquely identifies the table within the SPV file,
356 typically a large negative number such as @code{-4147135649387905023}.
359 @defvr {Optional} @code{creator-version}
360 As on the @code{heading} element. In the corpus, this is only present
361 for version 21 and up and always includes all 8 digits.
364 @node SPV Structure tableStructure Element
365 @subsection The @code{tableStructure} Element
367 Parent: @code{table} @*
368 Contents: @code{dataPath}
370 This element has no attributes.
372 @node SPV Structure dataPath Element
373 @subsection The @code{dataPath} Element
375 Parent: @code{tableStructure} @*
378 Contains the name of the Zip member that holds the table details,
379 e.g.@: @code{0000000001437_lightTableData.bin}.
381 This element has no attributes.
383 @node SPV Structure pageSetup Element
384 @subsection The @code{pageSetup} Element
386 Parent: @code{heading} @*
387 Contents: @code{pageHeader} @code{pageFooter}
389 This element has the following attributes.
391 @defvr {Required} @code{initial-page-number}
395 @defvr {Optional} @code{chart-size}
396 Always @code{as-is} or a localization (!) of it (e.g.@: @code{dimensione
397 attuale}, @code{Wie vorgegeben}).
400 @defvr {Optional} @code{margin-left}
401 @defvrx {Optional} @code{margin-right}
402 @defvrx {Optional} @code{margin-top}
403 @defvrx {Optional} @code{margin-bottom}
404 Margin sizes in the form @code{@var{size}in}, e.g.@: @code{0.25in}.
407 @defvr {Optional} @code{paper-height}
408 @defvrx {Optional} @code{paper-width}
409 Paper sizes in the form @code{@var{size}in}, e.g.@: @code{8.5in} by
410 @code{11in} for letter paper or @code{8.267in} by @code{11.692in} for
414 @defvr {Optional} @code{reference-orientation}
418 @defvr {Optional} @code{space-after}
422 @node SPV Structure pageHeader and pageFooter Elements
423 @subsection The @code{pageHeader} and @code{pageFooter} Elements
425 Parent: @code{pageSetup} @*
426 Contents: @code{pageParagraph}*
428 This element has no attributes.
430 @node SPV Structure pageParagraph Element
431 @subsection The @code{pageParagraph} Element
433 Parent: @code{pageHeader} or @code{pageFooter} @*
434 Contents: @code{text}
436 Text to go at the top or bottom of a page, respectively.
438 This element has no attributes.
440 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
441 @subsection The @code{text} Element (Inside @code{pageParagraph})
443 Parent: @code{pageParagraph}
446 This @code{text} element is nested inside a @code{pageParagraph}. There
447 is a different @code{text} element that is nested inside a
450 The element is either empty, or contains CDATA that holds almost-XHTML
451 text: in the corpus, either an @code{html} or @code{p} element. It is
452 @emph{almost}-XHTML because the @code{html} element designates the
454 @code{http://xml.spss.com/spss/viewer/viewer-tree} instead of an XHTML
455 namespace, and because the CDATA can contain substitution variables:
456 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
459 Typical contents (indented for clarity):
462 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
465 <p style="text-align:right; margin-top: 0">Page &[Page]</p>
470 This element has the following attributes.
472 @defvr {Required} @code{type}
476 @node SPV Light Detail Member Format
477 @section Light Detail Member Format
479 This section describes the format of ``light'' detail @file{.bin}
480 members. These members have a binary format which we describe here in
481 terms of a context-free grammar using the following conventions:
484 @item NonTerminal @result{} @dots{}
485 Nonterminals have CamelCaps names, and @result{} indicates a
486 production. The right-hand side of a production is often broken
487 across multiple lines. Break points are chosen for aesthetics only
488 and have no semantic significance.
490 @item 00, 01, @dots{}, ff.
491 Bytes with fixed values are written in hexadecimal:
493 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
494 32-bit integers with fixed values are written in decimal, prefixed by
501 A byte with value 0 or 1.
504 An arbitrary 16-bit integer.
507 An arbitrary 32-bit integer.
510 An arbitrary 64-bit IEEE floating-point number.
513 An arbitrary 32-bit IEEE floating-point number.
516 A 32-bit integer followed by the specified number of bytes of
517 character data. (The encoding is indicated by the Formats
521 @var{x} is optional, e.g.@: 00? is an optional zero byte.
523 @item @var{x}*@var{n}
524 @var{x} is repeated @var{n} times, e.g. byte*10 for ten arbitrary bytes.
526 @item @var{x}[@var{name}]
527 Gives @var{x} the specified @var{name}. Names are used in textual
528 explanations. They are also used, also bracketed, to indicate counts,
529 e.g.@: int[@t{n}] byte*[@t{n}] for a 32-bit integer followed by the
530 specified number of arbitrary bytes.
532 @item @var{a} @math{|} @var{b}
533 Either @var{a} or @var{b}.
536 Parentheses are used for grouping to make precedence clear, especially
537 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
541 A 32-bit integer that indicates the number of bytes in @var{x},
542 followed by @var{x} itself.
545 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
546 (The @file{.bin} header indicates the version.)
549 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
552 All integer and floating-point values in this format use little-endian
555 A ``light'' detail member @file{.bin} consists of a number of sections
556 concatenated together, terminated by a byte 01:
560 LightMember @result{} Header Title Caption Footnotes Fonts Formats Dimensions Data 01
564 The following sections go into more detail.
567 * SPV Light Member Header::
568 * SPV Light Member Title::
569 * PSV Light Member Caption::
570 * SPV Light Member Footnotes::
571 * SPV Light Member Fonts::
572 * SPV Light Member Formats::
573 * SPV Light Member Dimensions::
574 * SPV Light Member Categories::
575 * SPV Light Member Data::
576 * SPV Light Member Value::
577 * SPV Light Member ValueMod::
580 @node SPV Light Member Header
583 An SPV file begins with an 39-byte header:
589 (i1 @math{|} i3)[@t{version}]
590 01 (00 @math{|} 01) byte*21 00 00
591 int[@t{table-id}] byte*4
595 @code{version} is a version number that affects the interpretation of
596 some of the other data in the member. We will refer to ``version 1''
597 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
598 version-specific formatting (as described previously).
600 @code{table-id} is a binary version of the @code{tableId} attribute in
601 the structure member that refers to the detail member. For example,
602 if @code{tableId} is @code{-4154297861994971133}, then @code{table-id}
605 The meaning of the other variable parts of the header is not known.
607 @node SPV Light Member Title
613 Value[@t{title1}] 01?
615 Value[@t{title2}] 01?
619 The Title, which follows the Header, specifies the pivot table's title
620 twice, as @code{title1} and @code{title2}. In the corpus, they are
623 Whereas the Value in @code{title1} and in @code{title2} are
624 appropriate for presentation, and localized to the user's language,
625 @code{c} is in English, sometimes less specific, and sometimes less
626 well formatted. For example, for a frequency table, @code{title1} and
627 @code{title2} name the variable and @code{c} is simply ``Frequencies''.
629 @node PSV Light Member Caption
634 Caption @result{} Caption1 Caption2
635 Caption1 @result{} 31 Value @math{|} 58
636 Caption2 @result{} 31 Value @math{|} 58
640 The Caption, if present, is shown below the table. Caption2 is
641 normally present. Caption1 is only rarely nonempty; it might reflect
642 user editing of the caption.
644 @node SPV Light Member Footnotes
645 @subsection Footnotes
649 Footnotes @result{} int[@t{n}] Footnote*[@t{n}]
650 Footnote @result{} Value[@t{text}] (58 @math{|} 31 Value[@t{marker}]) byte*4
654 Each footnote has @code{text} and an optional customer @code{marker}
657 @node SPV Light Member Fonts
662 Fonts @result{} 00 Font*8
665 string[@t{typeface}] float[@t{size}] int[@t{style}] bool[@t{underline}]
666 int[@t{halign}] int[@t{valign}]
667 string[@t{fgcolor}] string[@t{bgcolor}]
668 byte[@t{alternate}] string[@t{altfg}] string[@t{altbg}]
669 v3(int[@t{left-margin}] int[@t{right-margin}] int[@t{top-margin}] int[@t{bottom-margin}])
673 Each Font represents the font style for a different element, in the
674 following order: title, caption, footer, corner, column
675 labels, row labels, data, and layers.
677 @code{index} is the 1-based index of the Font, i.e. 1 for the first
678 Font, through 8 for the final Font.
680 @code{typeface} is the string name of the font. In the corpus, this
681 is @code{SansSerif} in over 99% of instances and @code{Times New
684 @code{size} is the size of the font, in points. The most common size
685 in the corpus is 12 points.
687 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
688 1 (with value 2) is set for italic.
690 @code{underline} is 1 if the font is underlined, 0 otherwise.
692 @code{halign} specifies horizontal alignment: 0 for center, 2 for
693 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
694 alignment varies according to type: string data is left-justified,
695 numbers and most other formats are right-justified.
697 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
700 @code{fgcolor} and @code{bgcolor} are the foreground color and
701 background color, respectively. In the corpus, these are always
702 @code{#000000} and @code{#ffffff}, respectively.
704 @code{alternate} is 01 if rows should alternate colors, 00 if all rows
705 should be the same color. When @code{alternate} is 01, @code{altfg}
706 and @code{altbg} specify the colors for the alternate rows.
708 The meaning of the remaining data is unknown. It seems likely to
709 include font sizes, attributes such as bold or italic, and margins.
711 The table below lists the values observed in the corpus. When a cell
712 contains a single value, then 99@math{+}% of the corpus contains that value.
713 When a cell contains a pair of values, then the first value is seen in
714 about two-thirds of the corpus and the second value in about the
715 remaining one-third. In fonts that include multiple pairs, values are
716 correlated, that is, for font 3, f5 = 24, f6 = 24, f7 = 2 appears
717 about two-thirds of the time, as does the combination of f4 = 0, f6 =
720 @multitable {font} {40} {f2} {64173} {0/1} {24/11} {10/11} {2/3} {f8}
721 @headitem font @tab f1 @tab f2 @tab f3 @tab f4 @tab f5 @tab f6 @tab f7 @tab f8
722 @item 1 @tab 40 @tab 1 @tab 0 @tab 0 @tab 8 @tab 10/11 @tab 1 @tab 8
723 @item 2 @tab 40 @tab 0 @tab 2 @tab 1 @tab 8 @tab 10/11 @tab 1 @tab 1
724 @item 3 @tab 40 @tab 0 @tab 2 @tab 1 @tab 24/11 @tab 24/ 8 @tab 2/3 @tab 4
725 @item 4 @tab 40 @tab 0 @tab 2 @tab 3 @tab 8 @tab 10/11 @tab 1 @tab 1
726 @item 5 @tab 40 @tab 0 @tab 0 @tab 1 @tab 8 @tab 10/11 @tab 1 @tab 4
727 @item 6 @tab 40 @tab 0 @tab 2 @tab 1 @tab 8 @tab 10/11 @tab 1 @tab 4
728 @item 7 @tab 40 @tab 0 @tab 64173 @tab 0/1 @tab 8 @tab 10/11 @tab 1 @tab 1
729 @item 8 @tab 40 @tab 0 @tab 2 @tab 3 @tab 8 @tab 10/11 @tab 1 @tab 4
732 @node SPV Light Member Formats
741 int[@t{n4}] int*[@t{n4}]
743 (i0 @math{|} i-1) (00 @math{|} 01) 00 (00 @math{|} 01)
745 byte[@t{decimal}] byte[@t{grouping}]
746 int[@t{n-ccs}] string*[@t{n-ccs}]
748 v3(count(count(X5) count(X6)))
752 int[@t[n-borders}] Border*[@t{n-borders}]
753 bool[@t{show-grid-lines}]
761 PrintSettings @result{}
767 bool[@t{top-continuation}]
768 bool[@t{bottom-continuation}]
769 int[@t{n-orphan-lines}]
770 string[@t{continuation-string}]
772 TableSettings @result{}
775 int[@t{current-layer}]
777 bool[@t{show-dimension-in-corner}]
778 bool[@t{use-alphabetic-markers}]
779 bool[@t{footnote-marker-position}]
782 int[@t{n}] byte*[@t{n}]
784 string[@t{table-look}]
788 X5 @result{} byte*33 int[@t{n}] int*[@t{n}]
790 01 00 (03 @math{|} 04) 00 00 00
791 string[@t{command}] string[@t{subcommand}]
792 string[@t{language}] string[@t{charset}] string[@t{locale}]
793 (00 @math{|} 01) 00 (00 @math{|} 01) (00 @math{|} 01)
795 byte[@t{decimal}] byte[@t{grouping}]
797 (string[@t{dataset}] string[@t{data file}] i0 int i0)?
798 int[@t{n-ccs}] string*[@t{n-ccs}]
799 2e (00 @math{|} 01) (i2000000 i0)?
803 The Borders reflect how borders between regions are drawn. If
804 @code{endian} is 1, then values inside Borders, including
805 @code{endian} itself, are big-endian, otherwise they are
806 little-endian. In practice, they seem to always be big-endian, even
807 though the rest of the file is little-endian. @code{n-borders} seems
808 to always be 19. @code{show-grid-lines} is 1 to draw grid lines,
811 Each Border describes one kind of border. Each @code{border-type}
812 appears once in order, and they correspond to the following borders:
818 Left, top, right, and bottom outer frame.
820 Left, top, right, and bottom inner frame.
822 Left and top of data area.
824 Horizontal and vertical dimension rows.
826 Horizontal and vertical dimension columns.
828 Horizontal and vertical category rows.
830 Horizontal and vertical category columns.
833 @code{stroke-type} describes how a border is drawn, as one of:
850 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
851 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
852 opaque color, therefore opaque black is 0xff000000.
854 The PrintSettings reflect settings for printing. Like Borders, they
855 have independent endianness. The @code{continuation-string} is
856 usually empty but it may contain a text string such as ``(cont.)''.
858 The TableSettings reflect display settings. Like Borders, they
859 have independent endianness. @code{current-layer} is the displayed
860 layer. @code{use-alphabetic-markers} is 1 to show markers as letters
861 (e.g. @samp{a}, @samp{b}, @samp{c}, @dots{}), otherwise they are shown
862 as numbers starting from 1. When @code{footnote-marker-position} is
863 1, footnote markers are shown as superscripts, otherwise as
864 subscripts. @code{table-look} is the name of a SPSS ``TableLook''
865 table style, such as ``Default'' or ``Academic''; it is often empty.
866 TableSettings ends with an arbitrary number of null bytes.
868 Observed values of @code{n4} vary from 0 to 17. Out of 7,060 examples
869 in the corpus, it is nonzero only 36 times.
871 @code{encoding} is a character encoding, usually a Windows code page
872 such as @code{en_US.windows-1252} or @code{it_IT.windows-1252}. The
873 rest of the character strings in the member use this encoding. The
874 encoding string is itself encoded in US-ASCII.
876 @code{decimal} is the decimal point character. The observed values
877 are @samp{.} and @samp{,}.
879 @code{grouping} is the grouping character. Usually, it is @samp{,} if
880 @code{decimal} is @samp{.}, and vice versa. Other observed values are
881 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
882 indicating that digits should not be grouped).
884 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
885 following strings are CCA through CCE format strings. @xref{Custom
886 Currency Formats,,, pspp, PSPP}. Most commonly these are all
887 @code{-,,,} but other strings occur.
889 @node SPV Light Member Dimensions
890 @subsection Dimensions
892 A pivot table presents multidimensional data. A Dimension identifies
893 the categories associated with each dimension.
897 Dimensions @result{} int[@t{n-dims}] Dimension*[@t{n-dims}]
898 Dimension @result{} Value[@t{name}] DimUnknown int[@t{n-categories}] Category*[@t{n-categories}]
901 (00 @math{|} 01 @math{|} 02)[@t{d2}]
902 (i0 @math{|} i2)[@t{d3}]
903 (00 @math{|} 01)[@t{d4}]
904 (00 @math{|} 01)[@t{d5}]
910 @code{name} is the name of the dimension, e.g. @code{Variables},
911 @code{Statistics}, or a variable name.
913 @code{d1} is usually 0 but many other values have been observed.
915 @code{d3} is 2 over 99% of the time.
917 @code{d5} is 0 over 99% of the time.
919 @code{d6} is either -1 or the 0-based index of the dimension, e.g.@: 0
920 for the first dimension, 1 for the second, and so on. The latter is
921 the case 98% of the time in the corpus.
923 @node SPV Light Member Categories
924 @subsection Categories
926 Categories are arranged in a tree. Only the leaf nodes in the tree
927 are really categories; the others just serve as grouping constructs.
931 Category @result{} Value[@t{name}] (Leaf @math{|} Group)
932 Leaf @result{} 00 00 00 i2 int[@t{index}] i0
934 (00 @math{|} 01)[@t{merge}] 00 01 (i0 @math{|} i2)[@t{data}]
935 i-1 int[@t{n-subcategories}] Category*[@t{n-subcategories}]
939 @code{name} is the name of the category (or group).
941 A Leaf represents a leaf category. The Leaf's @code{index} is a
942 nonnegative integer less than @code{n-categories} in the Dimension in
943 which the Category is nested (directly or indirectly).
945 A Group represents a Group of nested categories. Usually a Group
946 contains at least one Category, so that @code{n-subcategories} is
947 positive, but a few Groups with @code{n-subcategories} 0 has been
950 If a Group's @code{merge} is 00, the most common value, then the group
951 is really a distinct group that should be represented as such in the
952 visual representation and user interface. If @code{merge} is 01, the
953 categories in this group should be shown and treated as if they were
954 direct children of the group's containing group (or if it has no
955 parent group, then direct children of the dimension), and this group's
956 name is irrelevant and should not be displayed. (Merged groups can be
959 A Group's @code{data} appears to be i2 when all of the categories
960 within a group are leaf categories that directly represent data values
961 for a variable (e.g. in a frequency table or crosstabulation, a group
962 of values in a variable being tabulated) and i0 otherwise.
964 @node SPV Light Member Data
967 The final part of an SPV light member contains the actual data.
972 int[@t{layers}] int[@t{rows}] int[@t{columns}] int*[@t{n-dimensions}]
973 int[@t{n-data}] Datum*[@t{n-data}]
974 Datum @result{} int64[@t{index}] v3(00?) Value
978 The values of @code{layers}, @code{rows}, and @code{columns} each
979 specifies the number of dimensions displayed in layers, rows, and
980 columns, respectively. Any of them may be zero. Their values sum to
981 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
984 The @code{n-dimensions} integers are a permutation of the 0-based
985 dimension numbers. The first @code{layers} integers specify each of
986 the dimensions represented by layers, the next @code{rows} integers
987 specify the dimensions represented by rows, and the final
988 @code{columns} integers specify the dimensions represented by columns.
989 When there is more than one dimension of a given kind, the inner
990 dimensions are given first.
992 The format of a Datum varies slightly from version 1 to version 3: in
993 version 1 it allows for an extra optional 00 byte.
995 A Datum consists of an @code{index} and a Value. Suppose there are
996 @math{d} dimensions and dimension @math{i}, @math{0 \le i < d}, has
997 @math{n_i} categories. Consider the datum at coordinates @math{x_i},
998 @math{0 \le i < d}, and note that @math{0 \le x_i < n_i}. Then the
999 index is calculated by the following algorithm:
1003 for each @math{i} from 0 to @math{d - 1}:
1004 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1007 For example, suppose there are 3 dimensions with 3, 4, and 5
1008 categories, respectively. The datum at coordinates (1, 2, 3) has
1009 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1011 @node SPV Light Member Value
1014 Value is used throughout the SPV light member format. It boils down
1015 to a number or a string.
1019 Value @result{} 00? 00? 00? 00? RawValue
1021 01 ValueMod int[@t{format}] double[@t{x}]
1022 @math{|} 02 ValueMod int[@t{format}] double[@t{x}]
1023 string[@t{varname}] string[@t{vallab}] (01 @math{|} 02 @math{|} 03)
1024 @math{|} 03 string[@t{local}] ValueMod string[@t{id}] string[@t{c}] (00 @math{|} 01)[@t{type}]
1025 @math{|} 04 ValueMod int[@t{format}] string[@t{vallab}] string[@t{varname}]
1026 (01 @math{|} 02 @math{|} 03) string[@t{s}]
1027 @math{|} 05 ValueMod string[@t{varname}] string[@t{varlabel}] (01 @math{|} 02 @math{|} 03)
1028 @math{|} ValueMod string[@t{format}] int[@t{n-args}] Argument*[@t{n-args}]
1031 @math{|} int[@t{x}] i0 Value*[@t{x}@math{+}1] /* @t{x} @math{>} 0 */
1035 There are several possible encodings, which one can distinguish by the
1036 first nonzero byte in the encoding.
1040 The numeric value @code{x}, intended to be presented to the user
1041 formatted according to @code{format}, which is in the format described
1042 for system files. @xref{System File Output Formats}, for details.
1043 Most commonly, @code{format} has width 40 (the maximum).
1045 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1046 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1047 not been observed.) @xref{System File Format}, for more about these
1051 Similar to @code{01}, with the additional information that @code{x} is
1052 a value of variable @code{varname} and has value label @code{vallab}.
1053 Both @code{varname} and @code{vallab} can be the empty string, the
1054 latter very commonly.
1056 The meaning of the final byte is unknown. Possibly it is connected to
1057 whether the value or the label should be displayed.
1060 A text string, in two forms: @code{c} is in English, and sometimes
1061 abbreviated or obscure, and @code{local} is localized to the user's
1062 locale. In an English-language locale, the two strings are often the
1063 same, and in the cases where they differ, @code{local} is more
1064 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1065 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1066 where P must be greater than 1.''
1068 @code{c} and @code{local} are always either both empty or both
1071 @code{id} is a brief identifying string whose form seems to resemble a
1072 programming language identifier, e.g.@: @code{cumulative_percent} or
1073 @code{factor_14}. It is not unique.
1075 @code{type} is 00 for text taken from user input, such as syntax
1076 fragment, expressions, file names, data set names, and 01 for fixed
1077 text strings such as names of procedures or statistics. In the former
1078 case, @code{id} is always the empty string; in the latter case,
1079 @code{id} is still sometimes empty.
1082 The string value @code{s}, intended to be presented to the user
1083 formatted according to @code{format}. The format for a string is not
1084 too interesting, and the corpus contains many clearly invalid formats
1085 like A16.39 or A255.127 or A134.1, so readers should probably ignore
1086 the format entirely.
1088 @code{s} is a value of variable @code{varname} and has value label
1089 @code{vallab}. @code{varname} is never empty but @code{vallab} is
1092 The meaning of the final byte is unknown.
1095 Variable @code{varname}, which is rarely observed as empty in the
1096 corpus, with variable label @code{varlabel}, which is often empty.
1098 The meaning of the final byte is unknown.
1101 (These bytes begin a ValueMod.) A format string, analogous to
1102 @code{printf}, followed by one or more Arguments, each of which has
1103 one or more values. The format string uses the following syntax:
1110 Each of these expands to the character following @samp{\\}, to escape
1111 characters that have special meaning in format strings. These are
1112 effective inside and outside the @code{[@dots{}]} syntax forms
1116 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1120 Expands to a formatted version of argument @var{i}, which must have
1121 only a single value. For example, @code{^1} expands to the first
1122 argument's @code{value}.
1124 @item [:@var{a}:]@var{i}
1125 Expands @var{a} for each of the values in @var{i}. @var{a}
1126 should contain one or more @code{^@var{j}} conversions, which are
1127 drawn from the values for argument @var{i} in order. Some examples
1132 All of the values for the first argument, concatenated.
1135 Expands to the values for the first argument, each followed by
1139 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1140 argument's first value and @var{y} is its second value. (This would
1141 be used only if the argument has two values. If there were more
1142 values, the second and third values would be directly concatenated,
1143 which would look funny.)
1146 @item [@var{a}:@var{b}:]@var{i}
1147 This extends the previous form so that the first values are expanded
1148 using @var{a} and later values are expanded using @var{b}. For an
1149 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1150 instead written as @code{%@var{j}}. Some examples from the corpus:
1154 Expands to all of the values for the first argument, separated by
1157 @item [%1 = %2:, ^1 = ^2:]1
1158 Given appropriate values for the first argument, expands to @code{X =
1162 Given appropriate values, expands to @code{1, 2, 3}.
1166 The format string is localized to the user's locale.
1169 @node SPV Light Member ValueMod
1170 @subsection ValueMod
1172 A ValueMod can specify special modifications to a Value.
1177 31 i0 (i0 @math{|} i1 string[@t{subscript}])
1178 v1(00 (i1 @math{|} i2) 00 00 int 00 00)
1179 v3(count(FormatString Style ValueModUnknown))
1180 @math{|} 31 int[@t{n-refs}] int16*[@t{n-refs}] Format
1182 Style @result{} 58 @math{|} 31 01? 00? 00? 00? 01 string[@t{fgcolor}] string[@t{bgcolor}] string[@t{typeface}] byte
1183 Format @result{} 00 00 count(FormatString Style 58)
1184 FormatString @result{} count((i0 (58 @math{|} 31 string))?)
1185 ValueModUnknown @result{} 58 @math{|} 31 i0 i0 i0 i0 01 00 (01 @math{|} 02 @math{|} 08) 00 08 00 0a 00)
1189 A ValueMod that begins with ``31 i0'' specifies a string to append to
1190 the main text of the Value, as a subscript. The subscript text is a
1191 brief indicator, e.g.@: @samp{a} or @samp{a,b}, with its meaning
1192 indicated by the table caption. In this usage, subscripts are similar
1193 to footnotes. One apparent difference is that a Value can only
1194 reference one footnote but a subscript can list more than one letter.
1196 A ValueMod that begins with 31 followed by a nonzero ``int'' specifies
1197 a footnote or footnotes that the Value references. Footnote markers
1198 are shown appended to the main text of the Value, as superscripts.
1200 The Format, if present, is a format string for substitutions using the
1201 syntax explained previously. It appears to be an English-language
1202 version of the localized format string in the Value in which the
1205 The Style, if present, changes the style for this individual Value.
1207 @node SPV Legacy Detail Member Binary Format
1208 @section Legacy Detail Member Binary Format
1210 Whereas the light binary format represents everything about a given
1211 pivot table, the legacy binary format conceptually consists of a
1212 number of named sources, each of which consists of a number of named
1213 variables, each of which is a 1-dimensional array of numbers or
1214 strings or a mix. Thus, the legacy binary member format is quite
1217 This section uses the same context-free grammar notation as in the
1218 previous section, with the following additions:
1222 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
1223 (The legacy member header indicates the version; see below.)
1226 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
1229 A legacy detail member @file{.bin} has the following overall format:
1233 LegacyBinary @result{}
1234 00 byte[@t{version}] int16[@t{n-sources}] int[@t{member-size}]
1235 Metadata*[@t{n-sources}] Data*[@t{n-sources}]
1239 @code{version} is a version number that affects the interpretation of
1240 some of the other data in the member. Versions 0xaf and 0xb0 are
1241 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
1244 A legacy member consists of @code{n-sources} data sources, each of
1245 which has Metadata and Data.
1247 @code{member-size} is the size of the legacy binary member, in bytes.
1249 The following sections go into more detail.
1252 * SPV Legacy Member Metadata::
1253 * SPV Legacy Member Data::
1256 @node SPV Legacy Member Metadata
1257 @subsection Metadata
1262 int[@t{n-data}] int[@t{n-variables}] int[@t{offset}]
1263 vAF(byte*32[@t{source-name}])
1264 vB0(byte*64[@t{source-name}] int[@t{x}])
1268 A data source has @code{n-variables} variables, each with
1269 @code{n-data} data values.
1271 @code{source-name} is a 32- or 64-byte string padded on the right with
1272 zero bytes. The names that appear in the corpus are very generic:
1273 usually @code{tableData} for pivot table data or @code{source0} for
1276 A given Metadata's @code{offset} is the offset, in bytes, from the
1277 beginning of the member to the start of the corresponding Data. This
1278 allows programs to skip to the beginning of the data for a particular
1279 source; it is also important to determine whether a source includes
1280 any string data (@pxref{SPV Legacy Member Data}).
1282 The meaning of @code{x} in version 0xb0 is unknown.
1284 @node SPV Legacy Member Data
1289 Data @result{} NumericData*[@t{n-variables}] StringData?
1290 NumericData @result{} byte*288[@t{variable-name}] double*[@t{n-data}]
1294 Data follow the Metadata in the legacy binary format, with sources in
1295 the same order. Each NumericSeries begins with a @code{variable-name}
1296 that generally indicates its role in the pivot table, e.g.@: ``cell'',
1297 ``cellFormat'', ``dimension0categories'', ``dimension0group0'',
1298 followed by the numeric data, one double per datum. A double with the
1299 maximum negative double @code{-DBL_MAX} represents the system-missing
1304 StringData @result{} i1 string[@t{source-name}] Pairs Labels
1306 Pairs @result{} int[@t{n-string-vars}] PairSeries*[@t{n-string-vars}]
1307 PairVar @result{} string[@t{pair-var-name}] int[@t{n-pairs}] Pair*[@t{n-pairs}]
1308 Pair @result{} int[@t{i}] int[@t{j}]
1310 Labels @result{} int[@t{n-labels}] Label*[@t{n-labels}]
1311 Label @result{} int[@t{frequency}] int[@t{s}]
1315 A source may include a mix of numeric and string data values. When a
1316 source includes any string data, the data values that are strings are
1317 set to SYSMIS in the NumericData, and StringData follows the
1318 NumericData. A source that contains no string data omits the
1319 StringData. To reliably determine whether a source includes
1320 StringData, the reader should check whether the offset following the
1321 NumericData is the offset of the next source, as indicated by its
1322 Metadata (or the end of the member, in the case of the last source).
1324 StringData repeats the name of the source (from Metadata).
1326 The string data overlays the numeric data. @code{n-string-vars} is
1327 the number of variables in the source that include string data. More
1328 precisely, it is the 1-based index of the last variable in the source
1329 that includes any string data; thus, it would be 4 if there are 5
1330 variables and only the fourth one includes string data.
1332 Each PairVar consists a sequence of 0 or more Pair nonterminals, each
1333 of which maps from a 0-based index within variable @code{i} to a
1334 0-based label index @code{j}, e.g.@: pair @code{i} = 2, @code{j} = 3,
1335 means that the third data value (with value SYSMIS) is to be replaced
1336 by the string of the fourth Label.
1338 The labels themselves follow the pairs. The valuable part of each
1339 label is the string @code{s}. Each label also includes a
1340 @code{frequency} that reports the number of pairs that reference it
1341 (although this is not useful).
1343 @node SPV Legacy Detail Member XML Format
1344 @section Legacy Detail Member XML Format
1346 This format is still under investigation.
1348 The design of the detail XML format is not what one would end up with
1349 for describing pivot tables. This is because it is a special case
1350 of a much more general format (``visualization XML'' or ``VizML'')
1351 that can describe a wide range of visualizations. Most of this
1352 generality is overkill for tables, and so we end up with a funny
1353 subset of a general-purpose format.
1355 The important elements of the detail XML format are:
1359 Variables. Variables in detail XML roughly correspond to the
1360 dimensions in a light detail member. There is one variable for each
1361 dimension, plus one variable for each level of labeling along an axis.
1363 The bulk of variables are defined with @code{sourceVariable} elements.
1364 The data for these variables comes from the associated
1365 @code{tableData.bin} member. Some variables are defined, with
1366 @code{derivedVariable} elements, as a constant or in terms of a
1367 mapping function from a source variable.
1370 Assignment of variables to axes. A variable can appear as columns, or
1371 rows, or layers. The @code{faceting} element and its sub-elements
1372 describe this assignment.
1375 All elements have an optional @code{id} attribute. In practice many
1376 elements are assigned @code{id} attributes that are never referenced.
1379 * SPV Detail visualization Element::
1380 * SPV Detail userSource Element::
1381 * SPV Detail sourceVariable Element::
1382 * SPV Detail derivedVariable Element::
1383 * SPV Detail extension Element::
1384 * SPV Detail graph Element::
1385 * SPV Detail location Element::
1386 * SPV Detail coordinates Element::
1387 * SPV Detail faceting Element::
1388 * SPV Detail facetLayout Element::
1391 @node SPV Detail visualization Element
1392 @subsection The @code{visualization} Element
1395 Parent: Document root
1399 (sourceVariable @math{|} derivedVariable)@math{+}
1407 This element has the following attributes.
1409 @defvr {Required} creator
1410 The version of the software that created this SPV file, as a string of
1411 the form @code{xxyyzz}, which represents software version xx.yy.zz,
1412 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
1413 versions 16 through 19.
1416 @defvr {Required} date
1417 The date on the which the file was created, as a string of the form
1421 @defvr {Required} lang
1422 The locale used for output, in Windows format, which is similar to the
1423 format used in Unix with the underscore replaced by a hyphen, e.g.@:
1424 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
1427 @defvr {Required} name
1428 The title of the pivot table, localized to the output language.
1431 @defvr {Required} style
1432 The @code{id} of a @code{style} element (@pxref{SPV Detail style
1433 element}). This is the base style for the entire pivot table. In
1434 every example in the corpus, the value is @code{visualizationStyle}
1435 and the corresponding @code{style} element has no attributes other
1439 @defvr {Required} type
1440 A floating-point number. The meaning is unknown.
1443 @defvr {Required} version
1444 The visualization schema version number. In the corpus, the value is
1445 one of 2.4, 2.5, 2.7, and 2.8.
1448 @node SPV Detail userSource Element
1449 @subsection The @code{userSource} Element
1451 Parent: @code{visualization} @*
1454 This element has the following attributes.
1456 @defvr {Optional} missing
1457 Always @code{listwise}.
1460 @node SPV Detail sourceVariable Element
1461 @subsection The @code{sourceVariable} Element
1463 Parent: @code{visualization} @*
1464 Contents: @code{extension}* (@code{format} @math{|} @code{stringFormat})?
1466 This element defines a variable whose values can be used elsewhere in
1467 the visualization. It ties this element's @code{id} to a variable
1468 from the @file{tableData.bin} member that corresponds to this
1471 This element has the following attributes.
1473 @defvr {Required} categorical
1474 Always set to @code{true}.
1477 @defvr {Required} source
1478 Always set to @code{tableData}, the @code{source-name} in the
1479 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
1483 @defvr {Required} sourceName
1484 The name of a variable within the source, the @code{variable-name} in
1485 the corresponding @file{tableData.bin} member (@pxref{SPV Legacy
1489 @defvr {Optional} dependsOn
1490 The @code{variable-name} of a variable linked to this one, so that a
1491 viewer can work with them together. For a group variable, this is the
1492 name of the corresponding categorical variable.
1495 @defvr {Optional} label
1496 The variable label, if any
1499 @defvr {Optional} labelVariable
1500 The @code{variable-name} of a variable whose string values correspond
1501 one-to-one with the values of this variable and are suitable for use
1505 @node SPV Detail derivedVariable Element
1506 @subsection The @code{derivedVariable} Element
1508 Parent: @code{visualization} @*
1509 Contents: @code{extension}* (@code{format} @math{|} @code{stringFormat} @code{valueMapEntry}*)
1511 Like @code{sourceVariable}, this element defines a variable whose
1512 values can be used elsewhere in the visualization. Instead of being
1513 read from a data source, the variable's data are defined by a
1514 mathematical expression.
1516 This element has the following attributes.
1518 @defvr {Required} categorical
1519 Always set to @code{true}.
1522 @defvr {Required} value
1523 An expression that defines the variable's value. In theory this could
1524 be an arbitrary expression in terms of constants, functions, and other
1525 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
1526 the corpus contains only the following forms of expressions:
1529 @item constant(@var{number})
1530 @itemx constant(@var{variable})
1531 A constant. The meaning when a variable is named is unknown.
1532 Sometimes the ``variable name'' has spaces in it.
1534 @item map(@var{variable})
1535 Transforms the values in the named @var{variable} using the
1536 @code{valueMapEntry}s contained within the element.
1540 @defvr {Optional} dependsOn
1541 The @code{variable-name} of a variable linked to this one, so that a
1542 viewer can work with them together. For a group variable, this is the
1543 name of the corresponding categorical variable.
1547 * SPV Detail valueMapEntry Element::
1550 @node SPV Detail valueMapEntry Element
1551 @subsubsection The @code{valueMapEntry} Element
1553 Parent: @code{derivedVariable} @*
1556 A @code{valueMapEntry} element defines a mapping from one or more
1557 values of a source expression to a target value. (In the corpus, the
1558 source expression is always just the name of a variable.) Each target
1559 value requires a separate @code{valueMapEntry}. If multiple source
1560 values map to the same target value, they can be combined or separate.
1562 @code{valueMapEntry} has the following attributes.
1564 @defvr {Required} from
1565 A source value, or multiple source values separated by semicolons,
1566 e.g.@: @code{0} or @code{13;14;15;16}.
1569 @defvr {Required} to
1573 @node SPV Detail extension Element
1574 @subsection The @code{extension} Element
1576 This is a general-purpose ``extension'' element. Readers that don't
1577 understand a given extension should be able to safely ignore it. The
1578 attributes on this element, and their meanings, vary based on the
1579 context. Each known usage is described separately below. The current
1580 extensions use attributes exclusively, without any nested elements.
1582 @subsubheading @code{visualization} Parent Element
1584 With @code{visualization} as its parent element, @code{extension} has
1585 the following attributes.
1587 @defvr {Optional} numRows
1588 An integer that presumably defines the number of rows in the displayed
1592 @defvr {Optional} showGridline
1593 Always set to @code{false} in the corpus.
1596 @defvr {Optional} minWidthSet
1597 @defvrx {Optional} maxWidthSet
1598 Always set to @code{true} in the corpus.
1601 @subsubheading @code{container} Parent Element
1603 With @code{container} as its parent element, @code{extension} has the
1604 following attributes.
1606 @defvr {Required} combinedFootnotes
1607 Always set to @code{true} in the corpus.
1610 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
1612 With @code{sourceVariable} or @code{derivedVariable} as its parent
1613 element, @code{extension} has the following attributes. A given
1614 parent element often contains several @code{extension} elements that
1615 specify the meaning of the source data's variables or sources, e.g.@:
1618 <extension from="0" helpId="corrected_model"/>
1619 <extension from="3" helpId="error"/>
1620 <extension from="4" helpId="total_9"/>
1621 <extension from="5" helpId="corrected_total"/>
1624 @defvr {Required} from
1625 An integer or a name like ``dimension0''.
1628 @defvr {Required} helpId
1632 @node SPV Detail graph Element
1633 @subsection The @code{graph} Element
1635 Parent: @code{visualization} @*
1636 Contents: @code{location}@math{+} @code{coordinates} @code{faceting} @code{facetLayout} @code{interval}
1638 @code{graph} has the following attributes.
1640 @defvr {Required} cellStyle
1641 @defvrx {Required} style
1642 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
1643 Detail style element}). The former is the default style for
1644 individual cells, the latter for the entire table.
1647 @node SPV Detail location Element
1648 @subsection The @code{location} Element
1650 Parent: @code{graph} @*
1653 Each instance of this element specifies where some part of the table
1654 frame is located. All the examples in the corpus have four instances
1655 of this element, one for each of the parts @code{height},
1656 @code{width}, @code{left}, and @code{top}. Some examples in the
1657 corpus add a fifth for part @code{bottom}, even though it is not clear
1658 how all of @code{top}, @code{bottom}, and @code{heigth} can be honored
1659 at the same time. In any case, @code{location} seems to have little
1660 importance in representing tables; a reader can safely ignore it.
1662 @defvr {Required} part
1663 One of @code{height}, @code{width}, @code{top}, @code{bottom}, or
1664 @code{left}. Presumably @code{right} is acceptable as well but the
1665 corpus contains no examples.
1668 @defvr {Required} method
1669 How the location is determined:
1673 Based on the natural size of the table. Observed only for
1674 parts @code{height} and @code{width}.
1677 Based on the location specified in @code{target}. Observed only for
1678 parts @code{top} and @code{bottom}.
1681 Using the value in @code{value}. Observed only for parts @code{top},
1682 @code{bottom}, and @code{left}.
1685 Same as the specified @code{target}. Observed only for part
1690 @defvr {Optional} min
1691 Minimum size. Only observed with value @code{100pt}. Only observed
1692 for part @code{width}.
1695 @defvr {Dependent} target
1696 Required when @code{method} is @code{attach} or @code{same}, not
1697 observed otherwise. This is the ID of an element to attach to.
1698 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
1702 @defvr {Dependent} value
1703 Required when @code{method} is @code{fixed}, not observed otherwise.
1704 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
1705 on parts @code{top} and @code{left}, and @code{100%} on part
1709 @node SPV Detail coordinates Element
1710 @subsection The @code{coordinates} Element
1712 Parent: @code{graph} @*
1715 This element is always present and always empty, with no attributes
1718 @node SPV Detail faceting Element
1719 @subsection The @code{faceting} Element
1721 Parent: @code{graph} @*
1722 Contents: @code{cross} @code{layer}*
1724 The @code{faceting} element describes the row, column, and layer
1725 structure of the table. Its @code{cross} child determines the row and
1726 column structure, and each @code{layer} child (if any) represents a
1729 @code{faceting} has no attributes (other than @code{id}).
1731 @subsubheading The @code{cross} Element
1733 Parent: @code{faceting} @*
1734 Contents: @code{nest} @code{nest}
1736 The @code{cross} element describes the row and column structure of the
1737 table. It has exactly two @code{nest} children, the first of which
1738 describes the table's rows and the second the table's columns.
1740 @code{cross} has no attributes (other than @code{id}).
1742 @subsubheading The @code{nest} Element
1744 Parent: @code{cross} @*
1745 Contents: @code{variableReference}@math{+}
1747 A given @code{nest} usually consists of one or more dimensions, each
1748 of which is represented by @code{variableReference} child elements.
1749 Minimally, a dimension has two @code{variableReference} children, one
1750 for the categories, one for the data, e.g.:
1754 <variableReference ref="dimension0categories"/>
1755 <variableReference ref="dimension0"/>
1760 Groups of categories introduce additional variable references, e.g.@:
1764 <variableReference ref="dimension0categories"/>
1765 <variableReference ref="dimension0group0"/>
1766 <variableReference ref="dimension0"/>
1771 Grouping can be hierarchical, e.g.@:
1775 <variableReference ref="dimension0categories"/>
1776 <variableReference ref="dimension0group1"/>
1777 <variableReference ref="dimension0group0"/>
1778 <variableReference ref="dimension0"/>
1783 XXX what are group maps?
1786 <nest id="nest_1973">
1787 <variableReference ref="dimension1categories"/>
1788 <variableReference ref="dimension1group1map"/>
1789 <variableReference ref="dimension1group0map"/>
1790 <variableReference ref="dimension1"/>
1793 <variableReference ref="dimension0categories"/>
1794 <variableReference ref="dimension0group0map"/>
1795 <variableReference ref="dimension0"/>
1800 A @code{nest} can contain multiple dimensions:
1804 <variableReference ref="dimension1categories"/>
1805 <variableReference ref="dimension1group0"/>
1806 <variableReference ref="dimension1"/>
1807 <variableReference ref="dimension0categories"/>
1808 <variableReference ref="dimension0"/>
1812 One @code{nest} within a given @code{cross} may have no dimensions, in
1813 which case it still has one @code{variableReference} child, which
1814 references a @code{derivedVariable} whose @code{value} attribute is
1815 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
1816 @code{row} or @code{column}, respectively, as its @code{id}.
1818 @code{nest} has no attributes (other than @code{id}).
1820 @subsubheading The @code{variableReference} Element
1822 Parent: @code{nest} @*
1825 @code{variableReference} has one attribute.
1827 @defvr {Required} ref
1828 The @code{id} of a @code{sourceVariable} or @code{derivedVariable}
1832 @subsubheading The @code{layer} Element
1834 Parent: @code{faceting} @*
1837 Each layer is represented by a pair of @code{layer} elements. The
1838 first of this pair is for a category variable, the second for the data
1842 <layer value="0" variable="dimension0categories" visible="true"/>
1843 <layer value="dimension0" variable="dimension0" visible="false"/>
1847 @code{layer} has the following attributes.
1849 @defvr {Required} variable
1850 The @code{id} of a @code{sourceVariable} or @code{derivedVariable}
1854 @defvr {Required} value
1855 The value to select. For a category variable, this is always
1856 @code{0}; for a data variable, it is the same as the @code{variable}
1860 @defvr {Optional} visible
1861 Whether the layer is visible. Generally, category layers are visible
1862 and data layers are not, but sometimes this attribute is omitted.
1865 @defvr {Optional} method
1866 When present, this is always @code{nest}.
1869 @node SPV Detail facetLayout Element
1870 @subsection The @code{facetLayout} Element
1872 Parent: @code{graph} @*
1873 Contents: @code{tableLayout} @code{facetLevel}@math{+} @code{setCellProperties}*
1875 @subsubheading The @code{tableLayout} Element
1877 Parent: @code{facetLayout} @*
1880 @defvr {Required} verticalTitlesInCorner
1881 Always set to @code{true}.
1884 @defvr {Optional} style
1885 The @code{id} of a @code{style} element.
1888 @defvr {Optional} fitCells
1889 Always set to @code{ticks}.
1892 @subsubheading The @code{facetLevel} Element
1894 Parent: @code{facetLayout} @*
1895 Contents: @code{axis}
1897 Each @code{facetLevel} describes a @code{variableReference} or
1898 @code{layer}, and a table has one @code{facetLevel} element for
1899 each such element. For example, an SPV detail member that contains
1900 four @code{variableReference} elements and two @code{layer} elements
1901 will contain six @code{facetLevel} elements.
1903 In the corpus, @code{facetLevel} elements and the elements that they
1904 describe are always in the same order. The correspondence may also be
1905 observed in two other ways. First, one may use the @code{level}
1906 attribute, described below. Second, in the corpus, a
1907 @code{facetLevel} always has an @code{id} that is the same as the
1908 @code{id} of the element it describes with @code{_facetLevel}
1909 appended. One should not formally rely on this, of course, but it is
1910 usefully indicative.
1912 @defvr {Required} level
1913 A 1-based index into the @code{variableReference} and @code{layer}
1914 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
1915 describes the first @code{variableReference} in the SPV detail member,
1916 and in a member with four @code{variableReference} elements, a
1917 @code{facetLayout} with a @code{level} of 5 describes the first
1918 @code{layer} in the member.
1921 @defvr {Required} gap
1922 Always observed as @code{0pt}.
1925 @subsubheading The @code{axis} Element
1927 Parent: @code{facetLevel} @*
1928 Contents: @code{label}? @code{majorTicks}
1930 @defvr {Attribute} style
1931 The @code{id} of a @code{style} element.
1934 @subsubheading The @code{label} Element
1936 Parent: @code{axis} or @code{labelFrame} @*
1937 Contents: @code{text}@math{+} @math{|} @code{descriptionGroup}
1939 This element represents a label on some aspect of the table. For example,
1940 the table's title is a @code{label}.
1942 The contents of the label can be one or more @code{text} elements or a
1943 @code{descriptionGroup}.
1945 @defvr {Attribute} style
1946 @defvrx {Optional} textFrameStyle
1947 Each of these is the @code{id} of a @code{style} element.
1948 @code{style} is the style of the label text, @code{textFrameStyle} the
1949 style for the frame around the label.
1952 @defvr {Optional} purpose
1953 The kind of entity being labeled, one of @code{title},
1954 @code{subTitle}, @code{layer}, or @code{footnote}.
1957 @subsubheading The @code{descriptionGroup} Element
1959 Parent: @code{label} @*
1960 Contents: (@code{description} @math{|} @code{text})@math{+}
1962 A @code{descriptionGroup} concatenates one or more elements to form a
1963 label. Each element can be a @code{text} element, which contains
1964 literal text, or a @code{description} element that substitutes a value
1967 @defvr {Attribute} target
1968 The @code{id} of an element being described. In the corpus, this is
1969 always @code{faceting}.
1972 @defvr {Attribute} separator
1973 A string to separate the description of multiple groups, if the
1974 @code{target} has more than one. In the corpus, this is always a
1978 Typical contents for a @code{descriptionGroup} are a value by itself:
1980 <description name="value"/>
1982 @noindent or a variable and its value, separated by a colon:
1984 <description name="variable"/><text>:</text><description name="value"/>
1987 @subsubheading The @code{description} Element
1989 Parent: @code{descriptionGroup} @*
1992 A @code{description} is like a macro that expands to some property of
1993 the target of its parent @code{descriptionGroup}.
1995 @defvr {Attribute} name
1996 The name of the property. Only @code{variable} and @code{value}
1997 appear in the corpus.
2000 @subsubheading The @code{majorTicks} Element
2002 Parent: @code{axis} @*
2003 Contents: @code{gridline}?
2005 @defvr {Attribute} labelAngle
2006 @defvrx {Attribute} length
2007 Both always defined to @code{0}.
2010 @defvr {Attribute} style
2011 @defvrx {Attribute} tickFrameStyle
2012 Each of these is the @code{id} of a @code{style} element.
2013 @code{style} is the style of the tick labels, @code{tickFrameStyle}
2014 the style for the frames around the labels.
2017 @subsubheading The @code{gridline} Element
2019 Parent: @code{majorTicks} @*
2022 Represents ``gridlines,'' which for a table represents the lines
2023 between the rows or columns of a table (XXX?).
2025 @defvr {Attribute} style
2026 The style for the gridline.
2029 @defvr {Attribute} zOrder
2030 Observed as a number between 28 and 31. Does not seem to be
2034 @subsubheading The @code{setCellProperties} Element
2036 Parent: @code{facetLayout} @*
2037 Contents: @code{setMetaData} @code{setStyle}* @code{setFormat}@math{+} @code{union}?
2039 This element sets style properties of cells designated by the
2040 @code{target} attribute of its child elements, as further restricted
2041 by the optional @code{union} element if present. The @code{target}
2042 values often used, e.g.@: @code{graph} or @code{labeling}, actually
2043 affect every cell, so the @code{union} element is a useful
2046 @defvr {Optional} applyToConverse
2047 If present, always @code{true}. This appears to invert the meaning of
2048 the @code{target} of sub-elements: the selected cells are the ones
2049 @emph{not} designated by @code{target}. This is confusing, given the
2050 additional restrictions of @code{union}, but in the corpus
2051 @code{applyToConverse} is never present along with @code{union}.
2054 @subsubheading The @code{setMetaData} Element
2056 Parent: @code{setCellProperties} @*
2059 This element is not known to have any visible effect.
2061 @defvr {Required} target
2062 The @code{id} of an element whose metadata is to be set. In the
2063 corpus, this is always @code{graph}, the @code{id} used for the
2064 @code{graph} element.
2067 @defvr {Required} key
2068 @defvrx {Required} value
2069 A key-value pair to set for the target.
2071 In the corpus, @code{key} is @code{cellPropId} or, rarely,
2072 @code{diagProps}, and @code{value} is always the @code{id} of the
2073 parent @code{setCellProperties}.
2076 @subsubheading The @code{setStyle} Element
2078 Parent: @code{setCellProperties} @*
2081 This element associates a style with the target.
2083 @defvr {Required} target
2084 The @code{id} of an element whose style is to be set. In the corpus,
2085 this is always the @code{id} of an @code{interval}, @code{labeling},
2086 or, rarely, @code{graph} element.
2089 @defvr {Required} style
2090 The @code{id} of a @code{style} element that identifies the style to
2094 @subsubheading The @code{setFormat} Element
2097 Parent: @code{setCellProperties}
2100 @math{|} @code{numberFormat}
2101 @math{|} @code{stringFormat}@math{+}
2102 @math{|} @code{dateTimeFormat}
2105 This element sets the format of the target, ``format'' in this case
2106 meaning the SPSS print format for a variable.
2108 The details of this element vary depending on the schema version, as
2109 declared in the root @code{visualization} element's @code{version}
2110 attribute (@pxref{SPV Detail visualization Element}). In version 2.5
2111 and earlier, @code{setFormat} contains one of a number of child
2112 elements that correspond to the different varieties of print formats.
2113 In version 2.7 and later, @code{setFormat} instead always contains a
2114 @code{format} element.
2116 XXX reinvestigate the above claim about versions: it appears to be
2119 The @code{setFormat} element itself has the following attributes.
2121 @defvr {Required} target
2122 The @code{id} of an element whose style is to be set. In the corpus,
2123 this is always the @code{id} of an @code{majorTicks} or
2124 @code{labeling} element.
2127 @defvr {Optional} reset
2128 If this is @code{true}, this format overrides the target's previous
2129 format. If it is @code{false}, the adds to the previous format. In
2130 the corpus this is always @code{true}. The default behavior is
2135 * SPV Detail format Element::
2136 * SPV Detail numberFormat Element::
2137 * SPV Detail stringFormat Element::
2138 * SPV Detail dateTimeFormat Element::
2139 * SPV Detail affix Element::
2140 * SPV Detail relabel Element::
2141 * SPV Detail union Element::
2144 @node SPV Detail format Element
2145 @subsubsection The @code{format} Element
2147 Parent: @code{sourceVariable}, @code{derivedVariable}, @code{formatMapping}, @code{labeling}, @code{formatMapping}, @code{setFormat} @*
2148 Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
2150 This element appears only in schema version 2.7 (@pxref{SPV Detail
2151 visualization Element}).
2153 This element determines a format, equivalent to an SPSS print format.
2155 @subsubheading Attributes for All Formats
2157 These attributes apply to all kinds of formats. The most important of
2158 these attributes determines the high-level kind of formatting in use:
2160 @defvr {Optional} baseFormat
2161 Either @code{dateTime} or @code{elapsedTime}. When this attribute is
2162 omitted, this element is a numeric or string format.
2166 Whether, in the corpus, other attributes are always present (``yes''),
2167 never present (``no''), or sometimes present (``opt'') depends on
2170 @multitable {maximumFractionDigits} {@code{dateTime}} {@code{elapsedTime}} {number} {string}
2171 @headitem Attribute @tab @code{dateTime} @tab @code{elapsedTime} @tab number @tab string
2172 @item errorCharacter @tab yes @tab yes @tab yes @tab opt
2174 @item separatorChars @tab yes @tab no @tab no @tab no
2176 @item mdyOrder @tab yes @tab no @tab no @tab no
2178 @item showYear @tab yes @tab no @tab no @tab no
2179 @item yearAbbreviation @tab yes @tab no @tab no @tab no
2181 @item showMonth @tab yes @tab no @tab no @tab no
2182 @item monthFormat @tab yes @tab no @tab no @tab no
2184 @item showDay @tab yes @tab opt @tab no @tab no
2185 @item dayPadding @tab yes @tab opt @tab no @tab no
2186 @item dayOfMonthPadding @tab yes @tab no @tab no @tab no
2187 @item dayType @tab yes @tab no @tab no @tab no
2189 @item showHour @tab yes @tab opt @tab no @tab no
2190 @item hourFormat @tab yes @tab opt @tab no @tab no
2191 @item hourPadding @tab yes @tab yes @tab no @tab no
2193 @item showMinute @tab yes @tab yes @tab no @tab no
2194 @item minutePadding @tab yes @tab yes @tab no @tab no
2196 @item showSecond @tab yes @tab yes @tab no @tab no
2197 @item secondPadding @tab no @tab yes @tab no @tab no
2199 @item showMillis @tab no @tab yes @tab no @tab no
2201 @item minimumIntegerDigits @tab no @tab no @tab yes @tab no
2202 @item maximumFractionDigits @tab no @tab yes @tab yes @tab no
2203 @item minimumFractionDigits @tab no @tab yes @tab yes @tab no
2204 @item useGrouping @tab no @tab opt @tab yes @tab no
2205 @item scientific @tab no @tab no @tab yes @tab no
2206 @item small @tab no @tab no @tab opt @tab no
2207 @item suffix @tab no @tab no @tab opt @tab no
2209 @item tryStringsAsNumbers @tab no @tab no @tab no @tab yes
2213 @defvr {Attribute} errorCharacter
2214 A character that replaces the formatted value when it cannot otherwise
2215 be represented in the given format. Always @samp{*}.
2218 @subsubheading Date and Time Attributes
2220 These attributes are used with @code{dateTime} and @code{elapsedTime}
2223 @defvr {Attribute} separatorChars
2224 Exactly four characters. In order, these are used for: decimal point,
2225 grouping, date separator, time separator. Always @samp{.,-:}.
2228 @defvr {Attribute} mdyOrder
2229 Within a date, the order of the days, months, and years.
2230 @code{dayMonthYear} is the only observed value, but one would expect
2231 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
2235 @defvr {Attribute} showYear
2236 @defvrx {Attribute} yearAbbreviation
2237 Whether to include the year and, if so, whether the year should be
2238 shown abbreviated, that is, with only 2 digits. Each is @code{true}
2239 or @code{false}; only values of @code{true} and @code{false},
2240 respectively, have been observed.
2243 @defvr {Attribute} showMonth
2244 @defvrx {Attribute} monthFormat
2245 Whether to include the month (@code{true} or @code{false}) and, if so,
2246 how to format it. @code{monthFormat} is one of the following:
2250 The full name of the month, e.g.@: in an English locale,
2254 The abbreviated name of the month, e.g.@: in an English locale,
2258 The number representing the month, e.g.@: 9 for September.
2261 A two-digit number representing the month, e.g.@: 09 for September.
2264 Only values of @code{true} and @code{short}, respectively, have been
2268 @defvr {Attribute} dayPadding
2269 @defvrx {Attribute} dayOfMonthPadding
2270 @defvrx {Attribute} hourPadding
2271 @defvrx {Attribute} minutePadding
2272 @defvrx {Attribute} secondPadding
2273 These attributes presumably control whether each field in the output
2274 is padded with spaces to its maximum width, but the details are not
2275 understood. The only observed value for any of these attributes is
2279 @defvr {Attribute} showDay
2280 @defvrx {Attribute} showHour
2281 @defvrx {Attribute} showMinute
2282 @defvrx {Attribute} showSecond
2283 @defvrx {Attribute} showMillis
2284 These attributes presumably control whether each field is displayed
2285 in the output, but the details are not understood. The only
2286 observed value for any of these attributes is @code{true}.
2289 @defvr {Attribute} dayType
2290 This attribute is always @code{month} in the corpus, specifying that
2291 the day of the month is to be displayed; a value of @code{year} is
2292 supposed to indicate that the day of the year, where 1 is January 1,
2293 is to be displayed instead.
2296 @defvr {Attribute} hourFormat
2297 @code{hourFormat}, if present, is one of:
2301 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
2305 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
2307 This is the only value observed in the corpus.
2310 The time is displayed in a 12-hour format, without distinguishing
2311 morning or evening, e.g.@: @code{10;15}.
2314 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
2315 which is confusing since a time duration does not have a concept of AM
2316 or PM. This might indicate a bug in the code that generated the XML
2317 in the corpus, or it might indicate that @code{elapsedTime} is
2318 sometimes used to format a time of day.
2321 @subsubheading Numeric Attributes
2323 These attributes are used for formats when @code{baseFormat} is
2324 @code{number}. Attributes @code{maximumFractionDigits}, and
2325 @code{minimumFractionDigits}, and @code{useGrouping} are also used
2326 when @code{baseFormat} is @code{elapsedTime}.
2328 @defvr {Attribute} minimumIntegerDigits
2329 Minimum number of digits to display before the decimal point. Always
2330 observed as @code{0}.
2333 @defvr {Attribute} maximumFractionDigits
2334 @defvrx {Attribute} maximumFractionDigits
2335 Maximum or minimum, respectively, number of digits to display after
2336 the decimal point. The observed values of each attribute range from 0
2340 @defvr {Attribute} useGrouping
2341 Whether to use the grouping character to group digits in large
2342 numbers. It would make sense for the grouping character to come from
2343 the @code{separatorChars} attribute, but that attribute is only
2344 present when @code{baseFormat} is @code{dateTime} or
2345 @code{elapsedTime}, in the corpus at least. Perhaps that is because
2346 this attribute has only been observed as @code{false}.
2349 @defvr {Attribute} scientific
2350 This attribute controls when and whether the number is formatted in
2351 scientific notation. It takes the following values:
2355 Use scientific notation only when the number's magnitude is smaller
2356 than the value of the @code{small} attribute.
2359 Use scientific notation when the number will not otherwise fit in the
2363 Always use scientific notation. Not observed in the corpus.
2366 Never use scientific notation. A number that won't otherwise fit will
2367 be replaced by an error indication (see the @code{errorCharacter}
2368 attribute). Not observed in the corpus.
2372 @defvr {Optional} small
2373 Only present when the @code{scientific} attribute is
2374 @code{onlyForSmall}, this is a numeric magnitude below which the
2375 number will be formatted in scientific notation. The values @code{0}
2376 and @code{0.0001} have been observed. The value @code{0} seems like a
2377 pathological choice, since no real number has a magnitude less than 0;
2378 perhaps in practice such a choice is equivalent to setting
2379 @code{scientific} to @code{false}.
2382 @defvr {Optional} prefix
2383 @defvrx {Optional} suffix
2384 Specifies a prefix or a suffix to apply to the formatted number. Only
2385 @code{suffix} has been observed, with value @samp{%}.
2388 @subsubheading String Attributes
2390 These attributes are used for formats when @code{baseFormat} is
2393 @defvr {Attribute} tryStringsAsNumbers
2394 When this is @code{true}, it is supposed to indicate that string
2395 values should be parsed as numbers and then displayed according to
2396 numeric formatting rules. However, in the corpus it is always
2400 @node SPV Detail numberFormat Element
2401 @subsubsection The @code{numberFormat} Element
2403 Parent: @code{setFormat} @*
2404 Contents: @code{affix}@math{+}
2406 This element appears only in schema version 2.5 and earlier
2407 (@pxref{SPV Detail visualization Element}). Possibly this element
2408 could also contain @code{relabel} elements in a more diverse corpus.
2410 This element has the following attributes.
2412 @defvr {Attribute} maximumFractionDigits
2413 @defvrx {Attribute} minimumFractionDigits
2414 @defvrx {Attribute} minimumIntegerDigits
2415 @defvrx {Optional} scientific
2416 @defvrx {Optional} small
2417 @defvrx {Optional} suffix
2418 @defvrx {Optional} useGroupging
2419 The syntax and meaning of these attributes is the same as on the
2420 @code{format} element for a numeric format. @pxref{SPV Detail format
2424 @node SPV Detail stringFormat Element
2425 @subsubsection The @code{stringFormat} Element
2427 Parent: @code{setFormat} @*
2428 Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
2430 This element appears only in schema version 2.5 and earlier
2431 (@pxref{SPV Detail visualization Element}).
2433 This element has no attributes.
2435 @node SPV Detail dateTimeFormat Element
2436 @subsubsection The @code{dateTimeFormat} Element
2438 Parent: @code{setFormat} @*
2441 This element appears only in schema version 2.5 and earlier
2442 (@pxref{SPV Detail visualization Element}). Possibly this element
2443 could also contain @code{affix} and @code{relabel} elements in a more
2446 The following attribute is required.
2448 @defvr {Attribute} baseFormat
2449 Either @code{dateTime} or @code{time}.
2452 When @code{baseFormat} is @code{dateTime}, the following attributes
2455 @defvr {Attribute} dayOfMonthPadding
2456 @defvrx {Attribute} dayPadding
2457 @defvrx {Attribute} dayType
2458 @defvrx {Attribute} hourFormat
2459 @defvrx {Attribute} hourPadding
2460 @defvrx {Attribute} mdyOrder
2461 @defvrx {Attribute} minutePadding
2462 @defvrx {Attribute} monthFormat
2463 @defvrx {Attribute} separatorChars
2464 @defvrx {Attribute} showDay
2465 @defvrx {Attribute} showHour
2466 @defvrx {Attribute} showMinute
2467 @defvrx {Attribute} showMonth
2468 @defvrx {Attribute} showSecond
2469 @defvrx {Attribute} showYear
2470 @defvrx {Attribute} yearAbbreviation
2471 The syntax and meaning of these attributes is the same as on the
2472 @code{format} element when that element's @code{baseFormat} is
2473 @code{dateTime}. @pxref{SPV Detail format Element}.
2476 When @code{baseFormat} is @code{time}, the following attributes are
2479 @defvr {Attribute} hourFormat
2480 @defvrx {Attribute} hourPadding
2481 @defvrx {Attribute} minutePadding
2482 @defvrx {Attribute} monthFormat
2483 @defvrx {Attribute} separatorChars
2484 @defvrx {Attribute} showDay
2485 @defvrx {Attribute} showHour
2486 @defvrx {Attribute} showMinute
2487 @defvrx {Attribute} showMonth
2488 @defvrx {Attribute} showSecond
2489 @defvrx {Attribute} showYear
2490 @defvrx {Attribute} yearAbbreviation
2491 The syntax and meaning of these attributes is the same as on the
2492 @code{format} element when that element's @code{baseFormat} is
2493 @code{elapsedTime}. @pxref{SPV Detail format Element}.
2496 @node SPV Detail affix Element
2497 @subsubsection The @code{affix} Element
2499 Parent: @code{format} or @code{numberFormat} or @code{stringFormat} @*
2502 Possibly this element could have @code{dateTimeFormat} as a parent in
2503 a more diverse corpus.
2505 This defines a suffix (or, theoretically, a prefix) for a formatted
2506 value. It is used to insert a reference to a footnote. It has the
2507 following attributes:
2509 @defvr {Attribute} definesReference
2510 This specifies the footnote number as a natural number: 1 for the
2511 first footnote, 2 for the second, and so on.
2514 @defvr {Attribute} position
2515 Position for the footnote label. Always @code{superscript}.
2518 @defvr {Attribute} suffix
2519 Whether the affix is a suffix (@code{true}) or a prefix
2520 (@code{false}). Always @code{true}.
2523 @defvr {Attribute} value
2524 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
2525 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
2526 contains other values: @code{*}, @code{**}, and a few that begin with
2527 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
2530 @node SPV Detail relabel Element
2531 @subsubsection The @code{relabel} Element
2533 Parent: @code{format} or @code{stringFormat} @*
2536 Possibly this element could have @code{numberFormat} or
2537 @code{dateTimeFormat} as a parent in a more diverse corpus.
2539 This specifies how to display a given value. It is used to implement
2540 value labels and to display the system-missing value in a
2541 human-readable way. It has the following attributes:
2543 @defvr {Attribute} from
2544 The value to map. In the corpus this is an integer or the
2545 system-missing value @code{-1.797693134862316E300}.
2548 @defvr {Attribute} to
2549 The string to display in place of the value of @code{from}. In the
2550 corpus this is a wide variety of value labels; the system-missing
2551 value is mapped to @samp{.}.
2554 @node SPV Detail union Element
2555 @subsubsection The @code{union} Element
2557 Parent: @code{setCellProperties} @*
2558 Contents: @code{intersect}@math{+}
2560 This element represents a set of cells, computed as the union of the
2561 sets represented by each of its children.
2563 @subsubheading The @code{intersect} Element
2565 Parent: @code{union} @*
2566 Contents: @code{where}@math{+} @math{|} @code{intersectWhere}?
2568 This element represents a set of cells, computed as the intersection
2569 of the sets represented by each of its children.
2571 Of the two possible children, in the corpus @code{where} is far more
2572 common, appearing thousands of times, whereas @code{intersectWhere}
2573 only appears 4 times.
2575 Most @code{intersect} elements have two or more children.
2577 @subsubheading The @code{where} Element
2579 Parent: @code{intersect} @*
2582 This element represents the set of cells in which the value of a
2583 specified variable falls within a specified set.
2585 @defvr {Attribute} variable
2586 The @code{id} of a variable, e.g.@: @code{dimension0categories} or
2587 @code{dimension0group0map}.
2590 @defvr {Attribute} include
2591 A value, or multiple values separated by semicolons,
2592 e.g.@: @code{0} or @code{13;14;15;16}.
2595 @subsubheading The @code{intersectWhere}
2597 Parent: @code{intersect} @*
2600 The meaning of this element is unknown.
2602 @defvr {Attribute} variable
2603 @defvrx {Attribute} variable2
2604 The meaning of these attributes is unknown. In the four examples in
2605 the corpus they always take the values @code{dimension2categories} and
2606 @code{dimension0categories}, respectively.