1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2019 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
11 @node SPSS Viewer File Format
12 @appendix SPSS Viewer File Format
14 SPSS Viewer or @file{.spv} files, here called SPV files, are written
15 by SPSS 16 and later to represent the contents of its output editor.
16 This chapter documents the format, based on examination of a corpus of
17 about 3,000 files from a variety of sources. This description is
18 detailed enough to both read and write SPV files.
20 SPSS 15 and earlier versions instead use @file{.spo} files, which have
21 a completely different output format based on the Microsoft Compound
22 Document Format. This format is not documented here.
24 An SPV file is a Zip archive that can be read with @command{zipinfo}
25 and @command{unzip} and similar programs. The final member in the Zip
26 archive is the @dfn{manifest}, a file named
27 @file{META-INF/MANIFEST.MF}. This structure makes SPV files resemble
28 Java ``JAR'' files (and ODF files), but whereas a JAR manifest
29 contains a sequence of colon-delimited key/value pairs, an SPV
30 manifest contains the string @samp{allowPivoting=true}, without a
31 new-line. PSPP uses this string to identify an SPV file; it is
32 invariant across the corpus.@footnote{SPV files always begin with the
33 7-byte sequence 50 4b 03 04 14 00 08, but this is not a useful magic
34 number because most Zip archives start the same way.}
36 The rest of the members in an SPV file's Zip archive fall into two
37 categories: @dfn{structure} and @dfn{detail} members. Structure
38 member names begin with @file{outputViewer@var{nnnnnnnnnn}}, where
39 each @var{n} is a decimal digit, and end with @file{.xml}, and often
40 include the string @file{_heading} in between. Each of these members
41 represents some kind of output item (a table, a heading, a block of
42 text, etc.) or a group of them. The member whose output goes at the
43 beginning of the document is numbered 0, the next member in the output
44 is numbered 1, and so on.
46 Structure members contain XML. This XML is sometimes self-contained,
47 but it often references detail members in the Zip archive, which are
51 @item @file{@var{prefix}_table.xml} and @file{@var{prefix}_tableData.bin}
52 @itemx @file{@var{prefix}_lightTableData.bin}
53 The structure of a table plus its data. Older SPV files pair a
54 @file{@var{prefix}_table.xml} file that describes the table's
55 structure with a binary @file{@var{prefix}_tableData.bin} file that
56 gives its data. Newer SPV files (the majority of those in the corpus)
57 instead include a single @file{@var{prefix}_lightTableData.bin} file
58 that incorporates both into a single binary format.
60 @item @file{@var{prefix}_warning.xml} and @file{@var{prefix}_warningData.bin}
61 @itemx @file{@var{prefix}_lightWarningData.bin}
62 Same format used for tables, with a different name.
64 @item @file{@var{prefix}_notes.xml} and @file{@var{prefix}_notesData.bin}
65 @itemx @file{@var{prefix}_lightNotesData.bin}
66 Same format used for tables, with a different name.
68 @item @file{@var{prefix}_chartData.bin} and @file{@var{prefix}_chart.xml}
69 The structure of a chart plus its data. Charts do not have a
72 @item @file{@var{prefix}_pmml.scf}
73 @itemx @file{@var{prefix}_stats.scf}
74 @item @file{@var{prefix}_model.xml}
75 Not yet investigated. The corpus contains few examples.
78 The @file{@var{prefix}} in the names of the detail members is
79 typically an 11-digit decimal number that increases for each item,
80 tending to skip values. Older SPV files use different naming
81 conventions. Structure member refer to detail members by name, and so
82 their exact names do not matter to readers as long as they are unique.
84 SPSS tolerates corrupted Zip archives that Zip reader libraries tend
85 to reject. These can be fixed up with @command{zip -FF}.
88 * SPV Structure Member Format::
89 * SPV Light Detail Member Format::
90 * SPV Legacy Detail Member Binary Format::
91 * SPV Legacy Detail Member XML Format::
94 @node SPV Structure Member Format
95 @section Structure Member Format
97 A structure member lays out the high-level structure for a group of
98 output items such as heading, tables, and charts. Structure members
99 do not include the details of tables and charts but instead refer to
100 them by their member names.
102 Structure members' XML files claim conformance with a collection of
103 XML Schemas. These schemas are distributed, under a nonfree license,
104 with SPSS binaries. Fortunately, the schemas are not necessary to
105 understand the structure members. The schemas can even
106 be deceptive because they document elements and attributes that are
107 not in the corpus and do not document elements and attributes that are
108 commonly found in the corpus.
110 Structure members use a different XML namespace for each schema, but
111 these namespaces are not entirely consistent. In some SPV files, for
112 example, the @code{viewer-tree} schema is associated with namespace
113 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
114 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
115 additional @file{viewer/}). Under either name, the schema URIs are
116 not resolvable to obtain the schemas themselves.
118 One may ignore all of the above in interpreting a structure member.
119 The actual XML has a simple and straightforward form that does not
120 require a reader to take schemas or namespaces into account. A
121 structure member's root is @code{heading} element, which contains
122 @code{heading} or @code{container} elements (or a mix), forming a
123 tree. In turn, @code{container} holds a @code{label} and one more
124 child, usually @code{text} or @code{table}.
126 The following sections document the elements found in structure
127 members in a context-free grammar-like fashion. Consider the
128 following example, which specifies the attributes and content for the
129 @code{container} element:
133 :visibility=(visible | hidden)
134 :page-break-before=(always)?
135 :text-align=(left | center)?
137 => label (table | container_text | graph | model | object | image)
140 Each attribute specification begins with @samp{:} followed by the
141 attribute's name. If the attribute's value has an easily specified
142 form, then @samp{=} and its description follows the name. Finally, if
143 the attribute is optional, the specification ends with @samp{?}. The
144 following value specifications are defined:
147 @item (@var{a} | @var{b} | @dots{})
148 One of the listed literal strings. If only one string is listed, it
149 is the only acceptable value. If @code{OTHER} is listed, then any
150 string not explicitly listed is also accepted.
153 Either @code{true} or @code{false}.
156 A floating-point number followed by a unit, e.g.@: @code{10pt}. Units
157 in the corpus include @code{in} (inch), @code{pt} (points, 72/inch),
158 @code{px} (``device-independent pixels'', 96/inch), and @code{cm}.
159 The corpus also contains localized names for units: @code{인치} for
160 inch, @code{пт} for points, and @code{см} for centimeters. If the
161 unit is omitted then points should be assumed. The number and unit
162 may be separated by white space.
165 A floating-point number.
171 A color in one of the forms @code{#@var{rr}@var{gg}@var{bb}} or
172 @code{@var{rr}@var{gg}@var{bb}}, or the string @code{transparent}, or
173 one of the standard Web color names.
176 @item ref @var{element}
177 @itemx ref(@var{elem1} | @var{elem2} | @dots{})
178 The name from the @code{id} attribute in some element. If one or more
179 elements are named, the name must refer to one of those elements,
180 otherwise any element is acceptable.
183 All elements have an optional @code{id} attribute. If present, its
184 value must be unique. In practice many elements are assigned
185 @code{id} attributes that are never referenced.
187 The content specification for an element supports the following
194 @item @var{a} @var{b}
195 @var{a} followed by @var{b}.
197 @item @var{a} | @var{b} | @var{c}
198 One of @var{a} or @var{b} or @var{c}.
201 Zero or one instances of @var{a}.
204 Zero or more instances of @var{a}.
207 One or more instances of @var{a}.
209 @item (@var{subexpression})
210 Grouping for a subexpression.
219 Element and attribute names are sometimes suffixed by another name in
220 square brackets to distinguish different uses of the same name. For
221 example, structure XML has two @code{text} elements, one inside
222 @code{container}, the other inside @code{pageParagraph}. The former
223 is defined as @code{text[container_text]} and referenced as
224 @code{container_text}, the latter defined as
225 @code{text[pageParagraph_text]} and referenced as
226 @code{pageParagraph_text}.
228 This language is used in the PSPP source code for parsing structure
229 and detail XML members. Refer to
230 @file{src/output/spv/structure-xml.grammar} and
231 @file{src/output/spv/detail-xml.grammar} for the full grammars.
233 The following example shows the contents of a typical structure member
234 for a @cmd{DESCRIPTIVES} procedure. A real structure member is not
235 indented. This example also omits most attributes, all XML namespace
236 information, and the CSS from the embedded HTML:
239 <?xml version="1.0" encoding="utf-8"?>
241 <label>Output</label>
242 <heading commandName="Descriptives">
243 <label>Descriptives</label>
246 <text commandName="Descriptives" type="title">
248 <![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
252 <container visibility="hidden">
254 <table commandName="Descriptives" subType="Notes" type="note">
256 <dataPath>00000000001_lightNotesData.bin</dataPath>
261 <label>Descriptive Statistics</label>
262 <table commandName="Descriptives" subType="Descriptive Statistics"
265 <dataPath>00000000002_lightTableData.bin</dataPath>
274 * SPV Structure heading Element::
275 * SPV Structure label Element::
276 * SPV Structure container Element::
277 * SPV Structure text Element (Inside @code{container})::
278 * SPV Structure html Element::
279 * SPV Structure table Element::
280 * SPV Structure graph Element::
281 * SPV Structure model Element::
282 * SPV Structure dataPath and path Elements::
283 * SPV Structure pageSetup Element::
284 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
287 @node SPV Structure heading Element
288 @subsection The @code{heading} Element
291 heading[root_heading]
297 => label pageSetup? (container | heading)*
302 :visibility[heading_visibility]=(collapsed)?
305 => label (container | heading)*
308 The root of a structure member is a @code{heading}, which represents a
309 section of output beginning with a title (the @code{label}) and
310 ordinarily followed by content containers or further nested
311 (sub)-sections of output. Unlike heading elements in HTML and other
312 common document formats, which precede the content that they head,
313 @code{heading} contains the elements that appear below the heading.
315 The document root heading, only, may contain a @code{pageSetup}
318 The following attributes have been observed on both document root and
319 nested @code{heading} elements.
321 @defvr {Attribute} creator-version
322 The version of the software that created this SPV file. A string of
323 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
324 e.g.@: @code{21000001} is version 21.0.0.1. Trailing pairs of zeros
325 are sometimes omitted, so that @code{21}, @code{210000}, and
326 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
327 three of those forms).
331 The following attributes have been observed on document root
332 @code{heading} elements only:
334 @defvr {Attribute} @code{creator}
335 The directory in the file system of the software that created this SPV
339 @defvr {Attribute} @code{creation-date-time}
340 The date and time at which the SPV file was written, in a
341 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
342 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
343 December 5, 2014 5:00:19 o'clock PM EST}.
346 @defvr {Attribute} @code{lockReader}
347 Whether a reader should be allowed to edit the output. The possible
348 values are @code{true} and @code{false}. The value @code{false} is by
352 @defvr {Attribute} @code{schemaLocation}
353 This is actually an XML Namespace attribute. A reader may ignore it.
357 The following attributes have been observed only on nested
358 @code{heading} elements:
360 @defvr {Attribute} @code{commandName}
361 A locale-invariant identifier for the command that produced the
362 output, e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
365 @defvr {Attribute} @code{visibility}
366 To what degree the output represented by the element is visible.
369 @defvr {Attribute} @code{locale}
370 The locale used for output, in Windows format, which is similar to the
371 format used in Unix with the underscore replaced by a hyphen, e.g.@:
372 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
375 @defvr {Attribute} @code{olang}
376 The output language, e.g.@: @code{en}, @code{it}, @code{es},
377 @code{de}, @code{pt-BR}.
380 @node SPV Structure label Element
381 @subsection The @code{label} Element
387 Every @code{heading} and @code{container} holds a @code{label} as its
388 first child. The root @code{heading} in a structure member always
389 contains the string ``Output'' (localized). Otherwise, the text in
390 @code{label} describes what it labels, often by naming the statistical
391 procedure that was executed, e.g.@: ``Frequencies'' or ``T-Test''.
392 Labels are often very generic, especially within a @code{container},
393 e.g.@: ``Title'' or ``Warnings'' or ``Notes''. Label text is
394 localized according to the output language, e.g.@: in Italian a
395 frequency table procedure is labeled ``Frequenze''.
397 The corpus contains a few examples of empty labels, ones that contain
400 @node SPV Structure container Element
401 @subsection The @code{container} Element
405 :visibility=(visible | hidden)
406 :page-break-before=(always)?
407 :text-align=(left | center)?
409 => label (table | container_text | graph | model | object | image)
412 A @code{container} serves to contain and label a @code{table},
413 @code{text}, or other kind of item.
415 This element has the following attributes.
417 @defvr {Attribute} @code{visibility}
418 Whether the container's content is displayed. ``Notes'' tables are
419 often hidden; other data is usually
422 @defvr {Attribute} @code{text-align}
423 Alignment of text within the container. Observed with nested
424 @code{table} and @code{text} elements.
427 @defvr {Attribute} @code{width}
428 The width of the container, e.g.@: @code{1097px}.
431 @node SPV Structure text Element (Inside @code{container})
432 @subsection The @code{text} Element (Inside @code{container})
436 :type[text_type]=(title | log | text | page-title)
442 This @code{text} element is nested inside a @code{container}. There
443 is a different @code{text} element that is nested inside a
444 @code{pageParagraph}.
446 This element has the following attributes.
448 @defvr {Attribute} @code{type}
449 The semantics of the text.
452 @defvr {Attribute} @code{commandName}
453 As on the @code{heading} element. For output not specific to a
454 command, this is simply @code{log}. The corpus contains one example
455 of where @code{commandName} is present but set to the empty string.
458 @defvr {Attribute} @code{creator-version}
459 As on the @code{heading} element.
462 @node SPV Structure html Element
463 @subsection The @code{html} Element
466 html :lang=(en) => TEXT
469 The element contains an HTML document as text (or, in practice, as
470 CDATA). In some cases, the document starts with @code{<html>} and
471 ends with @code{</html>}; in others the @code{html} element is
472 implied. Generally the HTML includes a @code{head} element with a CSS
473 stylesheet. The HTML body often begins with @code{<BR>}.
475 The HTML document uses only the following elements:
479 Sometimes, the document is enclosed with
480 @code{<html>}@dots{}@code{</html>}.
483 The HTML body often begins with @code{<BR>} and may contain it as well.
491 The attributes @code{face}, @code{color}, and @code{size} are
492 observed. The value of @code{color} takes one of the forms
493 @code{#@var{rr}@var{gg}@var{bb}} or @code{rgb (@var{r}, @var{g},
494 @var{b})}. The value of @code{size} is a number between 1 and 7,
498 The CSS in the corpus is simple. To understand it, a parser only
499 needs to be able to skip white space, @code{<!--}, and @code{-->}, and
500 parse style only for @code{p} elements. Only @code{font-weight},
501 @code{font-style}, @code{font-decoration}, @code{font-family}, and
502 @code{font-size} matter.
504 This element has the following attributes.
506 @defvr {Attribute} @code{lang}
507 This always contains @code{en} in the corpus.
510 @node SPV Structure table Element
511 @subsection The @code{table} Element
520 :displayFiltering=bool?
522 :orphanTolerance=int?
527 :type[table_type]=(table | note | warning)
528 => tableProperties? tableStructure
530 tableStructure => path? dataPath
533 This element has the following attributes.
535 @defvr {Attribute} @code{commandName}
536 As on the @code{heading} element.
539 @defvr {Attribute} @code{type}
540 One of @code{table}, @code{note}, or @code{warning}.
543 @defvr {Attribute} @code{subType}
544 The locale-invariant command ID for the particular kind of output that
545 this table represents in the procedure. This can be the same as
546 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
547 @code{Case Processing Summary}. Generic subtypes @code{Notes} and
548 @code{Warnings} are often used.
551 @defvr {Attribute} @code{tableId}
552 A number that uniquely identifies the table within the SPV file,
553 typically a large negative number such as @code{-4147135649387905023}.
556 @defvr {Attribute} @code{creator-version}
557 As on the @code{heading} element. In the corpus, this is only present
558 for version 21 and up and always includes all 8 digits.
561 @xref{SPV Detail Legacy Properties}, for details on the
562 @code{tableProperties} element.
564 @node SPV Structure graph Element
565 @subsection The @code{graph} Element
581 This element represents a graph. The @code{dataPath} and @code{path}
582 elements name the Zip members that give the details of the graph.
583 Normally, both elements are present; there is only one counterexample
586 @node SPV Structure model Element
587 @subsection The @code{model} Element
599 => ViZml? path | pmmlContainerPath statsContainerPath
601 pmmlContainerPath => TEXT
603 statsContainerPath => TEXT
605 ViZml :viewName? => TEXT
608 This element represents a model. The @code{dataPath} and @code{path}
609 elements name the Zip members that give the details of the model.
610 Normally, both elements are present; there is only one counterexample
613 The details are unexplored. The @code{ViZml} element contains base-64
614 encoded text, that decodes to a binary format with some embedded text
615 strings, and @code{path} names an Zip member that contains XML.
616 Alternatively, @code{pmmlContainerPath} and @code{statsContainerPath}
617 name Zip members with @file{.scf} extension.
619 @node SPV Structure dataPath and path Elements
620 @subsection The @code{dataPath} and @code{path} Elements
628 These element contain the name of the Zip members that hold details
629 for a container. For tables:
633 When a ``light'' format is used, only @code{dataPath} is present, and
634 it names a @file{.bin} member of the Zip file that has @code{light} in
635 its name, e.g.@: @code{0000000001437_lightTableData.bin} (@pxref{SPV
636 Light Detail Member Format}).
639 When the legacy format is used, both are present. In this case,
640 @code{dataPath} names a Zip member with a legacy binary format that
641 contains relevant data (@pxref{SPV Legacy Detail Member Binary
642 Format}), and @code{path} names a Zip member that uses an XML format
643 (@pxref{SPV Legacy Detail Member XML Format}).
646 Graphs normally follow the legacy approach described above. The
647 corpus contains one example of a graph with @code{path} but not
648 @code{dataPath}. The reason is unexplored.
650 Models use @code{path} but not @code{dataPath}. @xref{SPV Structure
651 graph Element}, for more information.
653 These elements have no attributes.
655 @node SPV Structure pageSetup Element
656 @subsection The @code{pageSetup} Element
660 :initial-page-number=int?
661 :chart-size=(as-is | full-height | half-height | quarter-height | OTHER)?
662 :margin-left=dimension?
663 :margin-right=dimension?
664 :margin-top=dimension?
665 :margin-bottom=dimension?
666 :paper-height=dimension?
667 :paper-width=dimension?
668 :reference-orientation?
669 :space-after=dimension?
670 => pageHeader pageFooter
672 pageHeader => pageParagraph?
674 pageFooter => pageParagraph?
676 pageParagraph => pageParagraph_text
679 The @code{pageSetup} element has the following attributes.
681 @defvr {Attribute} @code{initial-page-number}
682 The page number to put on the first page of printed output. Usually
686 @defvr {Attribute} @code{chart-size}
687 One of the listed, self-explanatory chart sizes,
688 @code{quarter-height}, or a localization (!) of one of these (e.g.@:
689 @code{dimensione attuale}, @code{Wie vorgegeben}).
692 @defvr {Attribute} @code{margin-left}
693 @defvrx {Attribute} @code{margin-right}
694 @defvrx {Attribute} @code{margin-top}
695 @defvrx {Attribute} @code{margin-bottom}
696 Margin sizes, e.g.@: @code{0.25in}.
699 @defvr {Attribute} @code{paper-height}
700 @defvrx {Attribute} @code{paper-width}
704 @defvr {Attribute} @code{reference-orientation}
705 Indicates the orientation of the output page. Either @code{0deg}
706 (portrait) or @code{90deg} (landscape),
709 @defvr {Attribute} @code{space-after}
710 The amount of space between printed objects, typically @code{12pt}.
713 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
714 @subsection The @code{text} Element (Inside @code{pageParagraph})
717 text[pageParagraph_text] :type=(title | text) => TEXT
720 This @code{text} element is nested inside a @code{pageParagraph}. There
721 is a different @code{text} element that is nested inside a
724 The element is either empty, or contains CDATA that holds almost-XHTML
725 text: in the corpus, either an @code{html} or @code{p} element. It is
726 @emph{almost}-XHTML because the @code{html} element designates the
728 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of
729 an XHTML namespace, and because the CDATA can contain substitution
730 variables. The following variables are supported:
735 The current date or time in the preferred format for the locale.
741 First-, second-, third-, or fourth-level heading.
747 Name of the output file.
753 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
756 Typical contents (indented for clarity):
759 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
762 <p style="text-align:right; margin-top: 0">Page &[Page]</p>
767 This element has the following attributes.
769 @defvr {Attribute} @code{type}
773 @node SPV Light Detail Member Format
774 @section Light Detail Member Format
776 This section describes the format of ``light'' detail @file{.bin}
777 members. These members have a binary format which we describe here in
778 terms of a context-free grammar using the following conventions:
781 @item NonTerminal @result{} @dots{}
782 Nonterminals have CamelCaps names, and @result{} indicates a
783 production. The right-hand side of a production is often broken
784 across multiple lines. Break points are chosen for aesthetics only
785 and have no semantic significance.
787 @item 00, 01, @dots{}, ff.
788 A bytes with a fixed value, written as a pair of hexadecimal digits.
790 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
791 @itemx ib0, ib1, @dots{}, ib9, ib10, ib11, @dots{}
792 A 32-bit integer in little-endian or big-endian byte order,
793 respectively, with a fixed value, written in decimal. Prefixed by
794 @samp{i} for little-endian or @samp{ib} for big-endian.
800 A byte with value 0 or 1.
804 A 16-bit integer in little-endian or big-endian byte order,
809 A 32-bit integer in little-endian or big-endian byte order,
814 A 64-bit integer in little-endian or big-endian byte order,
818 A 64-bit IEEE floating-point number.
821 A 32-bit IEEE floating-point number.
825 A 32-bit integer, in little-endian or big-endian byte order,
826 respectively, followed by the specified number of bytes of character
827 data. (The encoding is indicated by the Formats nonterminal.)
830 @var{x} is optional, e.g.@: 00? is an optional zero byte.
832 @item @var{x}*@var{n}
833 @var{x} is repeated @var{n} times, e.g.@: byte*10 for ten arbitrary bytes.
835 @item @var{x}[@var{name}]
836 Gives @var{x} the specified @var{name}. Names are used in textual
837 explanations. They are also used, also bracketed, to indicate counts,
838 e.g.@: @code{int32[n] byte*[n]} for a 32-bit integer followed by the
839 specified number of arbitrary bytes.
841 @item @var{a} @math{|} @var{b}
842 Either @var{a} or @var{b}.
845 Parentheses are used for grouping to make precedence clear, especially
846 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
850 @itemx becount(@var{x})
851 A 32-bit integer, in little-endian or big-endian byte order, respectively,
852 that indicates the number of bytes in @var{x}, followed by @var{x} itself.
855 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
856 (The @file{.bin} header indicates the version.)
859 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
862 PSPP uses this grammar to parse light detail members. See
863 @file{src/output/spv/light-binary.grammar} in the PSPP source tree for
866 Little-endian byte order is far more common in this format, but a few
867 pieces of the format use big-endian byte order.
869 Light detail members express linear units in two ways: points (pt), at
870 72/inch, and ``device-independent pixels'' (px), at 96/inch. To
871 convert from pt to px, multiply by 1.33 and round up. To convert
872 from px to pt, divide by 1.33 and round down.
874 A ``light'' detail member @file{.bin} consists of a number of sections
875 concatenated together, terminated by an optional byte 01:
879 Header Titles Footnotes
880 Areas Borders PrintSettings TableSettings Formats
881 Dimensions Axes Cells
885 The following sections go into more detail.
888 * SPV Light Member Header::
889 * SPV Light Member Titles::
890 * SPV Light Member Footnotes::
891 * SPV Light Member Areas::
892 * SPV Light Member Borders::
893 * SPV Light Member Print Settings::
894 * SPV Light Member Table Settings::
895 * SPV Light Member Formats::
896 * SPV Light Member Dimensions::
897 * SPV Light Member Categories::
898 * SPV Light Member Axes::
899 * SPV Light Member Cells::
900 * SPV Light Member Value::
901 * SPV Light Member ValueMod::
904 @node SPV Light Member Header
907 An SPV light member begins with a 39-byte header:
912 (i1 @math{|} i3)[version]
915 bool[rotate-inner-column-labels]
916 bool[rotate-outer-row-labels]
919 int32[min-col-width] int32[max-col-width]
920 int32[min-row-width] int32[max-row-width]
924 @code{version} is a version number that affects the interpretation of
925 some of the other data in the member. We will refer to ``version 1''
926 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
927 version-specific formatting (as described previously).
929 If @code{rotate-inner-column-labels} is 1, then column labels closest
930 to the data are rotated to be vertical; otherwise, they are shown
933 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
934 the data are rotated to be vertical; otherwise, they are shown in the
937 @code{table-id} is a binary version of the @code{tableId} attribute in
938 the structure member that refers to the detail member. For example,
939 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
940 would be 0xc6c99d183b300001.
942 @code{min-col-width} is the minimum width that a column will be
943 assigned automatically. @code{max-col-width} is the maximum width
944 that a column will be assigned to accommodate a long column label.
945 @code{min-row-width} and @code{max-row-width} are a similar range for
946 the width of row labels. All of these measurements are in 1/96 inch
947 units (called a ``device independent pixel'' unit in Windows).
949 The meaning of the other variable parts of the header is not known. A
950 writer may safely use version 3, true for @code{x0}, false for
951 @code{x1}, true for @code{x2}, and 0x15 for @code{x3}.
953 @node SPV Light Member Titles
959 Value[subtype] 01? 31
960 Value[user-title] 01?
961 (31 Value[corner-text] @math{|} 58)
962 (31 Value[caption] @math{|} 58)
965 The Titles follow the Header and specify the table's title, caption,
968 The @code{user-title} is shown above the title and reflects any user
969 editing of the title text or style. The @code{title} is the title
970 originally generated by the procedure. Both of these are appropriate
971 for presentation and localized to the user's language. For example,
972 for a frequency table, @code{title} and @code{user-title} normally
973 name the variable and @code{c} is simply ``Frequencies''.
975 @code{subtype} is the same as the @code{subType} attribute in the
976 @code{table} structure XML element that referred to this member.
977 @xref{SPV Structure table Element}, for details.
979 The @code{corner-text}, if present, is shown in the upper-left corner
980 of the table, above the row headings and to the left of the column
981 headings. It is usually absent. Corner text prevents row dimension
982 labels from being displayed above the dimension's group and category
983 labels (see @code{show-row-labels-in-corner}).
985 The @code{caption}, if present, is shown below the table.
986 @code{caption} reflects user editing of the caption.
988 @node SPV Light Member Footnotes
989 @subsection Footnotes
992 Footnotes => int32[n-footnotes] Footnote*[n-footnotes]
993 Footnote => Value[text] (58 @math{|} 31 Value[marker]) byte*4
996 Each footnote has @code{text} and an optional custom @code{marker}
999 @node SPV Light Member Areas
1006 string[typeface] float[size] int32[style] bool[underline]
1007 int32[halign] int32[valign]
1008 string[fg-color] string[bg-color]
1009 bool[alternate] string[alt-fg-color] string[alt-bg-color]
1010 v3(int32[left-margin] int32[right-margin] int32[top-margin] int32[bottom-margin])
1013 Each Area represents the style for a different area of the table, in
1014 the following order: title, caption, footer, corner, column labels,
1015 row labels, data, and layers.
1017 @code{index} is the 1-based index of the Area, i.e. 1 for the first
1018 Area, through 8 for the final Area.
1020 @code{typeface} is the string name of the font used in the area. In
1021 the corpus, this is @code{SansSerif} in over 99% of instances and
1022 @code{Times New Roman} in the rest.
1024 @code{size} is the size of the font, in px (@pxref{SPV Light Detail
1025 Member Format}) The most common size in the corpus is 12 px. Even
1026 though @code{size} has a floating-point type, in the corpus its values
1027 are always integers.
1029 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
1030 1 (with value 2) is set for italic.
1032 @code{underline} is 1 if the font is underlined, 0 otherwise.
1034 @code{halign} specifies horizontal alignment: 0 for center, 2 for
1035 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
1036 alignment varies according to type: string data is left-justified,
1037 numbers and most other formats are right-justified.
1039 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1042 @code{fg-color} and @code{bg-color} are the foreground color and
1043 background color, respectively. In the corpus, these are always
1044 @code{#000000} and @code{#ffffff}, respectively.
1046 @code{alternate} is 1 if rows should alternate colors, 0 if all rows
1047 should be the same color. When @code{alternate} is 1,
1048 @code{alt-fg-color} and @code{alt-bg-color} specify the colors for the
1049 alternate rows; otherwise they are empty strings.
1051 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1052 @code{bottom-margin} are measured in px.
1054 @node SPV Light Member Borders
1061 be32[n-borders] Border*[n-borders]
1062 bool[show-grid-lines]
1071 The Borders reflect how borders between regions are drawn.
1073 The fixed value of @code{endian} can be used to validate the
1076 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
1078 Each Border describes one kind of border. @code{n-borders} seems to
1079 always be 19. Each @code{border-type} appears once (although in an
1080 unpredictable order) and correspond to the following borders:
1086 Left, top, right, and bottom outer frame.
1088 Left, top, right, and bottom inner frame.
1090 Left and top of data area.
1092 Horizontal and vertical dimension rows.
1094 Horizontal and vertical dimension columns.
1096 Horizontal and vertical category rows.
1098 Horizontal and vertical category columns.
1101 @code{stroke-type} describes how a border is drawn, as one of:
1118 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
1119 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
1120 opaque color, therefore opaque black is 0xff000000.
1122 @node SPV Light Member Print Settings
1123 @subsection Print Settings
1130 bool[paginate-layers]
1133 bool[top-continuation]
1134 bool[bottom-continuation]
1135 be32[n-orphan-lines]
1136 bestring[continuation-string])
1139 The PrintSettings reflect settings for printing. The fixed value of
1140 @code{endian} can be used to validate the endianness.
1142 @code{all-layers} is 1 to print all layers, 0 to print only the
1145 @code{paginate-layers} is 1 to print each layer at the start of a new
1146 page, 0 otherwise. (This setting is honored only @code{all-layers} is
1147 1, since otherwise only one layer is printed.)
1149 @code{fit-width} and @code{fit-length} control whether the table is
1150 shrunk to fit within a page's width or length, respectively.
1152 @code{n-orphan-lines} is the minimum number of rows or columns to put
1153 in one part of a table that is broken across pages.
1155 If @code{top-continuation} is 1, then @code{continuation-string} is
1156 printed at the top of a page when a table is broken across pages for
1157 printing; similarly for @code{bottom-continuation} and the bottom of a
1158 page. Usually, @code{continuation-string} is empty.
1160 @node SPV Light Member Table Settings
1161 @subsection Table Settings
1171 bool[show-row-labels-in-corner]
1172 bool[show-alphabetic-markers]
1173 bool[footnote-marker-superscripts]
1176 Breakpoints[row-breaks] Breakpoints[column-breaks]
1177 Keeps[row-keeps] Keeps[column-keeps]
1178 PointKeeps[row-point-keeps] PointKeeps[column-point-keeps]
1181 bestring[table-look]
1184 Breakpoints => be32[n-breaks] be32*[n-breaks]
1186 Keeps => be32[n-keeps] Keep*[n-keeps]
1187 Keep => be32[offset] be32[n]
1189 PointKeeps => be32[n-point-keeps] PointKeep*[n-point-keeps]
1190 PointKeep => be32[offset] be32 be32
1193 The TableSettings reflect display settings. The fixed value of
1194 @code{endian} can be used to validate the endianness.
1196 @code{current-layer} is the displayed layer. The interpretation when
1197 there is more than one layer dimension is not yet known.
1199 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
1200 any cell) are hidden; otherwise, they are shown.
1202 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
1203 the upper left corner; otherwise, they are shown nested.
1205 If @code{show-alphabetic-markers} is 1, markers are shown as letters
1206 (e.g.@: @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
1207 shown as numbers starting from 1.
1209 When @code{footnote-marker-superscripts} is 1, footnote markers are shown
1210 as superscripts, otherwise as subscripts.
1212 The Breakpoints are rows or columns after which there is a page break;
1213 for example, a row break of 1 requests a page break after the second
1214 row. Usually no breakpoints are specified, indicating that page
1215 breaks should be selected automatically.
1217 The Keeps are ranges of rows or columns to be kept together without a
1218 page break; for example, a row Keep with @code{offset} 1 and @code{n}
1219 10 requests that the 10 rows starting with the second row be kept
1220 together. Usually no Keeps are specified.
1222 The PointKeeps seem to be generated automatically based on
1223 user-specified Keeps. They seems to indicate a conversion from rows
1224 or columns to pixel or point offsets.
1226 @code{notes} is a text string that contains user-specified notes. It
1227 is displayed when the user hovers the cursor over the table, like
1228 ``alt text'' on a webpage. It is not printed. It is usually empty.
1230 @code{table-look} is the name of a SPSS ``TableLook'' table style,
1231 such as ``Default'' or ``Academic''; it is often empty.
1233 TableSettings ends with an arbitrary number of null bytes. A writer
1234 may safely write 82 null bytes.
1236 A writer may safely use 4 for @code{x5} and 0 for @code{x6}.
1238 @node SPV Light Member Formats
1243 int32[n-widths] int32*[n-widths]
1245 int32[current-layer]
1251 v3(count(X1 count(X2)) count(X3)))
1252 Y0 => int32[epoch] byte[decimal] byte[grouping]
1253 CustomCurrency => int32[n-ccs] string*[n-ccs]
1256 If @code{n-widths} is nonzero, then the accompanying integers are
1257 column widths as manually adjusted by the user.
1259 @code{locale} is a locale including an encoding, such as
1260 @code{en_US.windows-1252} or @code{it_IT.windows-1252}. The rest of
1261 the character strings in the member use this encoding. The encoding
1262 string is itself encoded in US-ASCII.
1264 @code{epoch} is the year that starts the epoch. A 2-digit year is
1265 interpreted as belonging to the 100 years beginning at the epoch. The
1266 default epoch year is 69 years prior to the current year; thus, in
1267 2017 this field by default contains 1948. In the corpus, @code{epoch}
1268 ranges from 1943 to 1948, plus some contain -1.
1270 @code{decimal} is the decimal point character. The observed values
1271 are @samp{.} and @samp{,}.
1273 @code{grouping} is the grouping character. Usually, it is @samp{,} if
1274 @code{decimal} is @samp{.}, and vice versa. Other observed values are
1275 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1276 indicating that digits should not be grouped).
1278 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
1279 following strings are CCA through CCE format strings. @xref{Custom
1280 Currency Formats,,, pspp, PSPP}. Most commonly these are all
1281 @code{-,,,} but other strings occur.
1285 X0 only appears, optionally, in version 1 members.
1290 string[command] string[command-local]
1291 string[language] string[charset] string[locale]
1294 Y2 => CustomCurrency byte[missing] bool[x16]
1297 @code{command} describes the statistical procedure that generated the
1298 output, in English. It is not necessarily the literal syntax name of
1299 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1300 Tests.'' @code{command-local} is the procedure's name, translated
1301 into the output language; it is often empty and, when it is not,
1302 sometimes the same as @code{command}.
1304 @code{dataset} is the name of the dataset analyzed to produce the
1305 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1306 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}. The latter
1307 is sometimes the empty string.
1309 @code{missing} is the character used to indicate that a cell contains
1310 a missing value. It is always observed as @samp{.}.
1312 X0 repeats @code{decimal}, @code{grouping}, CustomCurrency, and
1313 @code{missing} already included in Formats.
1315 A writer may safely use false for @code{x16}.
1319 X1 only appears in version 3 members.
1323 00 byte[x14] bool[x15]
1325 byte[show-variables]
1327 int32[x17] int32[x18]
1333 @code{lang} may indicate the language in use. Some values seem to be
1334 0: @t{en}, 1: @t{de}, 2: @t{es}, 3: @t{it}, 5: @t{ko}, 6: @t{pl}, 8:
1335 @t{zh-tw}, 10: @t{pt_BR}, 11: @t{fr}. The @code{locale} in Formats
1336 and the @code{language}, @code{charset}, and @code{locale} in X0 are
1337 more likely to be useful in practice.
1339 @code{show-variables} determines how variables are displayed by
1340 default. A value of 1 means to display variable names, 2 to display
1341 variable labels when available, 3 to display both (name followed by
1342 label, separated by a space). The most common value is 0, which
1343 probably means to use a global default.
1345 @code{show-values} is a similar setting for values. A value of 1
1346 means to display the value, 2 to display the value label when
1347 available, 3 to display both. Again, the most common value is 0,
1348 which probably means to use a global default.
1350 A writer may safely use 1 for @code{x14}, false for @code{x15}, -1 for
1351 @code{x17} and @code{x18}, and false for @code{x19}.
1355 X2 only appears in version 3 members.
1359 int32[n-row-heights] int32*[n-row-heights]
1360 int32[n-style-map] StyleMap*[n-style-map]
1361 int32[n-styles] StylePair*[n-styles]
1363 StyleMap => int64[cell-index] int16[style-index]
1366 If present, @code{n-row-heights} and the accompanying integers are row
1367 heights as manually adjusted by the user.
1369 The rest of X2 specifies styles for data cells. At first glance this
1370 is odd, because each data cell can have its own style embedded as part
1371 of the data, but in practice X2 specifies a style for a cell only if
1372 that cell is empty (and thus does not appear in the data at all).
1373 Each StyleMap specifies the index of a blank cell, calculated the same
1374 was as in the Cells (@pxref{SPV Light Member Cells}), along with a
1375 0-based index into the accompanying StylePair array.
1377 A writer may safely omit the optional @code{i0 i0} inside the
1378 @code{count(@dots{})}.
1382 X3 only appears in version 3 members.
1386 01 00 byte[x20] 00 00 00
1389 (string[dataset] string[datafile] i0 int32[date] i0)?
1394 @code{date} is a date, as seconds since the epoch, i.e.@: since
1395 January 1, 1970. Pivot tables within an SPV file often have dates a
1396 few minutes apart, so this is probably a creation date for the table
1397 rather than for the file.
1399 X3 repeats @code{decimal}, @code{grouping}, CustomCurrency, and
1400 @code{missing} already included in Formats. @code{command},
1401 @code{command-local}, @code{language}, @code{charset}, and
1402 @code{locale} have the same meaning as in X0.
1404 @code{small} is a small real number, e.g.@: .001. Numbers smaller
1405 than this in absolute value are displayed in scientific notation.
1407 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1408 and other times they are absent. The reader can distinguish by
1409 assuming that they are present and then checking whether the
1410 presumptive @code{dataset} contains a null byte (a valid string never
1413 A writer may safely use 4 for @code{x20} and omit the optional bytes
1416 @node SPV Light Member Dimensions
1417 @subsection Dimensions
1419 A pivot table presents multidimensional data. A Dimension identifies
1420 the categories associated with each dimension.
1423 Dimensions => int32[n-dims] Dimension*[n-dims]
1425 Value[name] DimProperties
1426 int32[n-categories] Category*[n-categories]
1431 bool[hide-dim-label]
1432 bool[hide-all-labels]
1436 @code{name} is the name of the dimension, e.g.@: @code{Variables},
1437 @code{Statistics}, or a variable name.
1439 The meanings of @code{x1} and @code{x3} are unknown. @code{x1} is
1440 usually 0 but many other values have been observed. A writer may
1441 safely use 0 for @code{x1} and 2 for @code{x3}.
1443 @code{x2} is 0, 1, or 2. For a pivot table with @var{L} layer
1444 dimensions, @var{R} row dimensions, and @var{C} column dimensions,
1445 @code{x2} is 2 for the first @var{L} dimensions, 0 for the next
1446 @var{R} dimensions, and 1 for the remaining @var{C} dimensions. This
1447 does not mean that the layer dimensions must be presented first,
1448 followed by the row dimensions, followed by the column dimensions---on
1449 the contrary, they are frequently in a different order---but @code{x2}
1450 must follow this pattern to prevent the pivot table from being
1453 If @code{hide-dim-label} is 00, the pivot table displays a label for
1454 the dimension itself. Because usually the group and category labels
1455 are enough explanation, it is usually 01.
1457 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1458 the dimension, including group and category labels. It is usually 00.
1459 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1461 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1462 0 for the first dimension, 1 for the second, and so on. Sometimes it
1463 is -1. There is no visible difference.
1465 @node SPV Light Member Categories
1466 @subsection Categories
1468 Categories are arranged in a tree. Only the leaf nodes in the tree
1469 are really categories; the others just serve as grouping constructs.
1472 Category => Value[name] (Leaf @math{|} Group)
1473 Leaf => 00 00 00 i2 int32[leaf-index] i0
1475 bool[merge] 00 01 int32[x22]
1476 i-1 int32[n-subcategories] Category*[n-subcategories]
1479 @code{name} is the name of the category (or group).
1481 A Leaf represents a leaf category. The Leaf's @code{leaf-index} is a
1482 nonnegative integer unique within the Dimension and less than
1483 @code{n-categories} in the Dimension. If the user does not sort or
1484 rearrange the categories, then @code{leaf-index} starts at 0 for the
1485 first Leaf in the dimension and increments by 1 with each successive
1486 Leaf. If the user does sorts or rearrange the categories, then the
1487 order of categories in the file reflects that change and
1488 @code{leaf-index} reflects the original order.
1490 Occasionally a dimension has no leaf categories at all. A table that
1491 contains such a dimension necessarily has no data at all.
1493 A Group is a group of nested categories. Usually a Group contains at
1494 least one Category, so that @code{n-subcategories} is positive, but a
1495 few Groups with @code{n-subcategories} 0 has been observed.
1497 If a Group's @code{merge} is 00, the most common value, then the group
1498 is really a distinct group that should be represented as such in the
1499 visual representation and user interface. If @code{merge} is 01, the
1500 categories in this group should be shown and treated as if they were
1501 direct children of the group's containing group (or if it has no
1502 parent group, then direct children of the dimension), and this group's
1503 name is irrelevant and should not be displayed. (Merged groups can be
1506 (For writing an SPV file, there is no need to use the @code{merge}
1507 feature unless it is convenient.)
1509 A Group's @code{x22} appears to be i2 when all of the categories
1510 within a group are leaf categories that directly represent data values
1511 for a variable (e.g.@: in a frequency table or crosstabulation, a group
1512 of values in a variable being tabulated) and i0 otherwise. A writer
1513 may safely write a constant 0 in this field.
1515 @node SPV Light Member Axes
1518 After the dimensions come assignment of each dimension to one of the
1519 axes: layers, rows, and columns.
1523 int32[n-layers] int32[n-rows] int32[n-columns]
1524 int32*[n-layers] int32*[n-rows] int32*[n-columns]
1527 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1528 each specifies the number of dimensions displayed in layers, rows, and
1529 columns, respectively. Any of them may be zero. Their values sum to
1530 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1533 The following @code{n-dimensions} integers, in three groups, are a
1534 permutation of the 0-based dimension numbers. The first
1535 @code{n-layers} integers specify each of the dimensions represented by
1536 layers, the next @code{n-rows} integers specify the dimensions
1537 represented by rows, and the final @code{n-columns} integers specify
1538 the dimensions represented by columns. When there is more than one
1539 dimension of a given kind, the inner dimensions are given first.
1541 @node SPV Light Member Cells
1544 The final part of an SPV light member contains the actual data.
1547 Cells => int32[n-cells] Cell*[n-cells]
1548 Cell => int64[index] v1(00?) Value
1551 A Cell consists of an @code{index} and a Value. Suppose there are
1552 @math{d} dimensions, numbered 1 through @math{d} in the order given in
1553 the Dimensions previously, and that dimension @math{i}, has @math{n_i}
1554 categories. Consider the cell at coordinates @math{x_i}, @math{1 \le
1555 i \le d}, and note that @math{0 \le x_i < n_i}. Then the index is
1556 calculated by the following algorithm:
1560 for each @math{i} from 1 to @math{d}:
1561 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1564 For example, suppose there are 3 dimensions with 3, 4, and 5
1565 categories, respectively. The cell at coordinates (1, 2, 3) has
1566 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1567 Within a given dimension, the index is the @code{leaf-index} in a Leaf.
1569 @node SPV Light Member Value
1572 Value is used throughout the SPV light member format. It boils down
1573 to a number or a string.
1576 Value => 00? 00? 00? 00? RawValue
1578 01 ValueMod int32[format] double[x]
1579 @math{|} 02 ValueMod int32[format] double[x]
1580 string[var-name] string[value-label] byte[show]
1581 @math{|} 03 string[local] ValueMod string[id] string[c] bool[fixed]
1582 @math{|} 04 ValueMod int32[format] string[value-label] string[var-name]
1583 byte[show] string[s]
1584 @math{|} 05 ValueMod string[var-name] string[var-label] byte[show]
1585 @math{|} ValueMod string[template] int32[n-args] Argument*[n-args]
1588 @math{|} int32[x] i0 Value*[x] /* x > 0 */
1591 There are several possible encodings, which one can distinguish by the
1592 first nonzero byte in the encoding.
1596 The numeric value @code{x}, intended to be presented to the user
1597 formatted according to @code{format}, which is in the format described
1598 for system files, except that format 40 is a synonym for F format
1599 instead of MTIME. @xref{System File Output Formats}, for details.
1600 Most commonly, @code{format} has width 40 (the maximum).
1602 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1603 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1604 not been observed.) @xref{System File Format}, for more about these
1608 Similar to @code{01}, with the additional information that @code{x} is
1609 a value of variable @code{var-name} and has value label
1610 @code{value-label}. Both @code{var-name} and @code{value-label} can
1611 be the empty string, the latter very commonly.
1613 @code{show} determines whether to show the numeric value or the value
1614 label. A value of 1 means to show the value, 2 to show the label, 3
1615 to show both, and 0 means to use the default specified in
1616 @code{show-values} (@pxref{SPV Light Member Formats}).
1619 A text string, in two forms: @code{c} is in English, and sometimes
1620 abbreviated or obscure, and @code{local} is localized to the user's
1621 locale. In an English-language locale, the two strings are often the
1622 same, and in the cases where they differ, @code{local} is more
1623 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1624 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1625 where P must be greater than 1.''
1627 @code{c} and @code{local} are always either both empty or both
1630 @code{id} is a brief identifying string whose form seems to resemble a
1631 programming language identifier, e.g.@: @code{cumulative_percent} or
1632 @code{factor_14}. It is not unique.
1634 @code{fixed} is 00 for text taken from user input, such as syntax
1635 fragment, expressions, file names, data set names, and 01 for fixed
1636 text strings such as names of procedures or statistics. In the former
1637 case, @code{id} is always the empty string; in the latter case,
1638 @code{id} is still sometimes empty.
1641 The string value @code{s}, intended to be presented to the user
1642 formatted according to @code{format}. The format for a string is not
1643 too interesting, and the corpus contains many clearly invalid formats
1644 like A16.39 or A255.127 or A134.1, so readers should probably ignore
1645 the format entirely.
1647 @code{s} is a value of variable @code{var-name} and has value label
1648 @code{value-label}. @code{var-name} is never empty but
1649 @code{value-label} is commonly empty.
1651 @code{show} has the same meaning as in the encoding for 02.
1654 Variable @code{var-name}, which is rarely observed as empty in the
1655 corpus, with variable label @code{var-label}, which is often empty.
1657 @code{show} determines whether to show the variable name or the
1658 variable label. A value of 1 means to show the name, 2 to show the
1659 label, 3 to show both, and 0 means to use the default specified in
1660 @code{show-variables} (@pxref{SPV Light Member Formats}).
1663 When the first byte of a RawValue is not one of the above, the
1664 RawValue starts with a ValueMod, whose syntax is described in the next
1665 section. (A ValueMod always begins with byte 31 or 58.)
1667 This case is a template string, analogous to @code{printf}, followed
1668 by one or more Arguments, each of which has one or more values. The
1669 template string is copied directly into the output except for the
1670 following special syntax,
1677 Each of these expands to the character following @samp{\\}, to escape
1678 characters that have special meaning in template strings. These are
1679 effective inside and outside the @code{[@dots{}]} syntax forms
1683 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1687 Expands to a formatted version of argument @var{i}, which must have
1688 only a single value. For example, @code{^1} expands to the first
1689 argument's @code{value}.
1691 @item [:@var{a}:]@var{i}
1692 Expands @var{a} for each of the values in @var{i}. @var{a}
1693 should contain one or more @code{^@var{j}} conversions, which are
1694 drawn from the values for argument @var{i} in order. Some examples
1699 All of the values for the first argument, concatenated.
1702 Expands to the values for the first argument, each followed by
1706 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1707 argument's first value and @var{y} is its second value. (This would
1708 be used only if the argument has two values. If there were more
1709 values, the second and third values would be directly concatenated,
1710 which would look funny.)
1713 @item [@var{a}:@var{b}:]@var{i}
1714 This extends the previous form so that the first values are expanded
1715 using @var{a} and later values are expanded using @var{b}. For an
1716 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1717 instead written as @code{%@var{j}}. Some examples from the corpus:
1721 Expands to all of the values for the first argument, separated by
1724 @item [%1 = %2:, ^1 = ^2:]1
1725 Given appropriate values for the first argument, expands to @code{X =
1729 Given appropriate values, expands to @code{1, 2, 3}.
1733 The template string is localized to the user's locale.
1736 A writer may safely omit all of the optional 00 bytes at the beginning
1737 of a Value, except that it should write a single 00 byte before a
1740 @node SPV Light Member ValueMod
1741 @subsection ValueMod
1743 A ValueMod can specify special modifications to a Value.
1749 int32[n-refs] int16*[n-refs]
1750 (i0 | i1 string[subscript])
1751 v1(00 (i1 | i2) 00? 00? int32 00? 00?)
1752 v3(count(TemplateString StylePair))
1754 TemplateString => count((count((i0 58)?) (58 @math{|} 31 string[id]))?)
1761 bool[bold] bool[italic] bool[underline] bool[show]
1762 string[fg-color] string[bg-color]
1763 string[typeface] byte[size]
1766 int32[halign] int32[valign] double[decimal-offset]
1767 int16[left-margin] int16[right-margin]
1768 int16[top-margin] int16[bottom-margin]
1771 A ValueMod that begins with ``31'' specifies special modifications to
1774 Each of the @code{n-refs} integers is a reference to a Footnote
1775 (@pxref{SPV Light Member Footnotes}) by 0-based index. Footnote
1776 markers are shown appended to the main text of the Value, as
1779 The @code{subscript}, if present, is a string to append to the main
1780 text of the Value, as a subscript. The subscript text is a brief
1781 indicator, e.g.@: @samp{a} or @samp{a,b}, with its meaning indicated
1782 by the table caption.
1784 The @code{id} inside the TemplateString, if present, is a template
1785 string for substitutions using the syntax explained previously. It
1786 appears to be an English-language version of the localized template
1787 string in the Value in which the Template is nested. A writer may
1788 safely omit the optional fixed data in TemplateString.
1790 FontStyle and CellStyle, if present, change the style for this
1791 individual Value. In FontStyle, @code{bold}, @code{italic}, and
1792 @code{underline} control the particular style. @code{show} is
1793 ordinarily 1; if it is 0, then the cell data is not shown.
1794 @code{fg-color} and @code{bg-color} are strings in the format
1795 @code{#rrggbb}, e.g.@: @code{#ff0000} for red or @code{#ffffff} for
1796 white. The empty string is occasionally observed also. The
1797 @code{size} is a font size in units of 1/128 inch.
1799 In CellStyle, @code{halign} is 0 for center, 2 for left, 4 for right,
1800 6 for decimal, 0xffffffad for mixed. For decimal alignment,
1801 @code{decimal-offset} is the decimal point's offset from the right
1802 side of the cell, in pt (@pxref{SPV Light Detail Member Format}).
1803 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1804 for bottom. @code{left-margin}, @code{right-margin},
1805 @code{top-margin}, and @code{bottom-margin} are in pt.
1807 @node SPV Legacy Detail Member Binary Format
1808 @section Legacy Detail Member Binary Format
1810 Whereas the light binary format represents everything about a given
1811 pivot table, the legacy binary format conceptually consists of a
1812 number of named sources, each of which consists of a number of named
1813 variables, each of which is a 1-dimensional array of numbers or
1814 strings or a mix. Thus, the legacy binary member format is quite
1817 This section uses the same context-free grammar notation as in the
1818 previous section, with the following additions:
1822 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
1823 (The legacy member header indicates the version; see below.)
1826 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
1829 A legacy detail member @file{.bin} has the following overall format:
1833 00 byte[version] int16[n-sources] int32[member-size]
1834 Metadata*[n-sources]
1839 @code{version} is a version number that affects the interpretation of
1840 some of the other data in the member. Versions 0xaf and 0xb0 are
1841 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
1844 A legacy member consists of @code{n-sources} data sources, each of
1845 which has Metadata and Data.
1847 @code{member-size} is the size of the legacy binary member, in bytes.
1849 The Data and Strings above are commented out because the Metadata has
1850 some oddities that mean that the Data sometimes seems to start at
1851 an unexpected place. The following section goes into detail.
1854 * SPV Legacy Member Metadata::
1855 * SPV Legacy Member Numeric Data::
1856 * SPV Legacy Member String Data::
1859 @node SPV Legacy Member Metadata
1860 @subsection Metadata
1864 int32[n-values] int32[n-variables] int32[data-offset]
1865 vAF(byte*28[source-name])
1866 vB0(byte*64[source-name] int32[x])
1869 A data source has @code{n-variables} variables, each with
1870 @code{n-values} data values.
1872 @code{source-name} is a 28- or 64-byte string padded on the right with
1873 0-bytes. The names that appear in the corpus are very generic:
1874 usually @code{tableData} for pivot table data or @code{source0} for
1877 A given Metadata's @code{data-offset} is the offset, in bytes, from
1878 the beginning of the member to the start of the corresponding Data.
1879 This allows programs to skip to the beginning of the data for a
1880 particular source. In every case in the corpus, the Data follow the
1881 Metadata in the same order, but it is important to use
1882 @code{data-offset} instead of reading sequentially through the file
1883 because of the exception described below.
1885 One SPV file in the corpus has legacy binary members with version 0xb0
1886 but a 28-byte @code{source-name} field (and only a single source). In
1887 practice, this means that the 64-byte @code{source-name} used in
1888 version 0xb0 has a lot of 0-bytes in the middle followed by the
1889 @code{variable-name} of the following Data. As long as a reader
1890 treats the first 0-byte in the @code{source-name} as terminating the
1891 string, it can properly interpret these members.
1893 The meaning of @code{x} in version 0xb0 is unknown.
1895 @node SPV Legacy Member Numeric Data
1896 @subsection Numeric Data
1899 Data => Variable*[n-variables]
1900 Variable => byte*288[variable-name] double*[n-values]
1903 Data follow the Metadata in the legacy binary format, with sources in
1904 the same order (but readers should use the @code{data-offset} in
1905 Metadata records, rather than reading sequentially). Each Variable
1906 begins with a @code{variable-name} that generally indicates its role
1907 in the pivot table, e.g.@: ``cell'', ``cellFormat'',
1908 ``dimension0categories'', ``dimension0group0'', followed by the
1909 numeric data, one double per datum. A double with the maximum
1910 negative double @code{-DBL_MAX} represents the system-missing value
1913 @node SPV Legacy Member String Data
1914 @subsection String Data
1917 Strings => SourceMaps[maps] Labels
1919 SourceMaps => int32[n-maps] SourceMap*[n-maps]
1921 SourceMap => string[source-name] int32[n-variables] VariableMap*[n-variables]
1922 VariableMap => string[variable-name] int32[n-data] DatumMap*[n-data]
1923 DatumMap => int32[value-idx] int32[label-idx]
1925 Labels => int32[n-labels] Label*[n-labels]
1926 Label => int32[frequency] string[label]
1929 Each variable may include a mix of numeric and string data values. If
1930 a legacy binary member contains any string data, Strings is present;
1931 otherwise, it ends just after the last Data element.
1933 The string data overlays the numeric data. When a variable includes
1934 any string data, its Variable represents the string values with a
1935 SYSMIS or NaN placeholder. (Not all such values need be
1938 Each SourceMap provides a mapping between SYSMIS or NaN values in source
1939 @code{source-name} and the string data that they represent.
1940 @code{n-variables} is the number of variables in the source that
1941 include string data. More precisely, it is the 1-based index of the
1942 last variable in the source that includes any string data; thus, it
1943 would be 4 if there are 5 variables and only the fourth one includes
1946 A VariableMap repeats its variable's name, but variables are always
1947 present in the same order as the source, starting from the first
1948 variable, without skipping any even if they have no string values.
1949 Each VariableMap contains DatumMap nonterminals, each of which maps
1950 from a 0-based index within its variable's data to a 0-based label
1951 index, e.g.@: pair @code{value-idx} = 2, @code{label-idx} = 3, means
1952 that the third data value (which must be SYSMIS or NaN) is to be
1953 replaced by the string of the fourth Label.
1955 The labels themselves follow the pairs. The valuable part of each
1956 label is the string @code{label}. Each label also includes a
1957 @code{frequency} that reports the number of DatumMaps that reference
1958 it (although this is not useful).
1960 @node SPV Legacy Detail Member XML Format
1961 @section Legacy Detail Member XML Format
1963 The design of the detail XML format is not what one would end up with
1964 for describing pivot tables. This is because it is a special case
1965 of a much more general format (``visualization XML'' or ``VizML'')
1966 that can describe a wide range of visualizations. Most of this
1967 generality is overkill for tables, and so we end up with a funny
1968 subset of a general-purpose format.
1970 An XML Schema for VizML is available, distributed with SPSS binaries,
1971 under a nonfree license. It contains documentation that is
1972 occasionally helpful.
1974 This section describes the detail XML format using the same notation
1975 already used for the structure XML format (@pxref{SPV Structure Member
1976 Format}). See @file{src/output/spv/detail-xml.grammar} in the PSPP
1977 source tree for the full grammar that it uses for parsing.
1979 The important elements of the detail XML format are:
1983 Variables. @xref{SPV Detail Variable Elements}.
1986 Assignment of variables to axes. A variable can appear as columns, or
1987 rows, or layers. The @code{faceting} element and its sub-elements
1988 describe this assignment.
1991 Styles and other annotations.
1994 This description is not detailed enough to write legacy tables.
1995 Instead, write tables in the light binary format.
1998 * SPV Detail visualization Element::
1999 * SPV Detail Variable Elements::
2000 * SPV Detail extension Element::
2001 * SPV Detail graph Element::
2002 * SPV Detail location Element::
2003 * SPV Detail faceting Element::
2004 * SPV Detail facetLayout Element::
2005 * SPV Detail label Element::
2006 * SPV Detail setCellProperties Element::
2007 * SPV Detail setFormat Element::
2008 * SPV Detail interval Element::
2009 * SPV Detail style Element::
2010 * SPV Detail labelFrame Element::
2011 * SPV Detail Legacy Properties::
2014 @node SPV Detail visualization Element
2015 @subsection The @code{visualization} Element
2023 :style[style_ref]=ref style
2027 => visualization_extension?
2029 (sourceVariable | derivedVariable)+
2038 extension[visualization_extension]
2041 :minWidthSet=(true)?
2042 :maxWidthSet=(true)?
2045 userSource :missing=(listwise | pairwise)? => EMPTY
2047 categoricalDomain => variableReference simpleSort
2049 simpleSort :method[sort_method]=(custom) => categoryOrder
2051 container :style=ref style => container_extension? location+ labelFrame*
2053 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2061 The @code{visualization} element is the root of detail XML member. It
2062 has the following attributes:
2064 @defvr {Attribute} creator
2065 The version of the software that created this SPV file, as a string of
2066 the form @code{xxyyzz}, which represents software version xx.yy.zz,
2067 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
2068 versions 16 through 19.
2071 @defvr {Attribute} date
2072 The date on the which the file was created, as a string of the form
2076 @defvr {Attribute} lang
2077 The locale used for output, in Windows format, which is similar to the
2078 format used in Unix with the underscore replaced by a hyphen, e.g.@:
2079 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
2082 @defvr {Attribute} name
2083 The title of the pivot table, localized to the output language.
2086 @defvr {Attribute} style
2087 The base style for the pivot table. In every example in the corpus,
2088 the @code{style} element has no attributes other than @code{id}.
2091 @defvr {Attribute} type
2092 A floating-point number. The meaning is unknown.
2095 @defvr {Attribute} version
2096 The visualization schema version number. In the corpus, the value is
2097 one of 2.4, 2.5, 2.7, and 2.8.
2100 The @code{userSource} element has no visible effect.
2102 The @code{extension} element as a child of @code{visualization} has
2103 the following attributes.
2105 @defvr {Attribute} numRows
2106 An integer that presumably defines the number of rows in the displayed
2110 @defvr {Attribute} showGridline
2111 Always set to @code{false} in the corpus.
2114 @defvr {Attribute} minWidthSet
2115 @defvrx {Attribute} maxWidthSet
2116 Always set to @code{true} in the corpus.
2119 The @code{extension} element as a child of @code{container} has the
2122 @defvr {Attribute} combinedFootnotes
2126 The @code{categoricalDomain} and @code{simpleSort} elements have no
2129 The @code{layerController} element has no visible effect.
2131 @node SPV Detail Variable Elements
2132 @subsection Variable Elements
2134 A ``variable'' in detail XML is a 1-dimensional array of data. Each
2135 element of the array may, independently, have string or numeric
2136 content. All of the variables in a given detail XML member either
2137 have the same number of elements or have zero elements.
2139 Two different elements define variables and their content:
2142 @item sourceVariable
2143 These variables' data comes from the associated @code{tableData.bin}
2146 @item derivedVariable
2147 These variables are defined in terms of a mapping function from a
2148 source variable, or they are empty.
2151 A variable named @code{cell} always exists. This variable holds the
2152 data displayed in the table.
2154 Variables in detail XML roughly correspond to the dimensions in a
2155 light detail member. Each dimension has the following variables with
2156 stylized names, where @var{n} is a number for the dimension starting
2160 @item dimension@var{n}categories
2161 The dimension's leaf categories (@pxref{SPV Light Member Categories}).
2163 @item dimension@var{n}group0
2164 Present only if the dimension's categories are grouped, this variable
2165 holds the group labels for the categories. Grouping is inferred
2166 through adjacent identical labels. Categories that are not part of a
2167 group have empty-string data in this variable.
2169 @item dimension@var{n}group1
2170 Present only if the first-level groups are further grouped, this
2171 variable holds the labels for the second-level groups. There can be
2172 additional variables with further levels of grouping.
2174 @item dimension@var{n}
2178 Determining the data for a (non-empty) variable is a multi-step
2183 Draw initial data from its source, for a @code{sourceVariable}, or
2184 from another named variable, for a @code{derivedVariable}.
2187 Apply mappings from @code{valueMapEntry} elements within the
2188 @code{derivedVariable} element, if any.
2191 Apply mappings from @code{relabel} elements within a @code{format} or
2192 @code{stringFormat} element in the @code{sourceVariable} or
2193 @code{derivedVariable} element, if any.
2196 If the variable is a @code{sourceVariable} with a @code{labelVariable}
2197 attribute, and there were no mappings to apply in previous steps, then
2198 replace each element of the variable by the corresponding value in the
2202 A single variable's data can be modified in two of the steps, if both
2203 @code{valueMapEntry} and @code{relabel} are used. The following
2204 example from the corpus maps several integers to 2, then maps 2 in
2205 turn to the string ``Input'':
2208 <derivedVariable categorical="true" dependsOn="dimension0categories"
2209 id="dimension0group0map" value="map(dimension0group0)">
2211 <relabel from="2" to="Input"/>
2212 <relabel from="10" to="Missing Value Handling"/>
2213 <relabel from="14" to="Resources"/>
2214 <relabel from="0" to=""/>
2215 <relabel from="1" to=""/>
2216 <relabel from="13" to=""/>
2218 <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
2219 <valueMapEntry from="10;11" to="10"/>
2220 <valueMapEntry from="14;15" to="14"/>
2221 <valueMapEntry from="0" to="0"/>
2222 <valueMapEntry from="1" to="1"/>
2223 <valueMapEntry from="13" to="13"/>
2228 * SPV Detail sourceVariable Element::
2229 * SPV Detail derivedVariable Element::
2230 * SPV Detail valueMapEntry Element::
2233 @node SPV Detail sourceVariable Element
2234 @subsubsection The @code{sourceVariable} Element
2241 :domain=ref categoricalDomain?
2243 :dependsOn=ref sourceVariable?
2245 :labelVariable=ref sourceVariable?
2246 => variable_extension* (format | stringFormat)?
2249 This element defines a variable whose data comes from the
2250 @file{tableData.bin} member that corresponds to this @file{.xml}.
2252 This element has the following attributes.
2254 @defvr {Attribute} id
2255 An @code{id} is always present because this element exists to be
2256 referenced from other elements.
2259 @defvr {Attribute} categorical
2260 Always set to @code{true}.
2263 @defvr {Attribute} source
2264 Always set to @code{tableData}, the @code{source-name} in the
2265 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
2269 @defvr {Attribute} sourceName
2270 The name of a variable within the source, corresponding to the
2271 @code{variable-name} in the @file{tableData.bin} member (@pxref{SPV
2272 Legacy Member Numeric Data}).
2275 @defvr {Attribute} label
2276 The variable label, if any.
2279 @defvr {Attribute} labelVariable
2280 The @code{variable-name} of a variable whose string values correspond
2281 one-to-one with the values of this variable and are suitable for use
2285 @defvr {Attribute} dependsOn
2286 This attribute doesn't affect the display of a table.
2289 @node SPV Detail derivedVariable Element
2290 @subsubsection The @code{derivedVariable} Element
2297 :dependsOn=ref sourceVariable?
2298 => variable_extension* (format | stringFormat)? valueMapEntry*
2301 Like @code{sourceVariable}, this element defines a variable whose
2302 values can be used elsewhere in the visualization. Instead of being
2303 read from a data source, the variable's data are defined by a
2304 mathematical expression.
2306 This element has the following attributes.
2308 @defvr {Attribute} id
2309 An @code{id} is always present because this element exists to be
2310 referenced from other elements.
2313 @defvr {Attribute} categorical
2314 Always set to @code{true}.
2317 @defvr {Attribute} value
2318 An expression that defines the variable's value. In theory this could
2319 be an arbitrary expression in terms of constants, functions, and other
2320 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
2321 the corpus contains only the following forms of expressions:
2325 @itemx constant(@var{variable})
2326 All zeros. The reason why a variable is sometimes named is unknown.
2327 Sometimes the ``variable name'' has spaces in it.
2329 @item map(@var{variable})
2330 Transforms the values in the named @var{variable} using the
2331 @code{valueMapEntry}s contained within the element.
2335 @defvr {Attribute} dependsOn
2336 This attribute doesn't affect the display of a table.
2339 @node SPV Detail valueMapEntry Element
2340 @subsubsection The @code{valueMapEntry} Element
2343 valueMapEntry :from :to => EMPTY
2346 A @code{valueMapEntry} element defines a mapping from one or more
2347 values of a source expression to a target value. (In the corpus, the
2348 source expression is always just the name of a variable.) Each target
2349 value requires a separate @code{valueMapEntry}. If multiple source
2350 values map to the same target value, they can be combined or separate.
2352 In the corpus, all of the source and target values are integers.
2354 @code{valueMapEntry} has the following attributes.
2356 @defvr {Attribute} from
2357 A source value, or multiple source values separated by semicolons,
2358 e.g.@: @code{0} or @code{13;14;15;16}.
2361 @defvr {Attribute} to
2362 The target value, e.g.@: @code{0}.
2365 @node SPV Detail extension Element
2366 @subsection The @code{extension} Element
2368 This is a general-purpose ``extension'' element. Readers that don't
2369 understand a given extension should be able to safely ignore it. The
2370 attributes on this element, and their meanings, vary based on the
2371 context. Each known usage is described separately below. The current
2372 extensions use attributes exclusively, without any nested elements.
2374 @subsubheading @code{container} Parent Element
2377 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2380 With @code{container} as its parent element, @code{extension} has the
2381 following attributes.
2383 @defvr {Attribute} combinedFootnotes
2384 Always set to @code{true} in the corpus.
2387 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
2390 extension[variable_extension] :from :helpId => EMPTY
2393 With @code{sourceVariable} or @code{derivedVariable} as its parent
2394 element, @code{extension} has the following attributes. A given
2395 parent element often contains several @code{extension} elements that
2396 specify the meaning of the source data's variables or sources, e.g.@:
2399 <extension from="0" helpId="corrected_model"/>
2400 <extension from="3" helpId="error"/>
2401 <extension from="4" helpId="total_9"/>
2402 <extension from="5" helpId="corrected_total"/>
2405 More commonly they are less helpful, e.g.@:
2408 <extension from="0" helpId="notes"/>
2409 <extension from="1" helpId="notes"/>
2410 <extension from="2" helpId="notes"/>
2411 <extension from="5" helpId="notes"/>
2412 <extension from="6" helpId="notes"/>
2413 <extension from="7" helpId="notes"/>
2414 <extension from="8" helpId="notes"/>
2415 <extension from="12" helpId="notes"/>
2416 <extension from="13" helpId="no_help"/>
2417 <extension from="14" helpId="notes"/>
2420 @defvr {Attribute} from
2421 An integer or a name like ``dimension0''.
2424 @defvr {Attribute} helpId
2428 @node SPV Detail graph Element
2429 @subsection The @code{graph} Element
2433 :cellStyle=ref style
2435 => location+ coordinates faceting facetLayout interval
2437 coordinates => EMPTY
2440 @code{graph} has the following attributes.
2442 @defvr {Attribute} cellStyle
2443 @defvrx {Attribute} style
2444 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
2445 Detail style Element}). The former is the default style for
2446 individual cells, the latter for the entire table.
2449 @node SPV Detail location Element
2450 @subsection The @code{location} Element
2454 :part=(height | width | top | bottom | left | right)
2455 :method=(sizeToContent | attach | fixed | same)
2458 :target=ref (labelFrame | graph | container)?
2463 Each instance of this element specifies where some part of the table
2464 frame is located. All the examples in the corpus have four instances
2465 of this element, one for each of the parts @code{height},
2466 @code{width}, @code{left}, and @code{top}. Some examples in the
2467 corpus add a fifth for part @code{bottom}, even though it is not clear
2468 how all of @code{top}, @code{bottom}, and @code{height} can be honored
2469 at the same time. In any case, @code{location} seems to have little
2470 importance in representing tables; a reader can safely ignore it.
2472 @defvr {Attribute} part
2473 The part of the table being located.
2476 @defvr {Attribute} method
2477 How the location is determined:
2481 Based on the natural size of the table. Observed only for
2482 parts @code{height} and @code{width}.
2485 Based on the location specified in @code{target}. Observed only for
2486 parts @code{top} and @code{bottom}.
2489 Using the value in @code{value}. Observed only for parts @code{top},
2490 @code{bottom}, and @code{left}.
2493 Same as the specified @code{target}. Observed only for part
2498 @defvr {Attribute} min
2499 Minimum size. Only observed with value @code{100pt}. Only observed
2500 for part @code{width}.
2503 @defvr {Dependent} target
2504 Required when @code{method} is @code{attach} or @code{same}, not
2505 observed otherwise. This identifies an element to attach to.
2506 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
2510 @defvr {Dependent} value
2511 Required when @code{method} is @code{fixed}, not observed otherwise.
2512 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
2513 on parts @code{top} and @code{left}, and @code{100%} on part
2517 @node SPV Detail faceting Element
2518 @subsection The @code{faceting} Element
2521 faceting => layer[layers1]* cross layer[layers2]*
2523 cross => (unity | nest) (unity | nest)
2527 nest => variableReference[vars]+
2529 variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY
2532 :variable=ref (sourceVariable | derivedVariable)
2535 :method[layer_method]=(nest)?
2540 The @code{faceting} element describes the row, column, and layer
2541 structure of the table. Its @code{cross} child determines the row and
2542 column structure, and each @code{layer} child (if any) represents a
2543 layer. Layers may appear before or after @code{cross}.
2545 The @code{cross} element describes the row and column structure of the
2546 table. It has exactly two children, the first of which describes the
2547 table's columns and the second the table's rows. Each child is a
2548 @code{nest} element if the table has any dimensions along the axis in
2549 question, otherwise a @code{unity} element.
2551 A @code{nest} element contains of one or more dimensions listed from
2552 innermost to outermost, each represented by @code{variableReference}
2553 child elements. Each variable in a dimension is listed in order.
2554 @xref{SPV Detail Variable Elements}, for information on the variables
2555 that comprise a dimension.
2557 A @code{nest} can contain a single dimension, e.g.:
2561 <variableReference ref="dimension0categories"/>
2562 <variableReference ref="dimension0group0"/>
2563 <variableReference ref="dimension0"/>
2568 A @code{nest} can contain multiple dimensions, e.g.:
2572 <variableReference ref="dimension1categories"/>
2573 <variableReference ref="dimension1group0"/>
2574 <variableReference ref="dimension1"/>
2575 <variableReference ref="dimension0categories"/>
2576 <variableReference ref="dimension0"/>
2580 A @code{nest} may have no dimensions, in which case it still has one
2581 @code{variableReference} child, which references a
2582 @code{derivedVariable} whose @code{value} attribute is
2583 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
2584 @code{row} or @code{column}, respectively, as its @code{id}. This is
2585 equivalent to using a @code{unity} element in place of @code{nest}.
2587 A @code{variableReference} element refers to a variable through its
2588 @code{ref} attribute.
2590 Each @code{layer} element represents a dimension, e.g.:
2593 <layer value="0" variable="dimension0categories" visible="true"/>
2594 <layer value="dimension0" variable="dimension0" visible="false"/>
2598 @code{layer} has the following attributes.
2600 @defvr {Attribute} variable
2601 Refers to a @code{sourceVariable} or @code{derivedVariable} element.
2604 @defvr {Attribute} value
2605 The value to select. For a category variable, this is always
2606 @code{0}; for a data variable, it is the same as the @code{variable}
2610 @defvr {Attribute} visible
2611 Whether the layer is visible. Generally, category layers are visible
2612 and data layers are not, but sometimes this attribute is omitted.
2615 @defvr {Attribute} method
2616 When present, this is always @code{nest}.
2619 @node SPV Detail facetLayout Element
2620 @subsection The @code{facetLayout} Element
2623 facetLayout => tableLayout setCellProperties[scp1]*
2624 facetLevel+ setCellProperties[scp2]*
2627 :verticalTitlesInCorner=bool
2629 :fitCells=(ticks both)?
2633 The @code{facetLayout} element and its descendants control styling for
2636 Its @code{tableLayout} child has the following attributes
2638 @defvr {Attribute} verticalTitlesInCorner
2639 If true, in the absence of corner text, row headings will be displayed
2643 @defvr {Attribute} style
2644 Refers to a @code{style} element.
2647 @defvr {Attribute} fitCells
2651 @subsubheading The @code{facetLevel} Element
2654 facetLevel :level=int :gap=dimension? => axis
2656 axis :style=ref style => label? majorTicks
2662 :tickFrameStyle=ref style
2663 :labelFrequency=int?
2673 Each @code{facetLevel} describes a @code{variableReference} or
2674 @code{layer}, and a table has one @code{facetLevel} element for
2675 each such element. For example, an SPV detail member that contains
2676 four @code{variableReference} elements and two @code{layer} elements
2677 will contain six @code{facetLevel} elements.
2679 In the corpus, @code{facetLevel} elements and the elements that they
2680 describe are always in the same order. The correspondence may also be
2681 observed in two other ways. First, one may use the @code{level}
2682 attribute, described below. Second, in the corpus, a
2683 @code{facetLevel} always has an @code{id} that is the same as the
2684 @code{id} of the element it describes with @code{_facetLevel}
2685 appended. One should not formally rely on this, of course, but it is
2686 usefully indicative.
2688 @defvr {Attribute} level
2689 A 1-based index into the @code{variableReference} and @code{layer}
2690 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2691 describes the first @code{variableReference} in the SPV detail member,
2692 and in a member with four @code{variableReference} elements, a
2693 @code{facetLayout} with a @code{level} of 5 describes the first
2694 @code{layer} in the member.
2697 @defvr {Attribute} gap
2698 Always observed as @code{0pt}.
2701 Each @code{facetLevel} contains an @code{axis}, which in turn may
2702 contain a @code{label} for the @code{facetLevel} (@pxref{SPV Detail
2703 label Element}) and does contain a @code{majorTicks} element.
2705 @defvr {Attribute} labelAngle
2706 Normally 0. The value -90 causes inner column or outer row labels to
2707 be rotated vertically.
2710 @defvr {Attribute} style
2711 @defvrx {Attribute} tickFrameStyle
2712 Each refers to a @code{style} element. @code{style} is the style of
2713 the tick labels, @code{tickFrameStyle} the style for the frames around
2717 @node SPV Detail label Element
2718 @subsection The @code{label} Element
2723 :textFrameStyle=ref style?
2724 :purpose=(title | subTitle | subSubTitle | layer | footnote)?
2725 => text+ | descriptionGroup
2728 :target=ref faceting
2730 => (description | text)+
2732 description :name=(variable | value) => EMPTY
2736 :definesReference=int?
2737 :position=(subscript | superscript)?
2742 This element represents a label on some aspect of the table.
2744 @defvr {Attribute} style
2745 @defvrx {Attribute} textFrameStyle
2746 Each of these refers to a @code{style} element. @code{style} is the
2747 style of the label text, @code{textFrameStyle} the style for the frame
2751 @defvr {Attribute} purpose
2752 The kind of entity being labeled.
2755 A @code{descriptionGroup} concatenates one or more elements to form a
2756 label. Each element can be a @code{text} element, which contains
2757 literal text, or a @code{description} element that substitutes a value
2760 @defvr {Attribute} target
2761 The @code{id} of an element being described. In the corpus, this is
2762 always @code{faceting}.
2765 @defvr {Attribute} separator
2766 A string to separate the description of multiple groups, if the
2767 @code{target} has more than one. In the corpus, this is always a
2771 Typical contents for a @code{descriptionGroup} are a value by itself:
2773 <description name="value"/>
2775 @noindent or a variable and its value, separated by a colon:
2777 <description name="variable"/><text>:</text><description name="value"/>
2780 A @code{description} is like a macro that expands to some property of
2781 the target of its parent @code{descriptionGroup}. The @code{name}
2782 attribute specifies the property.
2784 @node SPV Detail setCellProperties Element
2785 @subsection The @code{setCellProperties} Element
2789 :applyToConverse=bool?
2790 => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]?
2793 The @code{setCellProperties} element sets style properties of cells or
2794 row or column labels.
2796 Interpreting @code{setCellProperties} requires answering two
2797 questions: which cells or labels to style, and what styles to use.
2799 @subsubheading Which Cells?
2804 intersect => where+ | intersectWhere | alternating | EMPTY
2807 :variable=ref (sourceVariable | derivedVariable)
2812 :variable=ref (sourceVariable | derivedVariable)
2813 :variable2=ref (sourceVariable | derivedVariable)
2816 alternating => EMPTY
2819 When @code{union} is present with @code{intersect} children, each of
2820 those children specifies a group of cells that should be styled, and
2821 the total group is all those cells taken together. When @code{union}
2822 is absent, every cell is styled. One attribute on
2823 @code{setCellProperties} affects the choice of cells:
2825 @defvr {Attribute} applyToConverse
2826 If true, this inverts the meaning of the cell selection: the selected
2827 cells are the ones @emph{not} designated. This is confusing, given
2828 the additional restrictions of @code{union}, but in the corpus
2829 @code{applyToConverse} is never present along with @code{union}.
2832 An @code{intersect} specifies restrictions on the cells to be matched.
2833 Each @code{where} child specifies which values of a given variable to
2834 include. The attributes of @code{intersect} are:
2836 @defvr {Attribute} variable
2837 Refers to a variable, e.g.@: @code{dimension0categories}. Only
2838 ``categories'' variables make sense here, but other variables, e.g.@:
2839 @code{dimension0group0map}, are sometimes seen. The reader may ignore
2843 @defvr {Attribute} include
2844 A value, or multiple values separated by semicolons,
2845 e.g.@: @code{0} or @code{13;14;15;16}.
2848 PSPP ignores @code{setCellProperties} when @code{intersectWhere} is
2851 @subsubheading What Styles?
2855 :target=ref (labeling | graph | interval | majorTicks)
2859 setMetaData :target=ref graph :key :value => EMPTY
2862 :target=ref (majorTicks | labeling)
2864 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
2868 :target=ref majorTicks
2872 The @code{set*} children of @code{setCellProperties} determine the
2875 When @code{setCellProperties} contains a @code{setFormat} whose
2876 @code{target} references a @code{labeling} element, or if it contains
2877 a @code{setStyle} that references a @code{labeling} or @code{interval}
2878 element, the @code{setCellProperties} sets the style for table cells.
2879 The format from the @code{setFormat}, if present, replaces the cells'
2880 format. The style from the @code{setStyle} that references
2881 @code{labeling}, if present, replaces the label's font and cell
2882 styles, except that the background color is taken instead from the
2883 @code{interval}'s style, if present.
2885 When @code{setCellProperties} contains a @code{setFormat} whose
2886 @code{target} references a @code{majorTicks} element, or if it
2887 contains a @code{setStyle} whose @code{target} references a
2888 @code{majorTicks}, or if it contains a @code{setFrameStyle} element,
2889 the @code{setCellProperties} sets the style for row or column labels.
2890 In this case, the @code{setCellProperties} always contains a single
2891 @code{where} element whose @code{variable} designates the variable
2892 whose labels are to be styled. The format from the @code{setFormat},
2893 if present, replaces the labels' format. The style from the
2894 @code{setStyle} that references @code{majorTicks}, if present,
2895 replaces the labels' font and cell styles, except that the background
2896 color is taken instead from the @code{setFrameStyle}'s style, if
2899 When @code{setCellProperties} contains a @code{setStyle} whose
2900 @code{target} references a @code{graph} element, and one that
2901 references a @code{labeling} element, and the @code{union} element
2902 contains @code{alternating}, the @code{setCellProperties} sets the
2903 alternate foreground and background colors for the data area. The
2904 foreground color is taken from the style referenced by the
2905 @code{setStyle} that targets the @code{graph}, the background color
2906 from the @code{setStyle} for @code{labeling}.
2908 A reader may ignore a @code{setCellProperties} that only contains
2909 @code{setMetaData}, as well as @code{setMetaData} within other
2910 @code{setCellProperties}.
2912 A reader may ignore a @code{setCellProperties} whose only @code{set*}
2913 child is a @code{setStyle} that targets the @code{graph} element.
2915 @subsubheading The @code{setStyle} Element
2919 :target=ref (labeling | graph | interval | majorTicks)
2924 This element associates a style with the target.
2926 @defvr {Attribute} target
2927 The @code{id} of an element whose style is to be set.
2930 @defvr {Attribute} style
2931 The @code{id} of a @code{style} element that identifies the style to
2935 @node SPV Detail setFormat Element
2936 @subsection The @code{setFormat} Element
2940 :target=ref (majorTicks | labeling)
2942 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
2945 This element sets the format of the target, ``format'' in this case
2946 meaning the SPSS print format for a variable.
2948 The details of this element vary depending on the schema version, as
2949 declared in the root @code{visualization} element's @code{version}
2950 attribute (@pxref{SPV Detail visualization Element}). A reader can
2951 interpret the content without knowing the schema version.
2953 The @code{setFormat} element itself has the following attributes.
2955 @defvr {Attribute} target
2956 Refers to an element whose style is to be set.
2959 @defvr {Attribute} reset
2960 If this is @code{true}, this format replaces the target's previous
2961 format. If it is @code{false}, the modifies the previous format.
2965 * SPV Detail numberFormat Element::
2966 * SPV Detail stringFormat Element::
2967 * SPV Detail dateTimeFormat Element::
2968 * SPV Detail elapsedTimeFormat Element::
2969 * SPV Detail format Element::
2970 * SPV Detail affix Element::
2973 @node SPV Detail numberFormat Element
2974 @subsubsection The @code{numberFormat} Element
2978 :minimumIntegerDigits=int?
2979 :maximumFractionDigits=int?
2980 :minimumFractionDigits=int?
2982 :scientific=(onlyForSmall | whenNeeded | true | false)?
2989 Specifies a format for displaying a number. The available options are
2990 a superset of those available from PSPP print formats. PSPP chooses a
2991 print format type for a @code{numberFormat} as follows:
2995 If @code{scientific} is @code{true}, uses @code{E} format.
2998 If @code{prefix} is @code{$}, uses @code{DOLLAR} format.
3001 If @code{suffix} is @code{%}, uses @code{PCT} format.
3004 If @code{useGrouping} is @code{true}, uses @code{COMMA} format.
3007 Otherwise, uses @code{F} format.
3010 For translating to a print format, PSPP uses
3011 @code{maximumFractionDigits} as the number of decimals, unless that
3012 attribute is missing or out of the range [0,15], in which case it uses
3015 @defvr {Attribute} minimumIntegerDigits
3016 Minimum number of digits to display before the decimal point. Always
3017 observed as @code{0}.
3020 @defvr {Attribute} maximumFractionDigits
3021 @defvrx {Attribute} minimumFractionDigits
3022 Maximum or minimum, respectively, number of digits to display after
3023 the decimal point. The observed values of each attribute range from 0
3027 @defvr {Attribute} useGrouping
3028 Whether to use the grouping character to group digits in large
3032 @defvr {Attribute} scientific
3033 This attribute controls when and whether the number is formatted in
3034 scientific notation. It takes the following values:
3038 Use scientific notation only when the number's magnitude is smaller
3039 than the value of the @code{small} attribute.
3042 Use scientific notation when the number will not otherwise fit in the
3046 Always use scientific notation. Not observed in the corpus.
3049 Never use scientific notation. A number that won't otherwise fit will
3050 be replaced by an error indication (see the @code{errorCharacter}
3051 attribute). Not observed in the corpus.
3055 @defvr {Attribute} small
3056 Only present when the @code{scientific} attribute is
3057 @code{onlyForSmall}, this is a numeric magnitude below which the
3058 number will be formatted in scientific notation. The values @code{0}
3059 and @code{0.0001} have been observed. The value @code{0} seems like a
3060 pathological choice, since no real number has a magnitude less than 0;
3061 perhaps in practice such a choice is equivalent to setting
3062 @code{scientific} to @code{false}.
3065 @defvr {Attribute} prefix
3066 @defvrx {Attribute} suffix
3067 Specifies a prefix or a suffix to apply to the formatted number. Only
3068 @code{suffix} has been observed, with value @samp{%}.
3071 @node SPV Detail stringFormat Element
3072 @subsubsection The @code{stringFormat} Element
3075 stringFormat => relabel* affix*
3077 relabel :from=real :to => EMPTY
3080 The @code{stringFormat} element specifies how to display a string. By
3081 default, a string is displayed verbatim, but @code{relabel} can change
3084 The @code{relabel} element appears as a child of @code{stringFormat}
3085 (and of @code{format}, when it is used to format strings). It
3086 specifies how to display a given value. It is used to implement value
3087 labels and to display the system-missing value in a human-readable
3088 way. It has the following attributes:
3090 @defvr {Attribute} from
3091 The value to map. In the corpus this is an integer or the
3092 system-missing value @code{-1.797693134862316E300}.
3095 @defvr {Attribute} to
3096 The string to display in place of the value of @code{from}. In the
3097 corpus this is a wide variety of value labels; the system-missing
3098 value is mapped to @samp{.}.
3101 @node SPV Detail dateTimeFormat Element
3102 @subsubsection The @code{dateTimeFormat} Element
3106 :baseFormat[dt_base_format]=(date | time | dateTime)
3108 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3110 :yearAbbreviation=bool?
3115 :monthFormat=(long | short | number | paddedNumber)?
3119 :showDayOfWeek=bool?
3120 :dayOfWeekAbbreviation=bool?
3122 :dayOfMonthPadding=bool?
3124 :minutePadding=bool?
3125 :secondPadding=bool?
3131 :dayType=(month | year)?
3132 :hourFormat=(AMPM | AS_24 | AS_12)?
3136 This element appears only in schema version 2.5 and earlier
3137 (@pxref{SPV Detail visualization Element}).
3139 Data to be formatted in date formats is stored as strings in legacy
3140 data, in the format @code{yyyy-mm-ddTHH:MM:SS.SSS} and must be parsed
3141 and reformatted by the reader.
3143 The following attribute is required.
3145 @defvr {Attribute} baseFormat
3146 Specifies whether a date and time are both to be displayed, or just
3150 Many of the attributes' meanings are obvious. The following seem to
3151 be worth documenting.
3153 @defvr {Attribute} separatorChars
3154 Exactly four characters. In order, these are used for: decimal point,
3155 grouping, date separator, time separator. Always @samp{.,-:}.
3158 @defvr {Attribute} mdyOrder
3159 Within a date, the order of the days, months, and years.
3160 @code{dayMonthYear} is the only observed value, but one would expect
3161 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
3165 @defvr {Attribute} showYear
3166 @defvrx {Attribute} yearAbbreviation
3167 Whether to include the year and, if so, whether the year should be
3168 shown abbreviated, that is, with only 2 digits. Each is @code{true}
3169 or @code{false}; only values of @code{true} and @code{false},
3170 respectively, have been observed.
3173 @defvr {Attribute} showMonth
3174 @defvrx {Attribute} monthFormat
3175 Whether to include the month (@code{true} or @code{false}) and, if so,
3176 how to format it. @code{monthFormat} is one of the following:
3180 The full name of the month, e.g.@: in an English locale,
3184 The abbreviated name of the month, e.g.@: in an English locale,
3188 The number representing the month, e.g.@: 9 for September.
3191 A two-digit number representing the month, e.g.@: 09 for September.
3194 Only values of @code{true} and @code{short}, respectively, have been
3198 @defvr {Attribute} dayType
3199 This attribute is always @code{month} in the corpus, specifying that
3200 the day of the month is to be displayed; a value of @code{year} is
3201 supposed to indicate that the day of the year, where 1 is January 1,
3202 is to be displayed instead.
3205 @defvr {Attribute} hourFormat
3206 @code{hourFormat}, if present, is one of:
3210 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
3214 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
3216 This is the only value observed in the corpus.
3219 The time is displayed in a 12-hour format, without distinguishing
3220 morning or evening, e.g.@: @code{10;15}.
3223 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
3224 which is confusing since a time duration does not have a concept of AM
3225 or PM. This might indicate a bug in the code that generated the XML
3226 in the corpus, or it might indicate that @code{elapsedTime} is
3227 sometimes used to format a time of day.
3230 For a @code{baseFormat} of @code{date}, PSPP chooses a print format
3231 type based on the following rules:
3235 If @code{showQuarter} is true: @code{QYR}.
3238 Otherwise, if @code{showWeek} is true: @code{WKYR}.
3241 Otherwise, if @code{mdyOrder} is @code{dayMonthYear}:
3245 If @code{monthFormat} is @code{number} or @code{paddedNumber}: @code{EDATE}.
3248 Otherwise: @code{DATE}.
3252 Otherwise, if @code{mdyOrder} is @code{yearMonthDay}: @code{SDATE}.
3255 Otherwise, @code{ADATE}.
3258 For a @code{baseFormat} of @code{dateTime}, PSPP uses @code{YMDHMS} if
3259 @code{mdyOrder} is @code{yearMonthDay} and @code{DATETIME} otherwise.
3260 For a @code{baseFormat} of @code{time}, PSPP uses @code{DTIME} if
3261 @code{showDay} is true, otherwise @code{TIME} if @code{showHour} is
3262 true, otherwise @code{MTIME}.
3264 For a @code{baseFormat} of @code{date}, the chosen width is the
3265 minimum for the format type, adding 2 if @code{yearAbbreviation} is
3266 false or omitted. For other base formats, the chosen width is the
3267 minimum for its type, plus 3 if @code{showSecond} is true, plus 4 more
3268 if @code{showMillis} is also true. Decimals are 0 by default, or 3
3269 if @code{showMillis} is true.
3271 @node SPV Detail elapsedTimeFormat Element
3272 @subsubsection The @code{elapsedTimeFormat} Element
3276 :baseFormat[dt_base_format]=(date | time | dateTime)
3279 :minutePadding=bool?
3280 :secondPadding=bool?
3290 This element specifies the way to display a time duration.
3292 Data to be formatted in elapsed time formats is stored as strings in
3293 legacy data, in the format @code{H:MM:SS.SSS}, with additional hour
3294 digits as needed for long durations, and must be parsed and
3295 reformatted by the reader.
3297 The following attribute is required.
3299 @defvr {Attribute} baseFormat
3300 Specifies whether a day and a time are both to be displayed, or just
3304 The remaining attributes specify exactly how to display the elapsed
3307 For @code{baseFormat} of @code{time}, PSPP converts this element to
3308 print format type @code{DTIME}; otherwise, if @code{showHour} is true,
3309 to @code{TIME}; otherwise, to @code{MTIME}. The chosen width is the
3310 minimum for the chosen type, adding 3 if @code{showSecond} is true,
3311 adding 4 more if @code{showMillis} is also true. Decimals are 0 by
3312 default, or 3 if @code{showMillis} is true.
3314 @node SPV Detail format Element
3315 @subsubsection The @code{format} Element
3319 :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)?
3322 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3327 :yearAbbreviation=bool?
3329 :monthFormat=(long | short | number | paddedNumber)?
3331 :dayOfMonthPadding=bool?
3335 :showDayOfWeek=bool?
3336 :dayOfWeekAbbreviation=bool?
3338 :minutePadding=bool?
3339 :secondPadding=bool?
3345 :dayType=(month | year)?
3346 :hourFormat=(AMPM | AS_24 | AS_12)?
3347 :minimumIntegerDigits=int?
3348 :maximumFractionDigits=int?
3349 :minimumFractionDigits=int?
3351 :scientific=(onlyForSmall | whenNeeded | true | false)?
3355 :tryStringsAsNumbers=bool?
3356 :negativesOutside=bool?
3360 This element is the union of all of the more-specific format elements.
3361 It is interpreted in the same way as one of those format elements,
3362 using @code{baseFormat} to determine which kind of format to use.
3364 There are a few attributes not present in the more specific formats:
3366 @defvr {Attribute} tryStringsAsNumbers
3367 When this is @code{true}, it is supposed to indicate that string
3368 values should be parsed as numbers and then displayed according to
3369 numeric formatting rules. However, in the corpus it is always
3373 @defvr {Attribute} negativesOutside
3374 If true, the negative sign should be shown before the prefix; if
3375 false, it should be shown after.
3378 @node SPV Detail affix Element
3379 @subsubsection The @code{affix} Element
3383 :definesReference=int
3384 :position=(subscript | superscript)
3390 This defines a suffix (or, theoretically, a prefix) for a formatted
3391 value. It is used to insert a reference to a footnote. It has the
3392 following attributes:
3394 @defvr {Attribute} definesReference
3395 This specifies the footnote number as a natural number: 1 for the
3396 first footnote, 2 for the second, and so on.
3399 @defvr {Attribute} position
3400 Position for the footnote label. Always @code{superscript}.
3403 @defvr {Attribute} suffix
3404 Whether the affix is a suffix (@code{true}) or a prefix
3405 (@code{false}). Always @code{true}.
3408 @defvr {Attribute} value
3409 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
3410 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
3411 contains other values: @code{*}, @code{**}, and a few that begin with
3412 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
3415 @node SPV Detail interval Element
3416 @subsection The @code{interval} Element
3419 interval :style=ref style => labeling footnotes?
3423 :variable=ref (sourceVariable | derivedVariable)
3424 => (formatting | format | footnotes)*
3426 formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping*
3428 formatMapping :from=int => format?
3432 :variable=ref (sourceVariable | derivedVariable)
3435 footnoteMapping :definesReference=int :from=int :to => EMPTY
3438 The @code{interval} element and its descendants determine the basic
3439 formatting and labeling for the table's cells. These basic styles are
3440 overridden by more specific styles set using @code{setCellProperties}
3441 (@pxref{SPV Detail setCellProperties Element}).
3443 The @code{style} attribute of @code{interval} itself may be ignored.
3445 The @code{labeling} element may have a single @code{formatting} child.
3446 If present, its @code{variable} attribute refers to a variable whose
3447 values are format specifiers as numbers, e.g. value 0x050802 for F8.2.
3448 However, the numbers are not actually interpreted that way. Instead,
3449 each number actually present in the variable's data is mapped by a
3450 @code{formatMapping} child of @code{formatting} to a @code{format}
3451 that specifies how to display it.
3453 The @code{labeling} element may also have a @code{footnotes} child
3454 element. The @code{variable} attribute of this element refers to a
3455 variable whose values are comma-delimited strings that list the
3456 1-based indexes of footnote references. (Cells without any footnote
3457 references are numeric 0 instead of strings.)
3459 Each @code{footnoteMapping} child of the @code{footnotes} element
3460 defines the footnote marker to be its @code{to} attribute text for the
3461 footnote whose 1-based index is given in its @code{definesReference}
3464 @node SPV Detail style Element
3465 @subsection The @code{style} Element
3472 :border-bottom=(solid | thick | thin | double | none)?
3473 :border-top=(solid | thick | thin | double | none)?
3474 :border-left=(solid | thick | thin | double | none)?
3475 :border-right=(solid | thick | thin | double | none)?
3476 :border-bottom-color?
3479 :border-right-color?
3482 :font-weight=(regular | bold)?
3483 :font-style=(regular | italic)?
3484 :font-underline=(none | underline)?
3485 :margin-bottom=dimension?
3486 :margin-left=dimension?
3487 :margin-right=dimension?
3488 :margin-top=dimension?
3489 :textAlignment=(left | right | center | decimal | mixed)?
3490 :labelLocationHorizontal=(positive | negative | center)?
3491 :labelLocationVertical=(positive | negative | center)?
3492 :decimal-offset=dimension?
3499 A @code{style} element has an effect only when it is referenced by
3500 another element to set some aspect of the table's style. Most of the
3501 attributes are self-explanatory. The rest are described below.
3503 @defvr {Attribute} {color}
3504 In some cases, the text color; in others, the background color.
3507 @defvr {Attribute} {color2}
3511 @defvr {Attribute} {labelAngle}
3512 Normally 0. The value -90 causes inner column or outer row labels to
3513 be rotated vertically.
3516 @defvr {Attribute} {labelLocationHorizontal}
3520 @defvr {Attribute} {labelLocationVertical}
3521 The value @code{positive} corresponds to vertically aligning text to
3522 the top of a cell, @code{negative} to the bottom, @code{center} to the
3526 @node SPV Detail labelFrame Element
3527 @subsection The @code{labelFrame} Element
3530 labelFrame :style=ref style => location+ label? paragraph?
3532 paragraph :hangingIndent=dimension? => EMPTY
3535 A @code{labelFrame} element specifies content and style for some
3536 aspect of a table. Only @code{labelFrame} elements that have a
3537 @code{label} child are important. The @code{purpose} attribute in the
3538 @code{label} determines what the @code{labelFrame} affects:
3542 The table's title and its style.
3545 The table's caption and its style.
3548 The table's footnotes and the style for the footer area.
3551 The style for the layer area.
3557 The @code{style} attribute references the style to use for the area.
3559 The @code{label}, if present, specifies the text to put into the title
3560 or caption or footnotes. For footnotes, the label has two @code{text}
3561 children for every footnote, each of which has a @code{usesReference}
3562 attribute identifying the 1-based index of a footnote. The first,
3563 third, fifth, @dots{} @code{text} child specifies the content for a
3564 footnote; the second, fourth, sixth, @dots{} child specifies the
3565 marker. Content tends to end in a new-line, which the reader may wish
3566 to trim; similarly, markers tend to end in @samp{.}.
3568 The @code{paragraph}, if present, may be ignored, since it is always
3571 @node SPV Detail Legacy Properties
3572 @subsection Legacy Properties
3574 The detail XML format has features for styling most of the aspects of
3575 a table. It also inherits defaults for many aspects from structure
3576 XML, which has the following @code{tableProperties} element:
3580 => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties
3583 :hideEmptyRows=bool?
3584 :maximumColumnWidth=dimension?
3585 :maximumRowWidth=dimension?
3586 :minimumColumnWidth=dimension?
3587 :minimumRowWidth=dimension?
3588 :rowDimensionLabels=(inCorner | nested)?
3592 :markerPosition=(superscript | subscript)?
3593 :numberFormat=(alphabetic | numeric)?
3596 cellFormatProperties => cell_style+
3599 :alternatingColor=color?
3600 :alternatingTextColor=color?
3608 :font-style=(regular | italic)?
3609 :font-weight=(regular | bold)?
3610 :labelLocationVertical=(positive | negative | center)?
3611 :margin-bottom=dimension?
3612 :margin-left=dimension?
3613 :margin-right=dimension?
3614 :margin-top=dimension?
3615 :textAlignment=(left | right | center | decimal | mixed)?
3616 :decimal-offset=dimension?
3619 borderProperties => border_style+
3622 :borderStyleType=(none | solid | dashed | thick | thin | double)?
3627 :printAllLayers=bool?
3628 :rescaleLongTableToFitPage=bool?
3629 :rescaleWideTableToFitPage=bool?
3630 :windowOrphanLines=int?
3632 :continuationTextAtBottom=bool?
3633 :continuationTextAtTop=bool?
3634 :printEachLayerOnSeparatePage=bool?