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 A bytes with a fixed value, written as a pair of hexadecimal digits.
493 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
494 @itemx b0, b1, @dots{}, b9, b10, b11, @dots{}
495 A 32-bit integer in little-endian or big-endian byte order,
496 respectively, with a fixed value, written in decimal, prefixed by
503 A byte with value 0 or 1.
507 A 16-bit integer in little-endian or big-endian byte order,
512 A 32-bit integer in little-endian or big-endian byte order,
517 A 64-bit integer in little-endian or big-endian byte order,
521 A 64-bit IEEE floating-point number.
524 A 32-bit IEEE floating-point number.
528 A 32-bit integer, in little-endian or big-endian byte order,
529 respectively, followed by the specified number of bytes of character
530 data. (The encoding is indicated by the Formats nonterminal.)
533 @var{x} is optional, e.g.@: 00? is an optional zero byte.
535 @item @var{x}*@var{n}
536 @var{x} is repeated @var{n} times, e.g. byte*10 for ten arbitrary bytes.
538 @item @var{x}[@var{name}]
539 Gives @var{x} the specified @var{name}. Names are used in textual
540 explanations. They are also used, also bracketed, to indicate counts,
541 e.g.@: int[@t{n}] byte*[@t{n}] for a 32-bit integer followed by the
542 specified number of arbitrary bytes.
544 @item @var{a} @math{|} @var{b}
545 Either @var{a} or @var{b}.
548 Parentheses are used for grouping to make precedence clear, especially
549 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
553 A 32-bit integer that indicates the number of bytes in @var{x},
554 followed by @var{x} itself.
557 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
558 (The @file{.bin} header indicates the version.)
561 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
564 Little-endian byte order is far more common in this format, but a few
565 pieces of the format use big-endian byte order.
567 A ``light'' detail member @file{.bin} consists of a number of sections
568 concatenated together, terminated by a byte 01:
572 LightMember @result{}
575 Fonts Borders PrintSettings TableSettings Formats
581 The following sections go into more detail.
584 * SPV Light Member Header::
585 * SPV Light Member Title::
586 * SPV Light Member Caption::
587 * SPV Light Member Footnotes::
588 * SPV Light Member Fonts::
589 * SPV Light Member Borders::
590 * SPV Light Member Print Settings::
591 * SPV Light Member Table Settings::
592 * SPV Light Member Formats::
593 * SPV Light Member Dimensions::
594 * SPV Light Member Categories::
595 * SPV Light Member Data::
596 * SPV Light Member Value::
597 * SPV Light Member ValueMod::
600 @node SPV Light Member Header
603 An SPV light member begins with a 39-byte header:
609 (i1 @math{|} i3)[@t{version}]
611 bool[@t{show-numeric-markers}]
612 bool[@t{rotate-inner-column-labels}]
613 bool[@t{rotate-outer-row-labels}]
616 int[@t{min-column-width}] int[@t{max-column-width}]
617 int[@t{min-row-width}] int[@t{max-row-width}]
622 @code{version} is a version number that affects the interpretation of
623 some of the other data in the member. We will refer to ``version 1''
624 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
625 version-specific formatting (as described previously).
627 If @code{show-numeric-markers} is 1, footnote markers are shown as
628 numbers, starting from 1; otherwise, they are shown as letters,
629 starting from @samp{a}.
631 If @code{rotate-inner-column-labels} is 1, then column labels closest
632 to the data are rotated to be vertical; otherwise, they are shown
635 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
636 the data are rotated to be vertical; otherwise, they are shown in the
639 @code{table-id} is a binary version of the @code{tableId} attribute in
640 the structure member that refers to the detail member. For example,
641 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
642 would be 0xc6c99d183b300001.
644 @code{min-column-width} is the minimum width that a column will be
645 assigned automatically. @code{max-column-width} is the maximum width
646 that a column will be assigned to accommodate a long column label.
647 @code{min-row-width} and @code{max-row-width} are a similar range for
648 the width of row labels. All of these measurements are in 1/96 inch
651 The meaning of the other variable parts of the header is not known.
653 @node SPV Light Member Title
659 Value[@t{title1}] 01?
661 Value[@t{title2}] 01?
665 The Title, which follows the Header, specifies the pivot table's title
666 twice, as @code{title1} and @code{title2}. In the corpus, they are
669 Whereas the Value in @code{title1} and in @code{title2} are
670 appropriate for presentation, and localized to the user's language,
671 @code{c} is in English, sometimes less specific, and sometimes less
672 well formatted. For example, for a frequency table, @code{title1} and
673 @code{title2} name the variable and @code{c} is simply ``Frequencies''.
675 @node SPV Light Member Caption
680 Caption @result{} Caption1 Caption2
681 Caption1 @result{} 31 Value @math{|} 58
682 Caption2 @result{} 31 Value @math{|} 58
686 The Caption, if present, is shown below the table. Caption2 is
687 normally present. Caption1 is only rarely nonempty; it might reflect
688 user editing of the caption.
690 @node SPV Light Member Footnotes
691 @subsection Footnotes
695 Footnotes @result{} int[@t{n}] Footnote*[@t{n}]
696 Footnote @result{} Value[@t{text}] (58 @math{|} 31 Value[@t{marker}]) byte*4
700 Each footnote has @code{text} and an optional customer @code{marker}
703 @node SPV Light Member Fonts
708 Fonts @result{} 00 Font*8
711 string[@t{typeface}] float[@t{size}] int[@t{style}] bool[@t{underline}]
712 int[@t{halign}] int[@t{valign}]
713 string[@t{fgcolor}] string[@t{bgcolor}]
714 byte[@t{alternate}] string[@t{altfg}] string[@t{altbg}]
715 v3(int[@t{left-margin}] int[@t{right-margin}] int[@t{top-margin}] int[@t{bottom-margin}])
719 Each Font represents the font style for a different element, in the
720 following order: title, caption, footer, corner, column
721 labels, row labels, data, and layers.
723 @code{index} is the 1-based index of the Font, i.e. 1 for the first
724 Font, through 8 for the final Font.
726 @code{typeface} is the string name of the font. In the corpus, this
727 is @code{SansSerif} in over 99% of instances and @code{Times New
730 @code{size} is the size of the font, in points. The most common size
731 in the corpus is 12 points.
733 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
734 1 (with value 2) is set for italic.
736 @code{underline} is 1 if the font is underlined, 0 otherwise.
738 @code{halign} specifies horizontal alignment: 0 for center, 2 for
739 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
740 alignment varies according to type: string data is left-justified,
741 numbers and most other formats are right-justified.
743 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
746 @code{fgcolor} and @code{bgcolor} are the foreground color and
747 background color, respectively. In the corpus, these are always
748 @code{#000000} and @code{#ffffff}, respectively.
750 @code{alternate} is 01 if rows should alternate colors, 00 if all rows
751 should be the same color. When @code{alternate} is 01, @code{altfg}
752 and @code{altbg} specify the colors for the alternate rows.
754 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
755 @code{bottom-margin} are measured in multiples of 1/96 inch.
757 @node SPV Light Member Borders
764 be32[@t{n-borders}] Border*[@t{n-borders}]
765 bool[@t{show-grid-lines}]
769 be32[@t{border-type}]
770 be32[@t{stroke-type}]
775 The Borders reflect how borders between regions are drawn.
777 The fixed value of @code{endian} can be used to validate the
780 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
782 Each Border describes one kind of border. @code{n-borders} seems to
783 always be 19. Each @code{border-type} appears once (although in an
784 unpredictable order) and correspond to the following borders:
790 Left, top, right, and bottom outer frame.
792 Left, top, right, and bottom inner frame.
794 Left and top of data area.
796 Horizontal and vertical dimension rows.
798 Horizontal and vertical dimension columns.
800 Horizontal and vertical category rows.
802 Horizontal and vertical category columns.
805 @code{stroke-type} describes how a border is drawn, as one of:
822 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
823 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
824 opaque color, therefore opaque black is 0xff000000.
826 @node SPV Light Member Print Settings
827 @subsection Print Settings
831 PrintSettings @result{}
834 bool[@t{paginate-layers}]
837 bool[@t{top-continuation}]
838 bool[@t{bottom-continuation}]
839 be32[@t{n-orphan-lines}]
840 bestring[@t{continuation-string}]
844 The PrintSettings reflect settings for printing. The fixed value of
845 @code{endian} can be used to validate the endianness.
847 @code{all-layers} is 1 to print all layers, 0 to print only the
850 @code{paginate-layers} is 1 to print each layer at the start of a new
851 page, 0 otherwise. (This setting is honored only @code{all-layers} is
852 1, since otherwise only one layer is printed.)
854 @code{fit-width} and @code{fit-length} control whether the table is
855 shrunk to fit within a page's width or length, respectively.
857 @code{n-orphan-lines} is the minimum number of rows or columns to put
858 in one part of a table that is broken across pages.
860 If @code{top-continuation} is 1, then @code{continuation-string} is
861 printed at the top of a page when a table is broken across pages for
862 printing; similarly for @code{bottom-continuation} and the bottom of a
863 page. Usually, @code{continuation-string} is empty.
865 @node SPV Light Member Table Settings
866 @subsection Table Settings
870 TableSettings @result{}
873 be32[@t{current-layer}]
875 bool[@t{show-row-labels-in-corner}]
876 bool[@t{show-alphabetic-markers}]
877 bool[@t{footnote-marker-position}]
881 Breakpoints[@t{row-breaks}] Breakpoints[@t{column-breaks}]
882 Keeps[@t{row-keeps}] Keeps[@t{column-keeps}]
883 PointKeeps[@t{row-keeps}] PointKeeps[@t{column-keeps}]
886 bestring[@t{table-look}]
890 Breakpoints @result{} be32[@t{n-breaks}] be32*[@t{n-breaks}]
892 Keeps @result{} be32[@t{n-keeps}] Keep*@t{n-keeps}
893 Keep @result{} be32[@t{offset}] be[@t{n}]
895 PointKeeps @result{} be32[@t{n-point-keeps}] PointKeep*@t{n-point-keeps}
896 PointKeep @result{} be32[@t{offset}] be32 be32
901 The TableSettings reflect display settings. The fixed value of
902 @code{endian} can be used to validate the endianness.
904 @code{current-layer} is the displayed layer.
906 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
907 any cell) are hidden; otherwise, they are shown.
909 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
910 the upper left corner; otherwise, they are shown nested.
912 If @code{show-alphabetic-markers} is 1, markers are shown as letters
913 (e.g. @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
914 shown as numbers starting from 1.
916 When @code{footnote-marker-position} is 1, footnote markers are shown
917 as superscripts, otherwise as subscripts.
919 The Breakpoints are rows or columns after which there is a page break;
920 for example, a row break of 1 requests a page break after the second
921 row. Usually no breakpoints are specified, indicating that page
922 breaks should be selected automatically.
924 The Keeps are ranges of rows or columns to be kept together without a
925 page break; for example, a row Keep with @code{offset} 1 and @code{n}
926 10 requests that the 10 rows starting with the second row be kept
927 together. Usually no Keeps are specified.
929 The PointKeeps seem to be generated automatically based on
930 user-specified Keeps. They seems to indicate a conversion from rows
931 or columns to pixel or point offsets.
933 @code{notes} is a text string that contains user-specified notes. It
934 is displayed when the user hovers the cursor over the table, like
935 ``alt text'' on a webpage. It is not printed. It is usually empty.
937 @code{table-look} is the name of a SPSS ``TableLook'' table style,
938 such as ``Default'' or ``Academic''; it is often empty.
940 TableSettings ends with an arbitrary number of null bytes.
942 @node SPV Light Member Formats
948 int[@t{n-widths}] int*[@t{n-widths}]
950 int[@t{current-layer}]
951 bool[@t{digit-grouping}] bool[@t{leading-zero}] bool
953 byte[@t{decimal}] byte[@t{grouping}]
957 v3(count(X1 count(X2)) count(X3))
961 string[@t{command}] string[@t{command-local}]
962 string[@t{language}] string[@t{charset}] string[@t{locale}]
965 byte[@t{decimal}] byte[@t{grouping}]
967 byte[@t{missing}] bool
972 byte[@t{variable-mode}]
979 int[@t{n-heights}] int*[@t{n-heights}]
980 int[@t{n-style-map}] BlankMap*[@t{n-style-map}]
981 int[@t{n-styles}] StylePair*[@t{n-styles}]
983 StyleMap @result{} int64[@t{cell-index}] int16[@t{style-index}]
985 01 00 (03 @math{|} 04) 00 00 00
986 string[@t{command}] string[@t{command-local}]
987 string[@t{language}] string[@t{charset}] string[@t{locale}]
990 byte[@t{decimal}] byte[@t{grouping}]
992 (string[@t{dataset}] string[@t{datafile}] i0 int[@t{date}] i0)?
994 byte[@t{missing}] bool (i2000000 i0)?
996 CustomCurrency @result{} int[@t{n-ccs}] string*[@t{n-ccs}]
1000 If @code{n-widths} is nonzero, then the accompanying integers are
1001 column widths as manually adjusted by the user. (Row heights are
1002 computed automatically based on the widths.)
1004 @code{encoding} is a character encoding, usually a Windows code page
1005 such as @code{en_US.windows-1252} or @code{it_IT.windows-1252}. The
1006 rest of the character strings in the member use this encoding. The
1007 encoding string is itself encoded in US-ASCII.
1009 @code{epoch} is the year that starts the epoch. A 2-digit year is
1010 interpreted as belonging to the 100 years beginning at the epoch. The
1011 default epoch year is 69 years prior to the current year; thus, in
1012 2017 this field by default contains 1948. In the corpus, @code{epoch}
1013 ranges from 1943 to 1948, plus some contain -1.
1015 @code{decimal} is the decimal point character. The observed values
1016 are @samp{.} and @samp{,}.
1018 @code{grouping} is the grouping character. Usually, it is @samp{,} if
1019 @code{decimal} is @samp{.}, and vice versa. Other observed values are
1020 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1021 indicating that digits should not be grouped).
1023 @code{command} describes the statistical procedure that generated the
1024 output, in English. It is not necessarily the literal syntax name of
1025 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1026 Tests.'' @code{command-local} is the procedure's name, translated
1027 into the output language; it is often empty and, when it is not,
1028 sometimes the same as @code{command}.
1030 @code{dataset} is the name of the dataset analyzed to produce the
1031 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1032 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}. The latter
1033 is sometimes the empty string.
1035 @code{date} is a date, as seconds since the epoch, i.e.@: since
1036 January 1, 1970. Pivot tables within an SPV files often have dates a
1037 few minutes apart, so this is probably a creation date for the tables
1038 rather than for the file.
1040 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1041 and other times they are absent. The reader can distinguish by
1042 assuming that they are present and then checking whether the
1043 presumptive @code{dataset} contains a null byte (a valid string never
1046 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
1047 following strings are CCA through CCE format strings. @xref{Custom
1048 Currency Formats,,, pspp, PSPP}. Most commonly these are all
1049 @code{-,,,} but other strings occur.
1051 @code{missing} is the character used to indicate that a cell contains
1052 a missing value. It is always observed as @samp{.}.
1054 @node SPV Light Member Dimensions
1055 @subsection Dimensions
1057 A pivot table presents multidimensional data. A Dimension identifies
1058 the categories associated with each dimension.
1062 Dimensions @result{} int[@t{n-dims}] Dimension*[@t{n-dims}]
1063 Dimension @result{} Value[@t{name}] DimProperties int[@t{n-categories}] Category*[@t{n-categories}]
1064 DimProperties @result{}
1066 (00 @math{|} 01 @math{|} 02)[@t{d2}]
1067 (i0 @math{|} i2)[@t{d3}]
1068 bool[@t{show-dim-label}]
1069 bool[@t{hide-all-labels}]
1070 01 int[@t{dim-index}]
1074 @code{name} is the name of the dimension, e.g. @code{Variables},
1075 @code{Statistics}, or a variable name.
1077 The meanings of @code{d1}, @code{d2}, and @code{d3} are unknown.
1078 @code{d1} is usually 0 but many other values have been observed.
1080 If @code{show-dim-label} is 01, the pivot table displays a label for
1081 the dimension itself. Because usually the group and category labels
1082 are enough explanation, it is usually 00.
1084 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1085 the dimension, including group and category labels. It is usually 00.
1086 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1088 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1089 0 for the first dimension, 1 for the second, and so on. Sometimes it
1090 is -1. There is no visible difference.
1092 @node SPV Light Member Categories
1093 @subsection Categories
1095 Categories are arranged in a tree. Only the leaf nodes in the tree
1096 are really categories; the others just serve as grouping constructs.
1100 Category @result{} Value[@t{name}] (Leaf @math{|} Group)
1101 Leaf @result{} 00 00 00 i2 int[@t{cat-index}] i0
1103 bool[@t{merge}] 00 01 (i0 @math{|} i2)[@t{data}]
1104 i-1 int[@t{n-subcategories}] Category*[@t{n-subcategories}]
1108 @code{name} is the name of the category (or group).
1110 A Leaf represents a leaf category. The Leaf's @code{cat-index} is a
1111 nonnegative integer less than @code{n-categories} in the Dimension in
1112 which the Category is nested (directly or indirectly). These
1113 categories represent the original order in which the categories were
1114 sorted; if the user sorted or rearranged the categories, then the
1115 order of categories in the file reflects that without changing the
1116 @code{cat-index} values.
1118 A Group is a group of nested categories. Usually a Group contains at
1119 least one Category, so that @code{n-subcategories} is positive, but a
1120 few Groups with @code{n-subcategories} 0 has been observed.
1122 If a Group's @code{merge} is 00, the most common value, then the group
1123 is really a distinct group that should be represented as such in the
1124 visual representation and user interface. If @code{merge} is 01, the
1125 categories in this group should be shown and treated as if they were
1126 direct children of the group's containing group (or if it has no
1127 parent group, then direct children of the dimension), and this group's
1128 name is irrelevant and should not be displayed. (Merged groups can be
1131 A Group's @code{data} appears to be i2 when all of the categories
1132 within a group are leaf categories that directly represent data values
1133 for a variable (e.g. in a frequency table or crosstabulation, a group
1134 of values in a variable being tabulated) and i0 otherwise.
1136 @node SPV Light Member Data
1139 The final part of an SPV light member contains the actual data.
1144 int[@t{layers}] int[@t{rows}] int[@t{columns}] int*[@t{n-dimensions}]
1145 int[@t{n-data}] Datum*[@t{n-data}]
1146 Datum @result{} int64[@t{index}] v1(00?) Value
1150 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1151 each specifies the number of dimensions displayed in layers, rows, and
1152 columns, respectively. Any of them may be zero. Their values sum to
1153 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1156 The @code{n-dimensions} integers are a permutation of the 0-based
1157 dimension numbers. The first @code{n-layers} integers specify each of
1158 the dimensions represented by layers, the next @code{n-rows} integers
1159 specify the dimensions represented by rows, and the final
1160 @code{n-columns} integers specify the dimensions represented by
1161 columns. When there is more than one dimension of a given kind, the
1162 inner dimensions are given first.
1164 The format of a Datum varies slightly from version 1 to version 3: in
1165 version 1 it allows for an extra optional 00 byte.
1167 A Datum consists of an @code{index} and a Value. Suppose there are
1168 @math{d} dimensions and dimension @math{i}, @math{0 \le i < d}, has
1169 @math{n_i} categories. Consider the datum at coordinates @math{x_i},
1170 @math{0 \le i < d}, and note that @math{0 \le x_i < n_i}. Then the
1171 index is calculated by the following algorithm:
1175 for each @math{i} from 0 to @math{d - 1}:
1176 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1179 For example, suppose there are 3 dimensions with 3, 4, and 5
1180 categories, respectively. The datum at coordinates (1, 2, 3) has
1181 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1182 Within a given dimension, the index is the @code{cat-index} in a Leaf.
1184 @node SPV Light Member Value
1187 Value is used throughout the SPV light member format. It boils down
1188 to a number or a string.
1192 Value @result{} 00? 00? 00? 00? RawValue
1194 01 ValueMod int[@t{format}] double[@t{x}]
1195 @math{|} 02 ValueMod int[@t{format}] double[@t{x}]
1196 string[@t{varname}] string[@t{vallab}] (01 @math{|} 02 @math{|} 03)
1197 @math{|} 03 string[@t{local}] ValueMod string[@t{id}] string[@t{c}] bool[@t{type}]
1198 @math{|} 04 ValueMod int[@t{format}] string[@t{vallab}] string[@t{varname}]
1199 (01 @math{|} 02 @math{|} 03) string[@t{s}]
1200 @math{|} 05 ValueMod string[@t{varname}] string[@t{varlabel}] (01 @math{|} 02 @math{|} 03)
1201 @math{|} ValueMod string[@t{format}] int[@t{n-args}] Argument*[@t{n-args}]
1204 @math{|} int[@t{x}] i0 Value*[@t{x}@math{+}1] /* @t{x} @math{>} 0 */
1208 There are several possible encodings, which one can distinguish by the
1209 first nonzero byte in the encoding.
1213 The numeric value @code{x}, intended to be presented to the user
1214 formatted according to @code{format}, which is in the format described
1215 for system files. @xref{System File Output Formats}, for details.
1216 Most commonly, @code{format} has width 40 (the maximum).
1218 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1219 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1220 not been observed.) @xref{System File Format}, for more about these
1224 Similar to @code{01}, with the additional information that @code{x} is
1225 a value of variable @code{varname} and has value label @code{vallab}.
1226 Both @code{varname} and @code{vallab} can be the empty string, the
1227 latter very commonly.
1229 The meaning of the final byte is unknown. Possibly it is connected to
1230 whether the value or the label should be displayed.
1233 A text string, in two forms: @code{c} is in English, and sometimes
1234 abbreviated or obscure, and @code{local} is localized to the user's
1235 locale. In an English-language locale, the two strings are often the
1236 same, and in the cases where they differ, @code{local} is more
1237 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1238 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1239 where P must be greater than 1.''
1241 @code{c} and @code{local} are always either both empty or both
1244 @code{id} is a brief identifying string whose form seems to resemble a
1245 programming language identifier, e.g.@: @code{cumulative_percent} or
1246 @code{factor_14}. It is not unique.
1248 @code{type} is 00 for text taken from user input, such as syntax
1249 fragment, expressions, file names, data set names, and 01 for fixed
1250 text strings such as names of procedures or statistics. In the former
1251 case, @code{id} is always the empty string; in the latter case,
1252 @code{id} is still sometimes empty.
1255 The string value @code{s}, intended to be presented to the user
1256 formatted according to @code{format}. The format for a string is not
1257 too interesting, and the corpus contains many clearly invalid formats
1258 like A16.39 or A255.127 or A134.1, so readers should probably ignore
1259 the format entirely.
1261 @code{s} is a value of variable @code{varname} and has value label
1262 @code{vallab}. @code{varname} is never empty but @code{vallab} is
1265 The meaning of the final byte is unknown.
1268 Variable @code{varname}, which is rarely observed as empty in the
1269 corpus, with variable label @code{varlabel}, which is often empty.
1271 The meaning of the final byte is unknown.
1274 (These bytes begin a ValueMod.) A format string, analogous to
1275 @code{printf}, followed by one or more Arguments, each of which has
1276 one or more values. The format string uses the following syntax:
1283 Each of these expands to the character following @samp{\\}, to escape
1284 characters that have special meaning in format strings. These are
1285 effective inside and outside the @code{[@dots{}]} syntax forms
1289 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1293 Expands to a formatted version of argument @var{i}, which must have
1294 only a single value. For example, @code{^1} expands to the first
1295 argument's @code{value}.
1297 @item [:@var{a}:]@var{i}
1298 Expands @var{a} for each of the values in @var{i}. @var{a}
1299 should contain one or more @code{^@var{j}} conversions, which are
1300 drawn from the values for argument @var{i} in order. Some examples
1305 All of the values for the first argument, concatenated.
1308 Expands to the values for the first argument, each followed by
1312 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1313 argument's first value and @var{y} is its second value. (This would
1314 be used only if the argument has two values. If there were more
1315 values, the second and third values would be directly concatenated,
1316 which would look funny.)
1319 @item [@var{a}:@var{b}:]@var{i}
1320 This extends the previous form so that the first values are expanded
1321 using @var{a} and later values are expanded using @var{b}. For an
1322 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1323 instead written as @code{%@var{j}}. Some examples from the corpus:
1327 Expands to all of the values for the first argument, separated by
1330 @item [%1 = %2:, ^1 = ^2:]1
1331 Given appropriate values for the first argument, expands to @code{X =
1335 Given appropriate values, expands to @code{1, 2, 3}.
1339 The format string is localized to the user's locale.
1342 @node SPV Light Member ValueMod
1343 @subsection ValueMod
1345 A ValueMod can specify special modifications to a Value.
1350 31 i0 (i0 @math{|} i1 string[@t{subscript}])
1351 v1(00 (i1 @math{|} i2) 00 00 int 00 00)
1352 v3(count(FormatString StylePair))
1353 @math{|} 31 int[@t{n-refs}] int16*[@t{n-refs}] Format
1356 Format @result{} 00 00 count(FormatString Style 58)
1357 FormatString @result{} count((count((i0 58)?) (58 @math{|} 31 string))?)
1364 bool[@t{bold}] bool[@t{italic}] bool[@t{underline}] bool[@t{show}]
1365 string[@t{fgcolor}] string[@t{bgcolor}]
1366 string[@t{typeface}] byte[@t{size}]
1369 int[@t{halign}] int[@t{valign}] double[@t{offset}]
1370 int16[@t{left-margin}] int16[@t{right-margin}]
1371 int16[@t{top-margin}] int16[@t{bottom-margin}]
1375 A ValueMod that begins with ``31 i0'' specifies a string to append to
1376 the main text of the Value, as a subscript. The subscript text is a
1377 brief indicator, e.g.@: @samp{a} or @samp{a,b}, with its meaning
1378 indicated by the table caption. In this usage, subscripts are similar
1379 to footnotes. One apparent difference is that a Value can only
1380 reference one footnote but a subscript can list more than one letter.
1382 A ValueMod that begins with 31 followed by a nonzero ``int'' specifies
1383 a footnote or footnotes that the Value references. Footnote markers
1384 are shown appended to the main text of the Value, as superscripts.
1386 The Format, if present, is a format string for substitutions using the
1387 syntax explained previously. It appears to be an English-language
1388 version of the localized format string in the Value in which the
1391 Style and Style2, if present, change the style for this individual
1392 Value. @code{bold}, @code{italic}, and @code{underline} control the
1393 particular style. @code{fgcolor} and @code{bgcolor} are strings, such
1394 as @code{#ffffff}. The @code{size} is a font size in units of 1/96
1397 @code{halign} is 0 for center, 2 for left, 4 for right, 6 for decimal,
1398 0xffffffad for mixed. For decimal alignment, @code{offset} is the
1399 decimal point's offset from the right side of the cell, in units of
1402 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1405 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1406 @code{bottom-margin} are in units of 1/72 inch.
1408 @node SPV Legacy Detail Member Binary Format
1409 @section Legacy Detail Member Binary Format
1411 Whereas the light binary format represents everything about a given
1412 pivot table, the legacy binary format conceptually consists of a
1413 number of named sources, each of which consists of a number of named
1414 variables, each of which is a 1-dimensional array of numbers or
1415 strings or a mix. Thus, the legacy binary member format is quite
1418 This section uses the same context-free grammar notation as in the
1419 previous section, with the following additions:
1423 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
1424 (The legacy member header indicates the version; see below.)
1427 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
1430 A legacy detail member @file{.bin} has the following overall format:
1434 LegacyBinary @result{}
1435 00 byte[@t{version}] int16[@t{n-sources}] int[@t{member-size}]
1436 Metadata*[@t{n-sources}] Data*[@t{n-sources}]
1440 @code{version} is a version number that affects the interpretation of
1441 some of the other data in the member. Versions 0xaf and 0xb0 are
1442 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
1445 A legacy member consists of @code{n-sources} data sources, each of
1446 which has Metadata and Data.
1448 @code{member-size} is the size of the legacy binary member, in bytes.
1450 The following sections go into more detail.
1453 * SPV Legacy Member Metadata::
1454 * SPV Legacy Member Data::
1457 @node SPV Legacy Member Metadata
1458 @subsection Metadata
1463 int[@t{n-data}] int[@t{n-variables}] int[@t{offset}]
1464 vAF(byte*32[@t{source-name}])
1465 vB0(byte*64[@t{source-name}] int[@t{x}])
1469 A data source has @code{n-variables} variables, each with
1470 @code{n-data} data values.
1472 @code{source-name} is a 32- or 64-byte string padded on the right with
1473 zero bytes. The names that appear in the corpus are very generic:
1474 usually @code{tableData} for pivot table data or @code{source0} for
1477 A given Metadata's @code{offset} is the offset, in bytes, from the
1478 beginning of the member to the start of the corresponding Data. This
1479 allows programs to skip to the beginning of the data for a particular
1480 source; it is also important to determine whether a source includes
1481 any string data (@pxref{SPV Legacy Member Data}).
1483 The meaning of @code{x} in version 0xb0 is unknown.
1485 @node SPV Legacy Member Data
1490 Data @result{} NumericData*[@t{n-variables}] StringData?
1491 NumericData @result{} byte*288[@t{variable-name}] double*[@t{n-data}]
1495 Data follow the Metadata in the legacy binary format, with sources in
1496 the same order. Each NumericSeries begins with a @code{variable-name}
1497 that generally indicates its role in the pivot table, e.g.@: ``cell'',
1498 ``cellFormat'', ``dimension0categories'', ``dimension0group0'',
1499 followed by the numeric data, one double per datum. A double with the
1500 maximum negative double @code{-DBL_MAX} represents the system-missing
1505 StringData @result{} i1 string[@t{source-name}] Pairs Labels
1507 Pairs @result{} int[@t{n-string-vars}] PairSeries*[@t{n-string-vars}]
1508 PairVar @result{} string[@t{pair-var-name}] int[@t{n-pairs}] Pair*[@t{n-pairs}]
1509 Pair @result{} int[@t{i}] int[@t{j}]
1511 Labels @result{} int[@t{n-labels}] Label*[@t{n-labels}]
1512 Label @result{} int[@t{frequency}] int[@t{s}]
1516 A source may include a mix of numeric and string data values. When a
1517 source includes any string data, the data values that are strings are
1518 set to SYSMIS in the NumericData, and StringData follows the
1519 NumericData. A source that contains no string data omits the
1520 StringData. To reliably determine whether a source includes
1521 StringData, the reader should check whether the offset following the
1522 NumericData is the offset of the next source, as indicated by its
1523 Metadata (or the end of the member, in the case of the last source).
1525 StringData repeats the name of the source (from Metadata).
1527 The string data overlays the numeric data. @code{n-string-vars} is
1528 the number of variables in the source that include string data. More
1529 precisely, it is the 1-based index of the last variable in the source
1530 that includes any string data; thus, it would be 4 if there are 5
1531 variables and only the fourth one includes string data.
1533 Each PairVar consists a sequence of 0 or more Pair nonterminals, each
1534 of which maps from a 0-based index within variable @code{i} to a
1535 0-based label index @code{j}, e.g.@: pair @code{i} = 2, @code{j} = 3,
1536 means that the third data value (with value SYSMIS) is to be replaced
1537 by the string of the fourth Label.
1539 The labels themselves follow the pairs. The valuable part of each
1540 label is the string @code{s}. Each label also includes a
1541 @code{frequency} that reports the number of pairs that reference it
1542 (although this is not useful).
1544 @node SPV Legacy Detail Member XML Format
1545 @section Legacy Detail Member XML Format
1547 This format is still under investigation.
1549 The design of the detail XML format is not what one would end up with
1550 for describing pivot tables. This is because it is a special case
1551 of a much more general format (``visualization XML'' or ``VizML'')
1552 that can describe a wide range of visualizations. Most of this
1553 generality is overkill for tables, and so we end up with a funny
1554 subset of a general-purpose format.
1556 The important elements of the detail XML format are:
1560 Variables. Variables in detail XML roughly correspond to the
1561 dimensions in a light detail member. There is one variable for each
1562 dimension, plus one variable for each level of labeling along an axis.
1564 The bulk of variables are defined with @code{sourceVariable} elements.
1565 The data for these variables comes from the associated
1566 @code{tableData.bin} member. Some variables are defined, with
1567 @code{derivedVariable} elements, as a constant or in terms of a
1568 mapping function from a source variable.
1571 Assignment of variables to axes. A variable can appear as columns, or
1572 rows, or layers. The @code{faceting} element and its sub-elements
1573 describe this assignment.
1576 All elements have an optional @code{id} attribute. In practice many
1577 elements are assigned @code{id} attributes that are never referenced.
1580 * SPV Detail visualization Element::
1581 * SPV Detail userSource Element::
1582 * SPV Detail sourceVariable Element::
1583 * SPV Detail derivedVariable Element::
1584 * SPV Detail extension Element::
1585 * SPV Detail graph Element::
1586 * SPV Detail location Element::
1587 * SPV Detail coordinates Element::
1588 * SPV Detail faceting Element::
1589 * SPV Detail facetLayout Element::
1590 * SPV Detail style Element::
1593 @node SPV Detail visualization Element
1594 @subsection The @code{visualization} Element
1597 Parent: Document root
1601 (sourceVariable @math{|} derivedVariable)@math{+}
1609 This element has the following attributes.
1611 @defvr {Required} creator
1612 The version of the software that created this SPV file, as a string of
1613 the form @code{xxyyzz}, which represents software version xx.yy.zz,
1614 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
1615 versions 16 through 19.
1618 @defvr {Required} date
1619 The date on the which the file was created, as a string of the form
1623 @defvr {Required} lang
1624 The locale used for output, in Windows format, which is similar to the
1625 format used in Unix with the underscore replaced by a hyphen, e.g.@:
1626 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
1629 @defvr {Required} name
1630 The title of the pivot table, localized to the output language.
1633 @defvr {Required} style
1634 The @code{id} of a @code{style} element (@pxref{SPV Detail style
1635 Element}). This is the base style for the entire pivot table. In
1636 every example in the corpus, the value is @code{visualizationStyle}
1637 and the corresponding @code{style} element has no attributes other
1641 @defvr {Required} type
1642 A floating-point number. The meaning is unknown.
1645 @defvr {Required} version
1646 The visualization schema version number. In the corpus, the value is
1647 one of 2.4, 2.5, 2.7, and 2.8.
1650 @node SPV Detail userSource Element
1651 @subsection The @code{userSource} Element
1653 Parent: @code{visualization} @*
1656 This element has the following attributes.
1658 @defvr {Optional} missing
1659 Always @code{listwise}.
1662 @node SPV Detail sourceVariable Element
1663 @subsection The @code{sourceVariable} Element
1665 Parent: @code{visualization} @*
1666 Contents: @code{extension}* (@code{format} @math{|} @code{stringFormat})?
1668 This element defines a variable whose values can be used elsewhere in
1669 the visualization. It ties this element's @code{id} to a variable
1670 from the @file{tableData.bin} member that corresponds to this
1673 This element has the following attributes.
1675 @defvr {Required} categorical
1676 Always set to @code{true}.
1679 @defvr {Required} source
1680 Always set to @code{tableData}, the @code{source-name} in the
1681 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
1685 @defvr {Required} sourceName
1686 The name of a variable within the source, the @code{variable-name} in
1687 the corresponding @file{tableData.bin} member (@pxref{SPV Legacy
1691 @defvr {Optional} dependsOn
1692 The @code{variable-name} of a variable linked to this one, so that a
1693 viewer can work with them together. For a group variable, this is the
1694 name of the corresponding categorical variable.
1697 @defvr {Optional} label
1698 The variable label, if any
1701 @defvr {Optional} labelVariable
1702 The @code{variable-name} of a variable whose string values correspond
1703 one-to-one with the values of this variable and are suitable for use
1707 @node SPV Detail derivedVariable Element
1708 @subsection The @code{derivedVariable} Element
1710 Parent: @code{visualization} @*
1711 Contents: @code{extension}* (@code{format} @math{|} @code{stringFormat} @code{valueMapEntry}*)
1713 Like @code{sourceVariable}, this element defines a variable whose
1714 values can be used elsewhere in the visualization. Instead of being
1715 read from a data source, the variable's data are defined by a
1716 mathematical expression.
1718 This element has the following attributes.
1720 @defvr {Required} categorical
1721 Always set to @code{true}.
1724 @defvr {Required} value
1725 An expression that defines the variable's value. In theory this could
1726 be an arbitrary expression in terms of constants, functions, and other
1727 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
1728 the corpus contains only the following forms of expressions:
1731 @item constant(@var{number})
1732 @itemx constant(@var{variable})
1733 A constant. The meaning when a variable is named is unknown.
1734 Sometimes the ``variable name'' has spaces in it.
1736 @item map(@var{variable})
1737 Transforms the values in the named @var{variable} using the
1738 @code{valueMapEntry}s contained within the element.
1742 @defvr {Optional} dependsOn
1743 The @code{variable-name} of a variable linked to this one, so that a
1744 viewer can work with them together. For a group variable, this is the
1745 name of the corresponding categorical variable.
1749 * SPV Detail valueMapEntry Element::
1752 @node SPV Detail valueMapEntry Element
1753 @subsubsection The @code{valueMapEntry} Element
1755 Parent: @code{derivedVariable} @*
1758 A @code{valueMapEntry} element defines a mapping from one or more
1759 values of a source expression to a target value. (In the corpus, the
1760 source expression is always just the name of a variable.) Each target
1761 value requires a separate @code{valueMapEntry}. If multiple source
1762 values map to the same target value, they can be combined or separate.
1764 @code{valueMapEntry} has the following attributes.
1766 @defvr {Required} from
1767 A source value, or multiple source values separated by semicolons,
1768 e.g.@: @code{0} or @code{13;14;15;16}.
1771 @defvr {Required} to
1775 @node SPV Detail extension Element
1776 @subsection The @code{extension} Element
1778 This is a general-purpose ``extension'' element. Readers that don't
1779 understand a given extension should be able to safely ignore it. The
1780 attributes on this element, and their meanings, vary based on the
1781 context. Each known usage is described separately below. The current
1782 extensions use attributes exclusively, without any nested elements.
1784 @subsubheading @code{visualization} Parent Element
1786 With @code{visualization} as its parent element, @code{extension} has
1787 the following attributes.
1789 @defvr {Optional} numRows
1790 An integer that presumably defines the number of rows in the displayed
1794 @defvr {Optional} showGridline
1795 Always set to @code{false} in the corpus.
1798 @defvr {Optional} minWidthSet
1799 @defvrx {Optional} maxWidthSet
1800 Always set to @code{true} in the corpus.
1803 @subsubheading @code{container} Parent Element
1805 With @code{container} as its parent element, @code{extension} has the
1806 following attributes.
1808 @defvr {Required} combinedFootnotes
1809 Always set to @code{true} in the corpus.
1812 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
1814 With @code{sourceVariable} or @code{derivedVariable} as its parent
1815 element, @code{extension} has the following attributes. A given
1816 parent element often contains several @code{extension} elements that
1817 specify the meaning of the source data's variables or sources, e.g.@:
1820 <extension from="0" helpId="corrected_model"/>
1821 <extension from="3" helpId="error"/>
1822 <extension from="4" helpId="total_9"/>
1823 <extension from="5" helpId="corrected_total"/>
1826 @defvr {Required} from
1827 An integer or a name like ``dimension0''.
1830 @defvr {Required} helpId
1834 @node SPV Detail graph Element
1835 @subsection The @code{graph} Element
1837 Parent: @code{visualization} @*
1838 Contents: @code{location}@math{+} @code{coordinates} @code{faceting} @code{facetLayout} @code{interval}
1840 @code{graph} has the following attributes.
1842 @defvr {Required} cellStyle
1843 @defvrx {Required} style
1844 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
1845 Detail style Element}). The former is the default style for
1846 individual cells, the latter for the entire table.
1849 @node SPV Detail location Element
1850 @subsection The @code{location} Element
1852 Parent: @code{graph} @*
1855 Each instance of this element specifies where some part of the table
1856 frame is located. All the examples in the corpus have four instances
1857 of this element, one for each of the parts @code{height},
1858 @code{width}, @code{left}, and @code{top}. Some examples in the
1859 corpus add a fifth for part @code{bottom}, even though it is not clear
1860 how all of @code{top}, @code{bottom}, and @code{heigth} can be honored
1861 at the same time. In any case, @code{location} seems to have little
1862 importance in representing tables; a reader can safely ignore it.
1864 @defvr {Required} part
1865 One of @code{height}, @code{width}, @code{top}, @code{bottom}, or
1866 @code{left}. Presumably @code{right} is acceptable as well but the
1867 corpus contains no examples.
1870 @defvr {Required} method
1871 How the location is determined:
1875 Based on the natural size of the table. Observed only for
1876 parts @code{height} and @code{width}.
1879 Based on the location specified in @code{target}. Observed only for
1880 parts @code{top} and @code{bottom}.
1883 Using the value in @code{value}. Observed only for parts @code{top},
1884 @code{bottom}, and @code{left}.
1887 Same as the specified @code{target}. Observed only for part
1892 @defvr {Optional} min
1893 Minimum size. Only observed with value @code{100pt}. Only observed
1894 for part @code{width}.
1897 @defvr {Dependent} target
1898 Required when @code{method} is @code{attach} or @code{same}, not
1899 observed otherwise. This is the ID of an element to attach to.
1900 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
1904 @defvr {Dependent} value
1905 Required when @code{method} is @code{fixed}, not observed otherwise.
1906 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
1907 on parts @code{top} and @code{left}, and @code{100%} on part
1911 @node SPV Detail coordinates Element
1912 @subsection The @code{coordinates} Element
1914 Parent: @code{graph} @*
1917 This element is always present and always empty, with no attributes
1920 @node SPV Detail faceting Element
1921 @subsection The @code{faceting} Element
1923 Parent: @code{graph} @*
1924 Contents: @code{cross} @code{layer}*
1926 The @code{faceting} element describes the row, column, and layer
1927 structure of the table. Its @code{cross} child determines the row and
1928 column structure, and each @code{layer} child (if any) represents a
1931 @code{faceting} has no attributes (other than @code{id}).
1933 @subsubheading The @code{cross} Element
1935 Parent: @code{faceting} @*
1936 Contents: @code{nest} @code{nest}
1938 The @code{cross} element describes the row and column structure of the
1939 table. It has exactly two @code{nest} children, the first of which
1940 describes the table's rows and the second the table's columns.
1942 @code{cross} has no attributes (other than @code{id}).
1944 @subsubheading The @code{nest} Element
1946 Parent: @code{cross} @*
1947 Contents: @code{variableReference}@math{+}
1949 A given @code{nest} usually consists of one or more dimensions, each
1950 of which is represented by @code{variableReference} child elements.
1951 Minimally, a dimension has two @code{variableReference} children, one
1952 for the categories, one for the data, e.g.:
1956 <variableReference ref="dimension0categories"/>
1957 <variableReference ref="dimension0"/>
1962 Groups of categories introduce additional variable references, e.g.@:
1966 <variableReference ref="dimension0categories"/>
1967 <variableReference ref="dimension0group0"/>
1968 <variableReference ref="dimension0"/>
1973 Grouping can be hierarchical, e.g.@:
1977 <variableReference ref="dimension0categories"/>
1978 <variableReference ref="dimension0group1"/>
1979 <variableReference ref="dimension0group0"/>
1980 <variableReference ref="dimension0"/>
1985 XXX what are group maps?
1988 <nest id="nest_1973">
1989 <variableReference ref="dimension1categories"/>
1990 <variableReference ref="dimension1group1map"/>
1991 <variableReference ref="dimension1group0map"/>
1992 <variableReference ref="dimension1"/>
1995 <variableReference ref="dimension0categories"/>
1996 <variableReference ref="dimension0group0map"/>
1997 <variableReference ref="dimension0"/>
2002 A @code{nest} can contain multiple dimensions:
2006 <variableReference ref="dimension1categories"/>
2007 <variableReference ref="dimension1group0"/>
2008 <variableReference ref="dimension1"/>
2009 <variableReference ref="dimension0categories"/>
2010 <variableReference ref="dimension0"/>
2014 One @code{nest} within a given @code{cross} may have no dimensions, in
2015 which case it still has one @code{variableReference} child, which
2016 references a @code{derivedVariable} whose @code{value} attribute is
2017 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
2018 @code{row} or @code{column}, respectively, as its @code{id}.
2020 @code{nest} has no attributes (other than @code{id}).
2022 @subsubheading The @code{variableReference} Element
2024 Parent: @code{nest} @*
2027 @code{variableReference} has one attribute.
2029 @defvr {Required} ref
2030 The @code{id} of a @code{sourceVariable} or @code{derivedVariable}
2034 @subsubheading The @code{layer} Element
2036 Parent: @code{faceting} @*
2039 Each layer is represented by a pair of @code{layer} elements. The
2040 first of this pair is for a category variable, the second for the data
2044 <layer value="0" variable="dimension0categories" visible="true"/>
2045 <layer value="dimension0" variable="dimension0" visible="false"/>
2049 @code{layer} has the following attributes.
2051 @defvr {Required} variable
2052 The @code{id} of a @code{sourceVariable} or @code{derivedVariable}
2056 @defvr {Required} value
2057 The value to select. For a category variable, this is always
2058 @code{0}; for a data variable, it is the same as the @code{variable}
2062 @defvr {Optional} visible
2063 Whether the layer is visible. Generally, category layers are visible
2064 and data layers are not, but sometimes this attribute is omitted.
2067 @defvr {Optional} method
2068 When present, this is always @code{nest}.
2071 @node SPV Detail facetLayout Element
2072 @subsection The @code{facetLayout} Element
2074 Parent: @code{graph} @*
2075 Contents: @code{tableLayout} @code{facetLevel}@math{+} @code{setCellProperties}*
2077 @subsubheading The @code{tableLayout} Element
2079 Parent: @code{facetLayout} @*
2082 @defvr {Required} verticalTitlesInCorner
2083 Always set to @code{true}.
2086 @defvr {Optional} style
2087 The @code{id} of a @code{style} element.
2090 @defvr {Optional} fitCells
2091 Always set to @code{ticks}.
2094 @subsubheading The @code{facetLevel} Element
2096 Parent: @code{facetLayout} @*
2097 Contents: @code{axis}
2099 Each @code{facetLevel} describes a @code{variableReference} or
2100 @code{layer}, and a table has one @code{facetLevel} element for
2101 each such element. For example, an SPV detail member that contains
2102 four @code{variableReference} elements and two @code{layer} elements
2103 will contain six @code{facetLevel} elements.
2105 In the corpus, @code{facetLevel} elements and the elements that they
2106 describe are always in the same order. The correspondence may also be
2107 observed in two other ways. First, one may use the @code{level}
2108 attribute, described below. Second, in the corpus, a
2109 @code{facetLevel} always has an @code{id} that is the same as the
2110 @code{id} of the element it describes with @code{_facetLevel}
2111 appended. One should not formally rely on this, of course, but it is
2112 usefully indicative.
2114 @defvr {Required} level
2115 A 1-based index into the @code{variableReference} and @code{layer}
2116 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2117 describes the first @code{variableReference} in the SPV detail member,
2118 and in a member with four @code{variableReference} elements, a
2119 @code{facetLayout} with a @code{level} of 5 describes the first
2120 @code{layer} in the member.
2123 @defvr {Required} gap
2124 Always observed as @code{0pt}.
2127 @subsubheading The @code{axis} Element
2129 Parent: @code{facetLevel} @*
2130 Contents: @code{label}? @code{majorTicks}
2132 @defvr {Attribute} style
2133 The @code{id} of a @code{style} element.
2136 @subsubheading The @code{label} Element
2138 Parent: @code{axis} or @code{labelFrame} @*
2139 Contents: @code{text}@math{+} @math{|} @code{descriptionGroup}
2141 This element represents a label on some aspect of the table. For example,
2142 the table's title is a @code{label}.
2144 The contents of the label can be one or more @code{text} elements or a
2145 @code{descriptionGroup}.
2147 @defvr {Attribute} style
2148 @defvrx {Optional} textFrameStyle
2149 Each of these is the @code{id} of a @code{style} element.
2150 @code{style} is the style of the label text, @code{textFrameStyle} the
2151 style for the frame around the label.
2154 @defvr {Optional} purpose
2155 The kind of entity being labeled, one of @code{title},
2156 @code{subTitle}, @code{layer}, or @code{footnote}.
2159 @subsubheading The @code{descriptionGroup} Element
2161 Parent: @code{label} @*
2162 Contents: (@code{description} @math{|} @code{text})@math{+}
2164 A @code{descriptionGroup} concatenates one or more elements to form a
2165 label. Each element can be a @code{text} element, which contains
2166 literal text, or a @code{description} element that substitutes a value
2169 @defvr {Attribute} target
2170 The @code{id} of an element being described. In the corpus, this is
2171 always @code{faceting}.
2174 @defvr {Attribute} separator
2175 A string to separate the description of multiple groups, if the
2176 @code{target} has more than one. In the corpus, this is always a
2180 Typical contents for a @code{descriptionGroup} are a value by itself:
2182 <description name="value"/>
2184 @noindent or a variable and its value, separated by a colon:
2186 <description name="variable"/><text>:</text><description name="value"/>
2189 @subsubheading The @code{description} Element
2191 Parent: @code{descriptionGroup} @*
2194 A @code{description} is like a macro that expands to some property of
2195 the target of its parent @code{descriptionGroup}.
2197 @defvr {Attribute} name
2198 The name of the property. Only @code{variable} and @code{value}
2199 appear in the corpus.
2202 @subsubheading The @code{majorTicks} Element
2204 Parent: @code{axis} @*
2205 Contents: @code{gridline}?
2207 @defvr {Attribute} labelAngle
2208 @defvrx {Attribute} length
2209 Both always defined to @code{0}.
2212 @defvr {Attribute} style
2213 @defvrx {Attribute} tickFrameStyle
2214 Each of these is the @code{id} of a @code{style} element.
2215 @code{style} is the style of the tick labels, @code{tickFrameStyle}
2216 the style for the frames around the labels.
2219 @subsubheading The @code{gridline} Element
2221 Parent: @code{majorTicks} @*
2224 Represents ``gridlines,'' which for a table represents the lines
2225 between the rows or columns of a table (XXX?).
2227 @defvr {Attribute} style
2228 The style for the gridline.
2231 @defvr {Attribute} zOrder
2232 Observed as a number between 28 and 31. Does not seem to be
2236 @subsubheading The @code{setCellProperties} Element
2238 Parent: @code{facetLayout} @*
2239 Contents: @code{setMetaData} @code{setStyle}* @code{setFormat}@math{+} @code{union}?
2241 This element sets style properties of cells designated by the
2242 @code{target} attribute of its child elements, as further restricted
2243 by the optional @code{union} element if present. The @code{target}
2244 values often used, e.g.@: @code{graph} or @code{labeling}, actually
2245 affect every cell, so the @code{union} element is a useful
2248 @defvr {Optional} applyToConverse
2249 If present, always @code{true}. This appears to invert the meaning of
2250 the @code{target} of sub-elements: the selected cells are the ones
2251 @emph{not} designated by @code{target}. This is confusing, given the
2252 additional restrictions of @code{union}, but in the corpus
2253 @code{applyToConverse} is never present along with @code{union}.
2256 @subsubheading The @code{setMetaData} Element
2258 Parent: @code{setCellProperties} @*
2261 This element is not known to have any visible effect.
2263 @defvr {Required} target
2264 The @code{id} of an element whose metadata is to be set. In the
2265 corpus, this is always @code{graph}, the @code{id} used for the
2266 @code{graph} element.
2269 @defvr {Required} key
2270 @defvrx {Required} value
2271 A key-value pair to set for the target.
2273 In the corpus, @code{key} is @code{cellPropId} or, rarely,
2274 @code{diagProps}, and @code{value} is always the @code{id} of the
2275 parent @code{setCellProperties}.
2278 @subsubheading The @code{setStyle} Element
2280 Parent: @code{setCellProperties} @*
2283 This element associates a style with the target.
2285 @defvr {Required} target
2286 The @code{id} of an element whose style is to be set. In the corpus,
2287 this is always the @code{id} of an @code{interval}, @code{labeling},
2288 or, rarely, @code{graph} element.
2291 @defvr {Required} style
2292 The @code{id} of a @code{style} element that identifies the style to
2296 @subsubheading The @code{setFormat} Element
2299 Parent: @code{setCellProperties}
2302 @math{|} @code{numberFormat}
2303 @math{|} @code{stringFormat}@math{+}
2304 @math{|} @code{dateTimeFormat}
2307 This element sets the format of the target, ``format'' in this case
2308 meaning the SPSS print format for a variable.
2310 The details of this element vary depending on the schema version, as
2311 declared in the root @code{visualization} element's @code{version}
2312 attribute (@pxref{SPV Detail visualization Element}). In version 2.5
2313 and earlier, @code{setFormat} contains one of a number of child
2314 elements that correspond to the different varieties of print formats.
2315 In version 2.7 and later, @code{setFormat} instead always contains a
2316 @code{format} element.
2318 XXX reinvestigate the above claim about versions: it appears to be
2321 The @code{setFormat} element itself has the following attributes.
2323 @defvr {Required} target
2324 The @code{id} of an element whose style is to be set. In the corpus,
2325 this is always the @code{id} of an @code{majorTicks} or
2326 @code{labeling} element.
2329 @defvr {Optional} reset
2330 If this is @code{true}, this format overrides the target's previous
2331 format. If it is @code{false}, the adds to the previous format. In
2332 the corpus this is always @code{true}. The default behavior is
2337 * SPV Detail format Element::
2338 * SPV Detail numberFormat Element::
2339 * SPV Detail stringFormat Element::
2340 * SPV Detail dateTimeFormat Element::
2341 * SPV Detail affix Element::
2342 * SPV Detail relabel Element::
2343 * SPV Detail union Element::
2346 @node SPV Detail format Element
2347 @subsubsection The @code{format} Element
2349 Parent: @code{sourceVariable}, @code{derivedVariable}, @code{formatMapping}, @code{labeling}, @code{formatMapping}, @code{setFormat} @*
2350 Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
2352 This element appears only in schema version 2.7 (@pxref{SPV Detail
2353 visualization Element}).
2355 This element determines a format, equivalent to an SPSS print format.
2357 @subsubheading Attributes for All Formats
2359 These attributes apply to all kinds of formats. The most important of
2360 these attributes determines the high-level kind of formatting in use:
2362 @defvr {Optional} baseFormat
2363 Either @code{dateTime} or @code{elapsedTime}. When this attribute is
2364 omitted, this element is a numeric or string format.
2368 Whether, in the corpus, other attributes are always present (``yes''),
2369 never present (``no''), or sometimes present (``opt'') depends on
2372 @multitable {maximumFractionDigits} {@code{dateTime}} {@code{elapsedTime}} {number} {string}
2373 @headitem Attribute @tab @code{dateTime} @tab @code{elapsedTime} @tab number @tab string
2374 @item errorCharacter @tab yes @tab yes @tab yes @tab opt
2376 @item separatorChars @tab yes @tab no @tab no @tab no
2378 @item mdyOrder @tab yes @tab no @tab no @tab no
2380 @item showYear @tab yes @tab no @tab no @tab no
2381 @item yearAbbreviation @tab yes @tab no @tab no @tab no
2383 @item showMonth @tab yes @tab no @tab no @tab no
2384 @item monthFormat @tab yes @tab no @tab no @tab no
2386 @item showDay @tab yes @tab opt @tab no @tab no
2387 @item dayPadding @tab yes @tab opt @tab no @tab no
2388 @item dayOfMonthPadding @tab yes @tab no @tab no @tab no
2389 @item dayType @tab yes @tab no @tab no @tab no
2391 @item showHour @tab yes @tab opt @tab no @tab no
2392 @item hourFormat @tab yes @tab opt @tab no @tab no
2393 @item hourPadding @tab yes @tab yes @tab no @tab no
2395 @item showMinute @tab yes @tab yes @tab no @tab no
2396 @item minutePadding @tab yes @tab yes @tab no @tab no
2398 @item showSecond @tab yes @tab yes @tab no @tab no
2399 @item secondPadding @tab no @tab yes @tab no @tab no
2401 @item showMillis @tab no @tab yes @tab no @tab no
2403 @item minimumIntegerDigits @tab no @tab no @tab yes @tab no
2404 @item maximumFractionDigits @tab no @tab yes @tab yes @tab no
2405 @item minimumFractionDigits @tab no @tab yes @tab yes @tab no
2406 @item useGrouping @tab no @tab opt @tab yes @tab no
2407 @item scientific @tab no @tab no @tab yes @tab no
2408 @item small @tab no @tab no @tab opt @tab no
2409 @item suffix @tab no @tab no @tab opt @tab no
2411 @item tryStringsAsNumbers @tab no @tab no @tab no @tab yes
2415 @defvr {Attribute} errorCharacter
2416 A character that replaces the formatted value when it cannot otherwise
2417 be represented in the given format. Always @samp{*}.
2420 @subsubheading Date and Time Attributes
2422 These attributes are used with @code{dateTime} and @code{elapsedTime}
2425 @defvr {Attribute} separatorChars
2426 Exactly four characters. In order, these are used for: decimal point,
2427 grouping, date separator, time separator. Always @samp{.,-:}.
2430 @defvr {Attribute} mdyOrder
2431 Within a date, the order of the days, months, and years.
2432 @code{dayMonthYear} is the only observed value, but one would expect
2433 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
2437 @defvr {Attribute} showYear
2438 @defvrx {Attribute} yearAbbreviation
2439 Whether to include the year and, if so, whether the year should be
2440 shown abbreviated, that is, with only 2 digits. Each is @code{true}
2441 or @code{false}; only values of @code{true} and @code{false},
2442 respectively, have been observed.
2445 @defvr {Attribute} showMonth
2446 @defvrx {Attribute} monthFormat
2447 Whether to include the month (@code{true} or @code{false}) and, if so,
2448 how to format it. @code{monthFormat} is one of the following:
2452 The full name of the month, e.g.@: in an English locale,
2456 The abbreviated name of the month, e.g.@: in an English locale,
2460 The number representing the month, e.g.@: 9 for September.
2463 A two-digit number representing the month, e.g.@: 09 for September.
2466 Only values of @code{true} and @code{short}, respectively, have been
2470 @defvr {Attribute} dayPadding
2471 @defvrx {Attribute} dayOfMonthPadding
2472 @defvrx {Attribute} hourPadding
2473 @defvrx {Attribute} minutePadding
2474 @defvrx {Attribute} secondPadding
2475 These attributes presumably control whether each field in the output
2476 is padded with spaces to its maximum width, but the details are not
2477 understood. The only observed value for any of these attributes is
2481 @defvr {Attribute} showDay
2482 @defvrx {Attribute} showHour
2483 @defvrx {Attribute} showMinute
2484 @defvrx {Attribute} showSecond
2485 @defvrx {Attribute} showMillis
2486 These attributes presumably control whether each field is displayed
2487 in the output, but the details are not understood. The only
2488 observed value for any of these attributes is @code{true}.
2491 @defvr {Attribute} dayType
2492 This attribute is always @code{month} in the corpus, specifying that
2493 the day of the month is to be displayed; a value of @code{year} is
2494 supposed to indicate that the day of the year, where 1 is January 1,
2495 is to be displayed instead.
2498 @defvr {Attribute} hourFormat
2499 @code{hourFormat}, if present, is one of:
2503 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
2507 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
2509 This is the only value observed in the corpus.
2512 The time is displayed in a 12-hour format, without distinguishing
2513 morning or evening, e.g.@: @code{10;15}.
2516 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
2517 which is confusing since a time duration does not have a concept of AM
2518 or PM. This might indicate a bug in the code that generated the XML
2519 in the corpus, or it might indicate that @code{elapsedTime} is
2520 sometimes used to format a time of day.
2523 @subsubheading Numeric Attributes
2525 These attributes are used for formats when @code{baseFormat} is
2526 @code{number}. Attributes @code{maximumFractionDigits}, and
2527 @code{minimumFractionDigits}, and @code{useGrouping} are also used
2528 when @code{baseFormat} is @code{elapsedTime}.
2530 @defvr {Attribute} minimumIntegerDigits
2531 Minimum number of digits to display before the decimal point. Always
2532 observed as @code{0}.
2535 @defvr {Attribute} maximumFractionDigits
2536 @defvrx {Attribute} maximumFractionDigits
2537 Maximum or minimum, respectively, number of digits to display after
2538 the decimal point. The observed values of each attribute range from 0
2542 @defvr {Attribute} useGrouping
2543 Whether to use the grouping character to group digits in large
2544 numbers. It would make sense for the grouping character to come from
2545 the @code{separatorChars} attribute, but that attribute is only
2546 present when @code{baseFormat} is @code{dateTime} or
2547 @code{elapsedTime}, in the corpus at least. Perhaps that is because
2548 this attribute has only been observed as @code{false}.
2551 @defvr {Attribute} scientific
2552 This attribute controls when and whether the number is formatted in
2553 scientific notation. It takes the following values:
2557 Use scientific notation only when the number's magnitude is smaller
2558 than the value of the @code{small} attribute.
2561 Use scientific notation when the number will not otherwise fit in the
2565 Always use scientific notation. Not observed in the corpus.
2568 Never use scientific notation. A number that won't otherwise fit will
2569 be replaced by an error indication (see the @code{errorCharacter}
2570 attribute). Not observed in the corpus.
2574 @defvr {Optional} small
2575 Only present when the @code{scientific} attribute is
2576 @code{onlyForSmall}, this is a numeric magnitude below which the
2577 number will be formatted in scientific notation. The values @code{0}
2578 and @code{0.0001} have been observed. The value @code{0} seems like a
2579 pathological choice, since no real number has a magnitude less than 0;
2580 perhaps in practice such a choice is equivalent to setting
2581 @code{scientific} to @code{false}.
2584 @defvr {Optional} prefix
2585 @defvrx {Optional} suffix
2586 Specifies a prefix or a suffix to apply to the formatted number. Only
2587 @code{suffix} has been observed, with value @samp{%}.
2590 @subsubheading String Attributes
2592 These attributes are used for formats when @code{baseFormat} is
2595 @defvr {Attribute} tryStringsAsNumbers
2596 When this is @code{true}, it is supposed to indicate that string
2597 values should be parsed as numbers and then displayed according to
2598 numeric formatting rules. However, in the corpus it is always
2602 @node SPV Detail numberFormat Element
2603 @subsubsection The @code{numberFormat} Element
2605 Parent: @code{setFormat} @*
2606 Contents: @code{affix}@math{+}
2608 This element appears only in schema version 2.5 and earlier
2609 (@pxref{SPV Detail visualization Element}). Possibly this element
2610 could also contain @code{relabel} elements in a more diverse corpus.
2612 This element has the following attributes.
2614 @defvr {Attribute} maximumFractionDigits
2615 @defvrx {Attribute} minimumFractionDigits
2616 @defvrx {Attribute} minimumIntegerDigits
2617 @defvrx {Optional} scientific
2618 @defvrx {Optional} small
2619 @defvrx {Optional} suffix
2620 @defvrx {Optional} useGroupging
2621 The syntax and meaning of these attributes is the same as on the
2622 @code{format} element for a numeric format. @pxref{SPV Detail format
2626 @node SPV Detail stringFormat Element
2627 @subsubsection The @code{stringFormat} Element
2629 Parent: @code{setFormat} @*
2630 Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
2632 This element appears only in schema version 2.5 and earlier
2633 (@pxref{SPV Detail visualization Element}).
2635 This element has no attributes.
2637 @node SPV Detail dateTimeFormat Element
2638 @subsubsection The @code{dateTimeFormat} Element
2640 Parent: @code{setFormat} @*
2643 This element appears only in schema version 2.5 and earlier
2644 (@pxref{SPV Detail visualization Element}). Possibly this element
2645 could also contain @code{affix} and @code{relabel} elements in a more
2648 The following attribute is required.
2650 @defvr {Attribute} baseFormat
2651 Either @code{dateTime} or @code{time}.
2654 When @code{baseFormat} is @code{dateTime}, the following attributes
2657 @defvr {Attribute} dayOfMonthPadding
2658 @defvrx {Attribute} dayPadding
2659 @defvrx {Attribute} dayType
2660 @defvrx {Attribute} hourFormat
2661 @defvrx {Attribute} hourPadding
2662 @defvrx {Attribute} mdyOrder
2663 @defvrx {Attribute} minutePadding
2664 @defvrx {Attribute} monthFormat
2665 @defvrx {Attribute} separatorChars
2666 @defvrx {Attribute} showDay
2667 @defvrx {Attribute} showHour
2668 @defvrx {Attribute} showMinute
2669 @defvrx {Attribute} showMonth
2670 @defvrx {Attribute} showSecond
2671 @defvrx {Attribute} showYear
2672 @defvrx {Attribute} yearAbbreviation
2673 The syntax and meaning of these attributes is the same as on the
2674 @code{format} element when that element's @code{baseFormat} is
2675 @code{dateTime}. @pxref{SPV Detail format Element}.
2678 When @code{baseFormat} is @code{time}, the following attributes are
2681 @defvr {Attribute} hourFormat
2682 @defvrx {Attribute} hourPadding
2683 @defvrx {Attribute} minutePadding
2684 @defvrx {Attribute} monthFormat
2685 @defvrx {Attribute} separatorChars
2686 @defvrx {Attribute} showDay
2687 @defvrx {Attribute} showHour
2688 @defvrx {Attribute} showMinute
2689 @defvrx {Attribute} showMonth
2690 @defvrx {Attribute} showSecond
2691 @defvrx {Attribute} showYear
2692 @defvrx {Attribute} yearAbbreviation
2693 The syntax and meaning of these attributes is the same as on the
2694 @code{format} element when that element's @code{baseFormat} is
2695 @code{elapsedTime}. @pxref{SPV Detail format Element}.
2698 @node SPV Detail affix Element
2699 @subsubsection The @code{affix} Element
2701 Parent: @code{format} or @code{numberFormat} or @code{stringFormat} @*
2704 Possibly this element could have @code{dateTimeFormat} as a parent in
2705 a more diverse corpus.
2707 This defines a suffix (or, theoretically, a prefix) for a formatted
2708 value. It is used to insert a reference to a footnote. It has the
2709 following attributes:
2711 @defvr {Attribute} definesReference
2712 This specifies the footnote number as a natural number: 1 for the
2713 first footnote, 2 for the second, and so on.
2716 @defvr {Attribute} position
2717 Position for the footnote label. Always @code{superscript}.
2720 @defvr {Attribute} suffix
2721 Whether the affix is a suffix (@code{true}) or a prefix
2722 (@code{false}). Always @code{true}.
2725 @defvr {Attribute} value
2726 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
2727 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
2728 contains other values: @code{*}, @code{**}, and a few that begin with
2729 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
2732 @node SPV Detail relabel Element
2733 @subsubsection The @code{relabel} Element
2735 Parent: @code{format} or @code{stringFormat} @*
2738 Possibly this element could have @code{numberFormat} or
2739 @code{dateTimeFormat} as a parent in a more diverse corpus.
2741 This specifies how to display a given value. It is used to implement
2742 value labels and to display the system-missing value in a
2743 human-readable way. It has the following attributes:
2745 @defvr {Attribute} from
2746 The value to map. In the corpus this is an integer or the
2747 system-missing value @code{-1.797693134862316E300}.
2750 @defvr {Attribute} to
2751 The string to display in place of the value of @code{from}. In the
2752 corpus this is a wide variety of value labels; the system-missing
2753 value is mapped to @samp{.}.
2756 @node SPV Detail union Element
2757 @subsubsection The @code{union} Element
2759 Parent: @code{setCellProperties} @*
2760 Contents: @code{intersect}@math{+}
2762 This element represents a set of cells, computed as the union of the
2763 sets represented by each of its children.
2765 @subsubheading The @code{intersect} Element
2767 Parent: @code{union} @*
2768 Contents: @code{where}@math{+} @math{|} @code{intersectWhere}?
2770 This element represents a set of cells, computed as the intersection
2771 of the sets represented by each of its children.
2773 Of the two possible children, in the corpus @code{where} is far more
2774 common, appearing thousands of times, whereas @code{intersectWhere}
2775 only appears 4 times.
2777 Most @code{intersect} elements have two or more children.
2779 @subsubheading The @code{where} Element
2781 Parent: @code{intersect} @*
2784 This element represents the set of cells in which the value of a
2785 specified variable falls within a specified set.
2787 @defvr {Attribute} variable
2788 The @code{id} of a variable, e.g.@: @code{dimension0categories} or
2789 @code{dimension0group0map}.
2792 @defvr {Attribute} include
2793 A value, or multiple values separated by semicolons,
2794 e.g.@: @code{0} or @code{13;14;15;16}.
2797 @subsubheading The @code{intersectWhere} Element
2799 Parent: @code{intersect} @*
2802 The meaning of this element is unknown.
2804 @defvr {Attribute} variable
2805 @defvrx {Attribute} variable2
2806 The meaning of these attributes is unknown. In the four examples in
2807 the corpus they always take the values @code{dimension2categories} and
2808 @code{dimension0categories}, respectively.
2811 @node SPV Detail style Element
2812 @subsection The @code{style} Element