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.
34 The rest of the members in an SPV file's Zip archive fall into two
35 categories: @dfn{structure} and @dfn{detail} members. Structure
36 member names begin with @file{outputViewer@var{nnnnnnnnnn}}, where
37 each @var{n} is a decimal digit, and end with @file{.xml}, and often
38 include the string @file{_heading} in between. Each of these members
39 represents some kind of output item (a table, a heading, a block of
40 text, etc.) or a group of them. The member whose output goes at the
41 beginning of the document is numbered 0, the next member in the output
42 is numbered 1, and so on.
44 Structure members contain XML. This XML is sometimes self-contained,
45 but it often references detail members in the Zip archive, which are
49 @item @file{@var{prefix}_table.xml} and @file{@var{prefix}_tableData.bin}
50 @itemx @file{@var{prefix}_lightTableData.bin}
51 The structure of a table plus its data. Older SPV files pair a
52 @file{@var{prefix}_table.xml} file that describes the table's
53 structure with a binary @file{@var{prefix}_tableData.bin} file that
54 gives its data. Newer SPV files (the majority of those in the corpus)
55 instead include a single @file{@var{prefix}_lightTableData.bin} file
56 that incorporates both into a single binary format.
58 @item @file{@var{prefix}_warning.xml} and @file{@var{prefix}_warningData.bin}
59 @itemx @file{@var{prefix}_lightWarningData.bin}
60 Same format used for tables, with a different name.
62 @item @file{@var{prefix}_notes.xml} and @file{@var{prefix}_notesData.bin}
63 @itemx @file{@var{prefix}_lightNotesData.bin}
64 Same format used for tables, with a different name.
66 @item @file{@var{prefix}_chartData.bin} and @file{@var{prefix}_chart.xml}
67 The structure of a chart plus its data. Charts do not have a
70 @item @file{@var{prefix}_pmml.scf}
71 @itemx @file{@var{prefix}_stats.scf}
72 @item @file{@var{prefix}_model.xml}
73 Not yet investigated. The corpus contains few examples.
76 The @file{@var{prefix}} in the names of the detail members is
77 typically an 11-digit decimal number that increases for each item,
78 tending to skip values. Older SPV files use different naming
79 conventions. Structure member refer to detail members by name, and so
80 their exact names do not matter to readers as long as they are unique.
82 SPSS tolerates corrupted Zip archives that Zip reader libraries tend
83 to reject. These can be fixed up with @command{zip -FF}.
86 * SPV Structure Member Format::
87 * SPV Light Detail Member Format::
88 * SPV Legacy Detail Member Binary Format::
89 * SPV Legacy Detail Member XML Format::
92 @node SPV Structure Member Format
93 @section Structure Member Format
95 A structure member lays out the high-level structure for a group of
96 output items such as heading, tables, and charts. Structure members
97 do not include the details of tables and charts but instead refer to
98 them by their member names.
100 Structure members' XML files claim conformance with a collection of
101 XML Schemas. These schemas are distributed, under a nonfree license,
102 with SPSS binaries. Fortunately, the schemas are not necessary to
103 understand the structure members. The schemas can even
104 be deceptive because they document elements and attributes that are
105 not in the corpus and do not document elements and attributes that are
106 commonly found in the corpus.
108 Structure members use a different XML namespace for each schema, but
109 these namespaces are not entirely consistent. In some SPV files, for
110 example, the @code{viewer-tree} schema is associated with namespace
111 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
112 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
113 additional @file{viewer/}). Under either name, the schema URIs are
114 not resolvable to obtain the schemas themselves.
116 One may ignore all of the above in interpreting a structure member.
117 The actual XML has a simple and straightforward form that does not
118 require a reader to take schemas or namespaces into account. A
119 structure member's root is @code{heading} element, which contains
120 @code{heading} or @code{container} elements (or a mix), forming a
121 tree. In turn, @code{container} holds a @code{label} and one more
122 child, usually @code{text} or @code{table}.
124 The following sections document the elements found in structure
125 members in a context-free grammar-like fashion. Consider the
126 following example, which specifies the attributes and content for the
127 @code{container} element:
131 :visibility=(visible | hidden)
132 :page-break-before=(always)?
133 :text-align=(left | center)?
135 => label (table | container_text | graph | model | object | image)
138 Each attribute specification begins with @samp{:} followed by the
139 attribute's name. If the attribute's value has an easily specified
140 form, then @samp{=} and its description follows the name. Finally, if
141 the attribute is optional, the specification ends with @samp{?}. The
142 following value specifications are defined:
145 @item (@var{a} | @var{b} | @dots{})
146 One of the listed literal strings. If only one string is listed, it
147 is the only acceptable value. If @code{OTHER} is listed, then any
148 string not explicitly listed is also accepted.
151 Either @code{true} or @code{false}.
154 A floating-point number followed by a unit, e.g.@: @code{10pt}. Units
155 in the corpus include @code{in} (inch), @code{pt} (points, 72/inch),
156 @code{px} (``device-independent pixels'', 96/inch), and @code{cm}.
157 The corpus also contains localized names for units: @code{인치} for
158 inch, @code{пт} for points, and @code{см} for centimeters. If the
159 unit is omitted then points should be assumed. The number and unit
160 may be separated by white space.
163 A floating-point number.
169 A color in one of the forms @code{#@var{rr}@var{gg}@var{bb}} or
170 @code{@var{rr}@var{gg}@var{bb}}, or the string @code{transparent}, or
171 one of the standard Web color names.
174 @item ref @var{element}
175 @itemx ref(@var{elem1} | @var{elem2} | @dots{})
176 The name from the @code{id} attribute in some element. If one or more
177 elements are named, the name must refer to one of those elements,
178 otherwise any element is acceptable.
181 All elements have an optional @code{id} attribute. If present, its
182 value must be unique. In practice many elements are assigned
183 @code{id} attributes that are never referenced.
185 The content specification for an element supports the following
192 @item @var{a} @var{b}
193 @var{a} followed by @var{b}.
195 @item @var{a} | @var{b} | @var{c}
196 One of @var{a} or @var{b} or @var{c}.
199 Zero or one instances of @var{a}.
202 Zero or more instances of @var{a}.
205 One or more instances of @var{a}.
207 @item (@var{subexpression})
208 Grouping for a subexpression.
217 Element and attribute names are sometimes suffixed by another name in
218 square brackets to distinguish different uses of the same name. For
219 example, structure XML has two @code{text} elements, one inside
220 @code{container}, the other inside @code{pageParagraph}. The former
221 is defined as @code{text[container_text]} and referenced as
222 @code{container_text}, the latter defined as
223 @code{text[pageParagraph_text]} and referenced as
224 @code{pageParagraph_text}.
226 This language is used in the PSPP source code for parsing structure
227 and detail XML members. Refer to
228 @file{src/output/spv/structure-xml.grammar} and
229 @file{src/output/spv/detail-xml.grammar} for the full grammars.
231 The following example shows the contents of a typical structure member
232 for a @cmd{DESCRIPTIVES} procedure. A real structure member is not
233 indented. This example also omits most attributes, all XML namespace
234 information, and the CSS from the embedded HTML:
237 <?xml version="1.0" encoding="utf-8"?>
239 <label>Output</label>
240 <heading commandName="Descriptives">
241 <label>Descriptives</label>
244 <text commandName="Descriptives" type="title">
246 <![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
250 <container visibility="hidden">
252 <table commandName="Descriptives" subType="Notes" type="note">
254 <dataPath>00000000001_lightNotesData.bin</dataPath>
259 <label>Descriptive Statistics</label>
260 <table commandName="Descriptives" subType="Descriptive Statistics"
263 <dataPath>00000000002_lightTableData.bin</dataPath>
272 * SPV Structure heading Element::
273 * SPV Structure label Element::
274 * SPV Structure container Element::
275 * SPV Structure text Element (Inside @code{container})::
276 * SPV Structure html Element::
277 * SPV Structure table Element::
278 * SPV Structure graph Element::
279 * SPV Structure model Element::
280 * SPV Structure dataPath and path Elements::
281 * SPV Structure pageSetup Element::
282 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
285 @node SPV Structure heading Element
286 @subsection The @code{heading} Element
289 heading[root_heading]
295 => label pageSetup? (container | heading)*
300 :visibility[heading_visibility]=(collapsed)?
303 => label (container | heading)*
306 The root of a structure member is a @code{heading}, which represents a
307 section of output beginning with a title (the @code{label}) and
308 ordinarily followed by content containers or further nested
309 (sub)-sections of output. Unlike heading elements in HTML and other
310 common document formats, which precede the content that they head,
311 @code{heading} contains the elements that appear below the heading.
313 The document root heading, only, may contain a @code{pageSetup}
316 The following attributes have been observed on both document root and
317 nested @code{heading} elements.
319 @defvr {Attribute} creator-version
320 The version of the software that created this SPV file. A string of
321 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
322 e.g.@: @code{21000001} is version 21.0.0.1. Trailing pairs of zeros
323 are sometimes omitted, so that @code{21}, @code{210000}, and
324 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
325 three of those forms).
329 The following attributes have been observed on document root
330 @code{heading} elements only:
332 @defvr {Attribute} @code{creator}
333 The directory in the file system of the software that created this SPV
337 @defvr {Attribute} @code{creation-date-time}
338 The date and time at which the SPV file was written, in a
339 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
340 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
341 December 5, 2014 5:00:19 o'clock PM EST}.
344 @defvr {Attribute} @code{lockReader}
345 Whether a reader should be allowed to edit the output. The possible
346 values are @code{true} and @code{false}, but the corpus only contains
350 @defvr {Attribute} @code{schemaLocation}
351 This is actually an XML Namespace attribute. A reader may ignore it.
355 The following attributes have been observed only on nested
356 @code{heading} elements:
358 @defvr {Attribute} @code{commandName}
359 A locale-invariant identifier for the command that produced the
360 output, e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
363 @defvr {Attribute} @code{visibility}
364 To what degree the output represented by the element is visible.
367 @defvr {Attribute} @code{locale}
368 The locale used for output, in Windows format, which is similar to the
369 format used in Unix with the underscore replaced by a hyphen, e.g.@:
370 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
373 @defvr {Attribute} @code{olang}
374 The output language, e.g.@: @code{en}, @code{it}, @code{es},
375 @code{de}, @code{pt-BR}.
378 @node SPV Structure label Element
379 @subsection The @code{label} Element
385 Every @code{heading} and @code{container} holds a @code{label} as its
386 first child. The root @code{heading} in a structure member always
387 contains the string ``Output'' (localized). Otherwise, the text in
388 @code{label} describes what it labels, often by naming the statistical
389 procedure that was executed, e.g.@: ``Frequencies'' or ``T-Test''.
390 Labels are often very generic, especially within a @code{container},
391 e.g.@: ``Title'' or ``Warnings'' or ``Notes''. Label text is
392 localized according to the output language, e.g.@: in Italian a
393 frequency table procedure is labeled ``Frequenze''.
395 The corpus contains a few examples of empty labels, ones that contain
398 @node SPV Structure container Element
399 @subsection The @code{container} Element
403 :visibility=(visible | hidden)
404 :page-break-before=(always)?
405 :text-align=(left | center)?
407 => label (table | container_text | graph | model | object | image)
410 A @code{container} serves to contain and label a @code{table},
411 @code{text}, or other kind of item.
413 This element has the following attributes.
415 @defvr {Attribute} @code{visibility}
416 Whether the container's content is displayed. ``Notes'' tables are
417 often hidden; other data is usually
420 @defvr {Attribute} @code{text-align}
421 Alignment of text within the container. Observed with nested
422 @code{table} and @code{text} elements.
425 @defvr {Attribute} @code{width}
426 The width of the container, e.g.@: @code{1097px}.
429 @node SPV Structure text Element (Inside @code{container})
430 @subsection The @code{text} Element (Inside @code{container})
434 :type[text_type]=(title | log | text | page-title)
440 This @code{text} element is nested inside a @code{container}. There
441 is a different @code{text} element that is nested inside a
442 @code{pageParagraph}.
444 This element has the following attributes.
446 @defvr {Attribute} @code{type}
447 The semantics of the text.
450 @defvr {Attribute} @code{commandName}
451 As on the @code{heading} element. For output not specific to a
452 command, this is simply @code{log}. The corpus contains one example
453 of where @code{commandName} is present but set to the empty string.
456 @defvr {Attribute} @code{creator-version}
457 As on the @code{heading} element.
460 @node SPV Structure html Element
461 @subsection The @code{html} Element
464 html :lang=(en) => TEXT
467 The element contains an HTML document as text (or, in practice, as
468 CDATA). In some cases, the document starts with @code{<html>} and
469 ends with @code{</html>}; in others the @code{html} element is
470 implied. Generally the HTML includes a @code{head} element with a CSS
471 stylesheet. The HTML body often begins with @code{<BR>}.
473 The HTML document uses only the following elements:
477 Sometimes, the document is enclosed with
478 @code{<html>}@dots{}@code{</html>}.
481 The HTML body often begins with @code{<BR>} and may contain it as well.
489 The attributes @code{face}, @code{color}, and @code{size} are
490 observed. The value of @code{color} takes one of the forms
491 @code{#@var{rr}@var{gg}@var{bb}} or @code{rgb (@var{r}, @var{g},
492 @var{b})}. The value of @code{size} is a number between 1 and 7,
496 The CSS in the corpus is simple. To understand it, a parser only
497 needs to be able to skip white space, @code{<!--}, and @code{-->}, and
498 parse style only for @code{p} elements. Only @code{font-weight},
499 @code{font-style}, @code{font-decoration}, @code{font-family}, and
500 @code{font-size} matter.
502 This element has the following attributes.
504 @defvr {Attribute} @code{lang}
505 This always contains @code{en} in the corpus.
508 @node SPV Structure table Element
509 @subsection The @code{table} Element
518 :displayFiltering=bool?
520 :orphanTolerance=int?
525 :type[table_type]=(table | note | warning)
526 => tableProperties? tableStructure
528 tableStructure => path? dataPath
531 This element has the following attributes.
533 @defvr {Attribute} @code{commandName}
534 As on the @code{heading} element.
537 @defvr {Attribute} @code{type}
538 One of @code{table}, @code{note}, or @code{warning}.
541 @defvr {Attribute} @code{subType}
542 The locale-invariant command ID for the particular kind of output that
543 this table represents in the procedure. This can be the same as
544 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
545 @code{Case Processing Summary}. Generic subtypes @code{Notes} and
546 @code{Warnings} are often used.
549 @defvr {Attribute} @code{tableId}
550 A number that uniquely identifies the table within the SPV file,
551 typically a large negative number such as @code{-4147135649387905023}.
554 @defvr {Attribute} @code{creator-version}
555 As on the @code{heading} element. In the corpus, this is only present
556 for version 21 and up and always includes all 8 digits.
559 @xref{SPV Detail Legacy Properties}, for details on the
560 @code{tableProperties} element.
562 @node SPV Structure graph Element
563 @subsection The @code{graph} Element
579 This element represents a graph. The @code{dataPath} and @code{path}
580 elements name the Zip members that give the details of the graph.
581 Normally, both elements are present; there is only one counterexample
584 @node SPV Structure model Element
585 @subsection The @code{model} Element
597 => ViZml? path | pmmlContainerPath statsContainerPath
599 pmmlContainerPath => TEXT
601 statsContainerPath => TEXT
603 ViZml :viewName? => TEXT
606 This element represents a model. The @code{dataPath} and @code{path}
607 elements name the Zip members that give the details of the model.
608 Normally, both elements are present; there is only one counterexample
611 The details are unexplored. The @code{ViZml} element contains base-64
612 encoded text, that decodes to a binary format with some embedded text
613 strings, and @code{path} names an Zip member that contains XML.
614 Alternatively, @code{pmmlContainerPath} and @code{statsContainerPath}
615 name Zip members with @file{.scf} extension.
617 @node SPV Structure dataPath and path Elements
618 @subsection The @code{dataPath} and @code{path} Elements
626 These element contain the name of the Zip members that hold details
627 for a container. For tables:
631 When a ``light'' format is used, only @code{dataPath} is present, and
632 it names a @file{.bin} member of the Zip file that has @code{light} in
633 its name, e.g.@: @code{0000000001437_lightTableData.bin} (@pxref{SPV
634 Light Detail Member Format}).
637 When the legacy format is used, both are present. In this case,
638 @code{dataPath} names a Zip member with a legacy binary format that
639 contains relevant data (@pxref{SPV Legacy Detail Member Binary
640 Format}), and @code{path} names a Zip member that uses an XML format
641 (@pxref{SPV Legacy Detail Member XML Format}).
644 Graphs normally follow the legacy approach described above. The
645 corpus contains one example of a graph with @code{path} but not
646 @code{dataPath}. The reason is unexplored.
648 Models use @code{path} but not @code{dataPath}. @xref{SPV Structure
649 graph Element}, for more information.
651 These elements have no attributes.
653 @node SPV Structure pageSetup Element
654 @subsection The @code{pageSetup} Element
658 :initial-page-number=int?
659 :chart-size=(as-is | full-height | half-height | quarter-height | OTHER)?
660 :margin-left=dimension?
661 :margin-right=dimension?
662 :margin-top=dimension?
663 :margin-bottom=dimension?
664 :paper-height=dimension?
665 :paper-width=dimension?
666 :reference-orientation?
667 :space-after=dimension?
668 => pageHeader pageFooter
670 pageHeader => pageParagraph?
672 pageFooter => pageParagraph?
674 pageParagraph => pageParagraph_text
677 The @code{pageSetup} element has the following attributes.
679 @defvr {Attribute} @code{initial-page-number}
680 The page number to put on the first page of printed output. Usually
684 @defvr {Attribute} @code{chart-size}
685 One of the listed, self-explanatory chart sizes,
686 @code{quarter-height}, or a localization (!) of one of these (e.g.@:
687 @code{dimensione attuale}, @code{Wie vorgegeben}).
690 @defvr {Attribute} @code{margin-left}
691 @defvrx {Attribute} @code{margin-right}
692 @defvrx {Attribute} @code{margin-top}
693 @defvrx {Attribute} @code{margin-bottom}
694 Margin sizes, e.g.@: @code{0.25in}.
697 @defvr {Attribute} @code{paper-height}
698 @defvrx {Attribute} @code{paper-width}
702 @defvr {Attribute} @code{reference-orientation}
703 Indicates the orientation of the output page. Either @code{0deg}
704 (portrait) or @code{90deg} (landscape),
707 @defvr {Attribute} @code{space-after}
708 The amount of space between printed objects, typically @code{12pt}.
711 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
712 @subsection The @code{text} Element (Inside @code{pageParagraph})
715 text[pageParagraph_text] :type=(title | text) => TEXT
718 This @code{text} element is nested inside a @code{pageParagraph}. There
719 is a different @code{text} element that is nested inside a
722 The element is either empty, or contains CDATA that holds almost-XHTML
723 text: in the corpus, either an @code{html} or @code{p} element. It is
724 @emph{almost}-XHTML because the @code{html} element designates the
726 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of
727 an XHTML namespace, and because the CDATA can contain substitution
728 variables. The following variables are supported:
733 The current date or time in the preferred format for the locale.
739 First-, second-, third-, or fourth-level heading.
745 Name of the output file.
751 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
754 Typical contents (indented for clarity):
757 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
760 <p style="text-align:right; margin-top: 0">Page &[Page]</p>
765 This element has the following attributes.
767 @defvr {Attribute} @code{type}
771 @node SPV Light Detail Member Format
772 @section Light Detail Member Format
774 This section describes the format of ``light'' detail @file{.bin}
775 members. These members have a binary format which we describe here in
776 terms of a context-free grammar using the following conventions:
779 @item NonTerminal @result{} @dots{}
780 Nonterminals have CamelCaps names, and @result{} indicates a
781 production. The right-hand side of a production is often broken
782 across multiple lines. Break points are chosen for aesthetics only
783 and have no semantic significance.
785 @item 00, 01, @dots{}, ff.
786 A bytes with a fixed value, written as a pair of hexadecimal digits.
788 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
789 @itemx ib0, ib1, @dots{}, ib9, ib10, ib11, @dots{}
790 A 32-bit integer in little-endian or big-endian byte order,
791 respectively, with a fixed value, written in decimal. Prefixed by
792 @samp{i} for little-endian or @samp{ib} for big-endian.
798 A byte with value 0 or 1.
802 A 16-bit integer in little-endian or big-endian byte order,
807 A 32-bit integer in little-endian or big-endian byte order,
812 A 64-bit integer in little-endian or big-endian byte order,
816 A 64-bit IEEE floating-point number.
819 A 32-bit IEEE floating-point number.
823 A 32-bit integer, in little-endian or big-endian byte order,
824 respectively, followed by the specified number of bytes of character
825 data. (The encoding is indicated by the Formats nonterminal.)
828 @var{x} is optional, e.g.@: 00? is an optional zero byte.
830 @item @var{x}*@var{n}
831 @var{x} is repeated @var{n} times, e.g.@: byte*10 for ten arbitrary bytes.
833 @item @var{x}[@var{name}]
834 Gives @var{x} the specified @var{name}. Names are used in textual
835 explanations. They are also used, also bracketed, to indicate counts,
836 e.g.@: @code{int32[n] byte*[n]} for a 32-bit integer followed by the
837 specified number of arbitrary bytes.
839 @item @var{a} @math{|} @var{b}
840 Either @var{a} or @var{b}.
843 Parentheses are used for grouping to make precedence clear, especially
844 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
848 @itemx becount(@var{x})
849 A 32-bit integer, in little-endian or big-endian byte order, respectively,
850 that indicates the number of bytes in @var{x}, followed by @var{x} itself.
853 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
854 (The @file{.bin} header indicates the version.)
857 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
860 PSPP uses this grammar to parse light detail members. See
861 @file{src/output/spv/light-binary.grammar} in the PSPP source tree for
864 Little-endian byte order is far more common in this format, but a few
865 pieces of the format use big-endian byte order.
867 Light detail members express linear units in two ways: points (pt), at
868 72/inch, and ``device-independent pixels'' (px), at 96/inch. To
869 convert from pt to px, multiply by 1.33 and round up. To convert
870 from px to pt, divide by 1.33 and round down.
872 A ``light'' detail member @file{.bin} consists of a number of sections
873 concatenated together, terminated by an optional byte 01:
877 Header Titles Footnotes
878 Areas Borders PrintSettings TableSettings Formats
879 Dimensions Axes Cells
883 The following sections go into more detail.
886 * SPV Light Member Header::
887 * SPV Light Member Titles::
888 * SPV Light Member Footnotes::
889 * SPV Light Member Areas::
890 * SPV Light Member Borders::
891 * SPV Light Member Print Settings::
892 * SPV Light Member Table Settings::
893 * SPV Light Member Formats::
894 * SPV Light Member Dimensions::
895 * SPV Light Member Categories::
896 * SPV Light Member Axes::
897 * SPV Light Member Cells::
898 * SPV Light Member Value::
899 * SPV Light Member ValueMod::
902 @node SPV Light Member Header
905 An SPV light member begins with a 39-byte header:
910 (i1 @math{|} i3)[version]
913 bool[rotate-inner-column-labels]
914 bool[rotate-outer-row-labels]
917 int32[min-col-width] int32[max-col-width]
918 int32[min-row-width] int32[max-row-width]
922 @code{version} is a version number that affects the interpretation of
923 some of the other data in the member. We will refer to ``version 1''
924 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
925 version-specific formatting (as described previously).
927 If @code{rotate-inner-column-labels} is 1, then column labels closest
928 to the data are rotated to be vertical; otherwise, they are shown
931 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
932 the data are rotated to be vertical; otherwise, they are shown in the
935 @code{table-id} is a binary version of the @code{tableId} attribute in
936 the structure member that refers to the detail member. For example,
937 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
938 would be 0xc6c99d183b300001.
940 @code{min-col-width} is the minimum width that a column will be
941 assigned automatically. @code{max-col-width} is the maximum width
942 that a column will be assigned to accommodate a long column label.
943 @code{min-row-width} and @code{max-row-width} are a similar range for
944 the width of row labels. All of these measurements are in 1/96 inch
945 units (called a ``device independent pixel'' unit in Windows).
947 The meaning of the other variable parts of the header is not known. A
948 writer may safely use version 3, true for @code{x0}, false for
949 @code{x1}, true for @code{x2}, and 0x15 for @code{x3}.
951 @node SPV Light Member Titles
957 Value[subtype] 01? 31
958 Value[user-title] 01?
959 (31 Value[corner-text] @math{|} 58)
960 (31 Value[caption] @math{|} 58)
963 The Titles follow the Header and specify the table's title, caption,
966 The @code{user-title} is shown above the title and reflects any user
967 editing of the title text or style. The @code{title} is the title
968 originally generated by the procedure. Both of these are appropriate
969 for presentation and localized to the user's language. For example,
970 for a frequency table, @code{title} and @code{user-title} normally
971 name the variable and @code{c} is simply ``Frequencies''.
973 @code{subtype} is the same as the @code{subType} attribute in the
974 @code{table} structure XML element that referred to this member.
975 @xref{SPV Structure table Element}, for details.
977 The @code{corner-text}, if present, is shown in the upper-left corner
978 of the table, above the row headings and to the left of the column
979 headings. It is usually absent. Corner text prevents row dimension
980 labels from being displayed above the dimension's group and category
981 labels (see @code{show-row-labels-in-corner}).
983 The @code{caption}, if present, is shown below the table.
984 @code{caption} reflects user editing of the caption.
986 @node SPV Light Member Footnotes
987 @subsection Footnotes
990 Footnotes => int32[n-footnotes] Footnote*[n-footnotes]
991 Footnote => Value[text] (58 @math{|} 31 Value[marker]) byte*4
994 Each footnote has @code{text} and an optional custom @code{marker}
997 @node SPV Light Member Areas
1004 string[typeface] float[size] int32[style] bool[underline]
1005 int32[halign] int32[valign]
1006 string[fg-color] string[bg-color]
1007 bool[alternate] string[alt-fg-color] string[alt-bg-color]
1008 v3(int32[left-margin] int32[right-margin] int32[top-margin] int32[bottom-margin])
1011 Each Area represents the style for a different area of the table, in
1012 the following order: title, caption, footer, corner, column labels,
1013 row labels, data, and layers.
1015 @code{index} is the 1-based index of the Area, i.e. 1 for the first
1016 Area, through 8 for the final Area.
1018 @code{typeface} is the string name of the font used in the area. In
1019 the corpus, this is @code{SansSerif} in over 99% of instances and
1020 @code{Times New Roman} in the rest.
1022 @code{size} is the size of the font, in px (@pxref{SPV Light Detail
1023 Member Format}) The most common size in the corpus is 12 px. Even
1024 though @code{size} has a floating-point type, in the corpus its values
1025 are always integers.
1027 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
1028 1 (with value 2) is set for italic.
1030 @code{underline} is 1 if the font is underlined, 0 otherwise.
1032 @code{halign} specifies horizontal alignment: 0 for center, 2 for
1033 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
1034 alignment varies according to type: string data is left-justified,
1035 numbers and most other formats are right-justified.
1037 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1040 @code{fg-color} and @code{bg-color} are the foreground color and
1041 background color, respectively. In the corpus, these are always
1042 @code{#000000} and @code{#ffffff}, respectively.
1044 @code{alternate} is 1 if rows should alternate colors, 0 if all rows
1045 should be the same color. When @code{alternate} is 1,
1046 @code{alt-fg-color} and @code{alt-bg-color} specify the colors for the
1047 alternate rows; otherwise they are empty strings.
1049 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1050 @code{bottom-margin} are measured in px.
1052 @node SPV Light Member Borders
1059 be32[n-borders] Border*[n-borders]
1060 bool[show-grid-lines]
1069 The Borders reflect how borders between regions are drawn.
1071 The fixed value of @code{endian} can be used to validate the
1074 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
1076 Each Border describes one kind of border. @code{n-borders} seems to
1077 always be 19. Each @code{border-type} appears once (although in an
1078 unpredictable order) and correspond to the following borders:
1084 Left, top, right, and bottom outer frame.
1086 Left, top, right, and bottom inner frame.
1088 Left and top of data area.
1090 Horizontal and vertical dimension rows.
1092 Horizontal and vertical dimension columns.
1094 Horizontal and vertical category rows.
1096 Horizontal and vertical category columns.
1099 @code{stroke-type} describes how a border is drawn, as one of:
1116 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
1117 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
1118 opaque color, therefore opaque black is 0xff000000.
1120 @node SPV Light Member Print Settings
1121 @subsection Print Settings
1128 bool[paginate-layers]
1131 bool[top-continuation]
1132 bool[bottom-continuation]
1133 be32[n-orphan-lines]
1134 bestring[continuation-string])
1137 The PrintSettings reflect settings for printing. The fixed value of
1138 @code{endian} can be used to validate the endianness.
1140 @code{all-layers} is 1 to print all layers, 0 to print only the
1143 @code{paginate-layers} is 1 to print each layer at the start of a new
1144 page, 0 otherwise. (This setting is honored only @code{all-layers} is
1145 1, since otherwise only one layer is printed.)
1147 @code{fit-width} and @code{fit-length} control whether the table is
1148 shrunk to fit within a page's width or length, respectively.
1150 @code{n-orphan-lines} is the minimum number of rows or columns to put
1151 in one part of a table that is broken across pages.
1153 If @code{top-continuation} is 1, then @code{continuation-string} is
1154 printed at the top of a page when a table is broken across pages for
1155 printing; similarly for @code{bottom-continuation} and the bottom of a
1156 page. Usually, @code{continuation-string} is empty.
1158 @node SPV Light Member Table Settings
1159 @subsection Table Settings
1169 bool[show-row-labels-in-corner]
1170 bool[show-alphabetic-markers]
1171 bool[footnote-marker-superscripts]
1174 Breakpoints[row-breaks] Breakpoints[column-breaks]
1175 Keeps[row-keeps] Keeps[column-keeps]
1176 PointKeeps[row-point-keeps] PointKeeps[column-point-keeps]
1179 bestring[table-look]
1182 Breakpoints => be32[n-breaks] be32*[n-breaks]
1184 Keeps => be32[n-keeps] Keep*[n-keeps]
1185 Keep => be32[offset] be32[n]
1187 PointKeeps => be32[n-point-keeps] PointKeep*[n-point-keeps]
1188 PointKeep => be32[offset] be32 be32
1191 The TableSettings reflect display settings. The fixed value of
1192 @code{endian} can be used to validate the endianness.
1194 @code{current-layer} is the displayed layer. The interpretation when
1195 there is more than one layer dimension is not yet known.
1197 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
1198 any cell) are hidden; otherwise, they are shown.
1200 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
1201 the upper left corner; otherwise, they are shown nested.
1203 If @code{show-alphabetic-markers} is 1, markers are shown as letters
1204 (e.g.@: @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
1205 shown as numbers starting from 1.
1207 When @code{footnote-marker-superscripts} is 1, footnote markers are shown
1208 as superscripts, otherwise as subscripts.
1210 The Breakpoints are rows or columns after which there is a page break;
1211 for example, a row break of 1 requests a page break after the second
1212 row. Usually no breakpoints are specified, indicating that page
1213 breaks should be selected automatically.
1215 The Keeps are ranges of rows or columns to be kept together without a
1216 page break; for example, a row Keep with @code{offset} 1 and @code{n}
1217 10 requests that the 10 rows starting with the second row be kept
1218 together. Usually no Keeps are specified.
1220 The PointKeeps seem to be generated automatically based on
1221 user-specified Keeps. They seems to indicate a conversion from rows
1222 or columns to pixel or point offsets.
1224 @code{notes} is a text string that contains user-specified notes. It
1225 is displayed when the user hovers the cursor over the table, like
1226 ``alt text'' on a webpage. It is not printed. It is usually empty.
1228 @code{table-look} is the name of a SPSS ``TableLook'' table style,
1229 such as ``Default'' or ``Academic''; it is often empty.
1231 TableSettings ends with an arbitrary number of null bytes. A writer
1232 may safely write 82 null bytes.
1234 A writer may safely use 4 for @code{x5} and 0 for @code{x6}.
1236 @node SPV Light Member Formats
1241 int32[n-widths] int32*[n-widths]
1243 int32[current-layer]
1249 v3(count(X1 count(X2)) count(X3)))
1250 Y0 => int32[epoch] byte[decimal] byte[grouping]
1251 CustomCurrency => int32[n-ccs] string*[n-ccs]
1254 If @code{n-widths} is nonzero, then the accompanying integers are
1255 column widths as manually adjusted by the user.
1257 @code{locale} is a locale including an encoding, such as
1258 @code{en_US.windows-1252} or @code{it_IT.windows-1252}. The rest of
1259 the character strings in the member use this encoding. The encoding
1260 string is itself encoded in US-ASCII.
1262 @code{epoch} is the year that starts the epoch. A 2-digit year is
1263 interpreted as belonging to the 100 years beginning at the epoch. The
1264 default epoch year is 69 years prior to the current year; thus, in
1265 2017 this field by default contains 1948. In the corpus, @code{epoch}
1266 ranges from 1943 to 1948, plus some contain -1.
1268 @code{decimal} is the decimal point character. The observed values
1269 are @samp{.} and @samp{,}.
1271 @code{grouping} is the grouping character. Usually, it is @samp{,} if
1272 @code{decimal} is @samp{.}, and vice versa. Other observed values are
1273 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1274 indicating that digits should not be grouped).
1276 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
1277 following strings are CCA through CCE format strings. @xref{Custom
1278 Currency Formats,,, pspp, PSPP}. Most commonly these are all
1279 @code{-,,,} but other strings occur.
1283 X0 only appears, optionally, in version 1 members.
1288 string[command] string[command-local]
1289 string[language] string[charset] string[locale]
1292 Y2 => CustomCurrency byte[missing] bool[x16]
1295 @code{command} describes the statistical procedure that generated the
1296 output, in English. It is not necessarily the literal syntax name of
1297 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1298 Tests.'' @code{command-local} is the procedure's name, translated
1299 into the output language; it is often empty and, when it is not,
1300 sometimes the same as @code{command}.
1302 @code{dataset} is the name of the dataset analyzed to produce the
1303 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1304 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}. The latter
1305 is sometimes the empty string.
1307 @code{missing} is the character used to indicate that a cell contains
1308 a missing value. It is always observed as @samp{.}.
1310 X0 repeats @code{decimal}, @code{grouping}, CustomCurrency, and
1311 @code{missing} already included in Formats.
1313 A writer may safely use false for @code{x16}.
1317 X1 only appears in version 3 members.
1321 00 byte[x14] bool[x15]
1323 byte[show-variables]
1325 int32[x17] int32[x18]
1331 @code{lang} may indicate the language in use. Some values seem to be
1332 0: @t{en}, 1: @t{de}, 2: @t{es}, 3: @t{it}, 5: @t{ko}, 6: @t{pl}, 8:
1333 @t{zh-tw}, 10: @t{pt_BR}, 11: @t{fr}. The @code{locale} in Formats
1334 and the @code{language}, @code{charset}, and @code{locale} in X0 are
1335 more likely to be useful in practice.
1337 @code{show-variables} determines how variables are displayed by
1338 default. A value of 1 means to display variable names, 2 to display
1339 variable labels when available, 3 to display both (name followed by
1340 label, separated by a space). The most common value is 0, which
1341 probably means to use a global default.
1343 @code{show-values} is a similar setting for values. A value of 1
1344 means to display the value, 2 to display the value label when
1345 available, 3 to display both. Again, the most common value is 0,
1346 which probably means to use a global default.
1348 A writer may safely use 1 for @code{x14}, false for @code{x15}, -1 for
1349 @code{x17} and @code{x18}, and false for @code{x19}.
1353 X2 only appears in version 3 members.
1357 int32[n-row-heights] int32*[n-row-heights]
1358 int32[n-style-map] StyleMap*[n-style-map]
1359 int32[n-styles] StylePair*[n-styles]
1361 StyleMap => int64[cell-index] int16[style-index]
1364 If present, @code{n-row-heights} and the accompanying integers are row
1365 heights as manually adjusted by the user.
1367 The rest of X2 specifies styles for data cells. At first glance this
1368 is odd, because each data cell can have its own style embedded as part
1369 of the data, but in practice X2 specifies a style for a cell only if
1370 that cell is empty (and thus does not appear in the data at all).
1371 Each StyleMap specifies the index of a blank cell, calculated the same
1372 was as in the Cells (@pxref{SPV Light Member Cells}), along with a
1373 0-based index into the accompanying StylePair array.
1375 A writer may safely omit the optional @code{i0 i0} inside the
1376 @code{count(@dots{})}.
1380 X3 only appears in version 3 members.
1384 01 00 byte[x20] 00 00 00
1387 (string[dataset] string[datafile] i0 int32[date] i0)?
1392 @code{date} is a date, as seconds since the epoch, i.e.@: since
1393 January 1, 1970. Pivot tables within an SPV file often have dates a
1394 few minutes apart, so this is probably a creation date for the table
1395 rather than for the file.
1397 X3 repeats @code{decimal}, @code{grouping}, CustomCurrency, and
1398 @code{missing} already included in Formats. @code{command},
1399 @code{command-local}, @code{language}, @code{charset}, and
1400 @code{locale} have the same meaning as in X0.
1402 @code{small} is a small real number, e.g.@: .001. Numbers smaller
1403 than this in absolute value are displayed in scientific notation.
1405 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1406 and other times they are absent. The reader can distinguish by
1407 assuming that they are present and then checking whether the
1408 presumptive @code{dataset} contains a null byte (a valid string never
1411 A writer may safely use 4 for @code{x20} and omit the optional bytes
1414 @node SPV Light Member Dimensions
1415 @subsection Dimensions
1417 A pivot table presents multidimensional data. A Dimension identifies
1418 the categories associated with each dimension.
1421 Dimensions => int32[n-dims] Dimension*[n-dims]
1423 Value[name] DimProperties
1424 int32[n-categories] Category*[n-categories]
1429 bool[hide-dim-label]
1430 bool[hide-all-labels]
1434 @code{name} is the name of the dimension, e.g.@: @code{Variables},
1435 @code{Statistics}, or a variable name.
1437 The meanings of @code{x1} and @code{x3} are unknown. @code{x1} is
1438 usually 0 but many other values have been observed. A writer may
1439 safely use 0 for @code{x1} and 2 for @code{x3}.
1441 @code{x2} is 0, 1, or 2. For a pivot table with @var{L} layer
1442 dimensions, @var{R} row dimensions, and @var{C} column dimensions,
1443 @code{x2} is 2 for the first @var{L} dimensions, 0 for the next
1444 @var{R} dimensions, and 1 for the remaining @var{C} dimensions. This
1445 does not mean that the layer dimensions must be presented first,
1446 followed by the row dimensions, followed by the column dimensions---on
1447 the contrary, they are frequently in a different order---but @code{x2}
1448 must follow this pattern to prevent the pivot table from being
1451 If @code{hide-dim-label} is 00, the pivot table displays a label for
1452 the dimension itself. Because usually the group and category labels
1453 are enough explanation, it is usually 01.
1455 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1456 the dimension, including group and category labels. It is usually 00.
1457 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1459 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1460 0 for the first dimension, 1 for the second, and so on. Sometimes it
1461 is -1. There is no visible difference.
1463 @node SPV Light Member Categories
1464 @subsection Categories
1466 Categories are arranged in a tree. Only the leaf nodes in the tree
1467 are really categories; the others just serve as grouping constructs.
1470 Category => Value[name] (Leaf @math{|} Group)
1471 Leaf => 00 00 00 i2 int32[leaf-index] i0
1473 bool[merge] 00 01 int32[x22]
1474 i-1 int32[n-subcategories] Category*[n-subcategories]
1477 @code{name} is the name of the category (or group).
1479 A Leaf represents a leaf category. The Leaf's @code{leaf-index} is a
1480 nonnegative integer unique within the Dimension and less than
1481 @code{n-categories} in the Dimension. If the user does not sort or
1482 rearrange the categories, then @code{leaf-index} starts at 0 for the
1483 first Leaf in the dimension and increments by 1 with each successive
1484 Leaf. If the user does sorts or rearrange the categories, then the
1485 order of categories in the file reflects that change and
1486 @code{leaf-index} reflects the original order.
1488 Occasionally a dimension has no leaf categories at all. A table that
1489 contains such a dimension necessarily has no data at all.
1491 A Group is a group of nested categories. Usually a Group contains at
1492 least one Category, so that @code{n-subcategories} is positive, but a
1493 few Groups with @code{n-subcategories} 0 has been observed.
1495 If a Group's @code{merge} is 00, the most common value, then the group
1496 is really a distinct group that should be represented as such in the
1497 visual representation and user interface. If @code{merge} is 01, the
1498 categories in this group should be shown and treated as if they were
1499 direct children of the group's containing group (or if it has no
1500 parent group, then direct children of the dimension), and this group's
1501 name is irrelevant and should not be displayed. (Merged groups can be
1504 (For writing an SPV file, there is no need to use the @code{merge}
1505 feature unless it is convenient.)
1507 A Group's @code{x22} appears to be i2 when all of the categories
1508 within a group are leaf categories that directly represent data values
1509 for a variable (e.g.@: in a frequency table or crosstabulation, a group
1510 of values in a variable being tabulated) and i0 otherwise. A writer
1511 may safely write a constant 0 in this field.
1513 @node SPV Light Member Axes
1516 After the dimensions come assignment of each dimension to one of the
1517 axes: layers, rows, and columns.
1521 int32[n-layers] int32[n-rows] int32[n-columns]
1522 int32*[n-layers] int32*[n-rows] int32*[n-columns]
1525 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1526 each specifies the number of dimensions displayed in layers, rows, and
1527 columns, respectively. Any of them may be zero. Their values sum to
1528 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1531 The following @code{n-dimensions} integers, in three groups, are a
1532 permutation of the 0-based dimension numbers. The first
1533 @code{n-layers} integers specify each of the dimensions represented by
1534 layers, the next @code{n-rows} integers specify the dimensions
1535 represented by rows, and the final @code{n-columns} integers specify
1536 the dimensions represented by columns. When there is more than one
1537 dimension of a given kind, the inner dimensions are given first.
1539 @node SPV Light Member Cells
1542 The final part of an SPV light member contains the actual data.
1545 Cells => int32[n-cells] Cell*[n-cells]
1546 Cell => int64[index] v1(00?) Value
1549 A Cell consists of an @code{index} and a Value. Suppose there are
1550 @math{d} dimensions, numbered 1 through @math{d} in the order given in
1551 the Dimensions previously, and that dimension @math{i}, has @math{n_i}
1552 categories. Consider the cell at coordinates @math{x_i}, @math{1 \le
1553 i \le d}, and note that @math{0 \le x_i < n_i}. Then the index is
1554 calculated by the following algorithm:
1558 for each @math{i} from 1 to @math{d}:
1559 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1562 For example, suppose there are 3 dimensions with 3, 4, and 5
1563 categories, respectively. The cell at coordinates (1, 2, 3) has
1564 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1565 Within a given dimension, the index is the @code{leaf-index} in a Leaf.
1567 @node SPV Light Member Value
1570 Value is used throughout the SPV light member format. It boils down
1571 to a number or a string.
1574 Value => 00? 00? 00? 00? RawValue
1576 01 ValueMod int32[format] double[x]
1577 @math{|} 02 ValueMod int32[format] double[x]
1578 string[var-name] string[value-label] byte[show]
1579 @math{|} 03 string[local] ValueMod string[id] string[c] bool[fixed]
1580 @math{|} 04 ValueMod int32[format] string[value-label] string[var-name]
1581 byte[show] string[s]
1582 @math{|} 05 ValueMod string[var-name] string[var-label] byte[show]
1583 @math{|} ValueMod string[template] int32[n-args] Argument*[n-args]
1586 @math{|} int32[x] i0 Value*[x] /* x > 0 */
1589 There are several possible encodings, which one can distinguish by the
1590 first nonzero byte in the encoding.
1594 The numeric value @code{x}, intended to be presented to the user
1595 formatted according to @code{format}, which is in the format described
1596 for system files, except that format 40 is a synonym for F format
1597 instead of MTIME. @xref{System File Output Formats}, for details.
1598 Most commonly, @code{format} has width 40 (the maximum).
1600 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1601 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1602 not been observed.) @xref{System File Format}, for more about these
1606 Similar to @code{01}, with the additional information that @code{x} is
1607 a value of variable @code{var-name} and has value label
1608 @code{value-label}. Both @code{var-name} and @code{value-label} can
1609 be the empty string, the latter very commonly.
1611 @code{show} determines whether to show the numeric value or the value
1612 label. A value of 1 means to show the value, 2 to show the label, 3
1613 to show both, and 0 means to use the default specified in
1614 @code{show-values} (@pxref{SPV Light Member Formats}).
1617 A text string, in two forms: @code{c} is in English, and sometimes
1618 abbreviated or obscure, and @code{local} is localized to the user's
1619 locale. In an English-language locale, the two strings are often the
1620 same, and in the cases where they differ, @code{local} is more
1621 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1622 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1623 where P must be greater than 1.''
1625 @code{c} and @code{local} are always either both empty or both
1628 @code{id} is a brief identifying string whose form seems to resemble a
1629 programming language identifier, e.g.@: @code{cumulative_percent} or
1630 @code{factor_14}. It is not unique.
1632 @code{fixed} is 00 for text taken from user input, such as syntax
1633 fragment, expressions, file names, data set names, and 01 for fixed
1634 text strings such as names of procedures or statistics. In the former
1635 case, @code{id} is always the empty string; in the latter case,
1636 @code{id} is still sometimes empty.
1639 The string value @code{s}, intended to be presented to the user
1640 formatted according to @code{format}. The format for a string is not
1641 too interesting, and the corpus contains many clearly invalid formats
1642 like A16.39 or A255.127 or A134.1, so readers should probably ignore
1643 the format entirely.
1645 @code{s} is a value of variable @code{var-name} and has value label
1646 @code{value-label}. @code{var-name} is never empty but
1647 @code{value-label} is commonly empty.
1649 @code{show} has the same meaning as in the encoding for 02.
1652 Variable @code{var-name}, which is rarely observed as empty in the
1653 corpus, with variable label @code{var-label}, which is often empty.
1655 @code{show} determines whether to show the variable name or the
1656 variable label. A value of 1 means to show the name, 2 to show the
1657 label, 3 to show both, and 0 means to use the default specified in
1658 @code{show-variables} (@pxref{SPV Light Member Formats}).
1661 When the first byte of a RawValue is not one of the above, the
1662 RawValue starts with a ValueMod, whose syntax is described in the next
1663 section. (A ValueMod always begins with byte 31 or 58.)
1665 This case is a template string, analogous to @code{printf}, followed
1666 by one or more Arguments, each of which has one or more values. The
1667 template string is copied directly into the output except for the
1668 following special syntax,
1675 Each of these expands to the character following @samp{\\}, to escape
1676 characters that have special meaning in template strings. These are
1677 effective inside and outside the @code{[@dots{}]} syntax forms
1681 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1685 Expands to a formatted version of argument @var{i}, which must have
1686 only a single value. For example, @code{^1} expands to the first
1687 argument's @code{value}.
1689 @item [:@var{a}:]@var{i}
1690 Expands @var{a} for each of the values in @var{i}. @var{a}
1691 should contain one or more @code{^@var{j}} conversions, which are
1692 drawn from the values for argument @var{i} in order. Some examples
1697 All of the values for the first argument, concatenated.
1700 Expands to the values for the first argument, each followed by
1704 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1705 argument's first value and @var{y} is its second value. (This would
1706 be used only if the argument has two values. If there were more
1707 values, the second and third values would be directly concatenated,
1708 which would look funny.)
1711 @item [@var{a}:@var{b}:]@var{i}
1712 This extends the previous form so that the first values are expanded
1713 using @var{a} and later values are expanded using @var{b}. For an
1714 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1715 instead written as @code{%@var{j}}. Some examples from the corpus:
1719 Expands to all of the values for the first argument, separated by
1722 @item [%1 = %2:, ^1 = ^2:]1
1723 Given appropriate values for the first argument, expands to @code{X =
1727 Given appropriate values, expands to @code{1, 2, 3}.
1731 The template string is localized to the user's locale.
1734 A writer may safely omit all of the optional 00 bytes at the beginning
1735 of a Value, except that it should write a single 00 byte before a
1738 @node SPV Light Member ValueMod
1739 @subsection ValueMod
1741 A ValueMod can specify special modifications to a Value.
1747 int32[n-refs] int16*[n-refs]
1748 (i0 | i1 string[subscript])
1749 v1(00 (i1 | i2) 00? 00? int32 00? 00?)
1750 v3(count(TemplateString StylePair))
1752 TemplateString => count((count((i0 58)?) (58 @math{|} 31 string[id]))?)
1759 bool[bold] bool[italic] bool[underline] bool[show]
1760 string[fg-color] string[bg-color]
1761 string[typeface] byte[size]
1764 int32[halign] int32[valign] double[decimal-offset]
1765 int16[left-margin] int16[right-margin]
1766 int16[top-margin] int16[bottom-margin]
1769 A ValueMod that begins with ``31'' specifies special modifications to
1772 Each of the @code{n-refs} integers is a reference to a Footnote
1773 (@pxref{SPV Light Member Footnotes}) by 0-based index. Footnote
1774 markers are shown appended to the main text of the Value, as
1777 The @code{subscript}, if present, is a string to append to the main
1778 text of the Value, as a subscript. The subscript text is a brief
1779 indicator, e.g.@: @samp{a} or @samp{a,b}, with its meaning indicated
1780 by the table caption.
1782 The @code{id} inside the TemplateString, if present, is a template
1783 string for substitutions using the syntax explained previously. It
1784 appears to be an English-language version of the localized template
1785 string in the Value in which the Template is nested. A writer may
1786 safely omit the optional fixed data in TemplateString.
1788 FontStyle and CellStyle, if present, change the style for this
1789 individual Value. In FontStyle, @code{bold}, @code{italic}, and
1790 @code{underline} control the particular style. @code{show} is
1791 ordinarily 1; if it is 0, then the cell data is not shown.
1792 @code{fg-color} and @code{bg-color} are strings in the format
1793 @code{#rrggbb}, e.g.@: @code{#ff0000} for red or @code{#ffffff} for
1794 white. The empty string is occasionally observed also. The
1795 @code{size} is a font size in units of 1/128 inch.
1797 In CellStyle, @code{halign} is 0 for center, 2 for left, 4 for right,
1798 6 for decimal, 0xffffffad for mixed. For decimal alignment,
1799 @code{decimal-offset} is the decimal point's offset from the right
1800 side of the cell, in pt (@pxref{SPV Light Detail Member Format}).
1801 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1802 for bottom. @code{left-margin}, @code{right-margin},
1803 @code{top-margin}, and @code{bottom-margin} are in pt.
1805 @node SPV Legacy Detail Member Binary Format
1806 @section Legacy Detail Member Binary Format
1808 Whereas the light binary format represents everything about a given
1809 pivot table, the legacy binary format conceptually consists of a
1810 number of named sources, each of which consists of a number of named
1811 variables, each of which is a 1-dimensional array of numbers or
1812 strings or a mix. Thus, the legacy binary member format is quite
1815 This section uses the same context-free grammar notation as in the
1816 previous section, with the following additions:
1820 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
1821 (The legacy member header indicates the version; see below.)
1824 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
1827 A legacy detail member @file{.bin} has the following overall format:
1831 00 byte[version] int16[n-sources] int32[member-size]
1832 Metadata*[n-sources]
1837 @code{version} is a version number that affects the interpretation of
1838 some of the other data in the member. Versions 0xaf and 0xb0 are
1839 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
1842 A legacy member consists of @code{n-sources} data sources, each of
1843 which has Metadata and Data.
1845 @code{member-size} is the size of the legacy binary member, in bytes.
1847 The Data and Strings above are commented out because the Metadata has
1848 some oddities that mean that the Data sometimes seems to start at
1849 an unexpected place. The following section goes into detail.
1852 * SPV Legacy Member Metadata::
1853 * SPV Legacy Member Numeric Data::
1854 * SPV Legacy Member String Data::
1857 @node SPV Legacy Member Metadata
1858 @subsection Metadata
1862 int32[n-values] int32[n-variables] int32[data-offset]
1863 vAF(byte*28[source-name])
1864 vB0(byte*64[source-name] int32[x])
1867 A data source has @code{n-variables} variables, each with
1868 @code{n-values} data values.
1870 @code{source-name} is a 28- or 64-byte string padded on the right with
1871 0-bytes. The names that appear in the corpus are very generic:
1872 usually @code{tableData} for pivot table data or @code{source0} for
1875 A given Metadata's @code{data-offset} is the offset, in bytes, from
1876 the beginning of the member to the start of the corresponding Data.
1877 This allows programs to skip to the beginning of the data for a
1878 particular source. In every case in the corpus, the Data follow the
1879 Metadata in the same order, but it is important to use
1880 @code{data-offset} instead of reading sequentially through the file
1881 because of the exception described below.
1883 One SPV file in the corpus has legacy binary members with version 0xb0
1884 but a 28-byte @code{source-name} field (and only a single source). In
1885 practice, this means that the 64-byte @code{source-name} used in
1886 version 0xb0 has a lot of 0-bytes in the middle followed by the
1887 @code{variable-name} of the following Data. As long as a reader
1888 treats the first 0-byte in the @code{source-name} as terminating the
1889 string, it can properly interpret these members.
1891 The meaning of @code{x} in version 0xb0 is unknown.
1893 @node SPV Legacy Member Numeric Data
1894 @subsection Numeric Data
1897 Data => Variable*[n-variables]
1898 Variable => byte*288[variable-name] double*[n-values]
1901 Data follow the Metadata in the legacy binary format, with sources in
1902 the same order (but readers should use the @code{data-offset} in
1903 Metadata records, rather than reading sequentially). Each Variable
1904 begins with a @code{variable-name} that generally indicates its role
1905 in the pivot table, e.g.@: ``cell'', ``cellFormat'',
1906 ``dimension0categories'', ``dimension0group0'', followed by the
1907 numeric data, one double per datum. A double with the maximum
1908 negative double @code{-DBL_MAX} represents the system-missing value
1911 @node SPV Legacy Member String Data
1912 @subsection String Data
1915 Strings => SourceMaps[maps] Labels
1917 SourceMaps => int32[n-maps] SourceMap*[n-maps]
1919 SourceMap => string[source-name] int32[n-variables] VariableMap*[n-variables]
1920 VariableMap => string[variable-name] int32[n-data] DatumMap*[n-data]
1921 DatumMap => int32[value-idx] int32[label-idx]
1923 Labels => int32[n-labels] Label*[n-labels]
1924 Label => int32[frequency] string[label]
1927 Each variable may include a mix of numeric and string data values. If
1928 a legacy binary member contains any string data, Strings is present;
1929 otherwise, it ends just after the last Data element.
1931 The string data overlays the numeric data. When a variable includes
1932 any string data, its Variable represents the string values with a
1933 SYSMIS or NaN placeholder. (Not all such values need be
1936 Each SourceMap provides a mapping between SYSMIS or NaN values in source
1937 @code{source-name} and the string data that they represent.
1938 @code{n-variables} is the number of variables in the source that
1939 include string data. More precisely, it is the 1-based index of the
1940 last variable in the source that includes any string data; thus, it
1941 would be 4 if there are 5 variables and only the fourth one includes
1944 A VariableMap repeats its variable's name, but variables are always
1945 present in the same order as the source, starting from the first
1946 variable, without skipping any even if they have no string values.
1947 Each VariableMap contains DatumMap nonterminals, each of which maps
1948 from a 0-based index within its variable's data to a 0-based label
1949 index, e.g.@: pair @code{value-idx} = 2, @code{label-idx} = 3, means
1950 that the third data value (which must be SYSMIS or NaN) is to be
1951 replaced by the string of the fourth Label.
1953 The labels themselves follow the pairs. The valuable part of each
1954 label is the string @code{label}. Each label also includes a
1955 @code{frequency} that reports the number of DatumMaps that reference
1956 it (although this is not useful).
1958 @node SPV Legacy Detail Member XML Format
1959 @section Legacy Detail Member XML Format
1961 The design of the detail XML format is not what one would end up with
1962 for describing pivot tables. This is because it is a special case
1963 of a much more general format (``visualization XML'' or ``VizML'')
1964 that can describe a wide range of visualizations. Most of this
1965 generality is overkill for tables, and so we end up with a funny
1966 subset of a general-purpose format.
1968 An XML Schema for VizML is available, distributed with SPSS binaries,
1969 under a nonfree license. It contains documentation that is
1970 occasionally helpful.
1972 See @file{src/output/spv/detail-xml.grammar} in the PSPP source tree
1973 for the full grammar that it uses for parsing.
1975 The important elements of the detail XML format are:
1979 Variables. @xref{SPV Detail Variable Elements}.
1982 Assignment of variables to axes. A variable can appear as columns, or
1983 rows, or layers. The @code{faceting} element and its sub-elements
1984 describe this assignment.
1987 Styles and other annotations.
1990 This description is not detailed enough to write legacy tables.
1991 Instead, write tables in the light binary format.
1994 * SPV Detail visualization Element::
1995 * SPV Detail Variable Elements::
1996 * SPV Detail extension Element::
1997 * SPV Detail graph Element::
1998 * SPV Detail location Element::
1999 * SPV Detail faceting Element::
2000 * SPV Detail facetLayout Element::
2001 * SPV Detail label Element::
2002 * SPV Detail setCellProperties Element::
2003 * SPV Detail setFormat Element::
2004 * SPV Detail interval Element::
2005 * SPV Detail style Element::
2006 * SPV Detail labelFrame Element::
2007 * SPV Detail Legacy Properties::
2010 @node SPV Detail visualization Element
2011 @subsection The @code{visualization} Element
2019 :style[style_ref]=ref style
2023 => visualization_extension?
2025 (sourceVariable | derivedVariable)+
2034 extension[visualization_extension]
2037 :minWidthSet=(true)?
2038 :maxWidthSet=(true)?
2041 userSource :missing=(listwise | pairwise)? => EMPTY
2043 categoricalDomain => variableReference simpleSort
2045 simpleSort :method[sort_method]=(custom) => categoryOrder
2047 container :style=ref style => container_extension? location+ labelFrame*
2049 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2057 The @code{visualization} element is the root of detail XML member. It
2058 has the following attributes:
2060 @defvr {Attribute} creator
2061 The version of the software that created this SPV file, as a string of
2062 the form @code{xxyyzz}, which represents software version xx.yy.zz,
2063 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
2064 versions 16 through 19.
2067 @defvr {Attribute} date
2068 The date on the which the file was created, as a string of the form
2072 @defvr {Attribute} lang
2073 The locale used for output, in Windows format, which is similar to the
2074 format used in Unix with the underscore replaced by a hyphen, e.g.@:
2075 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
2078 @defvr {Attribute} name
2079 The title of the pivot table, localized to the output language.
2082 @defvr {Attribute} style
2083 The base style for the pivot table. In every example in the corpus,
2084 the @code{style} element has no attributes other than @code{id}.
2087 @defvr {Attribute} type
2088 A floating-point number. The meaning is unknown.
2091 @defvr {Attribute} version
2092 The visualization schema version number. In the corpus, the value is
2093 one of 2.4, 2.5, 2.7, and 2.8.
2096 The @code{userSource} element has no visible effect.
2098 The @code{extension} element as a child of @code{visualization} has
2099 the following attributes.
2101 @defvr {Attribute} numRows
2102 An integer that presumably defines the number of rows in the displayed
2106 @defvr {Attribute} showGridline
2107 Always set to @code{false} in the corpus.
2110 @defvr {Attribute} minWidthSet
2111 @defvrx {Attribute} maxWidthSet
2112 Always set to @code{true} in the corpus.
2115 The @code{extension} element as a child of @code{container} has the
2118 @defvr {Attribute} combinedFootnotes
2122 The @code{categoricalDomain} and @code{simpleSort} elements have no
2125 The @code{layerController} element has no visible effect.
2127 @node SPV Detail Variable Elements
2128 @subsection Variable Elements
2130 A ``variable'' in detail XML is a 1-dimensional array of data. Each
2131 element of the array may, independently, have string or numeric
2132 content. All of the variables in a given detail XML member either
2133 have the same number of elements or have zero elements.
2135 Two different elements define variables and their content:
2138 @item sourceVariable
2139 These variables' data comes from the associated @code{tableData.bin}
2142 @item derivedVariable
2143 These variables are defined in terms of a mapping function from a
2144 source variable, or they are empty.
2147 A variable named @code{cell} always exists. This variable holds the
2148 data displayed in the table.
2150 Variables in detail XML roughly correspond to the dimensions in a
2151 light detail member. Each dimension has the following variables with
2152 stylized names, where @var{n} is a number for the dimension starting
2156 @item dimension@var{n}categories
2157 The dimension's leaf categories (@pxref{SPV Light Member Categories}).
2159 @item dimension@var{n}group0
2160 Present only if the dimension's categories are grouped, this variable
2161 holds the group labels for the categories. Grouping is inferred
2162 through adjacent identical labels. Categories that are not part of a
2163 group have empty-string data in this variable.
2165 @item dimension@var{n}group1
2166 Present only if the first-level groups are further grouped, this
2167 variable holds the labels for the second-level groups. There can be
2168 additional variables with further levels of grouping.
2170 @item dimension@var{n}
2174 Determining the data for a (non-empty) variable is a multi-step
2179 Draw initial data from its source, for a @code{sourceVariable}, or
2180 from another named variable, for a @code{derivedVariable}.
2183 Apply mappings from @code{valueMapEntry} elements within the
2184 @code{derivedVariable} element, if any.
2187 Apply mappings from @code{relabel} elements within a @code{format} or
2188 @code{stringFormat} element in the @code{sourceVariable} or
2189 @code{derivedVariable} element, if any.
2192 If the variable is a @code{sourceVariable} with a @code{labelVariable}
2193 attribute, and there were no mappings to apply in previous steps, then
2194 replace each element of the variable by the corresponding value in the
2198 A single variable's data can be modified in two of the steps, if both
2199 @code{valueMapEntry} and @code{relabel} are used. The following
2200 example from the corpus maps several integers to 2, then maps 2 in
2201 turn to the string ``Input'':
2204 <derivedVariable categorical="true" dependsOn="dimension0categories"
2205 id="dimension0group0map" value="map(dimension0group0)">
2207 <relabel from="2" to="Input"/>
2208 <relabel from="10" to="Missing Value Handling"/>
2209 <relabel from="14" to="Resources"/>
2210 <relabel from="0" to=""/>
2211 <relabel from="1" to=""/>
2212 <relabel from="13" to=""/>
2214 <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
2215 <valueMapEntry from="10;11" to="10"/>
2216 <valueMapEntry from="14;15" to="14"/>
2217 <valueMapEntry from="0" to="0"/>
2218 <valueMapEntry from="1" to="1"/>
2219 <valueMapEntry from="13" to="13"/>
2224 * SPV Detail sourceVariable Element::
2225 * SPV Detail derivedVariable Element::
2226 * SPV Detail valueMapEntry Element::
2229 @node SPV Detail sourceVariable Element
2230 @subsubsection The @code{sourceVariable} Element
2237 :domain=ref categoricalDomain?
2239 :dependsOn=ref sourceVariable?
2241 :labelVariable=ref sourceVariable?
2242 => variable_extension* (format | stringFormat)?
2245 This element defines a variable whose data comes from the
2246 @file{tableData.bin} member that corresponds to this @file{.xml}.
2248 This element has the following attributes.
2250 @defvr {Attribute} id
2251 An @code{id} is always present because this element exists to be
2252 referenced from other elements.
2255 @defvr {Attribute} categorical
2256 Always set to @code{true}.
2259 @defvr {Attribute} source
2260 Always set to @code{tableData}, the @code{source-name} in the
2261 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
2265 @defvr {Attribute} sourceName
2266 The name of a variable within the source, corresponding to the
2267 @code{variable-name} in the @file{tableData.bin} member (@pxref{SPV
2268 Legacy Member Numeric Data}).
2271 @defvr {Attribute} label
2272 The variable label, if any.
2275 @defvr {Attribute} labelVariable
2276 The @code{variable-name} of a variable whose string values correspond
2277 one-to-one with the values of this variable and are suitable for use
2281 @defvr {Attribute} dependsOn
2282 This attribute doesn't affect the display of a table.
2285 @node SPV Detail derivedVariable Element
2286 @subsubsection The @code{derivedVariable} Element
2293 :dependsOn=ref sourceVariable?
2294 => variable_extension* (format | stringFormat)? valueMapEntry*
2297 Like @code{sourceVariable}, this element defines a variable whose
2298 values can be used elsewhere in the visualization. Instead of being
2299 read from a data source, the variable's data are defined by a
2300 mathematical expression.
2302 This element has the following attributes.
2304 @defvr {Attribute} id
2305 An @code{id} is always present because this element exists to be
2306 referenced from other elements.
2309 @defvr {Attribute} categorical
2310 Always set to @code{true}.
2313 @defvr {Attribute} value
2314 An expression that defines the variable's value. In theory this could
2315 be an arbitrary expression in terms of constants, functions, and other
2316 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
2317 the corpus contains only the following forms of expressions:
2321 @itemx constant(@var{variable})
2322 All zeros. The reason why a variable is sometimes named is unknown.
2323 Sometimes the ``variable name'' has spaces in it.
2325 @item map(@var{variable})
2326 Transforms the values in the named @var{variable} using the
2327 @code{valueMapEntry}s contained within the element.
2331 @defvr {Attribute} dependsOn
2332 This attribute doesn't affect the display of a table.
2335 @node SPV Detail valueMapEntry Element
2336 @subsubsection The @code{valueMapEntry} Element
2339 valueMapEntry :from :to => EMPTY
2342 A @code{valueMapEntry} element defines a mapping from one or more
2343 values of a source expression to a target value. (In the corpus, the
2344 source expression is always just the name of a variable.) Each target
2345 value requires a separate @code{valueMapEntry}. If multiple source
2346 values map to the same target value, they can be combined or separate.
2348 In the corpus, all of the source and target values are integers.
2350 @code{valueMapEntry} has the following attributes.
2352 @defvr {Attribute} from
2353 A source value, or multiple source values separated by semicolons,
2354 e.g.@: @code{0} or @code{13;14;15;16}.
2357 @defvr {Attribute} to
2358 The target value, e.g.@: @code{0}.
2361 @node SPV Detail extension Element
2362 @subsection The @code{extension} Element
2364 This is a general-purpose ``extension'' element. Readers that don't
2365 understand a given extension should be able to safely ignore it. The
2366 attributes on this element, and their meanings, vary based on the
2367 context. Each known usage is described separately below. The current
2368 extensions use attributes exclusively, without any nested elements.
2370 @subsubheading @code{container} Parent Element
2373 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2376 With @code{container} as its parent element, @code{extension} has the
2377 following attributes.
2379 @defvr {Attribute} combinedFootnotes
2380 Always set to @code{true} in the corpus.
2383 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
2386 extension[variable_extension] :from :helpId => EMPTY
2389 With @code{sourceVariable} or @code{derivedVariable} as its parent
2390 element, @code{extension} has the following attributes. A given
2391 parent element often contains several @code{extension} elements that
2392 specify the meaning of the source data's variables or sources, e.g.@:
2395 <extension from="0" helpId="corrected_model"/>
2396 <extension from="3" helpId="error"/>
2397 <extension from="4" helpId="total_9"/>
2398 <extension from="5" helpId="corrected_total"/>
2401 More commonly they are less helpful, e.g.@:
2404 <extension from="0" helpId="notes"/>
2405 <extension from="1" helpId="notes"/>
2406 <extension from="2" helpId="notes"/>
2407 <extension from="5" helpId="notes"/>
2408 <extension from="6" helpId="notes"/>
2409 <extension from="7" helpId="notes"/>
2410 <extension from="8" helpId="notes"/>
2411 <extension from="12" helpId="notes"/>
2412 <extension from="13" helpId="no_help"/>
2413 <extension from="14" helpId="notes"/>
2416 @defvr {Attribute} from
2417 An integer or a name like ``dimension0''.
2420 @defvr {Attribute} helpId
2424 @node SPV Detail graph Element
2425 @subsection The @code{graph} Element
2429 :cellStyle=ref style
2431 => location+ coordinates faceting facetLayout interval
2433 coordinates => EMPTY
2436 @code{graph} has the following attributes.
2438 @defvr {Attribute} cellStyle
2439 @defvrx {Attribute} style
2440 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
2441 Detail style Element}). The former is the default style for
2442 individual cells, the latter for the entire table.
2445 @node SPV Detail location Element
2446 @subsection The @code{location} Element
2450 :part=(height | width | top | bottom | left | right)
2451 :method=(sizeToContent | attach | fixed | same)
2454 :target=ref (labelFrame | graph | container)?
2459 Each instance of this element specifies where some part of the table
2460 frame is located. All the examples in the corpus have four instances
2461 of this element, one for each of the parts @code{height},
2462 @code{width}, @code{left}, and @code{top}. Some examples in the
2463 corpus add a fifth for part @code{bottom}, even though it is not clear
2464 how all of @code{top}, @code{bottom}, and @code{height} can be honored
2465 at the same time. In any case, @code{location} seems to have little
2466 importance in representing tables; a reader can safely ignore it.
2468 @defvr {Attribute} part
2469 The part of the table being located.
2472 @defvr {Attribute} method
2473 How the location is determined:
2477 Based on the natural size of the table. Observed only for
2478 parts @code{height} and @code{width}.
2481 Based on the location specified in @code{target}. Observed only for
2482 parts @code{top} and @code{bottom}.
2485 Using the value in @code{value}. Observed only for parts @code{top},
2486 @code{bottom}, and @code{left}.
2489 Same as the specified @code{target}. Observed only for part
2494 @defvr {Attribute} min
2495 Minimum size. Only observed with value @code{100pt}. Only observed
2496 for part @code{width}.
2499 @defvr {Dependent} target
2500 Required when @code{method} is @code{attach} or @code{same}, not
2501 observed otherwise. This identifies an element to attach to.
2502 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
2506 @defvr {Dependent} value
2507 Required when @code{method} is @code{fixed}, not observed otherwise.
2508 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
2509 on parts @code{top} and @code{left}, and @code{100%} on part
2513 @node SPV Detail faceting Element
2514 @subsection The @code{faceting} Element
2517 faceting => layer[layers1]* cross layer[layers2]*
2519 cross => (unity | nest) (unity | nest)
2523 nest => variableReference[vars]+
2525 variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY
2528 :variable=ref (sourceVariable | derivedVariable)
2531 :method[layer_method]=(nest)?
2536 The @code{faceting} element describes the row, column, and layer
2537 structure of the table. Its @code{cross} child determines the row and
2538 column structure, and each @code{layer} child (if any) represents a
2539 layer. Layers may appear before or after @code{cross}.
2541 The @code{cross} element describes the row and column structure of the
2542 table. It has exactly two children, the first of which describes the
2543 table's columns and the second the table's rows. Each child is a
2544 @code{nest} element if the table has any dimensions along the axis in
2545 question, otherwise a @code{unity} element.
2547 A @code{nest} element contains of one or more dimensions listed from
2548 innermost to outermost, each represented by @code{variableReference}
2549 child elements. Each variable in a dimension is listed in order.
2550 @xref{SPV Detail Variable Elements}, for information on the variables
2551 that comprise a dimension.
2553 A @code{nest} can contain a single dimension, e.g.:
2557 <variableReference ref="dimension0categories"/>
2558 <variableReference ref="dimension0group0"/>
2559 <variableReference ref="dimension0"/>
2564 A @code{nest} can contain multiple dimensions, e.g.:
2568 <variableReference ref="dimension1categories"/>
2569 <variableReference ref="dimension1group0"/>
2570 <variableReference ref="dimension1"/>
2571 <variableReference ref="dimension0categories"/>
2572 <variableReference ref="dimension0"/>
2576 A @code{nest} may have no dimensions, in which case it still has one
2577 @code{variableReference} child, which references a
2578 @code{derivedVariable} whose @code{value} attribute is
2579 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
2580 @code{row} or @code{column}, respectively, as its @code{id}. This is
2581 equivalent to using a @code{unity} element in place of @code{nest}.
2583 A @code{variableReference} element refers to a variable through its
2584 @code{ref} attribute.
2586 Each @code{layer} element represents a dimension, e.g.:
2589 <layer value="0" variable="dimension0categories" visible="true"/>
2590 <layer value="dimension0" variable="dimension0" visible="false"/>
2594 @code{layer} has the following attributes.
2596 @defvr {Attribute} variable
2597 Refers to a @code{sourceVariable} or @code{derivedVariable} element.
2600 @defvr {Attribute} value
2601 The value to select. For a category variable, this is always
2602 @code{0}; for a data variable, it is the same as the @code{variable}
2606 @defvr {Attribute} visible
2607 Whether the layer is visible. Generally, category layers are visible
2608 and data layers are not, but sometimes this attribute is omitted.
2611 @defvr {Attribute} method
2612 When present, this is always @code{nest}.
2615 @node SPV Detail facetLayout Element
2616 @subsection The @code{facetLayout} Element
2619 facetLayout => tableLayout setCellProperties[scp1]*
2620 facetLevel+ setCellProperties[scp2]*
2623 :verticalTitlesInCorner=bool
2625 :fitCells=(ticks both)?
2629 The @code{facetLayout} element and its descendants control styling for
2632 Its @code{tableLayout} child has the following attributes
2634 @defvr {Attribute} verticalTitlesInCorner
2635 If true, in the absence of corner text, row headings will be displayed
2639 @defvr {Attribute} style
2640 Refers to a @code{style} element.
2643 @defvr {Attribute} fitCells
2647 @subsubheading The @code{facetLevel} Element
2650 facetLevel :level=int :gap=dimension? => axis
2652 axis :style=ref style => label? majorTicks
2658 :tickFrameStyle=ref style
2659 :labelFrequency=int?
2669 Each @code{facetLevel} describes a @code{variableReference} or
2670 @code{layer}, and a table has one @code{facetLevel} element for
2671 each such element. For example, an SPV detail member that contains
2672 four @code{variableReference} elements and two @code{layer} elements
2673 will contain six @code{facetLevel} elements.
2675 In the corpus, @code{facetLevel} elements and the elements that they
2676 describe are always in the same order. The correspondence may also be
2677 observed in two other ways. First, one may use the @code{level}
2678 attribute, described below. Second, in the corpus, a
2679 @code{facetLevel} always has an @code{id} that is the same as the
2680 @code{id} of the element it describes with @code{_facetLevel}
2681 appended. One should not formally rely on this, of course, but it is
2682 usefully indicative.
2684 @defvr {Attribute} level
2685 A 1-based index into the @code{variableReference} and @code{layer}
2686 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2687 describes the first @code{variableReference} in the SPV detail member,
2688 and in a member with four @code{variableReference} elements, a
2689 @code{facetLayout} with a @code{level} of 5 describes the first
2690 @code{layer} in the member.
2693 @defvr {Attribute} gap
2694 Always observed as @code{0pt}.
2697 Each @code{facetLevel} contains an @code{axis}, which in turn may
2698 contain a @code{label} for the @code{facetLevel} (@pxref{SPV Detail
2699 label Element}) and does contain a @code{majorTicks} element.
2701 @defvr {Attribute} labelAngle
2702 Normally 0. The value -90 causes inner column or outer row labels to
2703 be rotated vertically.
2706 @defvr {Attribute} style
2707 @defvrx {Attribute} tickFrameStyle
2708 Each refers to a @code{style} element. @code{style} is the style of
2709 the tick labels, @code{tickFrameStyle} the style for the frames around
2713 @node SPV Detail label Element
2714 @subsection The @code{label} Element
2719 :textFrameStyle=ref style?
2720 :purpose=(title | subTitle | subSubTitle | layer | footnote)?
2721 => text+ | descriptionGroup
2724 :target=ref faceting
2726 => (description | text)+
2728 description :name=(variable | value) => EMPTY
2732 :definesReference=int?
2733 :position=(subscript | superscript)?
2738 This element represents a label on some aspect of the table.
2740 @defvr {Attribute} style
2741 @defvrx {Attribute} textFrameStyle
2742 Each of these refers to a @code{style} element. @code{style} is the
2743 style of the label text, @code{textFrameStyle} the style for the frame
2747 @defvr {Attribute} purpose
2748 The kind of entity being labeled.
2751 A @code{descriptionGroup} concatenates one or more elements to form a
2752 label. Each element can be a @code{text} element, which contains
2753 literal text, or a @code{description} element that substitutes a value
2756 @defvr {Attribute} target
2757 The @code{id} of an element being described. In the corpus, this is
2758 always @code{faceting}.
2761 @defvr {Attribute} separator
2762 A string to separate the description of multiple groups, if the
2763 @code{target} has more than one. In the corpus, this is always a
2767 Typical contents for a @code{descriptionGroup} are a value by itself:
2769 <description name="value"/>
2771 @noindent or a variable and its value, separated by a colon:
2773 <description name="variable"/><text>:</text><description name="value"/>
2776 A @code{description} is like a macro that expands to some property of
2777 the target of its parent @code{descriptionGroup}. The @code{name}
2778 attribute specifies the property.
2780 @node SPV Detail setCellProperties Element
2781 @subsection The @code{setCellProperties} Element
2785 :applyToConverse=bool?
2786 => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]?
2789 The @code{setCellProperties} element sets style properties of cells or
2790 row or column labels.
2792 Interpreting @code{setCellProperties} requires answering two
2793 questions: which cells or labels to style, and what styles to use.
2795 @subsubheading Which Cells?
2800 intersect => where+ | intersectWhere | alternating | EMPTY
2803 :variable=ref (sourceVariable | derivedVariable)
2808 :variable=ref (sourceVariable | derivedVariable)
2809 :variable2=ref (sourceVariable | derivedVariable)
2812 alternating => EMPTY
2815 When @code{union} is present with @code{intersect} children, each of
2816 those children specifies a group of cells that should be styled, and
2817 the total group is all those cells taken together. When @code{union}
2818 is absent, every cell is styled. One attribute on
2819 @code{setCellProperties} affects the choice of cells:
2821 @defvr {Attribute} applyToConverse
2822 If true, this inverts the meaning of the cell selection: the selected
2823 cells are the ones @emph{not} designated. This is confusing, given
2824 the additional restrictions of @code{union}, but in the corpus
2825 @code{applyToConverse} is never present along with @code{union}.
2828 An @code{intersect} specifies restrictions on the cells to be matched.
2829 Each @code{where} child specifies which values of a given variable to
2830 include. The attributes of @code{intersect} are:
2832 @defvr {Attribute} variable
2833 Refers to a variable, e.g.@: @code{dimension0categories}. Only
2834 ``categories'' variables make sense here, but other variables, e.g.@:
2835 @code{dimension0group0map}, are sometimes seen. The reader may ignore
2839 @defvr {Attribute} include
2840 A value, or multiple values separated by semicolons,
2841 e.g.@: @code{0} or @code{13;14;15;16}.
2844 PSPP ignores @code{setCellProperties} when @code{intersectWhere} is
2847 @subsubheading What Styles?
2851 :target=ref (labeling | graph | interval | majorTicks)
2855 setMetaData :target=ref graph :key :value => EMPTY
2858 :target=ref (majorTicks | labeling)
2860 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
2864 :target=ref majorTicks
2868 The @code{set*} children of @code{setCellProperties} determine the
2871 When @code{setCellProperties} contains a @code{setFormat} whose
2872 @code{target} references a @code{labeling} element, or if it contains
2873 a @code{setStyle} that references a @code{labeling} or @code{interval}
2874 element, the @code{setCellProperties} sets the style for table cells.
2875 The format from the @code{setFormat}, if present, replaces the cells'
2876 format. The style from the @code{setStyle} that references
2877 @code{labeling}, if present, replaces the label's font and cell
2878 styles, except that the background color is taken instead from the
2879 @code{interval}'s style, if present.
2881 When @code{setCellProperties} contains a @code{setFormat} whose
2882 @code{target} references a @code{majorTicks} element, or if it
2883 contains a @code{setStyle} whose @code{target} references a
2884 @code{majorTicks}, or if it contains a @code{setFrameStyle} element,
2885 the @code{setCellProperties} sets the style for row or column labels.
2886 In this case, the @code{setCellProperties} always contains a single
2887 @code{where} element whose @code{variable} designates the variable
2888 whose labels are to be styled. The format from the @code{setFormat},
2889 if present, replaces the labels' format. The style from the
2890 @code{setStyle} that references @code{majorTicks}, if present,
2891 replaces the labels' font and cell styles, except that the background
2892 color is taken instead from the @code{setFrameStyle}'s style, if
2895 When @code{setCellProperties} contains a @code{setStyle} whose
2896 @code{target} references a @code{graph} element, and one that
2897 references a @code{labeling} element, and the @code{union} element
2898 contains @code{alternating}, the @code{setCellProperties} sets the
2899 alternate foreground and background colors for the data area. The
2900 foreground color is taken from the style referenced by the
2901 @code{setStyle} that targets the @code{graph}, the background color
2902 from the @code{setStyle} for @code{labeling}.
2904 A reader may ignore a @code{setCellProperties} that only contains
2905 @code{setMetaData}, as well as @code{setMetaData} within other
2906 @code{setCellProperties}.
2908 A reader may ignore a @code{setCellProperties} whose only @code{set*}
2909 child is a @code{setStyle} that targets the @code{graph} element.
2911 @subsubheading The @code{setStyle} Element
2915 :target=ref (labeling | graph | interval | majorTicks)
2920 This element associates a style with the target.
2922 @defvr {Attribute} target
2923 The @code{id} of an element whose style is to be set.
2926 @defvr {Attribute} style
2927 The @code{id} of a @code{style} element that identifies the style to
2931 @node SPV Detail setFormat Element
2932 @subsection The @code{setFormat} Element
2936 :target=ref (majorTicks | labeling)
2938 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
2941 This element sets the format of the target, ``format'' in this case
2942 meaning the SPSS print format for a variable.
2944 The details of this element vary depending on the schema version, as
2945 declared in the root @code{visualization} element's @code{version}
2946 attribute (@pxref{SPV Detail visualization Element}). A reader can
2947 interpret the content without knowing the schema version.
2949 The @code{setFormat} element itself has the following attributes.
2951 @defvr {Attribute} target
2952 Refers to an element whose style is to be set.
2955 @defvr {Attribute} reset
2956 If this is @code{true}, this format replaces the target's previous
2957 format. If it is @code{false}, the modifies the previous format.
2961 * SPV Detail numberFormat Element::
2962 * SPV Detail stringFormat Element::
2963 * SPV Detail dateTimeFormat Element::
2964 * SPV Detail elapsedTimeFormat Element::
2965 * SPV Detail format Element::
2966 * SPV Detail affix Element::
2969 @node SPV Detail numberFormat Element
2970 @subsubsection The @code{numberFormat} Element
2974 :minimumIntegerDigits=int?
2975 :maximumFractionDigits=int?
2976 :minimumFractionDigits=int?
2978 :scientific=(onlyForSmall | whenNeeded | true | false)?
2985 Specifies a format for displaying a number. The available options are
2986 a superset of those available from PSPP print formats. PSPP chooses a
2987 print format type for a @code{numberFormat} as follows:
2991 If @code{scientific} is @code{true}, uses @code{E} format.
2994 If @code{prefix} is @code{$}, uses @code{DOLLAR} format.
2997 If @code{suffix} is @code{%}, uses @code{PCT} format.
3000 If @code{useGrouping} is @code{true}, uses @code{COMMA} format.
3003 Otherwise, uses @code{F} format.
3006 For translating to a print format, PSPP uses
3007 @code{maximumFractionDigits} as the number of decimals, unless that
3008 attribute is missing or out of the range [0,15], in which case it uses
3011 @defvr {Attribute} minimumIntegerDigits
3012 Minimum number of digits to display before the decimal point. Always
3013 observed as @code{0}.
3016 @defvr {Attribute} maximumFractionDigits
3017 @defvrx {Attribute} minimumFractionDigits
3018 Maximum or minimum, respectively, number of digits to display after
3019 the decimal point. The observed values of each attribute range from 0
3023 @defvr {Attribute} useGrouping
3024 Whether to use the grouping character to group digits in large
3028 @defvr {Attribute} scientific
3029 This attribute controls when and whether the number is formatted in
3030 scientific notation. It takes the following values:
3034 Use scientific notation only when the number's magnitude is smaller
3035 than the value of the @code{small} attribute.
3038 Use scientific notation when the number will not otherwise fit in the
3042 Always use scientific notation. Not observed in the corpus.
3045 Never use scientific notation. A number that won't otherwise fit will
3046 be replaced by an error indication (see the @code{errorCharacter}
3047 attribute). Not observed in the corpus.
3051 @defvr {Attribute} small
3052 Only present when the @code{scientific} attribute is
3053 @code{onlyForSmall}, this is a numeric magnitude below which the
3054 number will be formatted in scientific notation. The values @code{0}
3055 and @code{0.0001} have been observed. The value @code{0} seems like a
3056 pathological choice, since no real number has a magnitude less than 0;
3057 perhaps in practice such a choice is equivalent to setting
3058 @code{scientific} to @code{false}.
3061 @defvr {Attribute} prefix
3062 @defvrx {Attribute} suffix
3063 Specifies a prefix or a suffix to apply to the formatted number. Only
3064 @code{suffix} has been observed, with value @samp{%}.
3067 @node SPV Detail stringFormat Element
3068 @subsubsection The @code{stringFormat} Element
3071 stringFormat => relabel* affix*
3073 relabel :from=real :to => EMPTY
3076 The @code{stringFormat} element specifies how to display a string. By
3077 default, a string is displayed verbatim, but @code{relabel} can change
3080 The @code{relabel} element appears as a child of @code{stringFormat}
3081 (and of @code{format}, when it is used to format strings). It
3082 specifies how to display a given value. It is used to implement value
3083 labels and to display the system-missing value in a human-readable
3084 way. It has the following attributes:
3086 @defvr {Attribute} from
3087 The value to map. In the corpus this is an integer or the
3088 system-missing value @code{-1.797693134862316E300}.
3091 @defvr {Attribute} to
3092 The string to display in place of the value of @code{from}. In the
3093 corpus this is a wide variety of value labels; the system-missing
3094 value is mapped to @samp{.}.
3097 @node SPV Detail dateTimeFormat Element
3098 @subsubsection The @code{dateTimeFormat} Element
3102 :baseFormat[dt_base_format]=(date | time | dateTime)
3104 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3106 :yearAbbreviation=bool?
3111 :monthFormat=(long | short | number | paddedNumber)?
3115 :showDayOfWeek=bool?
3116 :dayOfWeekAbbreviation=bool?
3118 :dayOfMonthPadding=bool?
3120 :minutePadding=bool?
3121 :secondPadding=bool?
3127 :dayType=(month | year)?
3128 :hourFormat=(AMPM | AS_24 | AS_12)?
3132 This element appears only in schema version 2.5 and earlier
3133 (@pxref{SPV Detail visualization Element}).
3135 Data to be formatted in date formats is stored as strings in legacy
3136 data, in the format @code{yyyy-mm-ddTHH:MM:SS.SSS} and must be parsed
3137 and reformatted by the reader.
3139 The following attribute is required.
3141 @defvr {Attribute} baseFormat
3142 Specifies whether a date and time are both to be displayed, or just
3146 Many of the attributes' meanings are obvious. The following seem to
3147 be worth documenting.
3149 @defvr {Attribute} separatorChars
3150 Exactly four characters. In order, these are used for: decimal point,
3151 grouping, date separator, time separator. Always @samp{.,-:}.
3154 @defvr {Attribute} mdyOrder
3155 Within a date, the order of the days, months, and years.
3156 @code{dayMonthYear} is the only observed value, but one would expect
3157 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
3161 @defvr {Attribute} showYear
3162 @defvrx {Attribute} yearAbbreviation
3163 Whether to include the year and, if so, whether the year should be
3164 shown abbreviated, that is, with only 2 digits. Each is @code{true}
3165 or @code{false}; only values of @code{true} and @code{false},
3166 respectively, have been observed.
3169 @defvr {Attribute} showMonth
3170 @defvrx {Attribute} monthFormat
3171 Whether to include the month (@code{true} or @code{false}) and, if so,
3172 how to format it. @code{monthFormat} is one of the following:
3176 The full name of the month, e.g.@: in an English locale,
3180 The abbreviated name of the month, e.g.@: in an English locale,
3184 The number representing the month, e.g.@: 9 for September.
3187 A two-digit number representing the month, e.g.@: 09 for September.
3190 Only values of @code{true} and @code{short}, respectively, have been
3194 @defvr {Attribute} dayType
3195 This attribute is always @code{month} in the corpus, specifying that
3196 the day of the month is to be displayed; a value of @code{year} is
3197 supposed to indicate that the day of the year, where 1 is January 1,
3198 is to be displayed instead.
3201 @defvr {Attribute} hourFormat
3202 @code{hourFormat}, if present, is one of:
3206 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
3210 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
3212 This is the only value observed in the corpus.
3215 The time is displayed in a 12-hour format, without distinguishing
3216 morning or evening, e.g.@: @code{10;15}.
3219 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
3220 which is confusing since a time duration does not have a concept of AM
3221 or PM. This might indicate a bug in the code that generated the XML
3222 in the corpus, or it might indicate that @code{elapsedTime} is
3223 sometimes used to format a time of day.
3226 For a @code{baseFormat} of @code{date}, PSPP chooses a print format
3227 type based on the following rules:
3231 If @code{showQuarter} is true: @code{QYR}.
3234 Otherwise, if @code{showWeek} is true: @code{WKYR}.
3237 Otherwise, if @code{mdyOrder} is @code{dayMonthYear}:
3241 If @code{monthFormat} is @code{number} or @code{paddedNumber}: @code{EDATE}.
3244 Otherwise: @code{DATE}.
3248 Otherwise, if @code{mdyOrder} is @code{yearMonthDay}: @code{SDATE}.
3251 Otherwise, @code{ADATE}.
3254 For a @code{baseFormat} of @code{dateTime}, PSPP uses @code{YMDHMS} if
3255 @code{mdyOrder} is @code{yearMonthDay} and @code{DATETIME} otherwise.
3256 For a @code{baseFormat} of @code{time}, PSPP uses @code{DTIME} if
3257 @code{showDay} is true, otherwise @code{TIME} if @code{showHour} is
3258 true, otherwise @code{MTIME}.
3260 For a @code{baseFormat} of @code{date}, the chosen width is the
3261 minimum for the format type, adding 2 if @code{yearAbbreviation} is
3262 false or omitted. For other base formats, the chosen width is the
3263 minimum for its type, plus 3 if @code{showSecond} is true, plus 4 more
3264 if @code{showMillis} is also true. Decimals are 0 by default, or 3
3265 if @code{showMillis} is true.
3267 @node SPV Detail elapsedTimeFormat Element
3268 @subsubsection The @code{elapsedTimeFormat} Element
3272 :baseFormat[dt_base_format]=(date | time | dateTime)
3275 :minutePadding=bool?
3276 :secondPadding=bool?
3286 This element specifies the way to display a time duration.
3288 Data to be formatted in elapsed time formats is stored as strings in
3289 legacy data, in the format @code{H:MM:SS.SSS}, with additional hour
3290 digits as needed for long durations, and must be parsed and
3291 reformatted by the reader.
3293 The following attribute is required.
3295 @defvr {Attribute} baseFormat
3296 Specifies whether a day and a time are both to be displayed, or just
3300 The remaining attributes specify exactly how to display the elapsed
3303 For @code{baseFormat} of @code{time}, PSPP converts this element to
3304 print format type @code{DTIME}; otherwise, if @code{showHour} is true,
3305 to @code{TIME}; otherwise, to @code{MTIME}. The chosen width is the
3306 minimum for the chosen type, adding 3 if @code{showSecond} is true,
3307 adding 4 more if @code{showMillis} is also true. Decimals are 0 by
3308 default, or 3 if @code{showMillis} is true.
3310 @node SPV Detail format Element
3311 @subsubsection The @code{format} Element
3315 :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)?
3318 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3323 :yearAbbreviation=bool?
3325 :monthFormat=(long | short | number | paddedNumber)?
3327 :dayOfMonthPadding=bool?
3331 :showDayOfWeek=bool?
3332 :dayOfWeekAbbreviation=bool?
3334 :minutePadding=bool?
3335 :secondPadding=bool?
3341 :dayType=(month | year)?
3342 :hourFormat=(AMPM | AS_24 | AS_12)?
3343 :minimumIntegerDigits=int?
3344 :maximumFractionDigits=int?
3345 :minimumFractionDigits=int?
3347 :scientific=(onlyForSmall | whenNeeded | true | false)?
3351 :tryStringsAsNumbers=bool?
3352 :negativesOutside=bool?
3356 This element is the union of all of the more-specific format elements.
3357 It is interpreted in the same way as one of those format elements,
3358 using @code{baseFormat} to determine which kind of format to use.
3360 There are a few attributes not present in the more specific formats:
3362 @defvr {Attribute} tryStringsAsNumbers
3363 When this is @code{true}, it is supposed to indicate that string
3364 values should be parsed as numbers and then displayed according to
3365 numeric formatting rules. However, in the corpus it is always
3369 @defvr {Attribute} negativesOutside
3370 If true, the negative sign should be shown before the prefix; if
3371 false, it should be shown after.
3374 @node SPV Detail affix Element
3375 @subsubsection The @code{affix} Element
3379 :definesReference=int
3380 :position=(subscript | superscript)
3386 This defines a suffix (or, theoretically, a prefix) for a formatted
3387 value. It is used to insert a reference to a footnote. It has the
3388 following attributes:
3390 @defvr {Attribute} definesReference
3391 This specifies the footnote number as a natural number: 1 for the
3392 first footnote, 2 for the second, and so on.
3395 @defvr {Attribute} position
3396 Position for the footnote label. Always @code{superscript}.
3399 @defvr {Attribute} suffix
3400 Whether the affix is a suffix (@code{true}) or a prefix
3401 (@code{false}). Always @code{true}.
3404 @defvr {Attribute} value
3405 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
3406 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
3407 contains other values: @code{*}, @code{**}, and a few that begin with
3408 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
3411 @node SPV Detail interval Element
3412 @subsection The @code{interval} Element
3415 interval :style=ref style => labeling footnotes?
3419 :variable=ref (sourceVariable | derivedVariable)
3420 => (formatting | format | footnotes)*
3422 formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping*
3424 formatMapping :from=int => format?
3428 :variable=ref (sourceVariable | derivedVariable)
3431 footnoteMapping :definesReference=int :from=int :to => EMPTY
3434 The @code{interval} element and its descendants determine the basic
3435 formatting and labeling for the table's cells. These basic styles are
3436 overridden by more specific styles set using @code{setCellProperties}
3437 (@pxref{SPV Detail setCellProperties Element}).
3439 The @code{style} attribute of @code{interval} itself may be ignored.
3441 The @code{labeling} element may have a single @code{formatting} child.
3442 If present, its @code{variable} attribute refers to a variable whose
3443 values are format specifiers as numbers, e.g. value 0x050802 for F8.2.
3444 However, the numbers are not actually interpreted that way. Instead,
3445 each number actually present in the variable's data is mapped by a
3446 @code{formatMapping} child of @code{formatting} to a @code{format}
3447 that specifies how to display it.
3449 The @code{labeling} element may also have a @code{footnotes} child
3450 element. The @code{variable} attribute of this element refers to a
3451 variable whose values are comma-delimited strings that list the
3452 1-based indexes of footnote references. (Cells without any footnote
3453 references are numeric 0 instead of strings.)
3455 Each @code{footnoteMapping} child of the @code{footnotes} element
3456 defines the footnote marker to be its @code{to} attribute text for the
3457 footnote whose 1-based index is given in its @code{definesReference}
3460 @node SPV Detail style Element
3461 @subsection The @code{style} Element
3468 :border-bottom=(solid | thick | thin | double | none)?
3469 :border-top=(solid | thick | thin | double | none)?
3470 :border-left=(solid | thick | thin | double | none)?
3471 :border-right=(solid | thick | thin | double | none)?
3472 :border-bottom-color?
3475 :border-right-color?
3478 :font-weight=(regular | bold)?
3479 :font-style=(regular | italic)?
3480 :font-underline=(none | underline)?
3481 :margin-bottom=dimension?
3482 :margin-left=dimension?
3483 :margin-right=dimension?
3484 :margin-top=dimension?
3485 :textAlignment=(left | right | center | decimal | mixed)?
3486 :labelLocationHorizontal=(positive | negative | center)?
3487 :labelLocationVertical=(positive | negative | center)?
3488 :decimal-offset=dimension?
3495 A @code{style} element has an effect only when it is referenced by
3496 another element to set some aspect of the table's style. Most of the
3497 attributes are self-explanatory. The rest are described below.
3499 @defvr {Attribute} {color}
3500 In some cases, the text color; in others, the background color.
3503 @defvr {Attribute} {color2}
3507 @defvr {Attribute} {labelAngle}
3508 Normally 0. The value -90 causes inner column or outer row labels to
3509 be rotated vertically.
3512 @defvr {Attribute} {labelLocationHorizontal}
3516 @defvr {Attribute} {labelLocationVertical}
3517 The value @code{positive} corresponds to vertically aligning text to
3518 the top of a cell, @code{negative} to the bottom, @code{center} to the
3522 @node SPV Detail labelFrame Element
3523 @subsection The @code{labelFrame} Element
3526 labelFrame :style=ref style => location+ label? paragraph?
3528 paragraph :hangingIndent=dimension? => EMPTY
3531 A @code{labelFrame} element specifies content and style for some
3532 aspect of a table. Only @code{labelFrame} elements that have a
3533 @code{label} child are important. The @code{purpose} attribute in the
3534 @code{label} determines what the @code{labelFrame} affects:
3538 The table's title and its style.
3541 The table's caption and its style.
3544 The table's footnotes and the style for the footer area.
3547 The style for the layer area.
3553 The @code{style} attribute references the style to use for the area.
3555 The @code{label}, if present, specifies the text to put into the title
3556 or caption or footnotes. For footnotes, the label has two @code{text}
3557 children for every footnote, each of which has a @code{usesReference}
3558 attribute identifying the 1-based index of a footnote. The first,
3559 third, fifth, @dots{} @code{text} child specifies the content for a
3560 footnote; the second, fourth, sixth, @dots{} child specifies the
3561 marker. Content tends to end in a new-line, which the reader may wish
3562 to trim; similarly, markers tend to end in @samp{.}.
3564 The @code{paragraph}, if present, may be ignored, since it is always
3567 @node SPV Detail Legacy Properties
3568 @subsection Legacy Properties
3570 The detail XML format has features for styling most of the aspects of
3571 a table. It also inherits defaults for many aspects from structure
3572 XML, which has the following @code{tableProperties} element:
3576 => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties
3579 :hideEmptyRows=bool?
3580 :maximumColumnWidth=dimension?
3581 :maximumRowWidth=dimension?
3582 :minimumColumnWidth=dimension?
3583 :minimumRowWidth=dimension?
3584 :rowDimensionLabels=(inCorner | nested)?
3588 :markerPosition=(superscript | subscript)?
3589 :numberFormat=(alphabetic | numeric)?
3592 cellFormatProperties => cell_style+
3595 :alternatingColor=color?
3596 :alternatingTextColor=color?
3604 :font-style=(regular | italic)?
3605 :font-weight=(regular | bold)?
3606 :labelLocationVertical=(positive | negative | center)?
3607 :margin-bottom=dimension?
3608 :margin-left=dimension?
3609 :margin-right=dimension?
3610 :margin-top=dimension?
3611 :textAlignment=(left | right | center | decimal | mixed)?
3612 :decimal-offset=dimension?
3615 borderProperties => border_style+
3618 :borderStyleType=(none | solid | dashed | thick | thin | double)?
3623 :printAllLayers=bool?
3624 :rescaleLongTableToFitPage=bool?
3625 :rescaleWideTableToFitPage=bool?
3626 :windowOrphanLines=int?
3628 :continuationTextAtBottom=bool?
3629 :continuationTextAtTop=bool?
3630 :printEachLayerOnSeparatePage=bool?