1 @node SPSS Viewer File Format
2 @chapter SPSS Viewer File Format
4 SPSS Viewer or @file{.spv} files, here called SPV files, are written
5 by SPSS 16 and later to represent the contents of its output editor.
6 This chapter documents the format, based on examination of a corpus of
7 about 500 files from a variety of sources. This description is
8 detailed enough to read SPV files, but probably not enough to write
11 SPSS 15 and earlier versions use a completely different output format
12 based on the Microsoft Compound Document Format. This format is not
15 An SPV file is a Zip archive that can be read with @command{zipinfo}
16 and @command{unzip} and similar programs. The final member in the Zip
17 archive is a file named @file{META-INF/MANIFEST.MF}. This structure
18 makes SPV files resemble Java ``JAR'' files (and ODF files), but
19 whereas a JAR manifest contains a sequence of colon-delimited
20 key/value pairs, an SPV manifest contains the string
21 @samp{allowPivoting=true}, without a new-line. (This string may be
22 the best way to identify an SPV file; it is invariant across the
25 The rest of the members in an SPV file's Zip archive fall into two
26 categories: @dfn{structure} and @dfn{detail} members. Structure
27 member names begin with @file{outputViewer@var{nnnnnnnnnn}}, where
28 each @var{n} is a decimal digit, and end with @file{.xml}, and often
29 include the string @file{_heading} in between. Each of these members
30 represents some kind of output item (a table, a heading, a block of
31 text, etc.) or a group of them. The member whose output goes at the
32 beginning of the document is numbered 0, the next member in the output
33 is numbered 1, and so on.
35 Structure members contain XML. This XML is sometimes self-contained,
36 but it often references detail members in the Zip archive, which are
40 @item @file{@var{prefix}_table.xml} and @file{@var{prefix}_tableData.bin}
41 @itemx @file{@var{prefix}_lightTableData.bin}
42 The structure of a table plus its data. Older SPV files pair a
43 @file{@var{prefix}_table.xml} file that describes the table's
44 structure with a binary @file{@var{prefix}_tableData.bin} file that
45 gives its data. Newer SPV files (the majority of those in the corpus)
46 instead include a single @file{@var{prefix}_lightTableData.bin} file
47 that incorporates both into a single binary format.
49 @item @file{@var{prefix}_warning.xml} and @file{@var{prefix}_warningData.bin}
50 @itemx @file{@var{prefix}_lightWarningData.bin}
51 Same format used for tables, with a different name.
53 @item @file{@var{prefix}_notes.xml} and @file{@var{prefix}_notesData.bin}
54 @itemx @file{@var{prefix}_lightNotesData.bin}
55 Same format used for tables, with a different name.
57 @item @file{@var{prefix}_chartData.bin} and @file{@var{prefix}_chart.xml}
58 The structure of a chart plus its data. Charts do not have a
61 @item @file{@var{prefix}_pmml.scf}
62 @itemx @file{@var{prefix}_stats.scf}
63 @item @file{@var{prefix}_model.xml}
64 Not yet investigated. The corpus contains few examples.
67 The @file{@var{prefix}} in the names of the detail members is
68 typically an 11-digit decimal number that increases for each item,
69 tending to skip values. Older SPV files use different naming
70 conventions. Structure member refer to detail members by name, and so
71 their exact names do not matter to readers as long as they are unique.
74 * SPV Structure Member Format::
75 * SPV Light Detail Member Format::
76 * SPV Legacy Detail Member Binary Format::
77 * SPV Legacy Detail Member XML Format::
80 @node SPV Structure Member Format
81 @section Structure Member Format
83 A structure member lays out the high-level structure for a group of
84 output items such as heading, tables, and charts. Structure members
85 do not include the details of tables and charts but instead refer to
86 them by their member names.
88 Structure members' XML files claim conformance with a collection of
89 XML Schemas. These schemas are distributed, under a nonfree license,
90 with SPSS binaries. Fortunately, the schemas are not necessary to
91 understand the structure members. The schemas can even
92 be deceptive because they document elements and attributes that are
93 not in the corpus and do not document elements and attributes that are
94 commonly found in the corpus.
96 Structure members use a different XML namespace for each schema, but
97 these namespaces are not entirely consistent. In some SPV files, for
98 example, the @code{viewer-tree} schema is associated with namespace
99 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
100 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
101 additional @file{viewer/}). Under either name, the schema URIs are
102 not resolvable to obtain the schemas themselves.
104 One may ignore all of the above in interpreting a structure member.
105 The actual XML has a simple and straightforward form that does not
106 require a reader to take schemas or namespaces into account.
108 The elements found in structure members are documented below. For
109 each element, we note the possible parent elements and the element's
110 contents. The contents are specified as pseudo-regular expressions
111 with the following conventions:
124 Grouping multiple elements.
129 @item @var{a} @math{|} @var{b}
130 A choice between @var{a} and @var{b}.
133 Zero or more @var{x}.
137 For a diagram illustrating the hierarchy of elements within an SPV
138 structure member, please refer to a PDF version of the manual.
142 The following diagram shows the hierarchy of elements within an SPV
143 structure member. Edges point from parent to child elements.
144 Unlabeled edges indicate that the child appears exactly once; edges
145 labeled with *, zero or more times; edges labeled with ?, zero or one
147 @center @image{dev/spv-structure, 5in}
150 The following example shows the contents of a typical structure member
151 for a @cmd{DESCRIPTIVES} procedure. A real structure member would not
152 have indentation. This example all omits most attributes, all XML
153 namespace information, and the CSS from the embedded HTML:
156 <?xml version="1.0" encoding="utf-8"?>
158 <label>Output</label>
159 <heading commandName="Descriptives">
160 <label>Descriptives</label>
163 <text commandName="Descriptives" type="title">
165 <![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
169 <container visibility="hidden">
171 <table commandName="Descriptives" subType="Notes" type="note">
173 <dataPath>00000000001_lightNotesData.bin</dataPath>
178 <label>Descriptive Statistics</label>
179 <table commandName="Descriptives" subType="Descriptive Statistics"
182 <dataPath>00000000002_lightTableData.bin</dataPath>
191 * SPV Structure heading Element::
192 * SPV Structure label Element::
193 * SPV Structure container Element::
194 * SPV Structure text Element (Inside @code{container})::
195 * SPV Structure html Element::
196 * SPV Structure table Element::
197 * SPV Structure tableStructure Element::
198 * SPV Structure dataPath Element::
199 * SPV Structure pageSetup Element::
200 * SPV Structure pageHeader and pageFooter Elements::
201 * SPV Structure pageParagraph Element::
202 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
205 @node SPV Structure heading Element
206 @subsection The @code{heading} Element
208 Parent: Document root or @code{heading} @*
209 Contents: @code{pageSetup}? @code{label} (@code{container} @math{|} @code{heading})*
211 The root of a structure member is a @code{heading}, which represents a
212 section of output beginning with a title (the @code{label}) and
213 ordinarily followed by content containers or further nested
214 (sub)-sections of output.
216 The document root heading, only, may also contain a @code{pageSetup}
219 The following attributes have been observed on both document root and
220 nested @code{heading} elements.
222 @defvr {Optional} creator-version
223 The version of the software that created this SPV file. A string of
224 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
225 e.g.@: @code{21000001} is version 21.0.0.1. Trailing pairs of zeros
226 are sometimes omitted, so that @code{21}, @code{210000}, and
227 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
228 three of those forms).
232 The following attributes have been observed on document root
233 @code{heading} elements only:
235 @defvr {Optional} @code{creator}
236 The directory in the file system of the software that created this SPV
240 @defvr {Optional} @code{creation-date-time}
241 The date and time at which the SPV file was written, in a
242 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
243 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
244 December 5, 2014 5:00:19 o'clock PM EST}.
247 @defvr {Optional} @code{lockReader}
248 Whether a reader should be allowed to edit the output. The possible
249 values are @code{true} and @code{false}, but the corpus only contains
253 @defvr {Optional} @code{schemaLocation}
254 This is actually an XML Namespace attribute. A reader may ignore it.
258 The following attributes have been observed only on nested
259 @code{heading} elements:
261 @defvr {Required} @code{commandName}
262 The locale-invariant name of the command that produced the output,
263 e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
266 @defvr {Optional} @code{visibility}
267 To what degree the output represented by the element is visible. The
268 only observed value is @code{collapsed}.
271 @defvr {Optional} @code{locale}
272 The locale used for output, in Windows format, which is similar to the
273 format used in Unix with the underscore replaced by a hyphen, e.g.@:
274 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
277 @defvr {Optional} @code{olang}
278 The output language, e.g.@: @code{en}, @code{it}, @code{es},
279 @code{de}, @code{pt-BR}.
282 @node SPV Structure label Element
283 @subsection The @code{label} Element
285 Parent: @code{heading} or @code{container} @*
288 Every @code{heading} and @code{container} holds a @code{label} as its
289 first child. The root @code{heading} in a structure member always
290 contains the string ``Output''. Otherwise, the text in @code{label}
291 describes what it labels, often by naming the statistical procedure
292 that was executed, e.g.@: ``Frequencies'' or ``T-Test''. Labels are
293 often very generic, especially within a @code{container}, e.g.@:
294 ``Title'' or ``Warnings'' or ``Notes''. Label text is localized
295 according to the output language, e.g.@: in Italian a frequency table
296 procedure is labeled ``Frequenze''.
298 The corpus contains one example of an empty label, one that contains
301 This element has no attributes.
303 @node SPV Structure container Element
304 @subsection The @code{container} Element
306 Parent: @code{heading} @*
307 Contents: @code{label} (@code{table} @math{|} @code{text})?
309 A @code{container} serves to label a @code{table} or a @code{text}
312 This element has the following attributes.
314 @defvr {Required} @code{visibility}
315 Either @code{visible} or @code{hidden}, this indicates whether the
316 container's content is displayed.
319 @defvr {Optional} @code{text-align}
320 Presumably indicates the alignment of text within the container. The
321 only observed value is @code{left}. Observed with nested @code{table}
322 and @code{text} elements.
325 @defvr {Optional} @code{width}
326 The width of the container in the form @code{@var{n}px}, e.g.@:
330 @node SPV Structure text Element (Inside @code{container})
331 @subsection The @code{text} Element (Inside @code{container})
333 Parent: @code{container} @*
334 Contents: @code{html}
336 This @code{text} element is nested inside a @code{container}. There
337 is a different @code{text} element that is nested inside a
338 @code{pageParagraph}.
340 This element has the following attributes.
342 @defvr {Required} @code{type}
343 One of @code{title}, @code{log}, or @code{text}.
346 @defvr {Optional} @code{commandName}
347 As on the @code{heading} element. For output not specific to a
348 command, this is simply @code{log}. The corpus contains one example
349 of where @code{commandName} is present but set to the empty string.
352 @defvr {Optional} @code{creator-version}
353 As on the @code{heading} element.
356 @node SPV Structure html Element
357 @subsection The @code{html} Element
359 Parent: @code{text} @*
362 The CDATA contains an HTML document. In some cases, the document
363 starts with @code{<html>} and ends with @code{</html>}; in others the
364 @code{html} element is implied. Generally the HTML includes a
365 @code{head} element with a CSS stylesheet. The HTML body often begins
366 with @code{<BR>}. The actual content ranges from trivial to simple:
367 just discarding the CSS and tags yields readable results.
369 This element has the following attributes.
371 @defvr {Required} @code{lang}
372 This always contains @code{en} in the corpus.
375 @node SPV Structure table Element
376 @subsection The @code{table} Element
378 Parent: @code{container} @*
379 Contents: @code{tableStructure}
381 This element has the following attributes.
383 @defvr {Required} @code{commandName}
384 As on the @code{heading} element.
387 @defvr {Required} @code{type}
388 One of @code{table}, @code{note}, or @code{warning}.
391 @defvr {Required} @code{subType}
392 The locale-invariant name for the particular kind of output that this
393 table represents in the procedure. This can be the same as
394 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
395 @code{Case Processing Summary}. Generic subtypes @code{Notes} and
396 @code{Warnings} are often used.
399 @defvr {Required} @code{tableId}
400 A number that uniquely identifies the table within the SPV file,
401 typically a large negative number such as @code{-4147135649387905023}.
404 @defvr {Optional} @code{creator-version}
405 As on the @code{heading} element. In the corpus, this is only present
406 for version 21 and up and always includes all 8 digits.
409 @node SPV Structure tableStructure Element
410 @subsection The @code{tableStructure} Element
412 Parent: @code{table} @*
413 Contents: @code{dataPath}
415 This element has no attributes.
417 @node SPV Structure dataPath Element
418 @subsection The @code{dataPath} Element
420 Parent: @code{tableStructure} @*
423 Contains the name of the Zip member that holds the table details,
424 e.g.@: @code{0000000001437_lightTableData.bin}.
426 This element has no attributes.
428 @node SPV Structure pageSetup Element
429 @subsection The @code{pageSetup} Element
431 Parent: @code{heading} @*
432 Contents: @code{pageHeader} @code{pageFooter}
434 This element has the following attributes.
436 @defvr {Required} @code{initial-page-number}
440 @defvr {Optional} @code{chart-size}
441 Always @code{as-is} or a localization (!) of it (e.g.@: @code{dimensione
442 attuale}, @code{Wie vorgegeben}).
445 @defvr {Optional} @code{margin-left}
446 @defvrx {Optional} @code{margin-right}
447 @defvrx {Optional} @code{margin-top}
448 @defvrx {Optional} @code{margin-bottom}
449 Margin sizes in the form @code{@var{size}in}, e.g.@: @code{0.25in}.
452 @defvr {Optional} @code{paper-height}
453 @defvrx {Optional} @code{paper-width}
454 Paper sizes in the form @code{@var{size}in}, e.g.@: @code{8.5in} by
455 @code{11in} for letter paper or @code{8.267in} by @code{11.692in} for
459 @defvr {Optional} @code{reference-orientation}
463 @defvr {Optional} @code{space-after}
467 @node SPV Structure pageHeader and pageFooter Elements
468 @subsection The @code{pageHeader} and @code{pageFooter} Elements
470 Parent: @code{pageSetup} @*
471 Contents: @code{pageParagraph}*
473 This element has no attributes.
475 @node SPV Structure pageParagraph Element
476 @subsection The @code{pageParagraph} Element
478 Parent: @code{pageHeader} or @code{pageFooter} @*
479 Contents: @code{text}
481 Text to go at the top or bottom of a page, respectively.
483 This element has no attributes.
485 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
486 @subsection The @code{text} Element (Inside @code{pageParagraph})
488 Parent: @code{pageParagraph} @*
491 This @code{text} element is nested inside a @code{pageParagraph}. There
492 is a different @code{text} element that is nested inside a
495 The element is either empty, or contains CDATA that holds almost-XHTML
496 text: in the corpus, either an @code{html} or @code{p} element. It is
497 @emph{almost}-XHTML because the @code{html} element designates the
499 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of an XHTML
500 namespace, and because the CDATA can contain substitution variables:
501 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
504 Typical contents (indented for clarity):
507 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
510 <p style="text-align:right; margin-top: 0">Page &[Page]</p>
515 This element has the following attributes.
517 @defvr {Required} @code{type}
521 @node SPV Light Detail Member Format
522 @section Light Detail Member Format
524 This section describes the format of ``light'' detail @file{.bin}
525 members. These members have a binary format which we describe here in
526 terms of a context-free grammar using the following conventions:
529 @item NonTerminal @result{} @dots{}
530 Nonterminals have CamelCaps names, and @result{} indicates a
531 production. The right-hand side of a production is often broken
532 across multiple lines. Break points are chosen for aesthetics only
533 and have no semantic significance.
535 @item 00, 01, @dots{}, ff.
536 A bytes with a fixed value, written as a pair of hexadecimal digits.
538 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
539 @itemx b0, b1, @dots{}, b9, b10, b11, @dots{}
540 A 32-bit integer in little-endian or big-endian byte order,
541 respectively, with a fixed value, written in decimal, prefixed by
548 A byte with value 0 or 1.
552 A 16-bit integer in little-endian or big-endian byte order,
557 A 32-bit integer in little-endian or big-endian byte order,
562 A 64-bit integer in little-endian or big-endian byte order,
566 A 64-bit IEEE floating-point number.
569 A 32-bit IEEE floating-point number.
573 A 32-bit integer, in little-endian or big-endian byte order,
574 respectively, followed by the specified number of bytes of character
575 data. (The encoding is indicated by the Formats nonterminal.)
578 @var{x} is optional, e.g.@: 00? is an optional zero byte.
580 @item @var{x}*@var{n}
581 @var{x} is repeated @var{n} times, e.g. byte*10 for ten arbitrary bytes.
583 @item @var{x}[@var{name}]
584 Gives @var{x} the specified @var{name}. Names are used in textual
585 explanations. They are also used, also bracketed, to indicate counts,
586 e.g.@: int[@t{n}] byte*[@t{n}] for a 32-bit integer followed by the
587 specified number of arbitrary bytes.
589 @item @var{a} @math{|} @var{b}
590 Either @var{a} or @var{b}.
593 Parentheses are used for grouping to make precedence clear, especially
594 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
598 A 32-bit integer that indicates the number of bytes in @var{x},
599 followed by @var{x} itself.
602 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
603 (The @file{.bin} header indicates the version.)
606 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
609 Little-endian byte order is far more common in this format, but a few
610 pieces of the format use big-endian byte order.
612 A ``light'' detail member @file{.bin} consists of a number of sections
613 concatenated together, terminated by a byte 01:
617 LightMember @result{}
620 Fonts Borders PrintSettings TableSettings Formats
626 The following sections go into more detail.
629 * SPV Light Member Header::
630 * SPV Light Member Title::
631 * SPV Light Member Caption::
632 * SPV Light Member Footnotes::
633 * SPV Light Member Fonts::
634 * SPV Light Member Borders::
635 * SPV Light Member Print Settings::
636 * SPV Light Member Table Settings::
637 * SPV Light Member Formats::
638 * SPV Light Member Dimensions::
639 * SPV Light Member Categories::
640 * SPV Light Member Data::
641 * SPV Light Member Value::
642 * SPV Light Member ValueMod::
645 @node SPV Light Member Header
648 An SPV light member begins with a 39-byte header:
654 (i1 @math{|} i3)[@t{version}]
656 bool[@t{show-numeric-markers}]
657 bool[@t{rotate-inner-column-labels}]
658 bool[@t{rotate-outer-row-labels}]
661 int[@t{min-column-width}] int[@t{max-column-width}]
662 int[@t{min-row-width}] int[@t{max-row-width}]
667 @code{version} is a version number that affects the interpretation of
668 some of the other data in the member. We will refer to ``version 1''
669 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
670 version-specific formatting (as described previously).
672 If @code{show-numeric-markers} is 1, footnote markers are shown as
673 numbers, starting from 1; otherwise, they are shown as letters,
674 starting from @samp{a}.
676 If @code{rotate-inner-column-labels} is 1, then column labels closest
677 to the data are rotated to be vertical; otherwise, they are shown
680 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
681 the data are rotated to be vertical; otherwise, they are shown in the
684 @code{table-id} is a binary version of the @code{tableId} attribute in
685 the structure member that refers to the detail member. For example,
686 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
687 would be 0xc6c99d183b300001.
689 @code{min-column-width} is the minimum width that a column will be
690 assigned automatically. @code{max-column-width} is the maximum width
691 that a column will be assigned to accommodate a long column label.
692 @code{min-row-width} and @code{max-row-width} are a similar range for
693 the width of row labels. All of these measurements are in 1/96 inch
696 The meaning of the other variable parts of the header is not known.
698 @node SPV Light Member Title
704 Value[@t{title1}] 01?
706 Value[@t{title2}] 01?
710 The Title, which follows the Header, specifies the pivot table's title
711 twice, as @code{title1} and @code{title2}. In the corpus, they are
714 Whereas the Value in @code{title1} and in @code{title2} are
715 appropriate for presentation, and localized to the user's language,
716 @code{c} is in English, sometimes less specific, and sometimes less
717 well formatted. For example, for a frequency table, @code{title1} and
718 @code{title2} name the variable and @code{c} is simply ``Frequencies''.
720 @node SPV Light Member Caption
725 Caption @result{} Caption1 Caption2
726 Caption1 @result{} 31 Value @math{|} 58
727 Caption2 @result{} 31 Value @math{|} 58
731 The Caption, if present, is shown below the table. Caption2 is
732 normally present. Caption1 is only rarely nonempty; it might reflect
733 user editing of the caption.
735 @node SPV Light Member Footnotes
736 @subsection Footnotes
740 Footnotes @result{} int[@t{n}] Footnote*[@t{n}]
741 Footnote @result{} Value[@t{text}] (58 @math{|} 31 Value[@t{marker}]) byte*4
745 Each footnote has @code{text} and an optional customer @code{marker}
748 @node SPV Light Member Fonts
753 Fonts @result{} 00 Font*8
756 string[@t{typeface}] float[@t{size}] int[@t{style}] bool[@t{underline}]
757 int[@t{halign}] int[@t{valign}]
758 string[@t{fgcolor}] string[@t{bgcolor}]
759 byte[@t{alternate}] string[@t{altfg}] string[@t{altbg}]
760 v3(int[@t{left-margin}] int[@t{right-margin}] int[@t{top-margin}] int[@t{bottom-margin}])
764 Each Font represents the font style for a different element, in the
765 following order: title, caption, footer, corner, column
766 labels, row labels, data, and layers.
768 @code{index} is the 1-based index of the Font, i.e. 1 for the first
769 Font, through 8 for the final Font.
771 @code{typeface} is the string name of the font. In the corpus, this
772 is @code{SansSerif} in over 99% of instances and @code{Times New
775 @code{size} is the size of the font, in points. The most common size
776 in the corpus is 12 points.
778 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
779 1 (with value 2) is set for italic.
781 @code{underline} is 1 if the font is underlined, 0 otherwise.
783 @code{halign} specifies horizontal alignment: 0 for center, 2 for
784 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
785 alignment varies according to type: string data is left-justified,
786 numbers and most other formats are right-justified.
788 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
791 @code{fgcolor} and @code{bgcolor} are the foreground color and
792 background color, respectively. In the corpus, these are always
793 @code{#000000} and @code{#ffffff}, respectively.
795 @code{alternate} is 01 if rows should alternate colors, 00 if all rows
796 should be the same color. When @code{alternate} is 01, @code{altfg}
797 and @code{altbg} specify the colors for the alternate rows.
799 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
800 @code{bottom-margin} are measured in multiples of 1/96 inch.
802 @node SPV Light Member Borders
809 be32[@t{n-borders}] Border*[@t{n-borders}]
810 bool[@t{show-grid-lines}]
814 be32[@t{border-type}]
815 be32[@t{stroke-type}]
820 The Borders reflect how borders between regions are drawn.
822 The fixed value of @code{endian} can be used to validate the
825 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
827 Each Border describes one kind of border. @code{n-borders} seems to
828 always be 19. Each @code{border-type} appears once (although in an
829 unpredictable order) and correspond to the following borders:
835 Left, top, right, and bottom outer frame.
837 Left, top, right, and bottom inner frame.
839 Left and top of data area.
841 Horizontal and vertical dimension rows.
843 Horizontal and vertical dimension columns.
845 Horizontal and vertical category rows.
847 Horizontal and vertical category columns.
850 @code{stroke-type} describes how a border is drawn, as one of:
867 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
868 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
869 opaque color, therefore opaque black is 0xff000000.
871 @node SPV Light Member Print Settings
872 @subsection Print Settings
876 PrintSettings @result{}
879 bool[@t{paginate-layers}]
882 bool[@t{top-continuation}]
883 bool[@t{bottom-continuation}]
884 be32[@t{n-orphan-lines}]
885 bestring[@t{continuation-string}]
889 The PrintSettings reflect settings for printing. The fixed value of
890 @code{endian} can be used to validate the endianness.
892 @code{all-layers} is 1 to print all layers, 0 to print only the
895 @code{paginate-layers} is 1 to print each layer at the start of a new
896 page, 0 otherwise. (This setting is honored only @code{all-layers} is
897 1, since otherwise only one layer is printed.)
899 @code{fit-width} and @code{fit-length} control whether the table is
900 shrunk to fit within a page's width or length, respectively.
902 @code{n-orphan-lines} is the minimum number of rows or columns to put
903 in one part of a table that is broken across pages.
905 If @code{top-continuation} is 1, then @code{continuation-string} is
906 printed at the top of a page when a table is broken across pages for
907 printing; similarly for @code{bottom-continuation} and the bottom of a
908 page. Usually, @code{continuation-string} is empty.
910 @node SPV Light Member Table Settings
911 @subsection Table Settings
915 TableSettings @result{}
918 be32[@t{current-layer}]
920 bool[@t{show-row-labels-in-corner}]
921 bool[@t{show-alphabetic-markers}]
922 bool[@t{footnote-marker-position}]
926 Breakpoints[@t{row-breaks}] Breakpoints[@t{column-breaks}]
927 Keeps[@t{row-keeps}] Keeps[@t{column-keeps}]
928 PointKeeps[@t{row-keeps}] PointKeeps[@t{column-keeps}]
931 bestring[@t{table-look}]
935 Breakpoints @result{} be32[@t{n-breaks}] be32*[@t{n-breaks}]
937 Keeps @result{} be32[@t{n-keeps}] Keep*@t{n-keeps}
938 Keep @result{} be32[@t{offset}] be[@t{n}]
940 PointKeeps @result{} be32[@t{n-point-keeps}] PointKeep*@t{n-point-keeps}
941 PointKeep @result{} be32[@t{offset}] be32 be32
946 The TableSettings reflect display settings. The fixed value of
947 @code{endian} can be used to validate the endianness.
949 @code{current-layer} is the displayed layer.
951 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
952 any cell) are hidden; otherwise, they are shown.
954 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
955 the upper left corner; otherwise, they are shown nested.
957 If @code{show-alphabetic-markers} is 1, markers are shown as letters
958 (e.g. @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
959 shown as numbers starting from 1.
961 When @code{footnote-marker-position} is 1, footnote markers are shown
962 as superscripts, otherwise as subscripts.
964 The Breakpoints are rows or columns after which there is a page break;
965 for example, a row break of 1 requests a page break after the second
966 row. Usually no breakpoints are specified, indicating that page
967 breaks should be selected automatically.
969 The Keeps are ranges of rows or columns to be kept together without a
970 page break; for example, a row Keep with @code{offset} 1 and @code{n}
971 10 requests that the 10 rows starting with the second row be kept
972 together. Usually no Keeps are specified.
974 The PointKeeps seem to be generated automatically based on
975 user-specified Keeps. They seems to indicate a conversion from rows
976 or columns to pixel or point offsets.
978 @code{notes} is a text string that contains user-specified notes. It
979 is displayed when the user hovers the cursor over the table, like
980 ``alt text'' on a webpage. It is not printed. It is usually empty.
982 @code{table-look} is the name of a SPSS ``TableLook'' table style,
983 such as ``Default'' or ``Academic''; it is often empty.
985 TableSettings ends with an arbitrary number of null bytes.
987 @node SPV Light Member Formats
993 int[@t{n-widths}] int*[@t{n-widths}]
995 int[@t{current-layer}]
996 bool[@t{digit-grouping}] bool[@t{leading-zero}] bool
998 byte[@t{decimal}] byte[@t{grouping}]
1002 v3(count(X1 count(X2)) count(X3))
1006 string[@t{command}] string[@t{command-local}]
1007 string[@t{language}] string[@t{charset}] string[@t{locale}]
1010 byte[@t{decimal}] byte[@t{grouping}]
1012 byte[@t{missing}] bool
1017 byte[@t{variable-mode}]
1018 byte[@t{value-mode}]
1024 int[@t{n-heights}] int*[@t{n-heights}]
1025 int[@t{n-style-map}] BlankMap*[@t{n-style-map}]
1026 int[@t{n-styles}] StylePair*[@t{n-styles}]
1028 StyleMap @result{} int64[@t{cell-index}] int16[@t{style-index}]
1030 01 00 (03 @math{|} 04) 00 00 00
1031 string[@t{command}] string[@t{command-local}]
1032 string[@t{language}] string[@t{charset}] string[@t{locale}]
1035 byte[@t{decimal}] byte[@t{grouping}]
1036 double[@t{small}] 01
1037 (string[@t{dataset}] string[@t{datafile}] i0 int[@t{date}] i0)?
1039 byte[@t{missing}] bool (i2000000 i0)?
1041 CustomCurrency @result{} int[@t{n-ccs}] string*[@t{n-ccs}]
1045 If @code{n-widths} is nonzero, then the accompanying integers are
1046 column widths as manually adjusted by the user. (Row heights are
1047 computed automatically based on the widths.)
1049 @code{encoding} is a character encoding, usually a Windows code page
1050 such as @code{en_US.windows-1252} or @code{it_IT.windows-1252}. The
1051 rest of the character strings in the member use this encoding. The
1052 encoding string is itself encoded in US-ASCII.
1054 @code{epoch} is the year that starts the epoch. A 2-digit year is
1055 interpreted as belonging to the 100 years beginning at the epoch. The
1056 default epoch year is 69 years prior to the current year; thus, in
1057 2017 this field by default contains 1948. In the corpus, @code{epoch}
1058 ranges from 1943 to 1948, plus some contain -1.
1060 @code{decimal} is the decimal point character. The observed values
1061 are @samp{.} and @samp{,}.
1063 @code{grouping} is the grouping character. Usually, it is @samp{,} if
1064 @code{decimal} is @samp{.}, and vice versa. Other observed values are
1065 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1066 indicating that digits should not be grouped).
1068 @code{command} describes the statistical procedure that generated the
1069 output, in English. It is not necessarily the literal syntax name of
1070 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1071 Tests.'' @code{command-local} is the procedure's name, translated
1072 into the output language; it is often empty and, when it is not,
1073 sometimes the same as @code{command}.
1075 @code{dataset} is the name of the dataset analyzed to produce the
1076 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1077 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}. The latter
1078 is sometimes the empty string.
1080 @code{date} is a date, as seconds since the epoch, i.e.@: since
1081 January 1, 1970. Pivot tables within an SPV files often have dates a
1082 few minutes apart, so this is probably a creation date for the tables
1083 rather than for the file.
1085 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1086 and other times they are absent. The reader can distinguish by
1087 assuming that they are present and then checking whether the
1088 presumptive @code{dataset} contains a null byte (a valid string never
1091 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
1092 following strings are CCA through CCE format strings. @xref{Custom
1093 Currency Formats,,, pspp, PSPP}. Most commonly these are all
1094 @code{-,,,} but other strings occur.
1096 @code{missing} is the character used to indicate that a cell contains
1097 a missing value. It is always observed as @samp{.}.
1099 @node SPV Light Member Dimensions
1100 @subsection Dimensions
1102 A pivot table presents multidimensional data. A Dimension identifies
1103 the categories associated with each dimension.
1107 Dimensions @result{} int[@t{n-dims}] Dimension*[@t{n-dims}]
1108 Dimension @result{} Value[@t{name}] DimProperties int[@t{n-categories}] Category*[@t{n-categories}]
1109 DimProperties @result{}
1111 (00 @math{|} 01 @math{|} 02)[@t{d2}]
1112 (i0 @math{|} i2)[@t{d3}]
1113 bool[@t{show-dim-label}]
1114 bool[@t{hide-all-labels}]
1115 01 int[@t{dim-index}]
1119 @code{name} is the name of the dimension, e.g. @code{Variables},
1120 @code{Statistics}, or a variable name.
1122 The meanings of @code{d1}, @code{d2}, and @code{d3} are unknown.
1123 @code{d1} is usually 0 but many other values have been observed.
1125 If @code{show-dim-label} is 01, the pivot table displays a label for
1126 the dimension itself. Because usually the group and category labels
1127 are enough explanation, it is usually 00.
1129 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1130 the dimension, including group and category labels. It is usually 00.
1131 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1133 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1134 0 for the first dimension, 1 for the second, and so on. Sometimes it
1135 is -1. There is no visible difference.
1137 @node SPV Light Member Categories
1138 @subsection Categories
1140 Categories are arranged in a tree. Only the leaf nodes in the tree
1141 are really categories; the others just serve as grouping constructs.
1145 Category @result{} Value[@t{name}] (Leaf @math{|} Group)
1146 Leaf @result{} 00 00 00 i2 int[@t{cat-index}] i0
1148 bool[@t{merge}] 00 01 (i0 @math{|} i2)[@t{data}]
1149 i-1 int[@t{n-subcategories}] Category*[@t{n-subcategories}]
1153 @code{name} is the name of the category (or group).
1155 A Leaf represents a leaf category. The Leaf's @code{cat-index} is a
1156 nonnegative integer less than @code{n-categories} in the Dimension in
1157 which the Category is nested (directly or indirectly). These
1158 categories represent the original order in which the categories were
1159 sorted; if the user sorted or rearranged the categories, then the
1160 order of categories in the file reflects that without changing the
1161 @code{cat-index} values.
1163 A Group is a group of nested categories. Usually a Group contains at
1164 least one Category, so that @code{n-subcategories} is positive, but a
1165 few Groups with @code{n-subcategories} 0 has been observed.
1167 If a Group's @code{merge} is 00, the most common value, then the group
1168 is really a distinct group that should be represented as such in the
1169 visual representation and user interface. If @code{merge} is 01, the
1170 categories in this group should be shown and treated as if they were
1171 direct children of the group's containing group (or if it has no
1172 parent group, then direct children of the dimension), and this group's
1173 name is irrelevant and should not be displayed. (Merged groups can be
1176 A Group's @code{data} appears to be i2 when all of the categories
1177 within a group are leaf categories that directly represent data values
1178 for a variable (e.g. in a frequency table or crosstabulation, a group
1179 of values in a variable being tabulated) and i0 otherwise.
1181 @node SPV Light Member Data
1184 The final part of an SPV light member contains the actual data.
1189 int[@t{layers}] int[@t{rows}] int[@t{columns}] int*[@t{n-dimensions}]
1190 int[@t{n-data}] Datum*[@t{n-data}]
1191 Datum @result{} int64[@t{index}] v1(00?) Value
1195 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1196 each specifies the number of dimensions displayed in layers, rows, and
1197 columns, respectively. Any of them may be zero. Their values sum to
1198 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1201 The @code{n-dimensions} integers are a permutation of the 0-based
1202 dimension numbers. The first @code{n-layers} integers specify each of
1203 the dimensions represented by layers, the next @code{n-rows} integers
1204 specify the dimensions represented by rows, and the final
1205 @code{n-columns} integers specify the dimensions represented by
1206 columns. When there is more than one dimension of a given kind, the
1207 inner dimensions are given first.
1209 The format of a Datum varies slightly from version 1 to version 3: in
1210 version 1 it allows for an extra optional 00 byte.
1212 A Datum consists of an @code{index} and a Value. Suppose there are
1213 @math{d} dimensions and dimension @math{i}, @math{0 \le i < d}, has
1214 @math{n_i} categories. Consider the datum at coordinates @math{x_i},
1215 @math{0 \le i < d}, and note that @math{0 \le x_i < n_i}. Then the
1216 index is calculated by the following algorithm:
1220 for each @math{i} from 0 to @math{d - 1}:
1221 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1224 For example, suppose there are 3 dimensions with 3, 4, and 5
1225 categories, respectively. The datum at coordinates (1, 2, 3) has
1226 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1227 Within a given dimension, the index is the @code{cat-index} in a Leaf.
1229 @node SPV Light Member Value
1232 Value is used throughout the SPV light member format. It boils down
1233 to a number or a string.
1237 Value @result{} 00? 00? 00? 00? RawValue
1239 01 ValueMod int[@t{format}] double[@t{x}]
1240 @math{|} 02 ValueMod int[@t{format}] double[@t{x}]
1241 string[@t{varname}] string[@t{vallab}] (01 @math{|} 02 @math{|} 03)
1242 @math{|} 03 string[@t{local}] ValueMod string[@t{id}] string[@t{c}] bool[@t{type}]
1243 @math{|} 04 ValueMod int[@t{format}] string[@t{vallab}] string[@t{varname}]
1244 (01 @math{|} 02 @math{|} 03) string[@t{s}]
1245 @math{|} 05 ValueMod string[@t{varname}] string[@t{varlabel}] (01 @math{|} 02 @math{|} 03)
1246 @math{|} ValueMod string[@t{format}] int[@t{n-args}] Argument*[@t{n-args}]
1249 @math{|} int[@t{x}] i0 Value*[@t{x}@math{+}1] /* @t{x} @math{>} 0 */
1253 There are several possible encodings, which one can distinguish by the
1254 first nonzero byte in the encoding.
1258 The numeric value @code{x}, intended to be presented to the user
1259 formatted according to @code{format}, which is in the format described
1260 for system files. @xref{System File Output Formats}, for details.
1261 Most commonly, @code{format} has width 40 (the maximum).
1263 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1264 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1265 not been observed.) @xref{System File Format}, for more about these
1269 Similar to @code{01}, with the additional information that @code{x} is
1270 a value of variable @code{varname} and has value label @code{vallab}.
1271 Both @code{varname} and @code{vallab} can be the empty string, the
1272 latter very commonly.
1274 The meaning of the final byte is unknown. Possibly it is connected to
1275 whether the value or the label should be displayed.
1278 A text string, in two forms: @code{c} is in English, and sometimes
1279 abbreviated or obscure, and @code{local} is localized to the user's
1280 locale. In an English-language locale, the two strings are often the
1281 same, and in the cases where they differ, @code{local} is more
1282 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1283 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1284 where P must be greater than 1.''
1286 @code{c} and @code{local} are always either both empty or both
1289 @code{id} is a brief identifying string whose form seems to resemble a
1290 programming language identifier, e.g.@: @code{cumulative_percent} or
1291 @code{factor_14}. It is not unique.
1293 @code{type} is 00 for text taken from user input, such as syntax
1294 fragment, expressions, file names, data set names, and 01 for fixed
1295 text strings such as names of procedures or statistics. In the former
1296 case, @code{id} is always the empty string; in the latter case,
1297 @code{id} is still sometimes empty.
1300 The string value @code{s}, intended to be presented to the user
1301 formatted according to @code{format}. The format for a string is not
1302 too interesting, and the corpus contains many clearly invalid formats
1303 like A16.39 or A255.127 or A134.1, so readers should probably ignore
1304 the format entirely.
1306 @code{s} is a value of variable @code{varname} and has value label
1307 @code{vallab}. @code{varname} is never empty but @code{vallab} is
1310 The meaning of the final byte is unknown.
1313 Variable @code{varname}, which is rarely observed as empty in the
1314 corpus, with variable label @code{varlabel}, which is often empty.
1316 The meaning of the final byte is unknown.
1319 (These bytes begin a ValueMod.) A format string, analogous to
1320 @code{printf}, followed by one or more Arguments, each of which has
1321 one or more values. The format string uses the following syntax:
1328 Each of these expands to the character following @samp{\\}, to escape
1329 characters that have special meaning in format strings. These are
1330 effective inside and outside the @code{[@dots{}]} syntax forms
1334 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1338 Expands to a formatted version of argument @var{i}, which must have
1339 only a single value. For example, @code{^1} expands to the first
1340 argument's @code{value}.
1342 @item [:@var{a}:]@var{i}
1343 Expands @var{a} for each of the values in @var{i}. @var{a}
1344 should contain one or more @code{^@var{j}} conversions, which are
1345 drawn from the values for argument @var{i} in order. Some examples
1350 All of the values for the first argument, concatenated.
1353 Expands to the values for the first argument, each followed by
1357 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1358 argument's first value and @var{y} is its second value. (This would
1359 be used only if the argument has two values. If there were more
1360 values, the second and third values would be directly concatenated,
1361 which would look funny.)
1364 @item [@var{a}:@var{b}:]@var{i}
1365 This extends the previous form so that the first values are expanded
1366 using @var{a} and later values are expanded using @var{b}. For an
1367 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1368 instead written as @code{%@var{j}}. Some examples from the corpus:
1372 Expands to all of the values for the first argument, separated by
1375 @item [%1 = %2:, ^1 = ^2:]1
1376 Given appropriate values for the first argument, expands to @code{X =
1380 Given appropriate values, expands to @code{1, 2, 3}.
1384 The format string is localized to the user's locale.
1387 @node SPV Light Member ValueMod
1388 @subsection ValueMod
1390 A ValueMod can specify special modifications to a Value.
1395 31 i0 (i0 @math{|} i1 string[@t{subscript}])
1396 v1(00 (i1 @math{|} i2) 00 00 int 00 00)
1397 v3(count(FormatString StylePair))
1398 @math{|} 31 int[@t{n-refs}] int16*[@t{n-refs}] Format
1401 Format @result{} 00 00 count(FormatString Style 58)
1402 FormatString @result{} count((count((i0 58)?) (58 @math{|} 31 string))?)
1409 bool[@t{bold}] bool[@t{italic}] bool[@t{underline}] bool[@t{show}]
1410 string[@t{fgcolor}] string[@t{bgcolor}]
1411 string[@t{typeface}] byte[@t{size}]
1414 int[@t{halign}] int[@t{valign}] double[@t{offset}]
1415 int16[@t{left-margin}] int16[@t{right-margin}]
1416 int16[@t{top-margin}] int16[@t{bottom-margin}]
1420 A ValueMod that begins with ``31 i0'' specifies a string to append to
1421 the main text of the Value, as a subscript. The subscript text is a
1422 brief indicator, e.g.@: @samp{a} or @samp{a,b}, with its meaning
1423 indicated by the table caption. In this usage, subscripts are similar
1424 to footnotes. One apparent difference is that a Value can only
1425 reference one footnote but a subscript can list more than one letter.
1427 A ValueMod that begins with 31 followed by a nonzero ``int'' specifies
1428 a footnote or footnotes that the Value references. Footnote markers
1429 are shown appended to the main text of the Value, as superscripts.
1431 The Format, if present, is a format string for substitutions using the
1432 syntax explained previously. It appears to be an English-language
1433 version of the localized format string in the Value in which the
1436 Style and Style2, if present, change the style for this individual
1437 Value. @code{bold}, @code{italic}, and @code{underline} control the
1438 particular style. @code{fgcolor} and @code{bgcolor} are strings, such
1439 as @code{#ffffff}. The @code{size} is a font size in units of 1/96
1442 @code{halign} is 0 for center, 2 for left, 4 for right, 6 for decimal,
1443 0xffffffad for mixed. For decimal alignment, @code{offset} is the
1444 decimal point's offset from the right side of the cell, in units of
1447 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1450 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1451 @code{bottom-margin} are in units of 1/72 inch.
1453 @node SPV Legacy Detail Member Binary Format
1454 @section Legacy Detail Member Binary Format
1456 Whereas the light binary format represents everything about a given
1457 pivot table, the legacy binary format conceptually consists of a
1458 number of named sources, each of which consists of a number of named
1459 variables, each of which is a 1-dimensional array of numbers or
1460 strings or a mix. Thus, the legacy binary member format is quite
1463 This section uses the same context-free grammar notation as in the
1464 previous section, with the following additions:
1468 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
1469 (The legacy member header indicates the version; see below.)
1472 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
1475 A legacy detail member @file{.bin} has the following overall format:
1479 LegacyBinary @result{}
1480 00 byte[@t{version}] int16[@t{n-sources}] int[@t{member-size}]
1481 Metadata*[@t{n-sources}] Data*[@t{n-sources}]
1485 @code{version} is a version number that affects the interpretation of
1486 some of the other data in the member. Versions 0xaf and 0xb0 are
1487 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
1490 A legacy member consists of @code{n-sources} data sources, each of
1491 which has Metadata and Data.
1493 @code{member-size} is the size of the legacy binary member, in bytes.
1495 The following sections go into more detail.
1498 * SPV Legacy Member Metadata::
1499 * SPV Legacy Member Data::
1502 @node SPV Legacy Member Metadata
1503 @subsection Metadata
1508 int[@t{n-data}] int[@t{n-variables}] int[@t{offset}]
1509 vAF(byte*32[@t{source-name}])
1510 vB0(byte*64[@t{source-name}] int[@t{x}])
1514 A data source has @code{n-variables} variables, each with
1515 @code{n-data} data values.
1517 @code{source-name} is a 32- or 64-byte string padded on the right with
1518 zero bytes. The names that appear in the corpus are very generic:
1519 usually @code{tableData} for pivot table data or @code{source0} for
1522 A given Metadata's @code{offset} is the offset, in bytes, from the
1523 beginning of the member to the start of the corresponding Data. This
1524 allows programs to skip to the beginning of the data for a particular
1525 source; it is also important to determine whether a source includes
1526 any string data (@pxref{SPV Legacy Member Data}).
1528 The meaning of @code{x} in version 0xb0 is unknown.
1530 @node SPV Legacy Member Data
1535 Data @result{} NumericData*[@t{n-variables}] StringData?
1536 NumericData @result{} byte*288[@t{variable-name}] double*[@t{n-data}]
1540 Data follow the Metadata in the legacy binary format, with sources in
1541 the same order. Each NumericSeries begins with a @code{variable-name}
1542 that generally indicates its role in the pivot table, e.g.@: ``cell'',
1543 ``cellFormat'', ``dimension0categories'', ``dimension0group0'',
1544 followed by the numeric data, one double per datum. A double with the
1545 maximum negative double @code{-DBL_MAX} represents the system-missing
1550 StringData @result{} i1 string[@t{source-name}] Pairs Labels
1552 Pairs @result{} int[@t{n-string-vars}] PairSeries*[@t{n-string-vars}]
1553 PairVar @result{} string[@t{pair-var-name}] int[@t{n-pairs}] Pair*[@t{n-pairs}]
1554 Pair @result{} int[@t{i}] int[@t{j}]
1556 Labels @result{} int[@t{n-labels}] Label*[@t{n-labels}]
1557 Label @result{} int[@t{frequency}] int[@t{s}]
1561 A source may include a mix of numeric and string data values. When a
1562 source includes any string data, the data values that are strings are
1563 set to SYSMIS in the NumericData, and StringData follows the
1564 NumericData. A source that contains no string data omits the
1565 StringData. To reliably determine whether a source includes
1566 StringData, the reader should check whether the offset following the
1567 NumericData is the offset of the next source, as indicated by its
1568 Metadata (or the end of the member, in the case of the last source).
1570 StringData repeats the name of the source (from Metadata).
1572 The string data overlays the numeric data. @code{n-string-vars} is
1573 the number of variables in the source that include string data. More
1574 precisely, it is the 1-based index of the last variable in the source
1575 that includes any string data; thus, it would be 4 if there are 5
1576 variables and only the fourth one includes string data.
1578 Each PairVar consists a sequence of 0 or more Pair nonterminals, each
1579 of which maps from a 0-based index within variable @code{i} to a
1580 0-based label index @code{j}, e.g.@: pair @code{i} = 2, @code{j} = 3,
1581 means that the third data value (with value SYSMIS) is to be replaced
1582 by the string of the fourth Label.
1584 The labels themselves follow the pairs. The valuable part of each
1585 label is the string @code{s}. Each label also includes a
1586 @code{frequency} that reports the number of pairs that reference it
1587 (although this is not useful).
1589 @node SPV Legacy Detail Member XML Format
1590 @section Legacy Detail Member XML Format
1592 This format is still under investigation.
1594 The design of the detail XML format is not what one would end up with
1595 for describing pivot tables. This is because it is a special case
1596 of a much more general format (``visualization XML'' or ``VizML'')
1597 that can describe a wide range of visualizations. Most of this
1598 generality is overkill for tables, and so we end up with a funny
1599 subset of a general-purpose format.
1601 The important elements of the detail XML format are:
1605 Variables. Variables in detail XML roughly correspond to the
1606 dimensions in a light detail member. There is one variable for each
1607 dimension, plus one variable for each level of labeling along an axis.
1609 The bulk of variables are defined with @code{sourceVariable} elements.
1610 The data for these variables comes from the associated
1611 @code{tableData.bin} member. Some variables are defined, with
1612 @code{derivedVariable} elements, as a constant or in terms of a
1613 mapping function from a source variable.
1616 Assignment of variables to axes. A variable can appear as columns, or
1617 rows, or layers. The @code{faceting} element and its sub-elements
1618 describe this assignment.
1621 All elements have an optional @code{id} attribute. In practice many
1622 elements are assigned @code{id} attributes that are never referenced.
1625 * SPV Detail visualization Element::
1626 * SPV Detail userSource Element::
1627 * SPV Detail sourceVariable Element::
1628 * SPV Detail derivedVariable Element::
1629 * SPV Detail extension Element::
1630 * SPV Detail graph Element::
1631 * SPV Detail location Element::
1632 * SPV Detail coordinates Element::
1633 * SPV Detail faceting Element::
1634 * SPV Detail facetLayout Element::
1635 * SPV Detail style Element::
1638 @node SPV Detail visualization Element
1639 @subsection The @code{visualization} Element
1642 Parent: Document root
1646 (sourceVariable @math{|} derivedVariable)@math{+}
1654 This element has the following attributes.
1656 @defvr {Required} creator
1657 The version of the software that created this SPV file, as a string of
1658 the form @code{xxyyzz}, which represents software version xx.yy.zz,
1659 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
1660 versions 16 through 19.
1663 @defvr {Required} date
1664 The date on the which the file was created, as a string of the form
1668 @defvr {Required} lang
1669 The locale used for output, in Windows format, which is similar to the
1670 format used in Unix with the underscore replaced by a hyphen, e.g.@:
1671 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
1674 @defvr {Required} name
1675 The title of the pivot table, localized to the output language.
1678 @defvr {Required} style
1679 The @code{id} of a @code{style} element (@pxref{SPV Detail style
1680 Element}). This is the base style for the entire pivot table. In
1681 every example in the corpus, the value is @code{visualizationStyle}
1682 and the corresponding @code{style} element has no attributes other
1686 @defvr {Required} type
1687 A floating-point number. The meaning is unknown.
1690 @defvr {Required} version
1691 The visualization schema version number. In the corpus, the value is
1692 one of 2.4, 2.5, 2.7, and 2.8.
1695 @node SPV Detail userSource Element
1696 @subsection The @code{userSource} Element
1698 Parent: @code{visualization} @*
1701 This element has the following attributes.
1703 @defvr {Optional} missing
1704 Always @code{listwise}.
1707 @node SPV Detail sourceVariable Element
1708 @subsection The @code{sourceVariable} Element
1710 Parent: @code{visualization} @*
1711 Contents: @code{extension}* (@code{format} @math{|} @code{stringFormat})?
1713 This element defines a variable whose values can be used elsewhere in
1714 the visualization. It ties this element's @code{id} to a variable
1715 from the @file{tableData.bin} member that corresponds to this
1718 This element has the following attributes.
1720 @defvr {Required} categorical
1721 Always set to @code{true}.
1724 @defvr {Required} source
1725 Always set to @code{tableData}, the @code{source-name} in the
1726 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
1730 @defvr {Required} sourceName
1731 The name of a variable within the source, the @code{variable-name} in
1732 the corresponding @file{tableData.bin} member (@pxref{SPV Legacy
1736 @defvr {Optional} dependsOn
1737 The @code{variable-name} of a variable linked to this one, so that a
1738 viewer can work with them together. For a group variable, this is the
1739 name of the corresponding categorical variable.
1742 @defvr {Optional} label
1743 The variable label, if any
1746 @defvr {Optional} labelVariable
1747 The @code{variable-name} of a variable whose string values correspond
1748 one-to-one with the values of this variable and are suitable for use
1752 @node SPV Detail derivedVariable Element
1753 @subsection The @code{derivedVariable} Element
1755 Parent: @code{visualization} @*
1756 Contents: @code{extension}* (@code{format} @math{|} @code{stringFormat} @code{valueMapEntry}*)
1758 Like @code{sourceVariable}, this element defines a variable whose
1759 values can be used elsewhere in the visualization. Instead of being
1760 read from a data source, the variable's data are defined by a
1761 mathematical expression.
1763 This element has the following attributes.
1765 @defvr {Required} categorical
1766 Always set to @code{true}.
1769 @defvr {Required} value
1770 An expression that defines the variable's value. In theory this could
1771 be an arbitrary expression in terms of constants, functions, and other
1772 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
1773 the corpus contains only the following forms of expressions:
1776 @item constant(@var{number})
1777 @itemx constant(@var{variable})
1778 A constant. The meaning when a variable is named is unknown.
1779 Sometimes the ``variable name'' has spaces in it.
1781 @item map(@var{variable})
1782 Transforms the values in the named @var{variable} using the
1783 @code{valueMapEntry}s contained within the element.
1787 @defvr {Optional} dependsOn
1788 The @code{variable-name} of a variable linked to this one, so that a
1789 viewer can work with them together. For a group variable, this is the
1790 name of the corresponding categorical variable.
1794 * SPV Detail valueMapEntry Element::
1797 @node SPV Detail valueMapEntry Element
1798 @subsubsection The @code{valueMapEntry} Element
1800 Parent: @code{derivedVariable} @*
1803 A @code{valueMapEntry} element defines a mapping from one or more
1804 values of a source expression to a target value. (In the corpus, the
1805 source expression is always just the name of a variable.) Each target
1806 value requires a separate @code{valueMapEntry}. If multiple source
1807 values map to the same target value, they can be combined or separate.
1809 @code{valueMapEntry} has the following attributes.
1811 @defvr {Required} from
1812 A source value, or multiple source values separated by semicolons,
1813 e.g.@: @code{0} or @code{13;14;15;16}.
1816 @defvr {Required} to
1820 @node SPV Detail extension Element
1821 @subsection The @code{extension} Element
1823 This is a general-purpose ``extension'' element. Readers that don't
1824 understand a given extension should be able to safely ignore it. The
1825 attributes on this element, and their meanings, vary based on the
1826 context. Each known usage is described separately below. The current
1827 extensions use attributes exclusively, without any nested elements.
1829 @subsubheading @code{visualization} Parent Element
1831 With @code{visualization} as its parent element, @code{extension} has
1832 the following attributes.
1834 @defvr {Optional} numRows
1835 An integer that presumably defines the number of rows in the displayed
1839 @defvr {Optional} showGridline
1840 Always set to @code{false} in the corpus.
1843 @defvr {Optional} minWidthSet
1844 @defvrx {Optional} maxWidthSet
1845 Always set to @code{true} in the corpus.
1848 @subsubheading @code{container} Parent Element
1850 With @code{container} as its parent element, @code{extension} has the
1851 following attributes.
1853 @defvr {Required} combinedFootnotes
1854 Always set to @code{true} in the corpus.
1857 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
1859 With @code{sourceVariable} or @code{derivedVariable} as its parent
1860 element, @code{extension} has the following attributes. A given
1861 parent element often contains several @code{extension} elements that
1862 specify the meaning of the source data's variables or sources, e.g.@:
1865 <extension from="0" helpId="corrected_model"/>
1866 <extension from="3" helpId="error"/>
1867 <extension from="4" helpId="total_9"/>
1868 <extension from="5" helpId="corrected_total"/>
1871 @defvr {Required} from
1872 An integer or a name like ``dimension0''.
1875 @defvr {Required} helpId
1879 @node SPV Detail graph Element
1880 @subsection The @code{graph} Element
1882 Parent: @code{visualization} @*
1883 Contents: @code{location}@math{+} @code{coordinates} @code{faceting} @code{facetLayout} @code{interval}
1885 @code{graph} has the following attributes.
1887 @defvr {Required} cellStyle
1888 @defvrx {Required} style
1889 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
1890 Detail style Element}). The former is the default style for
1891 individual cells, the latter for the entire table.
1894 @node SPV Detail location Element
1895 @subsection The @code{location} Element
1897 Parent: @code{graph} @*
1900 Each instance of this element specifies where some part of the table
1901 frame is located. All the examples in the corpus have four instances
1902 of this element, one for each of the parts @code{height},
1903 @code{width}, @code{left}, and @code{top}. Some examples in the
1904 corpus add a fifth for part @code{bottom}, even though it is not clear
1905 how all of @code{top}, @code{bottom}, and @code{heigth} can be honored
1906 at the same time. In any case, @code{location} seems to have little
1907 importance in representing tables; a reader can safely ignore it.
1909 @defvr {Required} part
1910 One of @code{height}, @code{width}, @code{top}, @code{bottom}, or
1911 @code{left}. Presumably @code{right} is acceptable as well but the
1912 corpus contains no examples.
1915 @defvr {Required} method
1916 How the location is determined:
1920 Based on the natural size of the table. Observed only for
1921 parts @code{height} and @code{width}.
1924 Based on the location specified in @code{target}. Observed only for
1925 parts @code{top} and @code{bottom}.
1928 Using the value in @code{value}. Observed only for parts @code{top},
1929 @code{bottom}, and @code{left}.
1932 Same as the specified @code{target}. Observed only for part
1937 @defvr {Optional} min
1938 Minimum size. Only observed with value @code{100pt}. Only observed
1939 for part @code{width}.
1942 @defvr {Dependent} target
1943 Required when @code{method} is @code{attach} or @code{same}, not
1944 observed otherwise. This is the ID of an element to attach to.
1945 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
1949 @defvr {Dependent} value
1950 Required when @code{method} is @code{fixed}, not observed otherwise.
1951 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
1952 on parts @code{top} and @code{left}, and @code{100%} on part
1956 @node SPV Detail coordinates Element
1957 @subsection The @code{coordinates} Element
1959 Parent: @code{graph} @*
1962 This element is always present and always empty, with no attributes
1965 @node SPV Detail faceting Element
1966 @subsection The @code{faceting} Element
1968 Parent: @code{graph} @*
1969 Contents: @code{cross} @code{layer}*
1971 The @code{faceting} element describes the row, column, and layer
1972 structure of the table. Its @code{cross} child determines the row and
1973 column structure, and each @code{layer} child (if any) represents a
1976 @code{faceting} has no attributes (other than @code{id}).
1978 @subsubheading The @code{cross} Element
1980 Parent: @code{faceting} @*
1981 Contents: @code{nest} @code{nest}
1983 The @code{cross} element describes the row and column structure of the
1984 table. It has exactly two @code{nest} children, the first of which
1985 describes the table's rows and the second the table's columns.
1987 @code{cross} has no attributes (other than @code{id}).
1989 @subsubheading The @code{nest} Element
1991 Parent: @code{cross} @*
1992 Contents: @code{variableReference}@math{+}
1994 A given @code{nest} usually consists of one or more dimensions, each
1995 of which is represented by @code{variableReference} child elements.
1996 Minimally, a dimension has two @code{variableReference} children, one
1997 for the categories, one for the data, e.g.:
2001 <variableReference ref="dimension0categories"/>
2002 <variableReference ref="dimension0"/>
2007 Groups of categories introduce additional variable references, e.g.@:
2011 <variableReference ref="dimension0categories"/>
2012 <variableReference ref="dimension0group0"/>
2013 <variableReference ref="dimension0"/>
2018 Grouping can be hierarchical, e.g.@:
2022 <variableReference ref="dimension0categories"/>
2023 <variableReference ref="dimension0group1"/>
2024 <variableReference ref="dimension0group0"/>
2025 <variableReference ref="dimension0"/>
2030 XXX what are group maps?
2033 <nest id="nest_1973">
2034 <variableReference ref="dimension1categories"/>
2035 <variableReference ref="dimension1group1map"/>
2036 <variableReference ref="dimension1group0map"/>
2037 <variableReference ref="dimension1"/>
2040 <variableReference ref="dimension0categories"/>
2041 <variableReference ref="dimension0group0map"/>
2042 <variableReference ref="dimension0"/>
2047 A @code{nest} can contain multiple dimensions:
2051 <variableReference ref="dimension1categories"/>
2052 <variableReference ref="dimension1group0"/>
2053 <variableReference ref="dimension1"/>
2054 <variableReference ref="dimension0categories"/>
2055 <variableReference ref="dimension0"/>
2059 One @code{nest} within a given @code{cross} may have no dimensions, in
2060 which case it still has one @code{variableReference} child, which
2061 references a @code{derivedVariable} whose @code{value} attribute is
2062 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
2063 @code{row} or @code{column}, respectively, as its @code{id}.
2065 @code{nest} has no attributes (other than @code{id}).
2067 @subsubheading The @code{variableReference} Element
2069 Parent: @code{nest} @*
2072 @code{variableReference} has one attribute.
2074 @defvr {Required} ref
2075 The @code{id} of a @code{sourceVariable} or @code{derivedVariable}
2079 @subsubheading The @code{layer} Element
2081 Parent: @code{faceting} @*
2084 Each layer is represented by a pair of @code{layer} elements. The
2085 first of this pair is for a category variable, the second for the data
2089 <layer value="0" variable="dimension0categories" visible="true"/>
2090 <layer value="dimension0" variable="dimension0" visible="false"/>
2094 @code{layer} has the following attributes.
2096 @defvr {Required} variable
2097 The @code{id} of a @code{sourceVariable} or @code{derivedVariable}
2101 @defvr {Required} value
2102 The value to select. For a category variable, this is always
2103 @code{0}; for a data variable, it is the same as the @code{variable}
2107 @defvr {Optional} visible
2108 Whether the layer is visible. Generally, category layers are visible
2109 and data layers are not, but sometimes this attribute is omitted.
2112 @defvr {Optional} method
2113 When present, this is always @code{nest}.
2116 @node SPV Detail facetLayout Element
2117 @subsection The @code{facetLayout} Element
2119 Parent: @code{graph} @*
2120 Contents: @code{tableLayout} @code{facetLevel}@math{+} @code{setCellProperties}*
2122 @subsubheading The @code{tableLayout} Element
2124 Parent: @code{facetLayout} @*
2127 @defvr {Required} verticalTitlesInCorner
2128 Always set to @code{true}.
2131 @defvr {Optional} style
2132 The @code{id} of a @code{style} element.
2135 @defvr {Optional} fitCells
2136 Always set to @code{ticks}.
2139 @subsubheading The @code{facetLevel} Element
2141 Parent: @code{facetLayout} @*
2142 Contents: @code{axis}
2144 Each @code{facetLevel} describes a @code{variableReference} or
2145 @code{layer}, and a table has one @code{facetLevel} element for
2146 each such element. For example, an SPV detail member that contains
2147 four @code{variableReference} elements and two @code{layer} elements
2148 will contain six @code{facetLevel} elements.
2150 In the corpus, @code{facetLevel} elements and the elements that they
2151 describe are always in the same order. The correspondence may also be
2152 observed in two other ways. First, one may use the @code{level}
2153 attribute, described below. Second, in the corpus, a
2154 @code{facetLevel} always has an @code{id} that is the same as the
2155 @code{id} of the element it describes with @code{_facetLevel}
2156 appended. One should not formally rely on this, of course, but it is
2157 usefully indicative.
2159 @defvr {Required} level
2160 A 1-based index into the @code{variableReference} and @code{layer}
2161 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2162 describes the first @code{variableReference} in the SPV detail member,
2163 and in a member with four @code{variableReference} elements, a
2164 @code{facetLayout} with a @code{level} of 5 describes the first
2165 @code{layer} in the member.
2168 @defvr {Required} gap
2169 Always observed as @code{0pt}.
2172 @subsubheading The @code{axis} Element
2174 Parent: @code{facetLevel} @*
2175 Contents: @code{label}? @code{majorTicks}
2177 @defvr {Attribute} style
2178 The @code{id} of a @code{style} element.
2181 @subsubheading The @code{label} Element
2183 Parent: @code{axis} or @code{labelFrame} @*
2184 Contents: @code{text}@math{+} @math{|} @code{descriptionGroup}
2186 This element represents a label on some aspect of the table. For example,
2187 the table's title is a @code{label}.
2189 The contents of the label can be one or more @code{text} elements or a
2190 @code{descriptionGroup}.
2192 @defvr {Attribute} style
2193 @defvrx {Optional} textFrameStyle
2194 Each of these is the @code{id} of a @code{style} element.
2195 @code{style} is the style of the label text, @code{textFrameStyle} the
2196 style for the frame around the label.
2199 @defvr {Optional} purpose
2200 The kind of entity being labeled, one of @code{title},
2201 @code{subTitle}, @code{layer}, or @code{footnote}.
2204 @subsubheading The @code{descriptionGroup} Element
2206 Parent: @code{label} @*
2207 Contents: (@code{description} @math{|} @code{text})@math{+}
2209 A @code{descriptionGroup} concatenates one or more elements to form a
2210 label. Each element can be a @code{text} element, which contains
2211 literal text, or a @code{description} element that substitutes a value
2214 @defvr {Attribute} target
2215 The @code{id} of an element being described. In the corpus, this is
2216 always @code{faceting}.
2219 @defvr {Attribute} separator
2220 A string to separate the description of multiple groups, if the
2221 @code{target} has more than one. In the corpus, this is always a
2225 Typical contents for a @code{descriptionGroup} are a value by itself:
2227 <description name="value"/>
2229 @noindent or a variable and its value, separated by a colon:
2231 <description name="variable"/><text>:</text><description name="value"/>
2234 @subsubheading The @code{description} Element
2236 Parent: @code{descriptionGroup} @*
2239 A @code{description} is like a macro that expands to some property of
2240 the target of its parent @code{descriptionGroup}.
2242 @defvr {Attribute} name
2243 The name of the property. Only @code{variable} and @code{value}
2244 appear in the corpus.
2247 @subsubheading The @code{majorTicks} Element
2249 Parent: @code{axis} @*
2250 Contents: @code{gridline}?
2252 @defvr {Attribute} labelAngle
2253 @defvrx {Attribute} length
2254 Both always defined to @code{0}.
2257 @defvr {Attribute} style
2258 @defvrx {Attribute} tickFrameStyle
2259 Each of these is the @code{id} of a @code{style} element.
2260 @code{style} is the style of the tick labels, @code{tickFrameStyle}
2261 the style for the frames around the labels.
2264 @subsubheading The @code{gridline} Element
2266 Parent: @code{majorTicks} @*
2269 Represents ``gridlines,'' which for a table represents the lines
2270 between the rows or columns of a table (XXX?).
2272 @defvr {Attribute} style
2273 The style for the gridline.
2276 @defvr {Attribute} zOrder
2277 Observed as a number between 28 and 31. Does not seem to be
2281 @subsubheading The @code{setCellProperties} Element
2283 Parent: @code{facetLayout} @*
2284 Contents: @code{setMetaData} @code{setStyle}* @code{setFormat}@math{+} @code{union}?
2286 This element sets style properties of cells designated by the
2287 @code{target} attribute of its child elements, as further restricted
2288 by the optional @code{union} element if present. The @code{target}
2289 values often used, e.g.@: @code{graph} or @code{labeling}, actually
2290 affect every cell, so the @code{union} element is a useful
2293 @defvr {Optional} applyToConverse
2294 If present, always @code{true}. This appears to invert the meaning of
2295 the @code{target} of sub-elements: the selected cells are the ones
2296 @emph{not} designated by @code{target}. This is confusing, given the
2297 additional restrictions of @code{union}, but in the corpus
2298 @code{applyToConverse} is never present along with @code{union}.
2301 @subsubheading The @code{setMetaData} Element
2303 Parent: @code{setCellProperties} @*
2306 This element is not known to have any visible effect.
2308 @defvr {Required} target
2309 The @code{id} of an element whose metadata is to be set. In the
2310 corpus, this is always @code{graph}, the @code{id} used for the
2311 @code{graph} element.
2314 @defvr {Required} key
2315 @defvrx {Required} value
2316 A key-value pair to set for the target.
2318 In the corpus, @code{key} is @code{cellPropId} or, rarely,
2319 @code{diagProps}, and @code{value} is always the @code{id} of the
2320 parent @code{setCellProperties}.
2323 @subsubheading The @code{setStyle} Element
2325 Parent: @code{setCellProperties} @*
2328 This element associates a style with the target.
2330 @defvr {Required} target
2331 The @code{id} of an element whose style is to be set. In the corpus,
2332 this is always the @code{id} of an @code{interval}, @code{labeling},
2333 or, rarely, @code{graph} element.
2336 @defvr {Required} style
2337 The @code{id} of a @code{style} element that identifies the style to
2341 @subsubheading The @code{setFormat} Element
2344 Parent: @code{setCellProperties}
2347 @math{|} @code{numberFormat}
2348 @math{|} @code{stringFormat}@math{+}
2349 @math{|} @code{dateTimeFormat}
2352 This element sets the format of the target, ``format'' in this case
2353 meaning the SPSS print format for a variable.
2355 The details of this element vary depending on the schema version, as
2356 declared in the root @code{visualization} element's @code{version}
2357 attribute (@pxref{SPV Detail visualization Element}). In version 2.5
2358 and earlier, @code{setFormat} contains one of a number of child
2359 elements that correspond to the different varieties of print formats.
2360 In version 2.7 and later, @code{setFormat} instead always contains a
2361 @code{format} element.
2363 XXX reinvestigate the above claim about versions: it appears to be
2366 The @code{setFormat} element itself has the following attributes.
2368 @defvr {Required} target
2369 The @code{id} of an element whose style is to be set. In the corpus,
2370 this is always the @code{id} of an @code{majorTicks} or
2371 @code{labeling} element.
2374 @defvr {Optional} reset
2375 If this is @code{true}, this format overrides the target's previous
2376 format. If it is @code{false}, the adds to the previous format. In
2377 the corpus this is always @code{true}. The default behavior is
2382 * SPV Detail format Element::
2383 * SPV Detail numberFormat Element::
2384 * SPV Detail stringFormat Element::
2385 * SPV Detail dateTimeFormat Element::
2386 * SPV Detail affix Element::
2387 * SPV Detail relabel Element::
2388 * SPV Detail union Element::
2391 @node SPV Detail format Element
2392 @subsubsection The @code{format} Element
2394 Parent: @code{sourceVariable}, @code{derivedVariable}, @code{formatMapping}, @code{labeling}, @code{formatMapping}, @code{setFormat} @*
2395 Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
2397 This element appears only in schema version 2.7 (@pxref{SPV Detail
2398 visualization Element}).
2400 This element determines a format, equivalent to an SPSS print format.
2402 @subsubheading Attributes for All Formats
2404 These attributes apply to all kinds of formats. The most important of
2405 these attributes determines the high-level kind of formatting in use:
2407 @defvr {Optional} baseFormat
2408 Either @code{dateTime} or @code{elapsedTime}. When this attribute is
2409 omitted, this element is a numeric or string format.
2413 Whether, in the corpus, other attributes are always present (``yes''),
2414 never present (``no''), or sometimes present (``opt'') depends on
2417 @multitable {maximumFractionDigits} {@code{dateTime}} {@code{elapsedTime}} {number} {string}
2418 @headitem Attribute @tab @code{dateTime} @tab @code{elapsedTime} @tab number @tab string
2419 @item errorCharacter @tab yes @tab yes @tab yes @tab opt
2421 @item separatorChars @tab yes @tab no @tab no @tab no
2423 @item mdyOrder @tab yes @tab no @tab no @tab no
2425 @item showYear @tab yes @tab no @tab no @tab no
2426 @item yearAbbreviation @tab yes @tab no @tab no @tab no
2428 @item showMonth @tab yes @tab no @tab no @tab no
2429 @item monthFormat @tab yes @tab no @tab no @tab no
2431 @item showDay @tab yes @tab opt @tab no @tab no
2432 @item dayPadding @tab yes @tab opt @tab no @tab no
2433 @item dayOfMonthPadding @tab yes @tab no @tab no @tab no
2434 @item dayType @tab yes @tab no @tab no @tab no
2436 @item showHour @tab yes @tab opt @tab no @tab no
2437 @item hourFormat @tab yes @tab opt @tab no @tab no
2438 @item hourPadding @tab yes @tab yes @tab no @tab no
2440 @item showMinute @tab yes @tab yes @tab no @tab no
2441 @item minutePadding @tab yes @tab yes @tab no @tab no
2443 @item showSecond @tab yes @tab yes @tab no @tab no
2444 @item secondPadding @tab no @tab yes @tab no @tab no
2446 @item showMillis @tab no @tab yes @tab no @tab no
2448 @item minimumIntegerDigits @tab no @tab no @tab yes @tab no
2449 @item maximumFractionDigits @tab no @tab yes @tab yes @tab no
2450 @item minimumFractionDigits @tab no @tab yes @tab yes @tab no
2451 @item useGrouping @tab no @tab opt @tab yes @tab no
2452 @item scientific @tab no @tab no @tab yes @tab no
2453 @item small @tab no @tab no @tab opt @tab no
2454 @item suffix @tab no @tab no @tab opt @tab no
2456 @item tryStringsAsNumbers @tab no @tab no @tab no @tab yes
2460 @defvr {Attribute} errorCharacter
2461 A character that replaces the formatted value when it cannot otherwise
2462 be represented in the given format. Always @samp{*}.
2465 @subsubheading Date and Time Attributes
2467 These attributes are used with @code{dateTime} and @code{elapsedTime}
2470 @defvr {Attribute} separatorChars
2471 Exactly four characters. In order, these are used for: decimal point,
2472 grouping, date separator, time separator. Always @samp{.,-:}.
2475 @defvr {Attribute} mdyOrder
2476 Within a date, the order of the days, months, and years.
2477 @code{dayMonthYear} is the only observed value, but one would expect
2478 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
2482 @defvr {Attribute} showYear
2483 @defvrx {Attribute} yearAbbreviation
2484 Whether to include the year and, if so, whether the year should be
2485 shown abbreviated, that is, with only 2 digits. Each is @code{true}
2486 or @code{false}; only values of @code{true} and @code{false},
2487 respectively, have been observed.
2490 @defvr {Attribute} showMonth
2491 @defvrx {Attribute} monthFormat
2492 Whether to include the month (@code{true} or @code{false}) and, if so,
2493 how to format it. @code{monthFormat} is one of the following:
2497 The full name of the month, e.g.@: in an English locale,
2501 The abbreviated name of the month, e.g.@: in an English locale,
2505 The number representing the month, e.g.@: 9 for September.
2508 A two-digit number representing the month, e.g.@: 09 for September.
2511 Only values of @code{true} and @code{short}, respectively, have been
2515 @defvr {Attribute} dayPadding
2516 @defvrx {Attribute} dayOfMonthPadding
2517 @defvrx {Attribute} hourPadding
2518 @defvrx {Attribute} minutePadding
2519 @defvrx {Attribute} secondPadding
2520 These attributes presumably control whether each field in the output
2521 is padded with spaces to its maximum width, but the details are not
2522 understood. The only observed value for any of these attributes is
2526 @defvr {Attribute} showDay
2527 @defvrx {Attribute} showHour
2528 @defvrx {Attribute} showMinute
2529 @defvrx {Attribute} showSecond
2530 @defvrx {Attribute} showMillis
2531 These attributes presumably control whether each field is displayed
2532 in the output, but the details are not understood. The only
2533 observed value for any of these attributes is @code{true}.
2536 @defvr {Attribute} dayType
2537 This attribute is always @code{month} in the corpus, specifying that
2538 the day of the month is to be displayed; a value of @code{year} is
2539 supposed to indicate that the day of the year, where 1 is January 1,
2540 is to be displayed instead.
2543 @defvr {Attribute} hourFormat
2544 @code{hourFormat}, if present, is one of:
2548 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
2552 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
2554 This is the only value observed in the corpus.
2557 The time is displayed in a 12-hour format, without distinguishing
2558 morning or evening, e.g.@: @code{10;15}.
2561 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
2562 which is confusing since a time duration does not have a concept of AM
2563 or PM. This might indicate a bug in the code that generated the XML
2564 in the corpus, or it might indicate that @code{elapsedTime} is
2565 sometimes used to format a time of day.
2568 @subsubheading Numeric Attributes
2570 These attributes are used for formats when @code{baseFormat} is
2571 @code{number}. Attributes @code{maximumFractionDigits}, and
2572 @code{minimumFractionDigits}, and @code{useGrouping} are also used
2573 when @code{baseFormat} is @code{elapsedTime}.
2575 @defvr {Attribute} minimumIntegerDigits
2576 Minimum number of digits to display before the decimal point. Always
2577 observed as @code{0}.
2580 @defvr {Attribute} maximumFractionDigits
2581 @defvrx {Attribute} maximumFractionDigits
2582 Maximum or minimum, respectively, number of digits to display after
2583 the decimal point. The observed values of each attribute range from 0
2587 @defvr {Attribute} useGrouping
2588 Whether to use the grouping character to group digits in large
2589 numbers. It would make sense for the grouping character to come from
2590 the @code{separatorChars} attribute, but that attribute is only
2591 present when @code{baseFormat} is @code{dateTime} or
2592 @code{elapsedTime}, in the corpus at least. Perhaps that is because
2593 this attribute has only been observed as @code{false}.
2596 @defvr {Attribute} scientific
2597 This attribute controls when and whether the number is formatted in
2598 scientific notation. It takes the following values:
2602 Use scientific notation only when the number's magnitude is smaller
2603 than the value of the @code{small} attribute.
2606 Use scientific notation when the number will not otherwise fit in the
2610 Always use scientific notation. Not observed in the corpus.
2613 Never use scientific notation. A number that won't otherwise fit will
2614 be replaced by an error indication (see the @code{errorCharacter}
2615 attribute). Not observed in the corpus.
2619 @defvr {Optional} small
2620 Only present when the @code{scientific} attribute is
2621 @code{onlyForSmall}, this is a numeric magnitude below which the
2622 number will be formatted in scientific notation. The values @code{0}
2623 and @code{0.0001} have been observed. The value @code{0} seems like a
2624 pathological choice, since no real number has a magnitude less than 0;
2625 perhaps in practice such a choice is equivalent to setting
2626 @code{scientific} to @code{false}.
2629 @defvr {Optional} prefix
2630 @defvrx {Optional} suffix
2631 Specifies a prefix or a suffix to apply to the formatted number. Only
2632 @code{suffix} has been observed, with value @samp{%}.
2635 @subsubheading String Attributes
2637 These attributes are used for formats when @code{baseFormat} is
2640 @defvr {Attribute} tryStringsAsNumbers
2641 When this is @code{true}, it is supposed to indicate that string
2642 values should be parsed as numbers and then displayed according to
2643 numeric formatting rules. However, in the corpus it is always
2647 @node SPV Detail numberFormat Element
2648 @subsubsection The @code{numberFormat} Element
2650 Parent: @code{setFormat} @*
2651 Contents: @code{affix}@math{+}
2653 This element appears only in schema version 2.5 and earlier
2654 (@pxref{SPV Detail visualization Element}). Possibly this element
2655 could also contain @code{relabel} elements in a more diverse corpus.
2657 This element has the following attributes.
2659 @defvr {Attribute} maximumFractionDigits
2660 @defvrx {Attribute} minimumFractionDigits
2661 @defvrx {Attribute} minimumIntegerDigits
2662 @defvrx {Optional} scientific
2663 @defvrx {Optional} small
2664 @defvrx {Optional} suffix
2665 @defvrx {Optional} useGroupging
2666 The syntax and meaning of these attributes is the same as on the
2667 @code{format} element for a numeric format. @pxref{SPV Detail format
2671 @node SPV Detail stringFormat Element
2672 @subsubsection The @code{stringFormat} Element
2674 Parent: @code{setFormat} @*
2675 Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
2677 This element appears only in schema version 2.5 and earlier
2678 (@pxref{SPV Detail visualization Element}).
2680 This element has no attributes.
2682 @node SPV Detail dateTimeFormat Element
2683 @subsubsection The @code{dateTimeFormat} Element
2685 Parent: @code{setFormat} @*
2688 This element appears only in schema version 2.5 and earlier
2689 (@pxref{SPV Detail visualization Element}). Possibly this element
2690 could also contain @code{affix} and @code{relabel} elements in a more
2693 The following attribute is required.
2695 @defvr {Attribute} baseFormat
2696 Either @code{dateTime} or @code{time}.
2699 When @code{baseFormat} is @code{dateTime}, the following attributes
2702 @defvr {Attribute} dayOfMonthPadding
2703 @defvrx {Attribute} dayPadding
2704 @defvrx {Attribute} dayType
2705 @defvrx {Attribute} hourFormat
2706 @defvrx {Attribute} hourPadding
2707 @defvrx {Attribute} mdyOrder
2708 @defvrx {Attribute} minutePadding
2709 @defvrx {Attribute} monthFormat
2710 @defvrx {Attribute} separatorChars
2711 @defvrx {Attribute} showDay
2712 @defvrx {Attribute} showHour
2713 @defvrx {Attribute} showMinute
2714 @defvrx {Attribute} showMonth
2715 @defvrx {Attribute} showSecond
2716 @defvrx {Attribute} showYear
2717 @defvrx {Attribute} yearAbbreviation
2718 The syntax and meaning of these attributes is the same as on the
2719 @code{format} element when that element's @code{baseFormat} is
2720 @code{dateTime}. @pxref{SPV Detail format Element}.
2723 When @code{baseFormat} is @code{time}, the following attributes are
2726 @defvr {Attribute} hourFormat
2727 @defvrx {Attribute} hourPadding
2728 @defvrx {Attribute} minutePadding
2729 @defvrx {Attribute} monthFormat
2730 @defvrx {Attribute} separatorChars
2731 @defvrx {Attribute} showDay
2732 @defvrx {Attribute} showHour
2733 @defvrx {Attribute} showMinute
2734 @defvrx {Attribute} showMonth
2735 @defvrx {Attribute} showSecond
2736 @defvrx {Attribute} showYear
2737 @defvrx {Attribute} yearAbbreviation
2738 The syntax and meaning of these attributes is the same as on the
2739 @code{format} element when that element's @code{baseFormat} is
2740 @code{elapsedTime}. @pxref{SPV Detail format Element}.
2743 @node SPV Detail affix Element
2744 @subsubsection The @code{affix} Element
2746 Parent: @code{format} or @code{numberFormat} or @code{stringFormat} @*
2749 Possibly this element could have @code{dateTimeFormat} as a parent in
2750 a more diverse corpus.
2752 This defines a suffix (or, theoretically, a prefix) for a formatted
2753 value. It is used to insert a reference to a footnote. It has the
2754 following attributes:
2756 @defvr {Attribute} definesReference
2757 This specifies the footnote number as a natural number: 1 for the
2758 first footnote, 2 for the second, and so on.
2761 @defvr {Attribute} position
2762 Position for the footnote label. Always @code{superscript}.
2765 @defvr {Attribute} suffix
2766 Whether the affix is a suffix (@code{true}) or a prefix
2767 (@code{false}). Always @code{true}.
2770 @defvr {Attribute} value
2771 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
2772 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
2773 contains other values: @code{*}, @code{**}, and a few that begin with
2774 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
2777 @node SPV Detail relabel Element
2778 @subsubsection The @code{relabel} Element
2780 Parent: @code{format} or @code{stringFormat} @*
2783 Possibly this element could have @code{numberFormat} or
2784 @code{dateTimeFormat} as a parent in a more diverse corpus.
2786 This specifies how to display a given value. It is used to implement
2787 value labels and to display the system-missing value in a
2788 human-readable way. It has the following attributes:
2790 @defvr {Attribute} from
2791 The value to map. In the corpus this is an integer or the
2792 system-missing value @code{-1.797693134862316E300}.
2795 @defvr {Attribute} to
2796 The string to display in place of the value of @code{from}. In the
2797 corpus this is a wide variety of value labels; the system-missing
2798 value is mapped to @samp{.}.
2801 @node SPV Detail union Element
2802 @subsubsection The @code{union} Element
2804 Parent: @code{setCellProperties} @*
2805 Contents: @code{intersect}@math{+}
2807 This element represents a set of cells, computed as the union of the
2808 sets represented by each of its children.
2810 @subsubheading The @code{intersect} Element
2812 Parent: @code{union} @*
2813 Contents: @code{where}@math{+} @math{|} @code{intersectWhere}?
2815 This element represents a set of cells, computed as the intersection
2816 of the sets represented by each of its children.
2818 Of the two possible children, in the corpus @code{where} is far more
2819 common, appearing thousands of times, whereas @code{intersectWhere}
2820 only appears 4 times.
2822 Most @code{intersect} elements have two or more children.
2824 @subsubheading The @code{where} Element
2826 Parent: @code{intersect} @*
2829 This element represents the set of cells in which the value of a
2830 specified variable falls within a specified set.
2832 @defvr {Attribute} variable
2833 The @code{id} of a variable, e.g.@: @code{dimension0categories} or
2834 @code{dimension0group0map}.
2837 @defvr {Attribute} include
2838 A value, or multiple values separated by semicolons,
2839 e.g.@: @code{0} or @code{13;14;15;16}.
2842 @subsubheading The @code{intersectWhere} Element
2844 Parent: @code{intersect} @*
2847 The meaning of this element is unknown.
2849 @defvr {Attribute} variable
2850 @defvrx {Attribute} variable2
2851 The meaning of these attributes is unknown. In the four examples in
2852 the corpus they always take the values @code{dimension2categories} and
2853 @code{dimension0categories}, respectively.
2856 @node SPV Detail style Element
2857 @subsection The @code{style} Element