1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2019 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
11 @node SPSS Viewer File Format
12 @appendix SPSS Viewer File Format
14 SPSS Viewer or @file{.spv} files, here called SPV files, are written
15 by SPSS 16 and later to represent the contents of its output editor.
16 This chapter documents the format, based on examination of a corpus of
17 about 500 files from a variety of sources. This description is
18 detailed enough to read SPV files, but probably not enough to write
21 SPSS 15 and earlier versions use a completely different output format
22 based on the Microsoft Compound Document Format. This format is not
25 An SPV file is a Zip archive that can be read with @command{zipinfo}
26 and @command{unzip} and similar programs. The final member in the Zip
27 archive is a file named @file{META-INF/MANIFEST.MF}. This structure
28 makes SPV files resemble Java ``JAR'' files (and ODF files), but
29 whereas a JAR manifest contains a sequence of colon-delimited
30 key/value pairs, an SPV manifest contains the string
31 @samp{allowPivoting=true}, without a new-line. (This string may be
32 the best way to identify an SPV file; it is invariant across the
35 The rest of the members in an SPV file's Zip archive fall into two
36 categories: @dfn{structure} and @dfn{detail} members. Structure
37 member names begin with @file{outputViewer@var{nnnnnnnnnn}}, where
38 each @var{n} is a decimal digit, and end with @file{.xml}, and often
39 include the string @file{_heading} in between. Each of these members
40 represents some kind of output item (a table, a heading, a block of
41 text, etc.) or a group of them. The member whose output goes at the
42 beginning of the document is numbered 0, the next member in the output
43 is numbered 1, and so on.
45 Structure members contain XML. This XML is sometimes self-contained,
46 but it often references detail members in the Zip archive, which are
50 @item @file{@var{prefix}_table.xml} and @file{@var{prefix}_tableData.bin}
51 @itemx @file{@var{prefix}_lightTableData.bin}
52 The structure of a table plus its data. Older SPV files pair a
53 @file{@var{prefix}_table.xml} file that describes the table's
54 structure with a binary @file{@var{prefix}_tableData.bin} file that
55 gives its data. Newer SPV files (the majority of those in the corpus)
56 instead include a single @file{@var{prefix}_lightTableData.bin} file
57 that incorporates both into a single binary format.
59 @item @file{@var{prefix}_warning.xml} and @file{@var{prefix}_warningData.bin}
60 @itemx @file{@var{prefix}_lightWarningData.bin}
61 Same format used for tables, with a different name.
63 @item @file{@var{prefix}_notes.xml} and @file{@var{prefix}_notesData.bin}
64 @itemx @file{@var{prefix}_lightNotesData.bin}
65 Same format used for tables, with a different name.
67 @item @file{@var{prefix}_chartData.bin} and @file{@var{prefix}_chart.xml}
68 The structure of a chart plus its data. Charts do not have a
71 @item @file{@var{prefix}_pmml.scf}
72 @itemx @file{@var{prefix}_stats.scf}
73 @item @file{@var{prefix}_model.xml}
74 Not yet investigated. The corpus contains few examples.
77 The @file{@var{prefix}} in the names of the detail members is
78 typically an 11-digit decimal number that increases for each item,
79 tending to skip values. Older SPV files use different naming
80 conventions. Structure member refer to detail members by name, and so
81 their exact names do not matter to readers as long as they are unique.
84 * SPV Structure Member Format::
85 * SPV Light Detail Member Format::
86 * SPV Legacy Detail Member Binary Format::
87 * SPV Legacy Detail Member XML Format::
90 @node SPV Structure Member Format
91 @section Structure Member Format
93 A structure member lays out the high-level structure for a group of
94 output items such as heading, tables, and charts. Structure members
95 do not include the details of tables and charts but instead refer to
96 them by their member names.
98 Structure members' XML files claim conformance with a collection of
99 XML Schemas. These schemas are distributed, under a nonfree license,
100 with SPSS binaries. Fortunately, the schemas are not necessary to
101 understand the structure members. The schemas can even
102 be deceptive because they document elements and attributes that are
103 not in the corpus and do not document elements and attributes that are
104 commonly found in the corpus.
106 Structure members use a different XML namespace for each schema, but
107 these namespaces are not entirely consistent. In some SPV files, for
108 example, the @code{viewer-tree} schema is associated with namespace
109 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
110 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
111 additional @file{viewer/}). Under either name, the schema URIs are
112 not resolvable to obtain the schemas themselves.
114 One may ignore all of the above in interpreting a structure member.
115 The actual XML has a simple and straightforward form that does not
116 require a reader to take schemas or namespaces into account. A
117 structure member's root is @code{heading} element, which contains
118 @code{heading} or @code{container} elements (or a mix), forming a
119 tree. In turn, @code{container} holds a @code{label} and one more
120 child, usually @code{text} or @code{table}.
122 The following diagram shows the hierarchy within an SPV structure
123 member more precisely. Names represent elements and <text> and
124 <cdata> represent plain text and CDATA, respectively. Edges point
125 from parent to child. Unlabeled edges indicate that the child appears
126 exactly once; edges labeled with *, zero or more times; edges labeled
127 with ?, zero or one times. Where possible, child elements are shown
128 in the order they actually appear within a parent element.
134 | +--> pageHeader +--> pageParagraph --> text --> <cdata>
135 | +--> pageFooter +--> pageParagraph --> text --> <cdata>
136 +-----> label --?--> <text>
139 +-----> label --?--> <text>
140 +--?--> text ---> html --> <cdata>
142 | +--?-- tableProperties
143 | | +--> generalProperties
144 | | +--> footnoteProperties
145 | | +--> cellFormatProperties
146 | | | +--> caption -------> style
147 | | | +--> footnotes -----> style
148 | | | +--> rowLabelse ----> style
149 | | | +--> columnLabels --> style
150 | | | +--> data ----------> style
151 | | | +--> layers --------> style
152 | | | +--> title ---------> style
153 | | | +--> cornerLabels --> style
154 | | +--> borderProperties
155 | | | +--> topInnerFrame
156 | | | +--> rightInnerFrame
157 | | | +--> horizontalDimensionBorderColumns
158 | | | +--> horizontalDimensionBorderRows
159 | | | +--> horizontalCategoryBorderColumns
160 | | | +--> leftInnerFrame
161 | | | +--> verticalDimensionBorderRows
162 | | | +--> titleLayerSeparator
163 | | | +--> verticalCategoryBorderRows
164 | | | +--> topOuterFrame
165 | | | +--> bottomInnerFrame
166 | | | +--> leftOuterFrame
167 | | | +--> dataAreaTop
168 | | | +--> verticalDimensionBorderColumns
169 | | | +--> dataAreaLeft
170 | | | +--> horizontalCategoryBorderRows
171 | | | +--> bottomOuterFrame
172 | | | +--> rightOuterFrame
173 | | | +--> verticalCategoryBorderColumns
174 | | +--> printingProperties
175 | +----- tableStructure
176 | +--?--> path ------> <text>
177 | +-----> dataPath --> <text>
179 | +--?--> dataPath --> <text>
180 | +-----> path ------> <text>
182 +--?--> ViZml --> <text>
183 +--?--> path ---> <text>
184 +--?--> pmmlContainerPath ---> <text>
185 +--?--> statsContainerPath --> <text>
189 The elements found in structure members are documented below. For
190 each element, we note the possible parent elements and the element's
191 contents. The contents are specified as pseudo-regular expressions
192 with the following conventions:
205 Grouping multiple elements.
210 @item @var{a} @math{|} @var{b}
211 A choice between @var{a} and @var{b}.
214 Zero or more @var{x}.
217 The following example shows the contents of a typical structure member
218 for a @cmd{DESCRIPTIVES} procedure. A real structure member is not
219 indented. This example also omits most attributes, all XML namespace
220 information, and the CSS from the embedded HTML:
223 <?xml version="1.0" encoding="utf-8"?>
225 <label>Output</label>
226 <heading commandName="Descriptives">
227 <label>Descriptives</label>
230 <text commandName="Descriptives" type="title">
232 <![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
236 <container visibility="hidden">
238 <table commandName="Descriptives" subType="Notes" type="note">
240 <dataPath>00000000001_lightNotesData.bin</dataPath>
245 <label>Descriptive Statistics</label>
246 <table commandName="Descriptives" subType="Descriptive Statistics"
249 <dataPath>00000000002_lightTableData.bin</dataPath>
258 * SPV Structure heading Element::
259 * SPV Structure label Element::
260 * SPV Structure container Element::
261 * SPV Structure text Element (Inside @code{container})::
262 * SPV Structure html Element::
263 * SPV Structure table Element::
264 * SPV Structure tableStructure Element::
265 * SPV Structure graph Element::
266 * SPV Structure model Element::
267 * SPV Structure dataPath and path Elements::
268 * SPV Structure pageSetup Element::
269 * SPV Structure pageHeader and pageFooter Elements::
270 * SPV Structure pageParagraph Element::
271 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
274 @node SPV Structure heading Element
275 @subsection The @code{heading} Element
277 Parent: Document root or @code{heading} @*
278 Contents: @code{pageSetup}? @code{label} (@code{container} @math{|} @code{heading})*
280 The root of a structure member is a @code{heading}, which represents a
281 section of output beginning with a title (the @code{label}) and
282 ordinarily followed by content containers or further nested
283 (sub)-sections of output. Unlike heading elements in HTML and other
284 common document formats, which precede the content that they head,
285 @code{heading} contains the elements that appear below the heading.
287 The document root heading, only, may also contain a @code{pageSetup}
290 The following attributes have been observed on both document root and
291 nested @code{heading} elements.
293 @defvr {Optional} creator-version
294 The version of the software that created this SPV file. A string of
295 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
296 e.g.@: @code{21000001} is version 21.0.0.1. Trailing pairs of zeros
297 are sometimes omitted, so that @code{21}, @code{210000}, and
298 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
299 three of those forms).
303 The following attributes have been observed on document root
304 @code{heading} elements only:
306 @defvr {Optional} @code{creator}
307 The directory in the file system of the software that created this SPV
311 @defvr {Optional} @code{creation-date-time}
312 The date and time at which the SPV file was written, in a
313 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
314 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
315 December 5, 2014 5:00:19 o'clock PM EST}.
318 @defvr {Optional} @code{lockReader}
319 Whether a reader should be allowed to edit the output. The possible
320 values are @code{true} and @code{false}, but the corpus only contains
324 @defvr {Optional} @code{schemaLocation}
325 This is actually an XML Namespace attribute. A reader may ignore it.
329 The following attributes have been observed only on nested
330 @code{heading} elements:
332 @defvr {Required} @code{commandName}
333 The locale-invariant name of the command that produced the output,
334 e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
337 @defvr {Optional} @code{visibility}
338 To what degree the output represented by the element is visible. The
339 only observed value is @code{collapsed}.
342 @defvr {Optional} @code{locale}
343 The locale used for output, in Windows format, which is similar to the
344 format used in Unix with the underscore replaced by a hyphen, e.g.@:
345 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
348 @defvr {Optional} @code{olang}
349 The output language, e.g.@: @code{en}, @code{it}, @code{es},
350 @code{de}, @code{pt-BR}.
353 @node SPV Structure label Element
354 @subsection The @code{label} Element
356 Parent: @code{heading} or @code{container} @*
359 Every @code{heading} and @code{container} holds a @code{label} as its
360 first child. The root @code{heading} in a structure member always
361 contains the string ``Output''. Otherwise, the text in @code{label}
362 describes what it labels, often by naming the statistical procedure
363 that was executed, e.g.@: ``Frequencies'' or ``T-Test''. Labels are
364 often very generic, especially within a @code{container}, e.g.@:
365 ``Title'' or ``Warnings'' or ``Notes''. Label text is localized
366 according to the output language, e.g.@: in Italian a frequency table
367 procedure is labeled ``Frequenze''.
369 The corpus contains a few examples of empty labels, ones that contain
372 This element has no attributes.
374 @node SPV Structure container Element
375 @subsection The @code{container} Element
377 Parent: @code{heading} @*
378 Contents: @code{label} (@code{table} @math{|} @code{text} @math{|} @code{graph} @math{|} @code{model})
380 A @code{container} serves to label a @code{table} or a @code{text}
383 This element has the following attributes.
385 @defvr {Required} @code{visibility}
386 Either @code{visible} or @code{hidden}, this indicates whether the
387 container's content is displayed.
390 @defvr {Optional} @code{text-align}
391 Presumably indicates the alignment of text within the container. The
392 only observed value is @code{left}. Observed with nested @code{table}
393 and @code{text} elements.
396 @defvr {Optional} @code{width}
397 The width of the container in the form @code{@var{n}px}, e.g.@:
401 @node SPV Structure text Element (Inside @code{container})
402 @subsection The @code{text} Element (Inside @code{container})
404 Parent: @code{container} @*
405 Contents: @code{html}
407 This @code{text} element is nested inside a @code{container}. There
408 is a different @code{text} element that is nested inside a
409 @code{pageParagraph}.
411 This element has the following attributes.
413 @defvr {Required} @code{type}
414 One of @code{title}, @code{log}, or @code{text}.
417 @defvr {Optional} @code{commandName}
418 As on the @code{heading} element. For output not specific to a
419 command, this is simply @code{log}. The corpus contains one example
420 of where @code{commandName} is present but set to the empty string.
423 @defvr {Optional} @code{creator-version}
424 As on the @code{heading} element.
427 @node SPV Structure html Element
428 @subsection The @code{html} Element
430 Parent: @code{text} @*
433 The CDATA contains an HTML document. In some cases, the document
434 starts with @code{<html>} and ends with @code{</html>}; in others the
435 @code{html} element is implied. Generally the HTML includes a
436 @code{head} element with a CSS stylesheet. The HTML body often begins
437 with @code{<BR>}. The actual content ranges from trivial to simple:
438 just discarding the CSS and tags yields readable results.
440 This element has the following attributes.
442 @defvr {Required} @code{lang}
443 This always contains @code{en} in the corpus.
446 @node SPV Structure table Element
447 @subsection The @code{table} Element
449 Parent: @code{container} @*
450 Contents: @code{tableStructure}
452 This element has the following attributes.
454 @defvr {Required} @code{commandName}
455 As on the @code{heading} element.
458 @defvr {Required} @code{type}
459 One of @code{table}, @code{note}, or @code{warning}.
462 @defvr {Required} @code{subType}
463 The locale-invariant name for the particular kind of output that this
464 table represents in the procedure. This can be the same as
465 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
466 @code{Case Processing Summary}. Generic subtypes @code{Notes} and
467 @code{Warnings} are often used.
470 @defvr {Required} @code{tableId}
471 A number that uniquely identifies the table within the SPV file,
472 typically a large negative number such as @code{-4147135649387905023}.
475 @defvr {Optional} @code{creator-version}
476 As on the @code{heading} element. In the corpus, this is only present
477 for version 21 and up and always includes all 8 digits.
480 @node SPV Structure tableStructure Element
481 @subsection The @code{tableStructure} Element
483 Parent: @code{table} @*
484 Contents: @code{dataPath}
486 This element has no attributes.
488 @node SPV Structure graph Element
489 @subsection The @code{graph} Element
491 Parent: @code{container} @*
492 Contents: @code{dataPath}? @code{path}
494 This element represents a graph. The @code{dataPath} and @code{path}
495 elements name the Zip members that give the details of the graph.
496 Normally, both elements are present; there is only one counterexample
499 @node SPV Structure model Element
500 @subsection The @code{model} Element
502 Parent: @code{container} @*
503 Contents: (@code{ViZml}? @code{path}) @math{|} (@code{pmmlContainerPath} @code{statsContainerPath})
505 This element represents a model. The @code{dataPath} and @code{path}
506 elements name the Zip members that give the details of the model.
507 Normally, both elements are present; there is only one counterexample
510 The details are unexplored. The @code{ViZml} element contains base-64
511 encoded text, that decodes to a binary format with some embedded text
512 strings, and @code{path} names an Zip member that contains XML.
513 Alternatively, @code{pmmlContainerPath} and @code{statsContainerPath}
514 name Zip members with @file{.scf} extension.
516 @node SPV Structure dataPath and path Elements
517 @subsection The @code{dataPath} and @code{path} Elements
519 Parent: @code{tableStructure} or @code{graph} or @code{model} @*
522 These element contain the name of the Zip members that hold details
523 for a container. For tables:
527 When a ``light'' format is used, only @code{dataPath} is present, and
528 it names a @file{.bin} member of the Zip file that has @code{light} in
529 its name, e.g.@: @code{0000000001437_lightTableData.bin} (@pxref{SPV
530 Light Detail Member Format}).
533 When the legacy format is used, both are present. In this case,
534 @code{dataPath} names a Zip member with a legacy binary format that
535 contains relevant data (@pxref{SPV Legacy Detail Member Binary
536 Format}), and @code{path} names a Zip member that uses an XML format
537 (@pxref{SPV Legacy Detail Member XML Format}).
540 Graphs normally follow the legacy approach described above. The
541 corpus contains one example of a graph with @code{path} but not
542 @code{dataPath}. The reason is unexplored.
544 Models use @code{path} but not @code{dataPath}. @xref{SPV Structure
545 graph Element}, for more information.
547 These elements have no attributes.
549 @node SPV Structure pageSetup Element
550 @subsection The @code{pageSetup} Element
552 Parent: @code{heading} @*
553 Contents: @code{pageHeader} @code{pageFooter}
555 This element has the following attributes.
557 @defvr {Required} @code{initial-page-number}
561 @defvr {Optional} @code{chart-size}
562 Always @code{as-is} or a localization (!) of it (e.g.@: @code{dimensione
563 attuale}, @code{Wie vorgegeben}).
566 @defvr {Optional} @code{margin-left}
567 @defvrx {Optional} @code{margin-right}
568 @defvrx {Optional} @code{margin-top}
569 @defvrx {Optional} @code{margin-bottom}
570 Margin sizes in the form @code{@var{size}in}, e.g.@: @code{0.25in}.
573 @defvr {Optional} @code{paper-height}
574 @defvrx {Optional} @code{paper-width}
575 Paper sizes in the form @code{@var{size}in}, e.g.@: @code{8.5in} by
576 @code{11in} for letter paper or @code{8.267in} by @code{11.692in} for
580 @defvr {Optional} @code{reference-orientation}
584 @defvr {Optional} @code{space-after}
588 @node SPV Structure pageHeader and pageFooter Elements
589 @subsection The @code{pageHeader} and @code{pageFooter} Elements
591 Parent: @code{pageSetup} @*
592 Contents: @code{pageParagraph}*
594 This element has no attributes.
596 @node SPV Structure pageParagraph Element
597 @subsection The @code{pageParagraph} Element
599 Parent: @code{pageHeader} or @code{pageFooter} @*
600 Contents: @code{text}
602 Text to go at the top or bottom of a page, respectively.
604 This element has no attributes.
606 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
607 @subsection The @code{text} Element (Inside @code{pageParagraph})
609 Parent: @code{pageParagraph} @*
612 This @code{text} element is nested inside a @code{pageParagraph}. There
613 is a different @code{text} element that is nested inside a
616 The element is either empty, or contains CDATA that holds almost-XHTML
617 text: in the corpus, either an @code{html} or @code{p} element. It is
618 @emph{almost}-XHTML because the @code{html} element designates the
620 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of an XHTML
621 namespace, and because the CDATA can contain substitution variables:
622 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
625 Typical contents (indented for clarity):
628 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
631 <p style="text-align:right; margin-top: 0">Page &[Page]</p>
636 This element has the following attributes.
638 @defvr {Required} @code{type}
642 @node SPV Light Detail Member Format
643 @section Light Detail Member Format
645 This section describes the format of ``light'' detail @file{.bin}
646 members. These members have a binary format which we describe here in
647 terms of a context-free grammar using the following conventions:
650 @item NonTerminal @result{} @dots{}
651 Nonterminals have CamelCaps names, and @result{} indicates a
652 production. The right-hand side of a production is often broken
653 across multiple lines. Break points are chosen for aesthetics only
654 and have no semantic significance.
656 @item 00, 01, @dots{}, ff.
657 A bytes with a fixed value, written as a pair of hexadecimal digits.
659 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
660 @itemx b0, b1, @dots{}, b9, b10, b11, @dots{}
661 A 32-bit integer in little-endian or big-endian byte order,
662 respectively, with a fixed value, written in decimal, prefixed by
669 A byte with value 0 or 1.
673 A 16-bit integer in little-endian or big-endian byte order,
678 A 32-bit integer in little-endian or big-endian byte order,
683 A 64-bit integer in little-endian or big-endian byte order,
687 A 64-bit IEEE floating-point number.
690 A 32-bit IEEE floating-point number.
694 A 32-bit integer, in little-endian or big-endian byte order,
695 respectively, followed by the specified number of bytes of character
696 data. (The encoding is indicated by the Formats nonterminal.)
699 @var{x} is optional, e.g.@: 00? is an optional zero byte.
701 @item @var{x}*@var{n}
702 @var{x} is repeated @var{n} times, e.g. byte*10 for ten arbitrary bytes.
704 @item @var{x}[@var{name}]
705 Gives @var{x} the specified @var{name}. Names are used in textual
706 explanations. They are also used, also bracketed, to indicate counts,
707 e.g.@: int[@t{n}] byte*[@t{n}] for a 32-bit integer followed by the
708 specified number of arbitrary bytes.
710 @item @var{a} @math{|} @var{b}
711 Either @var{a} or @var{b}.
714 Parentheses are used for grouping to make precedence clear, especially
715 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
719 A 32-bit integer that indicates the number of bytes in @var{x},
720 followed by @var{x} itself.
723 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
724 (The @file{.bin} header indicates the version.)
727 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
730 Little-endian byte order is far more common in this format, but a few
731 pieces of the format use big-endian byte order.
733 A ``light'' detail member @file{.bin} consists of a number of sections
734 concatenated together, terminated by a byte 01:
738 LightMember @result{}
741 Fonts Borders PrintSettings TableSettings Formats
747 The following sections go into more detail.
750 * SPV Light Member Header::
751 * SPV Light Member Title::
752 * SPV Light Member Caption::
753 * SPV Light Member Footnotes::
754 * SPV Light Member Fonts::
755 * SPV Light Member Borders::
756 * SPV Light Member Print Settings::
757 * SPV Light Member Table Settings::
758 * SPV Light Member Formats::
759 * SPV Light Member Dimensions::
760 * SPV Light Member Categories::
761 * SPV Light Member Data::
762 * SPV Light Member Value::
763 * SPV Light Member ValueMod::
766 @node SPV Light Member Header
769 An SPV light member begins with a 39-byte header:
775 (i1 @math{|} i3)[@t{version}]
777 bool[@t{show-numeric-markers}]
778 bool[@t{rotate-inner-column-labels}]
779 bool[@t{rotate-outer-row-labels}]
782 int[@t{min-column-width}] int[@t{max-column-width}]
783 int[@t{min-row-width}] int[@t{max-row-width}]
788 @code{version} is a version number that affects the interpretation of
789 some of the other data in the member. We will refer to ``version 1''
790 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
791 version-specific formatting (as described previously).
793 If @code{show-numeric-markers} is 1, footnote markers are shown as
794 numbers, starting from 1; otherwise, they are shown as letters,
795 starting from @samp{a}.
797 If @code{rotate-inner-column-labels} is 1, then column labels closest
798 to the data are rotated to be vertical; otherwise, they are shown
801 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
802 the data are rotated to be vertical; otherwise, they are shown in the
805 @code{table-id} is a binary version of the @code{tableId} attribute in
806 the structure member that refers to the detail member. For example,
807 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
808 would be 0xc6c99d183b300001.
810 @code{min-column-width} is the minimum width that a column will be
811 assigned automatically. @code{max-column-width} is the maximum width
812 that a column will be assigned to accommodate a long column label.
813 @code{min-row-width} and @code{max-row-width} are a similar range for
814 the width of row labels. All of these measurements are in 1/96 inch
817 The meaning of the other variable parts of the header is not known.
819 @node SPV Light Member Title
825 Value[@t{title1}] 01?
827 Value[@t{title2}] 01?
831 The Title, which follows the Header, specifies the pivot table's title
832 twice, as @code{title1} and @code{title2}. In the corpus, they are
835 Whereas the Value in @code{title1} and in @code{title2} are
836 appropriate for presentation, and localized to the user's language,
837 @code{c} is in English, sometimes less specific, and sometimes less
838 well formatted. For example, for a frequency table, @code{title1} and
839 @code{title2} name the variable and @code{c} is simply ``Frequencies''.
841 @node SPV Light Member Caption
846 Caption @result{} Caption1 Caption2
847 Caption1 @result{} 31 Value @math{|} 58
848 Caption2 @result{} 31 Value @math{|} 58
852 The Caption, if present, is shown below the table. Caption2 is
853 normally present. Caption1 is only rarely nonempty; it might reflect
854 user editing of the caption.
856 @node SPV Light Member Footnotes
857 @subsection Footnotes
861 Footnotes @result{} int[@t{n}] Footnote*[@t{n}]
862 Footnote @result{} Value[@t{text}] (58 @math{|} 31 Value[@t{marker}]) byte*4
866 Each footnote has @code{text} and an optional customer @code{marker}
869 @node SPV Light Member Fonts
874 Fonts @result{} 00 Font*8
877 string[@t{typeface}] float[@t{size}] int[@t{style}] bool[@t{underline}]
878 int[@t{halign}] int[@t{valign}]
879 string[@t{fgcolor}] string[@t{bgcolor}]
880 byte[@t{alternate}] string[@t{altfg}] string[@t{altbg}]
881 v3(int[@t{left-margin}] int[@t{right-margin}] int[@t{top-margin}] int[@t{bottom-margin}])
885 Each Font represents the font style for a different element, in the
886 following order: title, caption, footer, corner, column
887 labels, row labels, data, and layers.
889 @code{index} is the 1-based index of the Font, i.e. 1 for the first
890 Font, through 8 for the final Font.
892 @code{typeface} is the string name of the font. In the corpus, this
893 is @code{SansSerif} in over 99% of instances and @code{Times New
896 @code{size} is the size of the font, in points. The most common size
897 in the corpus is 12 points.
899 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
900 1 (with value 2) is set for italic.
902 @code{underline} is 1 if the font is underlined, 0 otherwise.
904 @code{halign} specifies horizontal alignment: 0 for center, 2 for
905 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
906 alignment varies according to type: string data is left-justified,
907 numbers and most other formats are right-justified.
909 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
912 @code{fgcolor} and @code{bgcolor} are the foreground color and
913 background color, respectively. In the corpus, these are always
914 @code{#000000} and @code{#ffffff}, respectively.
916 @code{alternate} is 01 if rows should alternate colors, 00 if all rows
917 should be the same color. When @code{alternate} is 01, @code{altfg}
918 and @code{altbg} specify the colors for the alternate rows.
920 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
921 @code{bottom-margin} are measured in multiples of 1/96 inch.
923 @node SPV Light Member Borders
930 be32[@t{n-borders}] Border*[@t{n-borders}]
931 bool[@t{show-grid-lines}]
935 be32[@t{border-type}]
936 be32[@t{stroke-type}]
941 The Borders reflect how borders between regions are drawn.
943 The fixed value of @code{endian} can be used to validate the
946 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
948 Each Border describes one kind of border. @code{n-borders} seems to
949 always be 19. Each @code{border-type} appears once (although in an
950 unpredictable order) and correspond to the following borders:
956 Left, top, right, and bottom outer frame.
958 Left, top, right, and bottom inner frame.
960 Left and top of data area.
962 Horizontal and vertical dimension rows.
964 Horizontal and vertical dimension columns.
966 Horizontal and vertical category rows.
968 Horizontal and vertical category columns.
971 @code{stroke-type} describes how a border is drawn, as one of:
988 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
989 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
990 opaque color, therefore opaque black is 0xff000000.
992 @node SPV Light Member Print Settings
993 @subsection Print Settings
997 PrintSettings @result{}
1000 bool[@t{paginate-layers}]
1002 bool[@t{fit-length}]
1003 bool[@t{top-continuation}]
1004 bool[@t{bottom-continuation}]
1005 be32[@t{n-orphan-lines}]
1006 bestring[@t{continuation-string}]
1010 The PrintSettings reflect settings for printing. The fixed value of
1011 @code{endian} can be used to validate the endianness.
1013 @code{all-layers} is 1 to print all layers, 0 to print only the
1016 @code{paginate-layers} is 1 to print each layer at the start of a new
1017 page, 0 otherwise. (This setting is honored only @code{all-layers} is
1018 1, since otherwise only one layer is printed.)
1020 @code{fit-width} and @code{fit-length} control whether the table is
1021 shrunk to fit within a page's width or length, respectively.
1023 @code{n-orphan-lines} is the minimum number of rows or columns to put
1024 in one part of a table that is broken across pages.
1026 If @code{top-continuation} is 1, then @code{continuation-string} is
1027 printed at the top of a page when a table is broken across pages for
1028 printing; similarly for @code{bottom-continuation} and the bottom of a
1029 page. Usually, @code{continuation-string} is empty.
1031 @node SPV Light Member Table Settings
1032 @subsection Table Settings
1036 TableSettings @result{}
1039 be32[@t{current-layer}]
1040 bool[@t{omit-empty}]
1041 bool[@t{show-row-labels-in-corner}]
1042 bool[@t{show-alphabetic-markers}]
1043 bool[@t{footnote-marker-position}]
1047 Breakpoints[@t{row-breaks}] Breakpoints[@t{column-breaks}]
1048 Keeps[@t{row-keeps}] Keeps[@t{column-keeps}]
1049 PointKeeps[@t{row-keeps}] PointKeeps[@t{column-keeps}]
1052 bestring[@t{table-look}]
1056 Breakpoints @result{} be32[@t{n-breaks}] be32*[@t{n-breaks}]
1058 Keeps @result{} be32[@t{n-keeps}] Keep*@t{n-keeps}
1059 Keep @result{} be32[@t{offset}] be[@t{n}]
1061 PointKeeps @result{} be32[@t{n-point-keeps}] PointKeep*@t{n-point-keeps}
1062 PointKeep @result{} be32[@t{offset}] be32 be32
1067 The TableSettings reflect display settings. The fixed value of
1068 @code{endian} can be used to validate the endianness.
1070 @code{current-layer} is the displayed layer.
1072 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
1073 any cell) are hidden; otherwise, they are shown.
1075 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
1076 the upper left corner; otherwise, they are shown nested.
1078 If @code{show-alphabetic-markers} is 1, markers are shown as letters
1079 (e.g. @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
1080 shown as numbers starting from 1.
1082 When @code{footnote-marker-position} is 1, footnote markers are shown
1083 as superscripts, otherwise as subscripts.
1085 The Breakpoints are rows or columns after which there is a page break;
1086 for example, a row break of 1 requests a page break after the second
1087 row. Usually no breakpoints are specified, indicating that page
1088 breaks should be selected automatically.
1090 The Keeps are ranges of rows or columns to be kept together without a
1091 page break; for example, a row Keep with @code{offset} 1 and @code{n}
1092 10 requests that the 10 rows starting with the second row be kept
1093 together. Usually no Keeps are specified.
1095 The PointKeeps seem to be generated automatically based on
1096 user-specified Keeps. They seems to indicate a conversion from rows
1097 or columns to pixel or point offsets.
1099 @code{notes} is a text string that contains user-specified notes. It
1100 is displayed when the user hovers the cursor over the table, like
1101 ``alt text'' on a webpage. It is not printed. It is usually empty.
1103 @code{table-look} is the name of a SPSS ``TableLook'' table style,
1104 such as ``Default'' or ``Academic''; it is often empty.
1106 TableSettings ends with an arbitrary number of null bytes.
1108 @node SPV Light Member Formats
1114 int[@t{n-widths}] int*[@t{n-widths}]
1115 string[@t{encoding}]
1116 int[@t{current-layer}]
1117 bool[@t{digit-grouping}] bool[@t{leading-zero}] bool
1119 byte[@t{decimal}] byte[@t{grouping}]
1123 v3(count(X1 count(X2)) count(X3))
1127 string[@t{command}] string[@t{command-local}]
1128 string[@t{language}] string[@t{charset}] string[@t{locale}]
1131 byte[@t{decimal}] byte[@t{grouping}]
1133 byte[@t{missing}] bool
1138 byte[@t{variable-mode}]
1139 byte[@t{value-mode}]
1145 int[@t{n-heights}] int*[@t{n-heights}]
1146 int[@t{n-style-map}] BlankMap*[@t{n-style-map}]
1147 int[@t{n-styles}] StylePair*[@t{n-styles}]
1149 StyleMap @result{} int64[@t{cell-index}] int16[@t{style-index}]
1151 01 00 (03 @math{|} 04) 00 00 00
1152 string[@t{command}] string[@t{command-local}]
1153 string[@t{language}] string[@t{charset}] string[@t{locale}]
1156 byte[@t{decimal}] byte[@t{grouping}]
1157 double[@t{small}] 01
1158 (string[@t{dataset}] string[@t{datafile}] i0 int[@t{date}] i0)?
1160 byte[@t{missing}] bool (i2000000 i0)?
1162 CustomCurrency @result{} int[@t{n-ccs}] string*[@t{n-ccs}]
1166 If @code{n-widths} is nonzero, then the accompanying integers are
1167 column widths as manually adjusted by the user. (Row heights are
1168 computed automatically based on the widths.)
1170 @code{encoding} is a character encoding, usually a Windows code page
1171 such as @code{en_US.windows-1252} or @code{it_IT.windows-1252}. The
1172 rest of the character strings in the member use this encoding. The
1173 encoding string is itself encoded in US-ASCII.
1175 @code{epoch} is the year that starts the epoch. A 2-digit year is
1176 interpreted as belonging to the 100 years beginning at the epoch. The
1177 default epoch year is 69 years prior to the current year; thus, in
1178 2017 this field by default contains 1948. In the corpus, @code{epoch}
1179 ranges from 1943 to 1948, plus some contain -1.
1181 @code{decimal} is the decimal point character. The observed values
1182 are @samp{.} and @samp{,}.
1184 @code{grouping} is the grouping character. Usually, it is @samp{,} if
1185 @code{decimal} is @samp{.}, and vice versa. Other observed values are
1186 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1187 indicating that digits should not be grouped).
1189 @code{command} describes the statistical procedure that generated the
1190 output, in English. It is not necessarily the literal syntax name of
1191 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1192 Tests.'' @code{command-local} is the procedure's name, translated
1193 into the output language; it is often empty and, when it is not,
1194 sometimes the same as @code{command}.
1196 @code{dataset} is the name of the dataset analyzed to produce the
1197 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1198 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}. The latter
1199 is sometimes the empty string.
1201 @code{date} is a date, as seconds since the epoch, i.e.@: since
1202 January 1, 1970. Pivot tables within an SPV files often have dates a
1203 few minutes apart, so this is probably a creation date for the tables
1204 rather than for the file.
1206 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1207 and other times they are absent. The reader can distinguish by
1208 assuming that they are present and then checking whether the
1209 presumptive @code{dataset} contains a null byte (a valid string never
1212 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
1213 following strings are CCA through CCE format strings. @xref{Custom
1214 Currency Formats,,, pspp, PSPP}. Most commonly these are all
1215 @code{-,,,} but other strings occur.
1217 @code{missing} is the character used to indicate that a cell contains
1218 a missing value. It is always observed as @samp{.}.
1220 @node SPV Light Member Dimensions
1221 @subsection Dimensions
1223 A pivot table presents multidimensional data. A Dimension identifies
1224 the categories associated with each dimension.
1228 Dimensions @result{} int[@t{n-dims}] Dimension*[@t{n-dims}]
1229 Dimension @result{} Value[@t{name}] DimProperties int[@t{n-categories}] Category*[@t{n-categories}]
1230 DimProperties @result{}
1232 (00 @math{|} 01 @math{|} 02)[@t{d2}]
1233 (i0 @math{|} i2)[@t{d3}]
1234 bool[@t{show-dim-label}]
1235 bool[@t{hide-all-labels}]
1236 01 int[@t{dim-index}]
1240 @code{name} is the name of the dimension, e.g. @code{Variables},
1241 @code{Statistics}, or a variable name.
1243 The meanings of @code{d1}, @code{d2}, and @code{d3} are unknown.
1244 @code{d1} is usually 0 but many other values have been observed.
1246 If @code{show-dim-label} is 01, the pivot table displays a label for
1247 the dimension itself. Because usually the group and category labels
1248 are enough explanation, it is usually 00.
1250 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1251 the dimension, including group and category labels. It is usually 00.
1252 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1254 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1255 0 for the first dimension, 1 for the second, and so on. Sometimes it
1256 is -1. There is no visible difference.
1258 @node SPV Light Member Categories
1259 @subsection Categories
1261 Categories are arranged in a tree. Only the leaf nodes in the tree
1262 are really categories; the others just serve as grouping constructs.
1266 Category @result{} Value[@t{name}] (Leaf @math{|} Group)
1267 Leaf @result{} 00 00 00 i2 int[@t{cat-index}] i0
1269 bool[@t{merge}] 00 01 (i0 @math{|} i2)[@t{data}]
1270 i-1 int[@t{n-subcategories}] Category*[@t{n-subcategories}]
1274 @code{name} is the name of the category (or group).
1276 A Leaf represents a leaf category. The Leaf's @code{cat-index} is a
1277 nonnegative integer less than @code{n-categories} in the Dimension in
1278 which the Category is nested (directly or indirectly). These
1279 categories represent the original order in which the categories were
1280 sorted; if the user sorted or rearranged the categories, then the
1281 order of categories in the file reflects that without changing the
1282 @code{cat-index} values.
1284 A Group is a group of nested categories. Usually a Group contains at
1285 least one Category, so that @code{n-subcategories} is positive, but a
1286 few Groups with @code{n-subcategories} 0 has been observed.
1288 If a Group's @code{merge} is 00, the most common value, then the group
1289 is really a distinct group that should be represented as such in the
1290 visual representation and user interface. If @code{merge} is 01, the
1291 categories in this group should be shown and treated as if they were
1292 direct children of the group's containing group (or if it has no
1293 parent group, then direct children of the dimension), and this group's
1294 name is irrelevant and should not be displayed. (Merged groups can be
1297 A Group's @code{data} appears to be i2 when all of the categories
1298 within a group are leaf categories that directly represent data values
1299 for a variable (e.g. in a frequency table or crosstabulation, a group
1300 of values in a variable being tabulated) and i0 otherwise.
1302 @node SPV Light Member Data
1305 The final part of an SPV light member contains the actual data.
1310 int[@t{layers}] int[@t{rows}] int[@t{columns}] int*[@t{n-dimensions}]
1311 int[@t{n-data}] Datum*[@t{n-data}]
1312 Datum @result{} int64[@t{index}] v1(00?) Value
1316 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1317 each specifies the number of dimensions displayed in layers, rows, and
1318 columns, respectively. Any of them may be zero. Their values sum to
1319 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1322 The @code{n-dimensions} integers are a permutation of the 0-based
1323 dimension numbers. The first @code{n-layers} integers specify each of
1324 the dimensions represented by layers, the next @code{n-rows} integers
1325 specify the dimensions represented by rows, and the final
1326 @code{n-columns} integers specify the dimensions represented by
1327 columns. When there is more than one dimension of a given kind, the
1328 inner dimensions are given first.
1330 The format of a Datum varies slightly from version 1 to version 3: in
1331 version 1 it allows for an extra optional 00 byte.
1333 A Datum consists of an @code{index} and a Value. Suppose there are
1334 @math{d} dimensions and dimension @math{i}, @math{0 \le i < d}, has
1335 @math{n_i} categories. Consider the datum at coordinates @math{x_i},
1336 @math{0 \le i < d}, and note that @math{0 \le x_i < n_i}. Then the
1337 index is calculated by the following algorithm:
1341 for each @math{i} from 0 to @math{d - 1}:
1342 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1345 For example, suppose there are 3 dimensions with 3, 4, and 5
1346 categories, respectively. The datum at coordinates (1, 2, 3) has
1347 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1348 Within a given dimension, the index is the @code{cat-index} in a Leaf.
1350 @node SPV Light Member Value
1353 Value is used throughout the SPV light member format. It boils down
1354 to a number or a string.
1358 Value @result{} 00? 00? 00? 00? RawValue
1360 01 ValueMod int[@t{format}] double[@t{x}]
1361 @math{|} 02 ValueMod int[@t{format}] double[@t{x}]
1362 string[@t{varname}] string[@t{vallab}] (01 @math{|} 02 @math{|} 03)
1363 @math{|} 03 string[@t{local}] ValueMod string[@t{id}] string[@t{c}] bool[@t{type}]
1364 @math{|} 04 ValueMod int[@t{format}] string[@t{vallab}] string[@t{varname}]
1365 (01 @math{|} 02 @math{|} 03) string[@t{s}]
1366 @math{|} 05 ValueMod string[@t{varname}] string[@t{varlabel}] (01 @math{|} 02 @math{|} 03)
1367 @math{|} ValueMod string[@t{format}] int[@t{n-args}] Argument*[@t{n-args}]
1370 @math{|} int[@t{x}] i0 Value*[@t{x}@math{+}1] /* @t{x} @math{>} 0 */
1374 There are several possible encodings, which one can distinguish by the
1375 first nonzero byte in the encoding.
1379 The numeric value @code{x}, intended to be presented to the user
1380 formatted according to @code{format}, which is in the format described
1381 for system files. @xref{System File Output Formats}, for details.
1382 Most commonly, @code{format} has width 40 (the maximum).
1384 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1385 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1386 not been observed.) @xref{System File Format}, for more about these
1390 Similar to @code{01}, with the additional information that @code{x} is
1391 a value of variable @code{varname} and has value label @code{vallab}.
1392 Both @code{varname} and @code{vallab} can be the empty string, the
1393 latter very commonly.
1395 The meaning of the final byte is unknown. Possibly it is connected to
1396 whether the value or the label should be displayed.
1399 A text string, in two forms: @code{c} is in English, and sometimes
1400 abbreviated or obscure, and @code{local} is localized to the user's
1401 locale. In an English-language locale, the two strings are often the
1402 same, and in the cases where they differ, @code{local} is more
1403 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1404 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1405 where P must be greater than 1.''
1407 @code{c} and @code{local} are always either both empty or both
1410 @code{id} is a brief identifying string whose form seems to resemble a
1411 programming language identifier, e.g.@: @code{cumulative_percent} or
1412 @code{factor_14}. It is not unique.
1414 @code{type} is 00 for text taken from user input, such as syntax
1415 fragment, expressions, file names, data set names, and 01 for fixed
1416 text strings such as names of procedures or statistics. In the former
1417 case, @code{id} is always the empty string; in the latter case,
1418 @code{id} is still sometimes empty.
1421 The string value @code{s}, intended to be presented to the user
1422 formatted according to @code{format}. The format for a string is not
1423 too interesting, and the corpus contains many clearly invalid formats
1424 like A16.39 or A255.127 or A134.1, so readers should probably ignore
1425 the format entirely.
1427 @code{s} is a value of variable @code{varname} and has value label
1428 @code{vallab}. @code{varname} is never empty but @code{vallab} is
1431 The meaning of the final byte is unknown.
1434 Variable @code{varname}, which is rarely observed as empty in the
1435 corpus, with variable label @code{varlabel}, which is often empty.
1437 The meaning of the final byte is unknown.
1440 (These bytes begin a ValueMod.) A format string, analogous to
1441 @code{printf}, followed by one or more Arguments, each of which has
1442 one or more values. The format string uses the following syntax:
1449 Each of these expands to the character following @samp{\\}, to escape
1450 characters that have special meaning in format strings. These are
1451 effective inside and outside the @code{[@dots{}]} syntax forms
1455 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1459 Expands to a formatted version of argument @var{i}, which must have
1460 only a single value. For example, @code{^1} expands to the first
1461 argument's @code{value}.
1463 @item [:@var{a}:]@var{i}
1464 Expands @var{a} for each of the values in @var{i}. @var{a}
1465 should contain one or more @code{^@var{j}} conversions, which are
1466 drawn from the values for argument @var{i} in order. Some examples
1471 All of the values for the first argument, concatenated.
1474 Expands to the values for the first argument, each followed by
1478 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1479 argument's first value and @var{y} is its second value. (This would
1480 be used only if the argument has two values. If there were more
1481 values, the second and third values would be directly concatenated,
1482 which would look funny.)
1485 @item [@var{a}:@var{b}:]@var{i}
1486 This extends the previous form so that the first values are expanded
1487 using @var{a} and later values are expanded using @var{b}. For an
1488 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1489 instead written as @code{%@var{j}}. Some examples from the corpus:
1493 Expands to all of the values for the first argument, separated by
1496 @item [%1 = %2:, ^1 = ^2:]1
1497 Given appropriate values for the first argument, expands to @code{X =
1501 Given appropriate values, expands to @code{1, 2, 3}.
1505 The format string is localized to the user's locale.
1508 @node SPV Light Member ValueMod
1509 @subsection ValueMod
1511 A ValueMod can specify special modifications to a Value.
1516 31 i0 (i0 @math{|} i1 string[@t{subscript}])
1517 v1(00 (i1 @math{|} i2) 00 00 int 00 00)
1518 v3(count(FormatString StylePair))
1519 @math{|} 31 int[@t{n-refs}] int16*[@t{n-refs}] Format
1522 Format @result{} 00 00 count(FormatString Style 58)
1523 FormatString @result{} count((count((i0 58)?) (58 @math{|} 31 string))?)
1530 bool[@t{bold}] bool[@t{italic}] bool[@t{underline}] bool[@t{show}]
1531 string[@t{fgcolor}] string[@t{bgcolor}]
1532 string[@t{typeface}] byte[@t{size}]
1535 int[@t{halign}] int[@t{valign}] double[@t{offset}]
1536 int16[@t{left-margin}] int16[@t{right-margin}]
1537 int16[@t{top-margin}] int16[@t{bottom-margin}]
1541 A ValueMod that begins with ``31 i0'' specifies a string to append to
1542 the main text of the Value, as a subscript. The subscript text is a
1543 brief indicator, e.g.@: @samp{a} or @samp{a,b}, with its meaning
1544 indicated by the table caption. In this usage, subscripts are similar
1545 to footnotes. One apparent difference is that a Value can only
1546 reference one footnote but a subscript can list more than one letter.
1548 A ValueMod that begins with 31 followed by a nonzero ``int'' specifies
1549 a footnote or footnotes that the Value references. Footnote markers
1550 are shown appended to the main text of the Value, as superscripts.
1552 The Format, if present, is a format string for substitutions using the
1553 syntax explained previously. It appears to be an English-language
1554 version of the localized format string in the Value in which the
1557 Style and Style2, if present, change the style for this individual
1558 Value. @code{bold}, @code{italic}, and @code{underline} control the
1559 particular style. @code{fgcolor} and @code{bgcolor} are strings, such
1560 as @code{#ffffff}. The @code{size} is a font size in units of 1/96
1563 @code{halign} is 0 for center, 2 for left, 4 for right, 6 for decimal,
1564 0xffffffad for mixed. For decimal alignment, @code{offset} is the
1565 decimal point's offset from the right side of the cell, in units of
1568 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1571 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1572 @code{bottom-margin} are in units of 1/72 inch.
1574 @node SPV Legacy Detail Member Binary Format
1575 @section Legacy Detail Member Binary Format
1577 Whereas the light binary format represents everything about a given
1578 pivot table, the legacy binary format conceptually consists of a
1579 number of named sources, each of which consists of a number of named
1580 variables, each of which is a 1-dimensional array of numbers or
1581 strings or a mix. Thus, the legacy binary member format is quite
1584 This section uses the same context-free grammar notation as in the
1585 previous section, with the following additions:
1589 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
1590 (The legacy member header indicates the version; see below.)
1593 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
1596 A legacy detail member @file{.bin} has the following overall format:
1600 LegacyBinary @result{}
1601 00 byte[@t{version}] int16[@t{n-sources}] int[@t{member-size}]
1602 Metadata*[@t{n-sources}] Data*[@t{n-sources}]
1606 @code{version} is a version number that affects the interpretation of
1607 some of the other data in the member. Versions 0xaf and 0xb0 are
1608 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
1611 A legacy member consists of @code{n-sources} data sources, each of
1612 which has Metadata and Data.
1614 @code{member-size} is the size of the legacy binary member, in bytes.
1616 The following sections go into more detail.
1619 * SPV Legacy Member Metadata::
1620 * SPV Legacy Member Data::
1623 @node SPV Legacy Member Metadata
1624 @subsection Metadata
1629 int[@t{n-data}] int[@t{n-variables}] int[@t{offset}]
1630 vAF(byte*32[@t{source-name}])
1631 vB0(byte*64[@t{source-name}] int[@t{x}])
1635 A data source has @code{n-variables} variables, each with
1636 @code{n-data} data values.
1638 @code{source-name} is a 32- or 64-byte string padded on the right with
1639 zero bytes. The names that appear in the corpus are very generic:
1640 usually @code{tableData} for pivot table data or @code{source0} for
1643 A given Metadata's @code{offset} is the offset, in bytes, from the
1644 beginning of the member to the start of the corresponding Data. This
1645 allows programs to skip to the beginning of the data for a particular
1646 source; it is also important to determine whether a source includes
1647 any string data (@pxref{SPV Legacy Member Data}).
1649 The meaning of @code{x} in version 0xb0 is unknown.
1651 @node SPV Legacy Member Data
1656 Data @result{} NumericData*[@t{n-variables}] StringData?
1657 NumericData @result{} byte*288[@t{variable-name}] double*[@t{n-data}]
1661 Data follow the Metadata in the legacy binary format, with sources in
1662 the same order. Each NumericSeries begins with a @code{variable-name}
1663 that generally indicates its role in the pivot table, e.g.@: ``cell'',
1664 ``cellFormat'', ``dimension0categories'', ``dimension0group0'',
1665 followed by the numeric data, one double per datum. A double with the
1666 maximum negative double @code{-DBL_MAX} represents the system-missing
1671 StringData @result{} i1 string[@t{source-name}] Pairs Labels
1673 Pairs @result{} int[@t{n-string-vars}] PairSeries*[@t{n-string-vars}]
1674 PairVar @result{} string[@t{pair-var-name}] int[@t{n-pairs}] Pair*[@t{n-pairs}]
1675 Pair @result{} int[@t{i}] int[@t{j}]
1677 Labels @result{} int[@t{n-labels}] Label*[@t{n-labels}]
1678 Label @result{} int[@t{frequency}] int[@t{s}]
1682 A source may include a mix of numeric and string data values. When a
1683 source includes any string data, the data values that are strings are
1684 set to SYSMIS in the NumericData, and StringData follows the
1685 NumericData. A source that contains no string data omits the
1686 StringData. To reliably determine whether a source includes
1687 StringData, the reader should check whether the offset following the
1688 NumericData is the offset of the next source, as indicated by its
1689 Metadata (or the end of the member, in the case of the last source).
1691 StringData repeats the name of the source (from Metadata).
1693 The string data overlays the numeric data. @code{n-string-vars} is
1694 the number of variables in the source that include string data. More
1695 precisely, it is the 1-based index of the last variable in the source
1696 that includes any string data; thus, it would be 4 if there are 5
1697 variables and only the fourth one includes string data.
1699 Each PairVar consists a sequence of 0 or more Pair nonterminals, each
1700 of which maps from a 0-based index within variable @code{i} to a
1701 0-based label index @code{j}, e.g.@: pair @code{i} = 2, @code{j} = 3,
1702 means that the third data value (with value SYSMIS) is to be replaced
1703 by the string of the fourth Label.
1705 The labels themselves follow the pairs. The valuable part of each
1706 label is the string @code{s}. Each label also includes a
1707 @code{frequency} that reports the number of pairs that reference it
1708 (although this is not useful).
1710 @node SPV Legacy Detail Member XML Format
1711 @section Legacy Detail Member XML Format
1713 This format is still under investigation.
1715 The design of the detail XML format is not what one would end up with
1716 for describing pivot tables. This is because it is a special case
1717 of a much more general format (``visualization XML'' or ``VizML'')
1718 that can describe a wide range of visualizations. Most of this
1719 generality is overkill for tables, and so we end up with a funny
1720 subset of a general-purpose format.
1722 The important elements of the detail XML format are:
1726 Variables. Variables in detail XML roughly correspond to the
1727 dimensions in a light detail member. There is one variable for each
1728 dimension, plus one variable for each level of labeling along an axis.
1730 The bulk of variables are defined with @code{sourceVariable} elements.
1731 The data for these variables comes from the associated
1732 @code{tableData.bin} member. Some variables are defined, with
1733 @code{derivedVariable} elements, as a constant or in terms of a
1734 mapping function from a source variable.
1737 Assignment of variables to axes. A variable can appear as columns, or
1738 rows, or layers. The @code{faceting} element and its sub-elements
1739 describe this assignment.
1742 All elements have an optional @code{id} attribute. In practice many
1743 elements are assigned @code{id} attributes that are never referenced.
1746 * SPV Detail visualization Element::
1747 * SPV Detail userSource Element::
1748 * SPV Detail sourceVariable Element::
1749 * SPV Detail derivedVariable Element::
1750 * SPV Detail extension Element::
1751 * SPV Detail graph Element::
1752 * SPV Detail location Element::
1753 * SPV Detail coordinates Element::
1754 * SPV Detail faceting Element::
1755 * SPV Detail facetLayout Element::
1756 * SPV Detail style Element::
1759 @node SPV Detail visualization Element
1760 @subsection The @code{visualization} Element
1763 Parent: Document root
1767 (sourceVariable @math{|} derivedVariable)@math{+}
1775 This element has the following attributes.
1777 @defvr {Required} creator
1778 The version of the software that created this SPV file, as a string of
1779 the form @code{xxyyzz}, which represents software version xx.yy.zz,
1780 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
1781 versions 16 through 19.
1784 @defvr {Required} date
1785 The date on the which the file was created, as a string of the form
1789 @defvr {Required} lang
1790 The locale used for output, in Windows format, which is similar to the
1791 format used in Unix with the underscore replaced by a hyphen, e.g.@:
1792 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
1795 @defvr {Required} name
1796 The title of the pivot table, localized to the output language.
1799 @defvr {Required} style
1800 The @code{id} of a @code{style} element (@pxref{SPV Detail style
1801 Element}). This is the base style for the entire pivot table. In
1802 every example in the corpus, the value is @code{visualizationStyle}
1803 and the corresponding @code{style} element has no attributes other
1807 @defvr {Required} type
1808 A floating-point number. The meaning is unknown.
1811 @defvr {Required} version
1812 The visualization schema version number. In the corpus, the value is
1813 one of 2.4, 2.5, 2.7, and 2.8.
1816 @node SPV Detail userSource Element
1817 @subsection The @code{userSource} Element
1819 Parent: @code{visualization} @*
1822 This element has the following attributes.
1824 @defvr {Optional} missing
1825 Always @code{listwise}.
1828 @node SPV Detail sourceVariable Element
1829 @subsection The @code{sourceVariable} Element
1831 Parent: @code{visualization} @*
1832 Contents: @code{extension}* (@code{format} @math{|} @code{stringFormat})?
1834 This element defines a variable whose values can be used elsewhere in
1835 the visualization. It ties this element's @code{id} to a variable
1836 from the @file{tableData.bin} member that corresponds to this
1839 This element has the following attributes.
1841 @defvr {Required} categorical
1842 Always set to @code{true}.
1845 @defvr {Required} source
1846 Always set to @code{tableData}, the @code{source-name} in the
1847 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
1851 @defvr {Required} sourceName
1852 The name of a variable within the source, the @code{variable-name} in
1853 the corresponding @file{tableData.bin} member (@pxref{SPV Legacy
1857 @defvr {Optional} dependsOn
1858 The @code{variable-name} of a variable linked to this one, so that a
1859 viewer can work with them together. For a group variable, this is the
1860 name of the corresponding categorical variable.
1863 @defvr {Optional} label
1864 The variable label, if any
1867 @defvr {Optional} labelVariable
1868 The @code{variable-name} of a variable whose string values correspond
1869 one-to-one with the values of this variable and are suitable for use
1873 @node SPV Detail derivedVariable Element
1874 @subsection The @code{derivedVariable} Element
1876 Parent: @code{visualization} @*
1877 Contents: @code{extension}* (@code{format} @math{|} @code{stringFormat} @code{valueMapEntry}*)
1879 Like @code{sourceVariable}, this element defines a variable whose
1880 values can be used elsewhere in the visualization. Instead of being
1881 read from a data source, the variable's data are defined by a
1882 mathematical expression.
1884 This element has the following attributes.
1886 @defvr {Required} categorical
1887 Always set to @code{true}.
1890 @defvr {Required} value
1891 An expression that defines the variable's value. In theory this could
1892 be an arbitrary expression in terms of constants, functions, and other
1893 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
1894 the corpus contains only the following forms of expressions:
1897 @item constant(@var{number})
1898 @itemx constant(@var{variable})
1899 A constant. The meaning when a variable is named is unknown.
1900 Sometimes the ``variable name'' has spaces in it.
1902 @item map(@var{variable})
1903 Transforms the values in the named @var{variable} using the
1904 @code{valueMapEntry}s contained within the element.
1908 @defvr {Optional} dependsOn
1909 The @code{variable-name} of a variable linked to this one, so that a
1910 viewer can work with them together. For a group variable, this is the
1911 name of the corresponding categorical variable.
1915 * SPV Detail valueMapEntry Element::
1918 @node SPV Detail valueMapEntry Element
1919 @subsubsection The @code{valueMapEntry} Element
1921 Parent: @code{derivedVariable} @*
1924 A @code{valueMapEntry} element defines a mapping from one or more
1925 values of a source expression to a target value. (In the corpus, the
1926 source expression is always just the name of a variable.) Each target
1927 value requires a separate @code{valueMapEntry}. If multiple source
1928 values map to the same target value, they can be combined or separate.
1930 @code{valueMapEntry} has the following attributes.
1932 @defvr {Required} from
1933 A source value, or multiple source values separated by semicolons,
1934 e.g.@: @code{0} or @code{13;14;15;16}.
1937 @defvr {Required} to
1941 @node SPV Detail extension Element
1942 @subsection The @code{extension} Element
1944 This is a general-purpose ``extension'' element. Readers that don't
1945 understand a given extension should be able to safely ignore it. The
1946 attributes on this element, and their meanings, vary based on the
1947 context. Each known usage is described separately below. The current
1948 extensions use attributes exclusively, without any nested elements.
1950 @subsubheading @code{visualization} Parent Element
1952 With @code{visualization} as its parent element, @code{extension} has
1953 the following attributes.
1955 @defvr {Optional} numRows
1956 An integer that presumably defines the number of rows in the displayed
1960 @defvr {Optional} showGridline
1961 Always set to @code{false} in the corpus.
1964 @defvr {Optional} minWidthSet
1965 @defvrx {Optional} maxWidthSet
1966 Always set to @code{true} in the corpus.
1969 @subsubheading @code{container} Parent Element
1971 With @code{container} as its parent element, @code{extension} has the
1972 following attributes.
1974 @defvr {Required} combinedFootnotes
1975 Always set to @code{true} in the corpus.
1978 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
1980 With @code{sourceVariable} or @code{derivedVariable} as its parent
1981 element, @code{extension} has the following attributes. A given
1982 parent element often contains several @code{extension} elements that
1983 specify the meaning of the source data's variables or sources, e.g.@:
1986 <extension from="0" helpId="corrected_model"/>
1987 <extension from="3" helpId="error"/>
1988 <extension from="4" helpId="total_9"/>
1989 <extension from="5" helpId="corrected_total"/>
1992 @defvr {Required} from
1993 An integer or a name like ``dimension0''.
1996 @defvr {Required} helpId
2000 @node SPV Detail graph Element
2001 @subsection The @code{graph} Element
2003 Parent: @code{visualization} @*
2004 Contents: @code{location}@math{+} @code{coordinates} @code{faceting} @code{facetLayout} @code{interval}
2006 @code{graph} has the following attributes.
2008 @defvr {Required} cellStyle
2009 @defvrx {Required} style
2010 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
2011 Detail style Element}). The former is the default style for
2012 individual cells, the latter for the entire table.
2015 @node SPV Detail location Element
2016 @subsection The @code{location} Element
2018 Parent: @code{graph} @*
2021 Each instance of this element specifies where some part of the table
2022 frame is located. All the examples in the corpus have four instances
2023 of this element, one for each of the parts @code{height},
2024 @code{width}, @code{left}, and @code{top}. Some examples in the
2025 corpus add a fifth for part @code{bottom}, even though it is not clear
2026 how all of @code{top}, @code{bottom}, and @code{heigth} can be honored
2027 at the same time. In any case, @code{location} seems to have little
2028 importance in representing tables; a reader can safely ignore it.
2030 @defvr {Required} part
2031 One of @code{height}, @code{width}, @code{top}, @code{bottom}, or
2032 @code{left}. Presumably @code{right} is acceptable as well but the
2033 corpus contains no examples.
2036 @defvr {Required} method
2037 How the location is determined:
2041 Based on the natural size of the table. Observed only for
2042 parts @code{height} and @code{width}.
2045 Based on the location specified in @code{target}. Observed only for
2046 parts @code{top} and @code{bottom}.
2049 Using the value in @code{value}. Observed only for parts @code{top},
2050 @code{bottom}, and @code{left}.
2053 Same as the specified @code{target}. Observed only for part
2058 @defvr {Optional} min
2059 Minimum size. Only observed with value @code{100pt}. Only observed
2060 for part @code{width}.
2063 @defvr {Dependent} target
2064 Required when @code{method} is @code{attach} or @code{same}, not
2065 observed otherwise. This is the ID of an element to attach to.
2066 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
2070 @defvr {Dependent} value
2071 Required when @code{method} is @code{fixed}, not observed otherwise.
2072 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
2073 on parts @code{top} and @code{left}, and @code{100%} on part
2077 @node SPV Detail coordinates Element
2078 @subsection The @code{coordinates} Element
2080 Parent: @code{graph} @*
2083 This element is always present and always empty, with no attributes
2086 @node SPV Detail faceting Element
2087 @subsection The @code{faceting} Element
2089 Parent: @code{graph} @*
2090 Contents: @code{cross} @code{layer}*
2092 The @code{faceting} element describes the row, column, and layer
2093 structure of the table. Its @code{cross} child determines the row and
2094 column structure, and each @code{layer} child (if any) represents a
2097 @code{faceting} has no attributes (other than @code{id}).
2099 @subsubheading The @code{cross} Element
2101 Parent: @code{faceting} @*
2102 Contents: @code{nest} @code{nest}
2104 The @code{cross} element describes the row and column structure of the
2105 table. It has exactly two @code{nest} children, the first of which
2106 describes the table's rows and the second the table's columns.
2108 @code{cross} has no attributes (other than @code{id}).
2110 @subsubheading The @code{nest} Element
2112 Parent: @code{cross} @*
2113 Contents: @code{variableReference}@math{+}
2115 A given @code{nest} usually consists of one or more dimensions, each
2116 of which is represented by @code{variableReference} child elements.
2117 Minimally, a dimension has two @code{variableReference} children, one
2118 for the categories, one for the data, e.g.:
2122 <variableReference ref="dimension0categories"/>
2123 <variableReference ref="dimension0"/>
2128 Groups of categories introduce additional variable references, e.g.@:
2132 <variableReference ref="dimension0categories"/>
2133 <variableReference ref="dimension0group0"/>
2134 <variableReference ref="dimension0"/>
2139 Grouping can be hierarchical, e.g.@:
2143 <variableReference ref="dimension0categories"/>
2144 <variableReference ref="dimension0group1"/>
2145 <variableReference ref="dimension0group0"/>
2146 <variableReference ref="dimension0"/>
2151 XXX what are group maps?
2154 <nest id="nest_1973">
2155 <variableReference ref="dimension1categories"/>
2156 <variableReference ref="dimension1group1map"/>
2157 <variableReference ref="dimension1group0map"/>
2158 <variableReference ref="dimension1"/>
2161 <variableReference ref="dimension0categories"/>
2162 <variableReference ref="dimension0group0map"/>
2163 <variableReference ref="dimension0"/>
2168 A @code{nest} can contain multiple dimensions:
2172 <variableReference ref="dimension1categories"/>
2173 <variableReference ref="dimension1group0"/>
2174 <variableReference ref="dimension1"/>
2175 <variableReference ref="dimension0categories"/>
2176 <variableReference ref="dimension0"/>
2180 One @code{nest} within a given @code{cross} may have no dimensions, in
2181 which case it still has one @code{variableReference} child, which
2182 references a @code{derivedVariable} whose @code{value} attribute is
2183 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
2184 @code{row} or @code{column}, respectively, as its @code{id}.
2186 @code{nest} has no attributes (other than @code{id}).
2188 @subsubheading The @code{variableReference} Element
2190 Parent: @code{nest} @*
2193 @code{variableReference} has one attribute.
2195 @defvr {Required} ref
2196 The @code{id} of a @code{sourceVariable} or @code{derivedVariable}
2200 @subsubheading The @code{layer} Element
2202 Parent: @code{faceting} @*
2205 Each layer is represented by a pair of @code{layer} elements. The
2206 first of this pair is for a category variable, the second for the data
2210 <layer value="0" variable="dimension0categories" visible="true"/>
2211 <layer value="dimension0" variable="dimension0" visible="false"/>
2215 @code{layer} has the following attributes.
2217 @defvr {Required} variable
2218 The @code{id} of a @code{sourceVariable} or @code{derivedVariable}
2222 @defvr {Required} value
2223 The value to select. For a category variable, this is always
2224 @code{0}; for a data variable, it is the same as the @code{variable}
2228 @defvr {Optional} visible
2229 Whether the layer is visible. Generally, category layers are visible
2230 and data layers are not, but sometimes this attribute is omitted.
2233 @defvr {Optional} method
2234 When present, this is always @code{nest}.
2237 @node SPV Detail facetLayout Element
2238 @subsection The @code{facetLayout} Element
2240 Parent: @code{graph} @*
2241 Contents: @code{tableLayout} @code{facetLevel}@math{+} @code{setCellProperties}*
2243 @subsubheading The @code{tableLayout} Element
2245 Parent: @code{facetLayout} @*
2248 @defvr {Required} verticalTitlesInCorner
2249 Always set to @code{true}.
2252 @defvr {Optional} style
2253 The @code{id} of a @code{style} element.
2256 @defvr {Optional} fitCells
2257 Always set to @code{ticks}.
2260 @subsubheading The @code{facetLevel} Element
2262 Parent: @code{facetLayout} @*
2263 Contents: @code{axis}
2265 Each @code{facetLevel} describes a @code{variableReference} or
2266 @code{layer}, and a table has one @code{facetLevel} element for
2267 each such element. For example, an SPV detail member that contains
2268 four @code{variableReference} elements and two @code{layer} elements
2269 will contain six @code{facetLevel} elements.
2271 In the corpus, @code{facetLevel} elements and the elements that they
2272 describe are always in the same order. The correspondence may also be
2273 observed in two other ways. First, one may use the @code{level}
2274 attribute, described below. Second, in the corpus, a
2275 @code{facetLevel} always has an @code{id} that is the same as the
2276 @code{id} of the element it describes with @code{_facetLevel}
2277 appended. One should not formally rely on this, of course, but it is
2278 usefully indicative.
2280 @defvr {Required} level
2281 A 1-based index into the @code{variableReference} and @code{layer}
2282 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2283 describes the first @code{variableReference} in the SPV detail member,
2284 and in a member with four @code{variableReference} elements, a
2285 @code{facetLayout} with a @code{level} of 5 describes the first
2286 @code{layer} in the member.
2289 @defvr {Required} gap
2290 Always observed as @code{0pt}.
2293 @subsubheading The @code{axis} Element
2295 Parent: @code{facetLevel} @*
2296 Contents: @code{label}? @code{majorTicks}
2298 @defvr {Attribute} style
2299 The @code{id} of a @code{style} element.
2302 @subsubheading The @code{label} Element
2304 Parent: @code{axis} or @code{labelFrame} @*
2305 Contents: @code{text}@math{+} @math{|} @code{descriptionGroup}
2307 This element represents a label on some aspect of the table. For example,
2308 the table's title is a @code{label}.
2310 The contents of the label can be one or more @code{text} elements or a
2311 @code{descriptionGroup}.
2313 @defvr {Attribute} style
2314 @defvrx {Optional} textFrameStyle
2315 Each of these is the @code{id} of a @code{style} element.
2316 @code{style} is the style of the label text, @code{textFrameStyle} the
2317 style for the frame around the label.
2320 @defvr {Optional} purpose
2321 The kind of entity being labeled, one of @code{title},
2322 @code{subTitle}, @code{layer}, or @code{footnote}.
2325 @subsubheading The @code{descriptionGroup} Element
2327 Parent: @code{label} @*
2328 Contents: (@code{description} @math{|} @code{text})@math{+}
2330 A @code{descriptionGroup} concatenates one or more elements to form a
2331 label. Each element can be a @code{text} element, which contains
2332 literal text, or a @code{description} element that substitutes a value
2335 @defvr {Attribute} target
2336 The @code{id} of an element being described. In the corpus, this is
2337 always @code{faceting}.
2340 @defvr {Attribute} separator
2341 A string to separate the description of multiple groups, if the
2342 @code{target} has more than one. In the corpus, this is always a
2346 Typical contents for a @code{descriptionGroup} are a value by itself:
2348 <description name="value"/>
2350 @noindent or a variable and its value, separated by a colon:
2352 <description name="variable"/><text>:</text><description name="value"/>
2355 @subsubheading The @code{description} Element
2357 Parent: @code{descriptionGroup} @*
2360 A @code{description} is like a macro that expands to some property of
2361 the target of its parent @code{descriptionGroup}.
2363 @defvr {Attribute} name
2364 The name of the property. Only @code{variable} and @code{value}
2365 appear in the corpus.
2368 @subsubheading The @code{majorTicks} Element
2370 Parent: @code{axis} @*
2371 Contents: @code{gridline}?
2373 @defvr {Attribute} labelAngle
2374 @defvrx {Attribute} length
2375 Both always defined to @code{0}.
2378 @defvr {Attribute} style
2379 @defvrx {Attribute} tickFrameStyle
2380 Each of these is the @code{id} of a @code{style} element.
2381 @code{style} is the style of the tick labels, @code{tickFrameStyle}
2382 the style for the frames around the labels.
2385 @subsubheading The @code{gridline} Element
2387 Parent: @code{majorTicks} @*
2390 Represents ``gridlines,'' which for a table represents the lines
2391 between the rows or columns of a table (XXX?).
2393 @defvr {Attribute} style
2394 The style for the gridline.
2397 @defvr {Attribute} zOrder
2398 Observed as a number between 28 and 31. Does not seem to be
2402 @subsubheading The @code{setCellProperties} Element
2404 Parent: @code{facetLayout} @*
2405 Contents: @code{setMetaData} @code{setStyle}* @code{setFormat}@math{+} @code{union}?
2407 This element sets style properties of cells designated by the
2408 @code{target} attribute of its child elements, as further restricted
2409 by the optional @code{union} element if present. The @code{target}
2410 values often used, e.g.@: @code{graph} or @code{labeling}, actually
2411 affect every cell, so the @code{union} element is a useful
2414 @defvr {Optional} applyToConverse
2415 If present, always @code{true}. This appears to invert the meaning of
2416 the @code{target} of sub-elements: the selected cells are the ones
2417 @emph{not} designated by @code{target}. This is confusing, given the
2418 additional restrictions of @code{union}, but in the corpus
2419 @code{applyToConverse} is never present along with @code{union}.
2422 @subsubheading The @code{setMetaData} Element
2424 Parent: @code{setCellProperties} @*
2427 This element is not known to have any visible effect.
2429 @defvr {Required} target
2430 The @code{id} of an element whose metadata is to be set. In the
2431 corpus, this is always @code{graph}, the @code{id} used for the
2432 @code{graph} element.
2435 @defvr {Required} key
2436 @defvrx {Required} value
2437 A key-value pair to set for the target.
2439 In the corpus, @code{key} is @code{cellPropId} or, rarely,
2440 @code{diagProps}, and @code{value} is always the @code{id} of the
2441 parent @code{setCellProperties}.
2444 @subsubheading The @code{setStyle} Element
2446 Parent: @code{setCellProperties} @*
2449 This element associates a style with the target.
2451 @defvr {Required} target
2452 The @code{id} of an element whose style is to be set. In the corpus,
2453 this is always the @code{id} of an @code{interval}, @code{labeling},
2454 or, rarely, @code{graph} element.
2457 @defvr {Required} style
2458 The @code{id} of a @code{style} element that identifies the style to
2462 @subsubheading The @code{setFormat} Element
2465 Parent: @code{setCellProperties}
2468 @math{|} @code{numberFormat}
2469 @math{|} @code{stringFormat}@math{+}
2470 @math{|} @code{dateTimeFormat}
2473 This element sets the format of the target, ``format'' in this case
2474 meaning the SPSS print format for a variable.
2476 The details of this element vary depending on the schema version, as
2477 declared in the root @code{visualization} element's @code{version}
2478 attribute (@pxref{SPV Detail visualization Element}). In version 2.5
2479 and earlier, @code{setFormat} contains one of a number of child
2480 elements that correspond to the different varieties of print formats.
2481 In version 2.7 and later, @code{setFormat} instead always contains a
2482 @code{format} element.
2484 XXX reinvestigate the above claim about versions: it appears to be
2487 The @code{setFormat} element itself has the following attributes.
2489 @defvr {Required} target
2490 The @code{id} of an element whose style is to be set. In the corpus,
2491 this is always the @code{id} of an @code{majorTicks} or
2492 @code{labeling} element.
2495 @defvr {Optional} reset
2496 If this is @code{true}, this format overrides the target's previous
2497 format. If it is @code{false}, the adds to the previous format. In
2498 the corpus this is always @code{true}. The default behavior is
2503 * SPV Detail format Element::
2504 * SPV Detail numberFormat Element::
2505 * SPV Detail stringFormat Element::
2506 * SPV Detail dateTimeFormat Element::
2507 * SPV Detail affix Element::
2508 * SPV Detail relabel Element::
2509 * SPV Detail union Element::
2512 @node SPV Detail format Element
2513 @subsubsection The @code{format} Element
2515 Parent: @code{sourceVariable}, @code{derivedVariable}, @code{formatMapping}, @code{labeling}, @code{formatMapping}, @code{setFormat} @*
2516 Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
2518 This element appears only in schema version 2.7 (@pxref{SPV Detail
2519 visualization Element}).
2521 This element determines a format, equivalent to an SPSS print format.
2523 @subsubheading Attributes for All Formats
2525 These attributes apply to all kinds of formats. The most important of
2526 these attributes determines the high-level kind of formatting in use:
2528 @defvr {Optional} baseFormat
2529 Either @code{dateTime} or @code{elapsedTime}. When this attribute is
2530 omitted, this element is a numeric or string format.
2534 Whether, in the corpus, other attributes are always present (``yes''),
2535 never present (``no''), or sometimes present (``opt'') depends on
2538 @multitable {maximumFractionDigits} {@code{dateTime}} {@code{elapsedTime}} {number} {string}
2539 @headitem Attribute @tab @code{dateTime} @tab @code{elapsedTime} @tab number @tab string
2540 @item errorCharacter @tab yes @tab yes @tab yes @tab opt
2542 @item separatorChars @tab yes @tab no @tab no @tab no
2544 @item mdyOrder @tab yes @tab no @tab no @tab no
2546 @item showYear @tab yes @tab no @tab no @tab no
2547 @item yearAbbreviation @tab yes @tab no @tab no @tab no
2549 @item showMonth @tab yes @tab no @tab no @tab no
2550 @item monthFormat @tab yes @tab no @tab no @tab no
2552 @item showDay @tab yes @tab opt @tab no @tab no
2553 @item dayPadding @tab yes @tab opt @tab no @tab no
2554 @item dayOfMonthPadding @tab yes @tab no @tab no @tab no
2555 @item dayType @tab yes @tab no @tab no @tab no
2557 @item showHour @tab yes @tab opt @tab no @tab no
2558 @item hourFormat @tab yes @tab opt @tab no @tab no
2559 @item hourPadding @tab yes @tab yes @tab no @tab no
2561 @item showMinute @tab yes @tab yes @tab no @tab no
2562 @item minutePadding @tab yes @tab yes @tab no @tab no
2564 @item showSecond @tab yes @tab yes @tab no @tab no
2565 @item secondPadding @tab no @tab yes @tab no @tab no
2567 @item showMillis @tab no @tab yes @tab no @tab no
2569 @item minimumIntegerDigits @tab no @tab no @tab yes @tab no
2570 @item maximumFractionDigits @tab no @tab yes @tab yes @tab no
2571 @item minimumFractionDigits @tab no @tab yes @tab yes @tab no
2572 @item useGrouping @tab no @tab opt @tab yes @tab no
2573 @item scientific @tab no @tab no @tab yes @tab no
2574 @item small @tab no @tab no @tab opt @tab no
2575 @item suffix @tab no @tab no @tab opt @tab no
2577 @item tryStringsAsNumbers @tab no @tab no @tab no @tab yes
2581 @defvr {Attribute} errorCharacter
2582 A character that replaces the formatted value when it cannot otherwise
2583 be represented in the given format. Always @samp{*}.
2586 @subsubheading Date and Time Attributes
2588 These attributes are used with @code{dateTime} and @code{elapsedTime}
2591 @defvr {Attribute} separatorChars
2592 Exactly four characters. In order, these are used for: decimal point,
2593 grouping, date separator, time separator. Always @samp{.,-:}.
2596 @defvr {Attribute} mdyOrder
2597 Within a date, the order of the days, months, and years.
2598 @code{dayMonthYear} is the only observed value, but one would expect
2599 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
2603 @defvr {Attribute} showYear
2604 @defvrx {Attribute} yearAbbreviation
2605 Whether to include the year and, if so, whether the year should be
2606 shown abbreviated, that is, with only 2 digits. Each is @code{true}
2607 or @code{false}; only values of @code{true} and @code{false},
2608 respectively, have been observed.
2611 @defvr {Attribute} showMonth
2612 @defvrx {Attribute} monthFormat
2613 Whether to include the month (@code{true} or @code{false}) and, if so,
2614 how to format it. @code{monthFormat} is one of the following:
2618 The full name of the month, e.g.@: in an English locale,
2622 The abbreviated name of the month, e.g.@: in an English locale,
2626 The number representing the month, e.g.@: 9 for September.
2629 A two-digit number representing the month, e.g.@: 09 for September.
2632 Only values of @code{true} and @code{short}, respectively, have been
2636 @defvr {Attribute} dayPadding
2637 @defvrx {Attribute} dayOfMonthPadding
2638 @defvrx {Attribute} hourPadding
2639 @defvrx {Attribute} minutePadding
2640 @defvrx {Attribute} secondPadding
2641 These attributes presumably control whether each field in the output
2642 is padded with spaces to its maximum width, but the details are not
2643 understood. The only observed value for any of these attributes is
2647 @defvr {Attribute} showDay
2648 @defvrx {Attribute} showHour
2649 @defvrx {Attribute} showMinute
2650 @defvrx {Attribute} showSecond
2651 @defvrx {Attribute} showMillis
2652 These attributes presumably control whether each field is displayed
2653 in the output, but the details are not understood. The only
2654 observed value for any of these attributes is @code{true}.
2657 @defvr {Attribute} dayType
2658 This attribute is always @code{month} in the corpus, specifying that
2659 the day of the month is to be displayed; a value of @code{year} is
2660 supposed to indicate that the day of the year, where 1 is January 1,
2661 is to be displayed instead.
2664 @defvr {Attribute} hourFormat
2665 @code{hourFormat}, if present, is one of:
2669 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
2673 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
2675 This is the only value observed in the corpus.
2678 The time is displayed in a 12-hour format, without distinguishing
2679 morning or evening, e.g.@: @code{10;15}.
2682 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
2683 which is confusing since a time duration does not have a concept of AM
2684 or PM. This might indicate a bug in the code that generated the XML
2685 in the corpus, or it might indicate that @code{elapsedTime} is
2686 sometimes used to format a time of day.
2689 @subsubheading Numeric Attributes
2691 These attributes are used for formats when @code{baseFormat} is
2692 @code{number}. Attributes @code{maximumFractionDigits}, and
2693 @code{minimumFractionDigits}, and @code{useGrouping} are also used
2694 when @code{baseFormat} is @code{elapsedTime}.
2696 @defvr {Attribute} minimumIntegerDigits
2697 Minimum number of digits to display before the decimal point. Always
2698 observed as @code{0}.
2701 @defvr {Attribute} maximumFractionDigits
2702 @defvrx {Attribute} maximumFractionDigits
2703 Maximum or minimum, respectively, number of digits to display after
2704 the decimal point. The observed values of each attribute range from 0
2708 @defvr {Attribute} useGrouping
2709 Whether to use the grouping character to group digits in large
2710 numbers. It would make sense for the grouping character to come from
2711 the @code{separatorChars} attribute, but that attribute is only
2712 present when @code{baseFormat} is @code{dateTime} or
2713 @code{elapsedTime}, in the corpus at least. Perhaps that is because
2714 this attribute has only been observed as @code{false}.
2717 @defvr {Attribute} scientific
2718 This attribute controls when and whether the number is formatted in
2719 scientific notation. It takes the following values:
2723 Use scientific notation only when the number's magnitude is smaller
2724 than the value of the @code{small} attribute.
2727 Use scientific notation when the number will not otherwise fit in the
2731 Always use scientific notation. Not observed in the corpus.
2734 Never use scientific notation. A number that won't otherwise fit will
2735 be replaced by an error indication (see the @code{errorCharacter}
2736 attribute). Not observed in the corpus.
2740 @defvr {Optional} small
2741 Only present when the @code{scientific} attribute is
2742 @code{onlyForSmall}, this is a numeric magnitude below which the
2743 number will be formatted in scientific notation. The values @code{0}
2744 and @code{0.0001} have been observed. The value @code{0} seems like a
2745 pathological choice, since no real number has a magnitude less than 0;
2746 perhaps in practice such a choice is equivalent to setting
2747 @code{scientific} to @code{false}.
2750 @defvr {Optional} prefix
2751 @defvrx {Optional} suffix
2752 Specifies a prefix or a suffix to apply to the formatted number. Only
2753 @code{suffix} has been observed, with value @samp{%}.
2756 @subsubheading String Attributes
2758 These attributes are used for formats when @code{baseFormat} is
2761 @defvr {Attribute} tryStringsAsNumbers
2762 When this is @code{true}, it is supposed to indicate that string
2763 values should be parsed as numbers and then displayed according to
2764 numeric formatting rules. However, in the corpus it is always
2768 @node SPV Detail numberFormat Element
2769 @subsubsection The @code{numberFormat} Element
2771 Parent: @code{setFormat} @*
2772 Contents: @code{affix}@math{+}
2774 This element appears only in schema version 2.5 and earlier
2775 (@pxref{SPV Detail visualization Element}). Possibly this element
2776 could also contain @code{relabel} elements in a more diverse corpus.
2778 This element has the following attributes.
2780 @defvr {Attribute} maximumFractionDigits
2781 @defvrx {Attribute} minimumFractionDigits
2782 @defvrx {Attribute} minimumIntegerDigits
2783 @defvrx {Optional} scientific
2784 @defvrx {Optional} small
2785 @defvrx {Optional} suffix
2786 @defvrx {Optional} useGroupging
2787 The syntax and meaning of these attributes is the same as on the
2788 @code{format} element for a numeric format. @pxref{SPV Detail format
2792 @node SPV Detail stringFormat Element
2793 @subsubsection The @code{stringFormat} Element
2795 Parent: @code{setFormat} @*
2796 Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
2798 This element appears only in schema version 2.5 and earlier
2799 (@pxref{SPV Detail visualization Element}).
2801 This element has no attributes.
2803 @node SPV Detail dateTimeFormat Element
2804 @subsubsection The @code{dateTimeFormat} Element
2806 Parent: @code{setFormat} @*
2809 This element appears only in schema version 2.5 and earlier
2810 (@pxref{SPV Detail visualization Element}). Possibly this element
2811 could also contain @code{affix} and @code{relabel} elements in a more
2814 The following attribute is required.
2816 @defvr {Attribute} baseFormat
2817 Either @code{dateTime} or @code{time}.
2820 When @code{baseFormat} is @code{dateTime}, the following attributes
2823 @defvr {Attribute} dayOfMonthPadding
2824 @defvrx {Attribute} dayPadding
2825 @defvrx {Attribute} dayType
2826 @defvrx {Attribute} hourFormat
2827 @defvrx {Attribute} hourPadding
2828 @defvrx {Attribute} mdyOrder
2829 @defvrx {Attribute} minutePadding
2830 @defvrx {Attribute} monthFormat
2831 @defvrx {Attribute} separatorChars
2832 @defvrx {Attribute} showDay
2833 @defvrx {Attribute} showHour
2834 @defvrx {Attribute} showMinute
2835 @defvrx {Attribute} showMonth
2836 @defvrx {Attribute} showSecond
2837 @defvrx {Attribute} showYear
2838 @defvrx {Attribute} yearAbbreviation
2839 The syntax and meaning of these attributes is the same as on the
2840 @code{format} element when that element's @code{baseFormat} is
2841 @code{dateTime}. @pxref{SPV Detail format Element}.
2844 When @code{baseFormat} is @code{time}, the following attributes are
2847 @defvr {Attribute} hourFormat
2848 @defvrx {Attribute} hourPadding
2849 @defvrx {Attribute} minutePadding
2850 @defvrx {Attribute} monthFormat
2851 @defvrx {Attribute} separatorChars
2852 @defvrx {Attribute} showDay
2853 @defvrx {Attribute} showHour
2854 @defvrx {Attribute} showMinute
2855 @defvrx {Attribute} showMonth
2856 @defvrx {Attribute} showSecond
2857 @defvrx {Attribute} showYear
2858 @defvrx {Attribute} yearAbbreviation
2859 The syntax and meaning of these attributes is the same as on the
2860 @code{format} element when that element's @code{baseFormat} is
2861 @code{elapsedTime}. @pxref{SPV Detail format Element}.
2864 @node SPV Detail affix Element
2865 @subsubsection The @code{affix} Element
2867 Parent: @code{format} or @code{numberFormat} or @code{stringFormat} @*
2870 Possibly this element could have @code{dateTimeFormat} as a parent in
2871 a more diverse corpus.
2873 This defines a suffix (or, theoretically, a prefix) for a formatted
2874 value. It is used to insert a reference to a footnote. It has the
2875 following attributes:
2877 @defvr {Attribute} definesReference
2878 This specifies the footnote number as a natural number: 1 for the
2879 first footnote, 2 for the second, and so on.
2882 @defvr {Attribute} position
2883 Position for the footnote label. Always @code{superscript}.
2886 @defvr {Attribute} suffix
2887 Whether the affix is a suffix (@code{true}) or a prefix
2888 (@code{false}). Always @code{true}.
2891 @defvr {Attribute} value
2892 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
2893 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
2894 contains other values: @code{*}, @code{**}, and a few that begin with
2895 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
2898 @node SPV Detail relabel Element
2899 @subsubsection The @code{relabel} Element
2901 Parent: @code{format} or @code{stringFormat} @*
2904 Possibly this element could have @code{numberFormat} or
2905 @code{dateTimeFormat} as a parent in a more diverse corpus.
2907 This specifies how to display a given value. It is used to implement
2908 value labels and to display the system-missing value in a
2909 human-readable way. It has the following attributes:
2911 @defvr {Attribute} from
2912 The value to map. In the corpus this is an integer or the
2913 system-missing value @code{-1.797693134862316E300}.
2916 @defvr {Attribute} to
2917 The string to display in place of the value of @code{from}. In the
2918 corpus this is a wide variety of value labels; the system-missing
2919 value is mapped to @samp{.}.
2922 @node SPV Detail union Element
2923 @subsubsection The @code{union} Element
2925 Parent: @code{setCellProperties} @*
2926 Contents: @code{intersect}@math{+}
2928 This element represents a set of cells, computed as the union of the
2929 sets represented by each of its children.
2931 @subsubheading The @code{intersect} Element
2933 Parent: @code{union} @*
2934 Contents: @code{where}@math{+} @math{|} @code{intersectWhere}?
2936 This element represents a set of cells, computed as the intersection
2937 of the sets represented by each of its children.
2939 Of the two possible children, in the corpus @code{where} is far more
2940 common, appearing thousands of times, whereas @code{intersectWhere}
2941 only appears 4 times.
2943 Most @code{intersect} elements have two or more children.
2945 @subsubheading The @code{where} Element
2947 Parent: @code{intersect} @*
2950 This element represents the set of cells in which the value of a
2951 specified variable falls within a specified set.
2953 @defvr {Attribute} variable
2954 The @code{id} of a variable, e.g.@: @code{dimension0categories} or
2955 @code{dimension0group0map}.
2958 @defvr {Attribute} include
2959 A value, or multiple values separated by semicolons,
2960 e.g.@: @code{0} or @code{13;14;15;16}.
2963 @subsubheading The @code{intersectWhere} Element
2965 Parent: @code{intersect} @*
2968 The meaning of this element is unknown.
2970 @defvr {Attribute} variable
2971 @defvrx {Attribute} variable2
2972 The meaning of these attributes is unknown. In the four examples in
2973 the corpus they always take the values @code{dimension2categories} and
2974 @code{dimension0categories}, respectively.
2977 @node SPV Detail style Element
2978 @subsection The @code{style} Element