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 8,000 files from a variety of sources. This description is
18 detailed enough to both read and write SPV files.
20 SPSS 15 and earlier versions instead use @file{.spo} files, which have
21 a completely different output format based on the Microsoft Compound
22 Document Format. This format is not documented here.
24 An SPV file is a Zip archive that can be read with @command{zipinfo}
25 and @command{unzip} and similar programs. The final member in the Zip
26 archive is the @dfn{manifest}, a file named
27 @file{META-INF/MANIFEST.MF}. This structure makes SPV files resemble
28 Java ``JAR'' files (and ODF files), but whereas a JAR manifest
29 contains a sequence of colon-delimited key/value pairs, an SPV
30 manifest contains the string @samp{allowPivoting=true}, without a
31 new-line. PSPP uses this string to identify an SPV file; it is
32 invariant across the corpus.@footnote{SPV files always begin with the
33 7-byte sequence 50 4b 03 04 14 00 08, but this is not a useful magic
34 number because most Zip archives start the same way.}
36 The rest of the members in an SPV file's Zip archive fall into two
37 categories: @dfn{structure} and @dfn{detail} members. Structure
38 member names begin with @file{outputViewer@var{nnnnnnnnnn}}, where
39 each @var{n} is a decimal digit, and end with @file{.xml}, and often
40 include the string @file{_heading} in between. Each of these members
41 represents some kind of output item (a table, a heading, a block of
42 text, etc.) or a group of them. The member whose output goes at the
43 beginning of the document is numbered 0, the next member in the output
44 is numbered 1, and so on.
46 Structure members contain XML. This XML is sometimes self-contained,
47 but it often references detail members in the Zip archive, which are
51 @item @file{@var{prefix}_table.xml} and @file{@var{prefix}_tableData.bin}
52 @itemx @file{@var{prefix}_lightTableData.bin}
53 The structure of a table plus its data. Older SPV files pair a
54 @file{@var{prefix}_table.xml} file that describes the table's
55 structure with a binary @file{@var{prefix}_tableData.bin} file that
56 gives its data. Newer SPV files (the majority of those in the corpus)
57 instead include a single @file{@var{prefix}_lightTableData.bin} file
58 that incorporates both into a single binary format.
60 @item @file{@var{prefix}_warning.xml} and @file{@var{prefix}_warningData.bin}
61 @itemx @file{@var{prefix}_lightWarningData.bin}
62 Same format used for tables, with a different name.
64 @item @file{@var{prefix}_notes.xml} and @file{@var{prefix}_notesData.bin}
65 @itemx @file{@var{prefix}_lightNotesData.bin}
66 Same format used for tables, with a different name.
68 @item @file{@var{prefix}_chartData.bin} and @file{@var{prefix}_chart.xml}
69 The structure of a chart plus its data. Charts do not have a
72 @item @file{@var{prefix}_pmml.scf}
73 @itemx @file{@var{prefix}_stats.scf}
74 @item @file{@var{prefix}_model.xml}
75 Not yet investigated. The corpus contains few examples.
78 The @file{@var{prefix}} in the names of the detail members is
79 typically an 11-digit decimal number that increases for each item,
80 tending to skip values. Older SPV files use different naming
81 conventions. Structure member refer to detail members by name, and so
82 their exact names do not matter to readers as long as they are unique.
84 SPSS tolerates corrupted Zip archives that Zip reader libraries tend
85 to reject. These can be fixed up with @command{zip -FF}.
88 * SPV Structure Member Format::
89 * SPV Light Detail Member Format::
90 * SPV Legacy Detail Member Binary Format::
91 * SPV Legacy Detail Member XML Format::
94 @node SPV Structure Member Format
95 @section Structure Member Format
97 A structure member lays out the high-level structure for a group of
98 output items such as heading, tables, and charts. Structure members
99 do not include the details of tables and charts but instead refer to
100 them by their member names.
102 Structure members' XML files claim conformance with a collection of
103 XML Schemas. These schemas are distributed, under a nonfree license,
104 with SPSS binaries. Fortunately, the schemas are not necessary to
105 understand the structure members. The schemas can even
106 be deceptive because they document elements and attributes that are
107 not in the corpus and do not document elements and attributes that are
108 commonly found in the corpus.
110 Structure members use a different XML namespace for each schema, but
111 these namespaces are not entirely consistent. In some SPV files, for
112 example, the @code{viewer-tree} schema is associated with namespace
113 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
114 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
115 additional @file{viewer/}). Under either name, the schema URIs are
116 not resolvable to obtain the schemas themselves.
118 One may ignore all of the above in interpreting a structure member.
119 The actual XML has a simple and straightforward form that does not
120 require a reader to take schemas or namespaces into account. A
121 structure member's root is @code{heading} element, which contains
122 @code{heading} or @code{container} elements (or a mix), forming a
123 tree. In turn, @code{container} holds a @code{label} and one more
124 child, usually @code{text} or @code{table}.
126 The following sections document the elements found in structure
127 members in a context-free grammar-like fashion. Consider the
128 following example, which specifies the attributes and content for the
129 @code{container} element:
133 :visibility=(visible | hidden)
134 :page-break-before=(always)?
135 :text-align=(left | center)?
137 => label (table | container_text | graph | model | object | image | tree)
140 Each attribute specification begins with @samp{:} followed by the
141 attribute's name. If the attribute's value has an easily specified
142 form, then @samp{=} and its description follows the name. Finally, if
143 the attribute is optional, the specification ends with @samp{?}. The
144 following value specifications are defined:
147 @item (@var{a} | @var{b} | @dots{})
148 One of the listed literal strings. If only one string is listed, it
149 is the only acceptable value. If @code{OTHER} is listed, then any
150 string not explicitly listed is also accepted.
153 Either @code{true} or @code{false}.
156 A floating-point number followed by a unit, e.g.@: @code{10pt}. Units
157 in the corpus include @code{in} (inch), @code{pt} (points, 72/inch),
158 @code{px} (``device-independent pixels'', 96/inch), and @code{cm}. If
159 the unit is omitted then points should be assumed. The number and
160 unit may be separated by white space.
162 The corpus also includes localized names for units. A reader must
163 understand these to properly interpret the dimension:
167 @code{인치}, @code{pol.}, @code{cala}, @code{cali}
177 A floating-point number.
183 A color in one of the forms @code{#@var{rr}@var{gg}@var{bb}} or
184 @code{@var{rr}@var{gg}@var{bb}}, or the string @code{transparent}, or
185 one of the standard Web color names.
188 @item ref @var{element}
189 @itemx ref(@var{elem1} | @var{elem2} | @dots{})
190 The name from the @code{id} attribute in some element. If one or more
191 elements are named, the name must refer to one of those elements,
192 otherwise any element is acceptable.
195 All elements have an optional @code{id} attribute. If present, its
196 value must be unique. In practice many elements are assigned
197 @code{id} attributes that are never referenced.
199 The content specification for an element supports the following
206 @item @var{a} @var{b}
207 @var{a} followed by @var{b}.
209 @item @var{a} | @var{b} | @var{c}
210 One of @var{a} or @var{b} or @var{c}.
213 Zero or one instances of @var{a}.
216 Zero or more instances of @var{a}.
219 One or more instances of @var{a}.
221 @item (@var{subexpression})
222 Grouping for a subexpression.
231 Element and attribute names are sometimes suffixed by another name in
232 square brackets to distinguish different uses of the same name. For
233 example, structure XML has two @code{text} elements, one inside
234 @code{container}, the other inside @code{pageParagraph}. The former
235 is defined as @code{text[container_text]} and referenced as
236 @code{container_text}, the latter defined as
237 @code{text[pageParagraph_text]} and referenced as
238 @code{pageParagraph_text}.
240 This language is used in the PSPP source code for parsing structure
241 and detail XML members. Refer to
242 @file{src/output/spv/structure-xml.grammar} and
243 @file{src/output/spv/detail-xml.grammar} for the full grammars.
245 The following example shows the contents of a typical structure member
246 for a @cmd{DESCRIPTIVES} procedure. A real structure member is not
247 indented. This example also omits most attributes, all XML namespace
248 information, and the CSS from the embedded HTML:
251 <?xml version="1.0" encoding="utf-8"?>
253 <label>Output</label>
254 <heading commandName="Descriptives">
255 <label>Descriptives</label>
258 <text commandName="Descriptives" type="title">
260 <![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
264 <container visibility="hidden">
266 <table commandName="Descriptives" subType="Notes" type="note">
268 <dataPath>00000000001_lightNotesData.bin</dataPath>
273 <label>Descriptive Statistics</label>
274 <table commandName="Descriptives" subType="Descriptive Statistics"
277 <dataPath>00000000002_lightTableData.bin</dataPath>
286 * SPV Structure heading Element::
287 * SPV Structure label Element::
288 * SPV Structure container Element::
289 * SPV Structure text Element (Inside @code{container})::
290 * SPV Structure html Element::
291 * SPV Structure table Element::
292 * SPV Structure graph Element::
293 * SPV Structure model Element::
294 * SPV Structure tree Element::
295 * SPV Structure Path Elements::
296 * SPV Structure pageSetup Element::
297 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
300 @node SPV Structure heading Element
301 @subsection The @code{heading} Element
304 heading[root_heading]
310 => label pageSetup? (container | heading)*
315 :visibility[heading_visibility]=(collapsed)?
318 => label (container | heading)*
321 The root of a structure member is a @code{heading}, which represents a
322 section of output beginning with a @code{label} and
323 ordinarily followed by content containers or further nested
324 (sub)-sections of output. Unlike heading elements in HTML and other
325 common document formats, which precede the content that they head,
326 @code{heading} contains the elements that appear below the heading.
328 The document root heading, only, may contain a @code{pageSetup}
331 The following attributes have been observed on both document root and
332 nested @code{heading} elements.
334 @defvr {Attribute} creator-version
335 The version of the software that created this SPV file. A string of
336 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
337 e.g.@: @code{21000001} is version 21.0.0.1. Trailing pairs of zeros
338 are sometimes omitted, so that @code{21}, @code{210000}, and
339 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
340 three of those forms).
344 The following attributes have been observed on document root
345 @code{heading} elements only:
347 @defvr {Attribute} @code{creator}
348 The directory in the file system of the software that created this SPV
352 @defvr {Attribute} @code{creation-date-time}
353 The date and time at which the SPV file was written, in a
354 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
355 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
356 December 5, 2014 5:00:19 o'clock PM EST}.
359 @defvr {Attribute} @code{lockReader}
360 Whether a reader should be allowed to edit the output. The possible
361 values are @code{true} and @code{false}. The value @code{false} is by
365 @defvr {Attribute} @code{schemaLocation}
366 This is actually an XML Namespace attribute. A reader may ignore it.
370 The following attributes have been observed only on nested
371 @code{heading} elements:
373 @defvr {Attribute} @code{commandName}
374 A locale-invariant identifier for the command that produced the
375 output, e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
378 @defvr {Attribute} @code{visibility}
379 To what degree the output represented by the element is visible.
382 @defvr {Attribute} @code{locale}
383 The locale used for output, in Windows format, which is similar to the
384 format used in Unix with the underscore replaced by a hyphen, e.g.@:
385 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
388 @defvr {Attribute} @code{olang}
389 The output language, e.g.@: @code{en}, @code{it}, @code{es},
390 @code{de}, @code{pt-BR}.
393 @node SPV Structure label Element
394 @subsection The @code{label} Element
400 Every @code{heading} and @code{container} holds a @code{label} as its
401 first child. The label text is what appears in the outline pane of
402 the GUI's viewer window. PSPP also puts it into the outline of PDF
403 output. The label text doesn't appear in the output itself.
405 The text in @code{label} describes what it labels, often by naming the
406 statistical procedure that was executed, e.g.@: ``Frequencies'' or
407 ``T-Test''. The root @code{heading} in a structure member is normally
408 ``Output''. Labels are often very generic, especially within a
409 @code{container}, e.g.@: ``Title'' or ``Warnings'' or ``Notes''.
410 Label text is localized according to the output language, e.g.@: in
411 Italian a frequency table procedure is labeled ``Frequenze''.
413 The user can edit labels to be anything they want. The corpus
414 contains a few examples of empty labels, ones that contain no text,
415 probably as a result of user editing.
417 @node SPV Structure container Element
418 @subsection The @code{container} Element
422 :visibility=(visible | hidden)
423 :page-break-before=(always)?
424 :text-align=(left | center)?
426 => label (table | container_text | graph | model | object | image | tree)
429 A @code{container} serves to contain and label a @code{table},
430 @code{text}, or other kind of item.
432 This element has the following attributes.
434 @defvr {Attribute} @code{visibility}
435 Whether the container's content is displayed. ``Notes'' tables are
436 often hidden; other data is usually
439 @defvr {Attribute} @code{text-align}
440 Alignment of text within the container. Observed with nested
441 @code{table} and @code{text} elements.
444 @defvr {Attribute} @code{width}
445 The width of the container, e.g.@: @code{1097px}.
448 @node SPV Structure text Element (Inside @code{container})
449 @subsection The @code{text} Element (Inside @code{container})
453 :type[text_type]=(title | log | text | page-title)
459 This @code{text} element is nested inside a @code{container}. There
460 is a different @code{text} element that is nested inside a
461 @code{pageParagraph}.
463 This element has the following attributes.
465 @defvr {Attribute} @code{type}
466 The semantics of the text.
469 @defvr {Attribute} @code{commandName}
470 As on the @code{heading} element. For output not specific to a
471 command, this is simply @code{log}. The corpus contains one example
472 of where @code{commandName} is present but set to the empty string.
475 @defvr {Attribute} @code{creator-version}
476 As on the @code{heading} element.
479 @node SPV Structure html Element
480 @subsection The @code{html} Element
483 html :lang=(en) => TEXT
486 The element contains an HTML document as text (or, in practice, as
487 CDATA). In some cases, the document starts with @code{<html>} and
488 ends with @code{</html>}; in others the @code{html} element is
489 implied. Generally the HTML includes a @code{head} element with a CSS
490 stylesheet. The HTML body often begins with @code{<BR>}.
492 The HTML document uses only the following elements:
496 Sometimes, the document is enclosed with
497 @code{<html>}@dots{}@code{</html>}.
500 The HTML body often begins with @code{<BR>} and may contain it as well.
508 The attributes @code{face}, @code{color}, and @code{size} are
509 observed. The value of @code{color} takes one of the forms
510 @code{#@var{rr}@var{gg}@var{bb}} or @code{rgb (@var{r}, @var{g},
511 @var{b})}. The value of @code{size} is a number between 1 and 7,
515 The CSS in the corpus is simple. To understand it, a parser only
516 needs to be able to skip white space, @code{<!--}, and @code{-->}, and
517 parse style only for @code{p} elements. Only @code{font-weight},
518 @code{font-style}, @code{font-decoration}, @code{font-family}, and
519 @code{font-size} matter.
521 This element has the following attributes.
523 @defvr {Attribute} @code{lang}
524 This always contains @code{en} in the corpus.
527 @node SPV Structure table Element
528 @subsection The @code{table} Element
537 :displayFiltering=bool?
539 :orphanTolerance=int?
544 :type[table_type]=(table | note | warning)
545 => tableProperties? tableStructure
547 tableStructure => path? dataPath csvPath?
550 This element has the following attributes.
552 @defvr {Attribute} @code{commandName}
553 As on the @code{heading} element.
556 @defvr {Attribute} @code{type}
557 One of @code{table}, @code{note}, or @code{warning}.
560 @defvr {Attribute} @code{subType}
561 The locale-invariant command ID for the particular kind of output that
562 this table represents in the procedure. This can be the same as
563 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
564 @code{Case Processing Summary}. Generic subtypes @code{Notes} and
565 @code{Warnings} are often used.
568 @defvr {Attribute} @code{tableId}
569 A number that uniquely identifies the table within the SPV file,
570 typically a large negative number such as @code{-4147135649387905023}.
573 @defvr {Attribute} @code{creator-version}
574 As on the @code{heading} element. In the corpus, this is only present
575 for version 21 and up and always includes all 8 digits.
578 @xref{SPV Detail Legacy Properties}, for details on the
579 @code{tableProperties} element.
581 @node SPV Structure graph Element
582 @subsection The @code{graph} Element
597 => dataPath? path csvPath?
600 This element represents a graph. The @code{dataPath} and @code{path}
601 elements name the Zip members that give the details of the graph.
602 Normally, both elements are present; there is only one counterexample
605 @code{csvPath} only appears in one SPV file in the corpus, for two
606 graphs. In these two cases, @code{dataPath}, @code{path}, and
607 @code{csvPath} all appear. These @code{csvPath} name Zip members with
608 names of the form @file{@var{number}_csv.bin}, where @var{number} is a
609 many-digit number and the same as the @code{csvFileIds}. The named
610 Zip members are CSV text files (despite the @file{.bin} extension).
611 The CSV files are encoded in UTF-8 and begin with a U+FEFF byte-order
614 @node SPV Structure model Element
615 @subsection The @code{model} Element
627 => ViZml? dataPath? path | pmmlContainerPath statsContainerPath
629 pmmlContainerPath => TEXT
631 statsContainerPath => TEXT
633 ViZml :viewName? => TEXT
636 This element represents a model. The @code{dataPath} and @code{path}
637 elements name the Zip members that give the details of the model.
638 Normally, both elements are present; there is only one counterexample
641 The details are unexplored. The @code{ViZml} element contains base-64
642 encoded text, that decodes to a binary format with some embedded text
643 strings, and @code{path} names an Zip member that contains XML.
644 Alternatively, @code{pmmlContainerPath} and @code{statsContainerPath}
645 name Zip members with @file{.scf} extension.
647 @node SPV Structure tree Element
648 @subsection The @code{tree} Element
659 This element represents a tree. The @code{dataPath} and @code{path}
660 elements name the Zip members that give the details of the tree.
661 The details are unexplored.
663 @node SPV Structure Path Elements
664 @subsection Path Elements
674 These element contain the name of the Zip members that hold details
675 for a container. For tables:
679 When a ``light'' format is used, only @code{dataPath} is present, and
680 it names a @file{.bin} member of the Zip file that has @code{light} in
681 its name, e.g.@: @code{0000000001437_lightTableData.bin} (@pxref{SPV
682 Light Detail Member Format}).
685 When the legacy format is used, both are present. In this case,
686 @code{dataPath} names a Zip member with a legacy binary format that
687 contains relevant data (@pxref{SPV Legacy Detail Member Binary
688 Format}), and @code{path} names a Zip member that uses an XML format
689 (@pxref{SPV Legacy Detail Member XML Format}).
692 Graphs normally follow the legacy approach described above. The
693 corpus contains one example of a graph with @code{path} but not
694 @code{dataPath}. The reason is unexplored.
696 Models use @code{path} but not @code{dataPath}. @xref{SPV Structure
697 graph Element}, for more information.
699 These elements have no attributes.
701 @node SPV Structure pageSetup Element
702 @subsection The @code{pageSetup} Element
706 :initial-page-number=int?
707 :chart-size=(as-is | full-height | half-height | quarter-height | OTHER)?
708 :margin-left=dimension?
709 :margin-right=dimension?
710 :margin-top=dimension?
711 :margin-bottom=dimension?
712 :paper-height=dimension?
713 :paper-width=dimension?
714 :reference-orientation?
715 :space-after=dimension?
716 => pageHeader pageFooter
718 pageHeader => pageParagraph?
720 pageFooter => pageParagraph?
722 pageParagraph => pageParagraph_text
725 The @code{pageSetup} element has the following attributes.
727 @defvr {Attribute} @code{initial-page-number}
728 The page number to put on the first page of printed output. Usually
732 @defvr {Attribute} @code{chart-size}
733 One of the listed, self-explanatory chart sizes,
734 @code{quarter-height}, or a localization (!) of one of these (e.g.@:
735 @code{dimensione attuale}, @code{Wie vorgegeben}).
738 @defvr {Attribute} @code{margin-left}
739 @defvrx {Attribute} @code{margin-right}
740 @defvrx {Attribute} @code{margin-top}
741 @defvrx {Attribute} @code{margin-bottom}
742 Margin sizes, e.g.@: @code{0.25in}.
745 @defvr {Attribute} @code{paper-height}
746 @defvrx {Attribute} @code{paper-width}
750 @defvr {Attribute} @code{reference-orientation}
751 Indicates the orientation of the output page. Either @code{0deg}
752 (portrait) or @code{90deg} (landscape),
755 @defvr {Attribute} @code{space-after}
756 The amount of space between printed objects, typically @code{12pt}.
759 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
760 @subsection The @code{text} Element (Inside @code{pageParagraph})
763 text[pageParagraph_text] :type=(title | text) => TEXT
766 This @code{text} element is nested inside a @code{pageParagraph}. There
767 is a different @code{text} element that is nested inside a
770 The element is either empty, or contains CDATA that holds almost-XHTML
771 text: in the corpus, either an @code{html} or @code{p} element. It is
772 @emph{almost}-XHTML because the @code{html} element designates the
774 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of
775 an XHTML namespace, and because the CDATA can contain substitution
776 variables. The following variables are supported:
781 The current date or time in the preferred format for the locale.
787 First-, second-, third-, or fourth-level heading.
793 Name of the output file.
799 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
802 Typical contents (indented for clarity):
805 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
808 <p style="text-align:right; margin-top: 0">Page &[Page]</p>
813 This element has the following attributes.
815 @defvr {Attribute} @code{type}
819 @node SPV Light Detail Member Format
820 @section Light Detail Member Format
822 This section describes the format of ``light'' detail @file{.bin}
823 members. These members have a binary format which we describe here in
824 terms of a context-free grammar using the following conventions:
827 @item NonTerminal @result{} @dots{}
828 Nonterminals have CamelCaps names, and @result{} indicates a
829 production. The right-hand side of a production is often broken
830 across multiple lines. Break points are chosen for aesthetics only
831 and have no semantic significance.
833 @item 00, 01, @dots{}, ff.
834 A bytes with a fixed value, written as a pair of hexadecimal digits.
836 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
837 @itemx ib0, ib1, @dots{}, ib9, ib10, ib11, @dots{}
838 A 32-bit integer in little-endian or big-endian byte order,
839 respectively, with a fixed value, written in decimal. Prefixed by
840 @samp{i} for little-endian or @samp{ib} for big-endian.
846 A byte with value 0 or 1.
850 A 16-bit unsigned integer in little-endian or big-endian byte order,
855 A 32-bit unsigned integer in little-endian or big-endian byte order,
860 A 64-bit unsigned integer in little-endian or big-endian byte order,
864 A 64-bit IEEE floating-point number.
867 A 32-bit IEEE floating-point number.
871 A 32-bit unsigned integer, in little-endian or big-endian byte order,
872 respectively, followed by the specified number of bytes of character
873 data. (The encoding is indicated by the Formats nonterminal.)
876 @var{x} is optional, e.g.@: 00? is an optional zero byte.
878 @item @var{x}*@var{n}
879 @var{x} is repeated @var{n} times, e.g.@: byte*10 for ten arbitrary bytes.
881 @item @var{x}[@var{name}]
882 Gives @var{x} the specified @var{name}. Names are used in textual
883 explanations. They are also used, also bracketed, to indicate counts,
884 e.g.@: @code{int32[n] byte*[n]} for a 32-bit integer followed by the
885 specified number of arbitrary bytes.
887 @item @var{a} @math{|} @var{b}
888 Either @var{a} or @var{b}.
891 Parentheses are used for grouping to make precedence clear, especially
892 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
896 @itemx becount(@var{x})
897 A 32-bit unsigned integer, in little-endian or big-endian byte order,
898 respectively, that indicates the number of bytes in @var{x}, followed
902 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
903 (The @file{.bin} header indicates the version.)
906 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
909 PSPP uses this grammar to parse light detail members. See
910 @file{src/output/spv/light-binary.grammar} in the PSPP source tree for
913 Little-endian byte order is far more common in this format, but a few
914 pieces of the format use big-endian byte order.
916 Light detail members express linear units in two ways: points (pt), at
917 72/inch, and ``device-independent pixels'' (px), at 96/inch. To
918 convert from pt to px, multiply by 1.33 and round up. To convert
919 from px to pt, divide by 1.33 and round down.
921 A ``light'' detail member @file{.bin} consists of a number of sections
922 concatenated together, terminated by an optional byte 01:
926 Header Titles Footnotes
927 Areas Borders PrintSettings TableSettings Formats
928 Dimensions Axes Cells
932 The following sections go into more detail.
935 * SPV Light Member Header::
936 * SPV Light Member Titles::
937 * SPV Light Member Footnotes::
938 * SPV Light Member Areas::
939 * SPV Light Member Borders::
940 * SPV Light Member Print Settings::
941 * SPV Light Member Table Settings::
942 * SPV Light Member Formats::
943 * SPV Light Member Dimensions::
944 * SPV Light Member Categories::
945 * SPV Light Member Axes::
946 * SPV Light Member Cells::
947 * SPV Light Member Value::
948 * SPV Light Member ValueMod::
951 @node SPV Light Member Header
954 An SPV light member begins with a 39-byte header:
959 (i1 @math{|} i3)[version]
962 bool[rotate-inner-column-labels]
963 bool[rotate-outer-row-labels]
966 int32[min-col-width] int32[max-col-width]
967 int32[min-row-width] int32[max-row-width]
971 @code{version} is a version number that affects the interpretation of
972 some of the other data in the member. We will refer to ``version 1''
973 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
974 version-specific formatting (as described previously).
976 If @code{rotate-inner-column-labels} is 1, then column labels closest
977 to the data are rotated to be vertical; otherwise, they are shown
980 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
981 the data are rotated to be vertical; otherwise, they are shown in the
984 @code{table-id} is a binary version of the @code{tableId} attribute in
985 the structure member that refers to the detail member. For example,
986 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
987 would be 0xc6c99d183b300001.
989 @code{min-col-width} is the minimum width that a column will be
990 assigned automatically. @code{max-col-width} is the maximum width
991 that a column will be assigned to accommodate a long column label.
992 @code{min-row-width} and @code{max-row-width} are a similar range for
993 the width of row labels. All of these measurements are in 1/96 inch
994 units (called a ``device independent pixel'' unit in Windows).
996 The meaning of the other variable parts of the header is not known. A
997 writer may safely use version 3, true for @code{x0}, false for
998 @code{x1}, true for @code{x2}, and 0x15 for @code{x3}.
1000 @node SPV Light Member Titles
1006 Value[subtype] 01? 31
1007 Value[user-title] 01?
1008 (31 Value[corner-text] @math{|} 58)
1009 (31 Value[caption] @math{|} 58)
1012 The Titles follow the Header and specify the table's title, caption,
1015 The @code{user-title} is shown above the title and reflects any user
1016 editing of the title text or style. The @code{title} is the title
1017 originally generated by the procedure. Both of these are appropriate
1018 for presentation and localized to the user's language. For example,
1019 for a frequency table, @code{title} and @code{user-title} normally
1020 name the variable and @code{c} is simply ``Frequencies''.
1022 @code{subtype} is the same as the @code{subType} attribute in the
1023 @code{table} structure XML element that referred to this member.
1024 @xref{SPV Structure table Element}, for details.
1026 The @code{corner-text}, if present, is shown in the upper-left corner
1027 of the table, above the row headings and to the left of the column
1028 headings. It is usually absent. Corner text prevents row dimension
1029 labels from being displayed above the dimension's group and category
1030 labels (see @code{show-row-labels-in-corner}).
1032 The @code{caption}, if present, is shown below the table.
1033 @code{caption} reflects user editing of the caption.
1035 @node SPV Light Member Footnotes
1036 @subsection Footnotes
1039 Footnotes => int32[n-footnotes] Footnote*[n-footnotes]
1040 Footnote => Value[text] (58 @math{|} 31 Value[marker]) int32[show]
1043 Each footnote has @code{text} and an optional custom @code{marker}
1046 @code{show} is a 32-bit signed integer. It is positive to show the
1047 footnote or negative to hide it. Its magnitude is often 1, and in
1048 other cases tends to be the number of references to the footnote.
1050 @node SPV Light Member Areas
1057 string[typeface] float[size] int32[style] bool[underline]
1058 int32[halign] int32[valign]
1059 string[fg-color] string[bg-color]
1060 bool[alternate] string[alt-fg-color] string[alt-bg-color]
1061 v3(int32[left-margin] int32[right-margin] int32[top-margin] int32[bottom-margin])
1064 Each Area represents the style for a different area of the table, in
1065 the following order: title, caption, footer, corner, column labels,
1066 row labels, data, and layers.
1068 @code{index} is the 1-based index of the Area, i.e. 1 for the first
1069 Area, through 8 for the final Area.
1071 @code{typeface} is the string name of the font used in the area. In
1072 the corpus, this is @code{SansSerif} in over 99% of instances and
1073 @code{Times New Roman} in the rest.
1075 @code{size} is the size of the font, in px (@pxref{SPV Light Detail
1076 Member Format}) The most common size in the corpus is 12 px. Even
1077 though @code{size} has a floating-point type, in the corpus its values
1078 are always integers.
1080 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
1081 1 (with value 2) is set for italic.
1083 @code{underline} is 1 if the font is underlined, 0 otherwise.
1085 @code{halign} specifies horizontal alignment: 0 for center, 2 for
1086 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
1087 alignment varies according to type: string data is left-justified,
1088 numbers and most other formats are right-justified.
1090 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1093 @code{fg-color} and @code{bg-color} are the foreground color and
1094 background color, respectively. In the corpus, these are always
1095 @code{#000000} and @code{#ffffff}, respectively.
1097 @code{alternate} is 1 if rows should alternate colors, 0 if all rows
1098 should be the same color. When @code{alternate} is 1,
1099 @code{alt-fg-color} and @code{alt-bg-color} specify the colors for the
1100 alternate rows; otherwise they are empty strings.
1102 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1103 @code{bottom-margin} are measured in px.
1105 @node SPV Light Member Borders
1112 be32[n-borders] Border*[n-borders]
1113 bool[show-grid-lines]
1122 The Borders reflect how borders between regions are drawn.
1124 The fixed value of @code{endian} can be used to validate the
1127 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
1129 Each Border describes one kind of border. @code{n-borders} seems to
1130 always be 19. Each @code{border-type} appears once (although in an
1131 unpredictable order) and correspond to the following borders:
1137 Left, top, right, and bottom outer frame.
1139 Left, top, right, and bottom inner frame.
1141 Left and top of data area.
1143 Horizontal and vertical dimension rows.
1145 Horizontal and vertical dimension columns.
1147 Horizontal and vertical category rows.
1149 Horizontal and vertical category columns.
1152 @code{stroke-type} describes how a border is drawn, as one of:
1169 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
1170 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
1171 opaque color, therefore opaque black is 0xff000000.
1173 @node SPV Light Member Print Settings
1174 @subsection Print Settings
1181 bool[paginate-layers]
1184 bool[top-continuation]
1185 bool[bottom-continuation]
1186 be32[n-orphan-lines]
1187 bestring[continuation-string])
1190 The PrintSettings reflect settings for printing. The fixed value of
1191 @code{endian} can be used to validate the endianness.
1193 @code{all-layers} is 1 to print all layers, 0 to print only the
1196 @code{paginate-layers} is 1 to print each layer at the start of a new
1197 page, 0 otherwise. (This setting is honored only @code{all-layers} is
1198 1, since otherwise only one layer is printed.)
1200 @code{fit-width} and @code{fit-length} control whether the table is
1201 shrunk to fit within a page's width or length, respectively.
1203 @code{n-orphan-lines} is the minimum number of rows or columns to put
1204 in one part of a table that is broken across pages.
1206 If @code{top-continuation} is 1, then @code{continuation-string} is
1207 printed at the top of a page when a table is broken across pages for
1208 printing; similarly for @code{bottom-continuation} and the bottom of a
1209 page. Usually, @code{continuation-string} is empty.
1211 @node SPV Light Member Table Settings
1212 @subsection Table Settings
1222 bool[show-row-labels-in-corner]
1223 bool[show-alphabetic-markers]
1224 bool[footnote-marker-superscripts]
1227 Breakpoints[row-breaks] Breakpoints[column-breaks]
1228 Keeps[row-keeps] Keeps[column-keeps]
1229 PointKeeps[row-point-keeps] PointKeeps[column-point-keeps]
1232 bestring[table-look]
1235 Breakpoints => be32[n-breaks] be32*[n-breaks]
1237 Keeps => be32[n-keeps] Keep*[n-keeps]
1238 Keep => be32[offset] be32[n]
1240 PointKeeps => be32[n-point-keeps] PointKeep*[n-point-keeps]
1241 PointKeep => be32[offset] be32 be32
1244 The TableSettings reflect display settings. The fixed value of
1245 @code{endian} can be used to validate the endianness.
1247 @code{current-layer} is the displayed layer. The interpretation when
1248 there is more than one layer dimension is not yet known.
1250 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
1251 any cell) are hidden; otherwise, they are shown.
1253 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
1254 the upper left corner; otherwise, they are shown nested.
1256 If @code{show-alphabetic-markers} is 1, markers are shown as letters
1257 (e.g.@: @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
1258 shown as numbers starting from 1.
1260 When @code{footnote-marker-superscripts} is 1, footnote markers are shown
1261 as superscripts, otherwise as subscripts.
1263 The Breakpoints are rows or columns after which there is a page break;
1264 for example, a row break of 1 requests a page break after the second
1265 row. Usually no breakpoints are specified, indicating that page
1266 breaks should be selected automatically.
1268 The Keeps are ranges of rows or columns to be kept together without a
1269 page break; for example, a row Keep with @code{offset} 1 and @code{n}
1270 10 requests that the 10 rows starting with the second row be kept
1271 together. Usually no Keeps are specified.
1273 The PointKeeps seem to be generated automatically based on
1274 user-specified Keeps. They seems to indicate a conversion from rows
1275 or columns to pixel or point offsets.
1277 @code{notes} is a text string that contains user-specified notes. It
1278 is displayed when the user hovers the cursor over the table, like text
1279 in the @code{title} attribute in HTML. It is not printed. It is
1282 @code{table-look} is the name of a SPSS ``TableLook'' table style,
1283 such as ``Default'' or ``Academic''; it is often empty.
1285 TableSettings ends with an arbitrary number of null bytes. A writer
1286 may safely write 82 null bytes.
1288 A writer may safely use 4 for @code{x5} and 0 for @code{x6}.
1290 @node SPV Light Member Formats
1295 int32[n-widths] int32*[n-widths]
1297 int32[current-layer]
1303 v3(count(X1 count(X2)) count(X3)))
1304 Y0 => int32[epoch] byte[decimal] byte[grouping]
1305 CustomCurrency => int32[n-ccs] string*[n-ccs]
1308 If @code{n-widths} is nonzero, then the accompanying integers are
1309 column widths as manually adjusted by the user.
1311 @code{locale} is a locale including an encoding, such as
1312 @code{en_US.windows-1252} or @code{it_IT.windows-1252}. The rest of
1313 the character strings in the member use this encoding. The encoding
1314 string is itself encoded in US-ASCII.
1316 @code{epoch} is the year that starts the epoch. A 2-digit year is
1317 interpreted as belonging to the 100 years beginning at the epoch. The
1318 default epoch year is 69 years prior to the current year; thus, in
1319 2017 this field by default contains 1948. In the corpus, @code{epoch}
1320 ranges from 1943 to 1948, plus some contain -1.
1322 @code{decimal} is the decimal point character. The observed values
1323 are @samp{.} and @samp{,}.
1325 @code{grouping} is the grouping character. Usually, it is @samp{,} if
1326 @code{decimal} is @samp{.}, and vice versa. Other observed values are
1327 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1328 indicating that digits should not be grouped).
1330 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
1331 following strings are CCA through CCE format strings. @xref{Custom
1332 Currency Formats,,, pspp, PSPP}. Most commonly these are all
1333 @code{-,,,} but other strings occur.
1337 X0 only appears, optionally, in version 1 members.
1342 string[command] string[command-local]
1343 string[language] string[charset] string[locale]
1346 Y2 => CustomCurrency byte[missing] bool[x17]
1349 @code{command} describes the statistical procedure that generated the
1350 output, in English. It is not necessarily the literal syntax name of
1351 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1352 Tests.'' @code{command-local} is the procedure's name, translated
1353 into the output language; it is often empty and, when it is not,
1354 sometimes the same as @code{command}.
1356 @code{dataset} is the name of the dataset analyzed to produce the
1357 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1358 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}. The latter
1359 is sometimes the empty string.
1361 @code{missing} is the character used to indicate that a cell contains
1362 a missing value. It is always observed as @samp{.}.
1364 X0 repeats @code{decimal}, @code{grouping}, CustomCurrency, and
1365 @code{missing} already included in Formats.
1367 A writer may safely use false for @code{x17}.
1371 X1 only appears in version 3 members.
1375 bool byte[x15] bool[x16]
1377 byte[show-variables]
1379 int32[x18] int32[x19]
1385 @code{lang} may indicate the language in use. Some values seem to be
1386 0: @t{en}, 1: @t{de}, 2: @t{es}, 3: @t{it}, 5: @t{ko}, 6: @t{pl}, 8:
1387 @t{zh-tw}, 10: @t{pt_BR}, 11: @t{fr}. The @code{locale} in Formats
1388 and the @code{language}, @code{charset}, and @code{locale} in X0 are
1389 more likely to be useful in practice.
1391 @code{show-variables} determines how variables are displayed by
1392 default. A value of 1 means to display variable names, 2 to display
1393 variable labels when available, 3 to display both (name followed by
1394 label, separated by a space). The most common value is 0, which
1395 probably means to use a global default.
1397 @code{show-values} is a similar setting for values. A value of 1
1398 means to display the value, 2 to display the value label when
1399 available, 3 to display both. Again, the most common value is 0,
1400 which probably means to use a global default.
1402 @code{show-caption} is true to show the caption, false to hide it.
1404 A writer may safely use false for @code{x14}, 1 for @code{x15}, false
1405 for @code{x16}, -1 for @code{x18} and @code{x19}, and false for
1410 X2 only appears in version 3 members.
1414 int32[n-row-heights] int32*[n-row-heights]
1415 int32[n-style-map] StyleMap*[n-style-map]
1416 int32[n-styles] StylePair*[n-styles]
1418 StyleMap => int64[cell-index] int16[style-index]
1421 If present, @code{n-row-heights} and the accompanying integers are row
1422 heights as manually adjusted by the user.
1424 The rest of X2 specifies styles for data cells. At first glance this
1425 is odd, because each data cell can have its own style embedded as part
1426 of the data, but in practice X2 specifies a style for a cell only if
1427 that cell is empty (and thus does not appear in the data at all).
1428 Each StyleMap specifies the index of a blank cell, calculated the same
1429 was as in the Cells (@pxref{SPV Light Member Cells}), along with a
1430 0-based index into the accompanying StylePair array.
1432 A writer may safely omit the optional @code{i0 i0} inside the
1433 @code{count(@dots{})}.
1437 X3 only appears in version 3 members.
1441 01 00 byte[x21] 00 00 00
1444 (string[dataset] string[datafile] i0 int32[date] i0)?
1449 @code{date} is a date, as seconds since the epoch, i.e.@: since
1450 January 1, 1970. Pivot tables within an SPV file often have dates a
1451 few minutes apart, so this is probably a creation date for the table
1452 rather than for the file.
1454 X3 repeats @code{decimal}, @code{grouping}, CustomCurrency, and
1455 @code{missing} already included in Formats. @code{command},
1456 @code{command-local}, @code{language}, @code{charset}, and
1457 @code{locale} have the same meaning as in X0.
1459 @code{small} is a small real number, e.g.@: .001. Numbers smaller
1460 than this in absolute value are displayed in scientific notation.
1462 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1463 and other times they are absent. The reader can distinguish by
1464 assuming that they are present and then checking whether the
1465 presumptive @code{dataset} contains a null byte (a valid string never
1468 @code{x22} is usually 0 or 2000000.
1470 A writer may safely use 4 for @code{x21} and omit @code{x22} and the
1471 other optional bytes at the end.
1473 @node SPV Light Member Dimensions
1474 @subsection Dimensions
1476 A pivot table presents multidimensional data. A Dimension identifies
1477 the categories associated with each dimension.
1480 Dimensions => int32[n-dims] Dimension*[n-dims]
1482 Value[name] DimProperties
1483 int32[n-categories] Category*[n-categories]
1488 bool[hide-dim-label]
1489 bool[hide-all-labels]
1493 @code{name} is the name of the dimension, e.g.@: @code{Variables},
1494 @code{Statistics}, or a variable name.
1496 The meanings of @code{x1} and @code{x3} are unknown. @code{x1} is
1497 usually 0 but many other values have been observed. A writer may
1498 safely use 0 for @code{x1} and 2 for @code{x3}.
1500 @code{x2} is 0, 1, or 2. For a pivot table with @var{L} layer
1501 dimensions, @var{R} row dimensions, and @var{C} column dimensions,
1502 @code{x2} is 2 for the first @var{L} dimensions, 0 for the next
1503 @var{R} dimensions, and 1 for the remaining @var{C} dimensions. This
1504 does not mean that the layer dimensions must be presented first,
1505 followed by the row dimensions, followed by the column dimensions---on
1506 the contrary, they are frequently in a different order---but @code{x2}
1507 must follow this pattern to prevent the pivot table from being
1510 If @code{hide-dim-label} is 00, the pivot table displays a label for
1511 the dimension itself. Because usually the group and category labels
1512 are enough explanation, it is usually 01.
1514 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1515 the dimension, including group and category labels. It is usually 00.
1516 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1518 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1519 0 for the first dimension, 1 for the second, and so on. Sometimes it
1520 is -1. There is no visible difference.
1522 @node SPV Light Member Categories
1523 @subsection Categories
1525 Categories are arranged in a tree. Only the leaf nodes in the tree
1526 are really categories; the others just serve as grouping constructs.
1529 Category => Value[name] (Leaf @math{|} Group)
1530 Leaf => 00 00 00 i2 int32[leaf-index] i0
1532 bool[merge] 00 01 int32[x23]
1533 i-1 int32[n-subcategories] Category*[n-subcategories]
1536 @code{name} is the name of the category (or group).
1538 A Leaf represents a leaf category. The Leaf's @code{leaf-index} is a
1539 nonnegative integer unique within the Dimension and less than
1540 @code{n-categories} in the Dimension. If the user does not sort or
1541 rearrange the categories, then @code{leaf-index} starts at 0 for the
1542 first Leaf in the dimension and increments by 1 with each successive
1543 Leaf. If the user does sorts or rearrange the categories, then the
1544 order of categories in the file reflects that change and
1545 @code{leaf-index} reflects the original order.
1547 Occasionally a dimension has no leaf categories at all. A table that
1548 contains such a dimension necessarily has no data at all.
1550 A Group is a group of nested categories. Usually a Group contains at
1551 least one Category, so that @code{n-subcategories} is positive, but a
1552 few Groups with @code{n-subcategories} 0 has been observed.
1554 If a Group's @code{merge} is 00, the most common value, then the group
1555 is really a distinct group that should be represented as such in the
1556 visual representation and user interface. If @code{merge} is 01, the
1557 categories in this group should be shown and treated as if they were
1558 direct children of the group's containing group (or if it has no
1559 parent group, then direct children of the dimension), and this group's
1560 name is irrelevant and should not be displayed. (Merged groups can be
1563 (For writing an SPV file, there is no need to use the @code{merge}
1564 feature unless it is convenient.)
1566 A Group's @code{x23} appears to be i2 when all of the categories
1567 within a group are leaf categories that directly represent data values
1568 for a variable (e.g.@: in a frequency table or crosstabulation, a group
1569 of values in a variable being tabulated) and i0 otherwise. A writer
1570 may safely write a constant 0 in this field.
1572 @node SPV Light Member Axes
1575 After the dimensions come assignment of each dimension to one of the
1576 axes: layers, rows, and columns.
1580 int32[n-layers] int32[n-rows] int32[n-columns]
1581 int32*[n-layers] int32*[n-rows] int32*[n-columns]
1584 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1585 each specifies the number of dimensions displayed in layers, rows, and
1586 columns, respectively. Any of them may be zero. Their values sum to
1587 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1590 The following @code{n-dimensions} integers, in three groups, are a
1591 permutation of the 0-based dimension numbers. The first
1592 @code{n-layers} integers specify each of the dimensions represented by
1593 layers, the next @code{n-rows} integers specify the dimensions
1594 represented by rows, and the final @code{n-columns} integers specify
1595 the dimensions represented by columns. When there is more than one
1596 dimension of a given kind, the inner dimensions are given first.
1598 @node SPV Light Member Cells
1601 The final part of an SPV light member contains the actual data.
1604 Cells => int32[n-cells] Cell*[n-cells]
1605 Cell => int64[index] v1(00?) Value
1608 A Cell consists of an @code{index} and a Value. Suppose there are
1609 @math{d} dimensions, numbered 1 through @math{d} in the order given in
1610 the Dimensions previously, and that dimension @math{i}, has @math{n_i}
1611 categories. Consider the cell at coordinates @math{x_i}, @math{1 \le
1612 i \le d}, and note that @math{0 \le x_i < n_i}. Then the index is
1613 calculated by the following algorithm:
1617 for each @math{i} from 1 to @math{d}:
1618 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1621 For example, suppose there are 3 dimensions with 3, 4, and 5
1622 categories, respectively. The cell at coordinates (1, 2, 3) has
1623 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1624 Within a given dimension, the index is the @code{leaf-index} in a Leaf.
1626 @node SPV Light Member Value
1629 Value is used throughout the SPV light member format. It boils down
1630 to a number or a string.
1633 Value => 00? 00? 00? 00? RawValue
1635 01 ValueMod int32[format] double[x]
1636 @math{|} 02 ValueMod int32[format] double[x]
1637 string[var-name] string[value-label] byte[show]
1638 @math{|} 03 string[local] ValueMod string[id] string[c] bool[fixed]
1639 @math{|} 04 ValueMod int32[format] string[value-label] string[var-name]
1640 byte[show] string[s]
1641 @math{|} 05 ValueMod string[var-name] string[var-label] byte[show]
1642 @math{|} ValueMod string[template] int32[n-args] Argument*[n-args]
1645 @math{|} int32[x] i0 Value*[x] /* x > 0 */
1648 There are several possible encodings, which one can distinguish by the
1649 first nonzero byte in the encoding.
1653 The numeric value @code{x}, intended to be presented to the user
1654 formatted according to @code{format}, which is in the format described
1655 for system files, except that format 40 is a synonym for F format
1656 instead of MTIME. @xref{System File Output Formats}, for details.
1657 Most commonly, @code{format} has width 40 (the maximum).
1659 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1660 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1661 not been observed.) @xref{System File Format}, for more about these
1665 Similar to @code{01}, with the additional information that @code{x} is
1666 a value of variable @code{var-name} and has value label
1667 @code{value-label}. Both @code{var-name} and @code{value-label} can
1668 be the empty string, the latter very commonly.
1670 @code{show} determines whether to show the numeric value or the value
1671 label. A value of 1 means to show the value, 2 to show the label, 3
1672 to show both, and 0 means to use the default specified in
1673 @code{show-values} (@pxref{SPV Light Member Formats}).
1676 A text string, in two forms: @code{c} is in English, and sometimes
1677 abbreviated or obscure, and @code{local} is localized to the user's
1678 locale. In an English-language locale, the two strings are often the
1679 same, and in the cases where they differ, @code{local} is more
1680 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1681 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1682 where P must be greater than 1.''
1684 @code{c} and @code{local} are always either both empty or both
1687 @code{id} is a brief identifying string whose form seems to resemble a
1688 programming language identifier, e.g.@: @code{cumulative_percent} or
1689 @code{factor_14}. It is not unique.
1691 @code{fixed} is 00 for text taken from user input, such as syntax
1692 fragment, expressions, file names, data set names, and 01 for fixed
1693 text strings such as names of procedures or statistics. In the former
1694 case, @code{id} is always the empty string; in the latter case,
1695 @code{id} is still sometimes empty.
1698 The string value @code{s}, intended to be presented to the user
1699 formatted according to @code{format}. The format for a string is not
1700 too interesting, and the corpus contains many clearly invalid formats
1701 like A16.39 or A255.127 or A134.1, so readers should probably ignore
1702 the format entirely.
1704 @code{s} is a value of variable @code{var-name} and has value label
1705 @code{value-label}. @code{var-name} is never empty but
1706 @code{value-label} is commonly empty.
1708 @code{show} has the same meaning as in the encoding for 02.
1711 Variable @code{var-name}, which is rarely observed as empty in the
1712 corpus, with variable label @code{var-label}, which is often empty.
1714 @code{show} determines whether to show the variable name or the
1715 variable label. A value of 1 means to show the name, 2 to show the
1716 label, 3 to show both, and 0 means to use the default specified in
1717 @code{show-variables} (@pxref{SPV Light Member Formats}).
1720 When the first byte of a RawValue is not one of the above, the
1721 RawValue starts with a ValueMod, whose syntax is described in the next
1722 section. (A ValueMod always begins with byte 31 or 58.)
1724 This case is a template string, analogous to @code{printf}, followed
1725 by one or more Arguments, each of which has one or more values. The
1726 template string is copied directly into the output except for the
1727 following special syntax,
1734 Each of these expands to the character following @samp{\\}, to escape
1735 characters that have special meaning in template strings. These are
1736 effective inside and outside the @code{[@dots{}]} syntax forms
1740 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1744 Expands to a formatted version of argument @var{i}, which must have
1745 only a single value. For example, @code{^1} expands to the first
1746 argument's @code{value}.
1748 @item [:@var{a}:]@var{i}
1749 Expands @var{a} for each of the values in @var{i}. @var{a}
1750 should contain one or more @code{^@var{j}} conversions, which are
1751 drawn from the values for argument @var{i} in order. Some examples
1756 All of the values for the first argument, concatenated.
1759 Expands to the values for the first argument, each followed by
1763 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1764 argument's first value and @var{y} is its second value. (This would
1765 be used only if the argument has two values. If there were more
1766 values, the second and third values would be directly concatenated,
1767 which would look funny.)
1770 @item [@var{a}:@var{b}:]@var{i}
1771 This extends the previous form so that the first values are expanded
1772 using @var{a} and later values are expanded using @var{b}. For an
1773 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1774 instead written as @code{%@var{j}}. Some examples from the corpus:
1778 Expands to all of the values for the first argument, separated by
1781 @item [%1 = %2:, ^1 = ^2:]1
1782 Given appropriate values for the first argument, expands to @code{X =
1786 Given appropriate values, expands to @code{1, 2, 3}.
1790 The template string is localized to the user's locale.
1793 A writer may safely omit all of the optional 00 bytes at the beginning
1794 of a Value, except that it should write a single 00 byte before a
1797 @node SPV Light Member ValueMod
1798 @subsection ValueMod
1800 A ValueMod can specify special modifications to a Value.
1806 int32[n-refs] int16*[n-refs]
1807 int32[n-subscripts] string*[n-subscripts]
1808 v1(00 (i1 | i2) 00? 00? int32 00? 00?)
1809 v3(count(TemplateString StylePair))
1811 TemplateString => count((count((i0 (58 @math{|} 31 55))?) (58 @math{|} 31 string[id]))?)
1818 bool[bold] bool[italic] bool[underline] bool[show]
1819 string[fg-color] string[bg-color]
1820 string[typeface] byte[size]
1823 int32[halign] int32[valign] double[decimal-offset]
1824 int16[left-margin] int16[right-margin]
1825 int16[top-margin] int16[bottom-margin]
1828 A ValueMod that begins with ``31'' specifies special modifications to
1831 Each of the @code{n-refs} integers is a reference to a Footnote
1832 (@pxref{SPV Light Member Footnotes}) by 0-based index. Footnote
1833 markers are shown appended to the main text of the Value, as
1836 The @code{subscripts}, if present, are strings to append to the main
1837 text of the Value, as subscripts. Each subscript text is a brief
1838 indicator, e.g.@: @samp{a} or @samp{b}, with its meaning indicated by
1839 the table caption. When multiple subscripts are present, they are
1840 displayed separated by commas.
1842 The @code{id} inside the TemplateString, if present, is a template
1843 string for substitutions using the syntax explained previously. It
1844 appears to be an English-language version of the localized template
1845 string in the Value in which the Template is nested. A writer may
1846 safely omit the optional fixed data in TemplateString.
1848 FontStyle and CellStyle, if present, change the style for this
1849 individual Value. In FontStyle, @code{bold}, @code{italic}, and
1850 @code{underline} control the particular style. @code{show} is
1851 ordinarily 1; if it is 0, then the cell data is not shown.
1852 @code{fg-color} and @code{bg-color} are strings in the format
1853 @code{#rrggbb}, e.g.@: @code{#ff0000} for red or @code{#ffffff} for
1854 white. The empty string is occasionally observed also. The
1855 @code{size} is a font size in units of 1/128 inch.
1857 In CellStyle, @code{halign} is 0 for center, 2 for left, 4 for right,
1858 6 for decimal, 0xffffffad for mixed. For decimal alignment,
1859 @code{decimal-offset} is the decimal point's offset from the right
1860 side of the cell, in pt (@pxref{SPV Light Detail Member Format}).
1861 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1862 for bottom. @code{left-margin}, @code{right-margin},
1863 @code{top-margin}, and @code{bottom-margin} are in pt.
1865 @node SPV Legacy Detail Member Binary Format
1866 @section Legacy Detail Member Binary Format
1868 Whereas the light binary format represents everything about a given
1869 pivot table, the legacy binary format conceptually consists of a
1870 number of named sources, each of which consists of a number of named
1871 variables, each of which is a 1-dimensional array of numbers or
1872 strings or a mix. Thus, the legacy binary member format is quite
1875 This section uses the same context-free grammar notation as in the
1876 previous section, with the following additions:
1880 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
1881 (The legacy member header indicates the version; see below.)
1884 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
1887 A legacy detail member @file{.bin} has the following overall format:
1891 00 byte[version] int16[n-sources] int32[member-size]
1892 Metadata*[n-sources]
1897 @code{version} is a version number that affects the interpretation of
1898 some of the other data in the member. Versions 0xaf and 0xb0 are
1899 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
1902 A legacy member consists of @code{n-sources} data sources, each of
1903 which has Metadata and Data.
1905 @code{member-size} is the size of the legacy binary member, in bytes.
1907 The Data and Strings above are commented out because the Metadata has
1908 some oddities that mean that the Data sometimes seems to start at
1909 an unexpected place. The following section goes into detail.
1912 * SPV Legacy Member Metadata::
1913 * SPV Legacy Member Numeric Data::
1914 * SPV Legacy Member String Data::
1917 @node SPV Legacy Member Metadata
1918 @subsection Metadata
1922 int32[n-values] int32[n-variables] int32[data-offset]
1923 vAF(byte*28[source-name])
1924 vB0(byte*64[source-name] int32[x])
1927 A data source has @code{n-variables} variables, each with
1928 @code{n-values} data values.
1930 @code{source-name} is a 28- or 64-byte string padded on the right with
1931 0-bytes. The names that appear in the corpus are very generic:
1932 usually @code{tableData} for pivot table data or @code{source0} for
1935 A given Metadata's @code{data-offset} is the offset, in bytes, from
1936 the beginning of the member to the start of the corresponding Data.
1937 This allows programs to skip to the beginning of the data for a
1938 particular source. In every case in the corpus, the Data follow the
1939 Metadata in the same order, but it is important to use
1940 @code{data-offset} instead of reading sequentially through the file
1941 because of the exception described below.
1943 One SPV file in the corpus has legacy binary members with version 0xb0
1944 but a 28-byte @code{source-name} field (and only a single source). In
1945 practice, this means that the 64-byte @code{source-name} used in
1946 version 0xb0 has a lot of 0-bytes in the middle followed by the
1947 @code{variable-name} of the following Data. As long as a reader
1948 treats the first 0-byte in the @code{source-name} as terminating the
1949 string, it can properly interpret these members.
1951 The meaning of @code{x} in version 0xb0 is unknown.
1953 @node SPV Legacy Member Numeric Data
1954 @subsection Numeric Data
1957 Data => Variable*[n-variables]
1958 Variable => byte*288[variable-name] double*[n-values]
1961 Data follow the Metadata in the legacy binary format, with sources in
1962 the same order (but readers should use the @code{data-offset} in
1963 Metadata records, rather than reading sequentially). Each Variable
1964 begins with a @code{variable-name} that generally indicates its role
1965 in the pivot table, e.g.@: ``cell'', ``cellFormat'',
1966 ``dimension0categories'', ``dimension0group0'', followed by the
1967 numeric data, one double per datum. A double with the maximum
1968 negative double @code{-DBL_MAX} represents the system-missing value
1971 @node SPV Legacy Member String Data
1972 @subsection String Data
1975 Strings => SourceMaps[maps] Labels
1977 SourceMaps => int32[n-maps] SourceMap*[n-maps]
1979 SourceMap => string[source-name] int32[n-variables] VariableMap*[n-variables]
1980 VariableMap => string[variable-name] int32[n-data] DatumMap*[n-data]
1981 DatumMap => int32[value-idx] int32[label-idx]
1983 Labels => int32[n-labels] Label*[n-labels]
1984 Label => int32[frequency] string[label]
1987 Each variable may include a mix of numeric and string data values. If
1988 a legacy binary member contains any string data, Strings is present;
1989 otherwise, it ends just after the last Data element.
1991 The string data overlays the numeric data. When a variable includes
1992 any string data, its Variable represents the string values with a
1993 SYSMIS or NaN placeholder. (Not all such values need be
1996 Each SourceMap provides a mapping between SYSMIS or NaN values in source
1997 @code{source-name} and the string data that they represent.
1998 @code{n-variables} is the number of variables in the source that
1999 include string data. More precisely, it is the 1-based index of the
2000 last variable in the source that includes any string data; thus, it
2001 would be 4 if there are 5 variables and only the fourth one includes
2004 A VariableMap repeats its variable's name, but variables are always
2005 present in the same order as the source, starting from the first
2006 variable, without skipping any even if they have no string values.
2007 Each VariableMap contains DatumMap nonterminals, each of which maps
2008 from a 0-based index within its variable's data to a 0-based label
2009 index, e.g.@: pair @code{value-idx} = 2, @code{label-idx} = 3, means
2010 that the third data value (which must be SYSMIS or NaN) is to be
2011 replaced by the string of the fourth Label.
2013 The labels themselves follow the pairs. The valuable part of each
2014 label is the string @code{label}. Each label also includes a
2015 @code{frequency} that reports the number of DatumMaps that reference
2016 it (although this is not useful).
2018 @node SPV Legacy Detail Member XML Format
2019 @section Legacy Detail Member XML Format
2021 The design of the detail XML format is not what one would end up with
2022 for describing pivot tables. This is because it is a special case
2023 of a much more general format (``visualization XML'' or ``VizML'')
2024 that can describe a wide range of visualizations. Most of this
2025 generality is overkill for tables, and so we end up with a funny
2026 subset of a general-purpose format.
2028 An XML Schema for VizML is available, distributed with SPSS binaries,
2029 under a nonfree license. It contains documentation that is
2030 occasionally helpful.
2032 This section describes the detail XML format using the same notation
2033 already used for the structure XML format (@pxref{SPV Structure Member
2034 Format}). See @file{src/output/spv/detail-xml.grammar} in the PSPP
2035 source tree for the full grammar that it uses for parsing.
2037 The important elements of the detail XML format are:
2041 Variables. @xref{SPV Detail Variable Elements}.
2044 Assignment of variables to axes. A variable can appear as columns, or
2045 rows, or layers. The @code{faceting} element and its sub-elements
2046 describe this assignment.
2049 Styles and other annotations.
2052 This description is not detailed enough to write legacy tables.
2053 Instead, write tables in the light binary format.
2056 * SPV Detail visualization Element::
2057 * SPV Detail Variable Elements::
2058 * SPV Detail extension Element::
2059 * SPV Detail graph Element::
2060 * SPV Detail location Element::
2061 * SPV Detail faceting Element::
2062 * SPV Detail facetLayout Element::
2063 * SPV Detail label Element::
2064 * SPV Detail setCellProperties Element::
2065 * SPV Detail setFormat Element::
2066 * SPV Detail interval Element::
2067 * SPV Detail style Element::
2068 * SPV Detail labelFrame Element::
2069 * SPV Detail Legacy Properties::
2072 @node SPV Detail visualization Element
2073 @subsection The @code{visualization} Element
2081 :style[style_ref]=ref style
2085 => visualization_extension?
2087 (sourceVariable | derivedVariable)+
2096 extension[visualization_extension]
2099 :minWidthSet=(true)?
2100 :maxWidthSet=(true)?
2103 userSource :missing=(listwise | pairwise)? => EMPTY
2105 categoricalDomain => variableReference simpleSort
2107 simpleSort :method[sort_method]=(custom) => categoryOrder
2109 container :style=ref style => container_extension? location+ labelFrame*
2111 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2119 The @code{visualization} element is the root of detail XML member. It
2120 has the following attributes:
2122 @defvr {Attribute} creator
2123 The version of the software that created this SPV file, as a string of
2124 the form @code{xxyyzz}, which represents software version xx.yy.zz,
2125 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
2126 versions 16 through 19.
2129 @defvr {Attribute} date
2130 The date on the which the file was created, as a string of the form
2134 @defvr {Attribute} lang
2135 The locale used for output, in Windows format, which is similar to the
2136 format used in Unix with the underscore replaced by a hyphen, e.g.@:
2137 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
2140 @defvr {Attribute} name
2141 The title of the pivot table, localized to the output language.
2144 @defvr {Attribute} style
2145 The base style for the pivot table. In every example in the corpus,
2146 the @code{style} element has no attributes other than @code{id}.
2149 @defvr {Attribute} type
2150 A floating-point number. The meaning is unknown.
2153 @defvr {Attribute} version
2154 The visualization schema version number. In the corpus, the value is
2155 one of 2.4, 2.5, 2.7, and 2.8.
2158 The @code{userSource} element has no visible effect.
2160 The @code{extension} element as a child of @code{visualization} has
2161 the following attributes.
2163 @defvr {Attribute} numRows
2164 An integer that presumably defines the number of rows in the displayed
2168 @defvr {Attribute} showGridline
2169 Always set to @code{false} in the corpus.
2172 @defvr {Attribute} minWidthSet
2173 @defvrx {Attribute} maxWidthSet
2174 Always set to @code{true} in the corpus.
2177 The @code{extension} element as a child of @code{container} has the
2180 @defvr {Attribute} combinedFootnotes
2184 The @code{categoricalDomain} and @code{simpleSort} elements have no
2187 The @code{layerController} element has no visible effect.
2189 @node SPV Detail Variable Elements
2190 @subsection Variable Elements
2192 A ``variable'' in detail XML is a 1-dimensional array of data. Each
2193 element of the array may, independently, have string or numeric
2194 content. All of the variables in a given detail XML member either
2195 have the same number of elements or have zero elements.
2197 Two different elements define variables and their content:
2200 @item sourceVariable
2201 These variables' data comes from the associated @code{tableData.bin}
2204 @item derivedVariable
2205 These variables are defined in terms of a mapping function from a
2206 source variable, or they are empty.
2209 A variable named @code{cell} always exists. This variable holds the
2210 data displayed in the table.
2212 Variables in detail XML roughly correspond to the dimensions in a
2213 light detail member. Each dimension has the following variables with
2214 stylized names, where @var{n} is a number for the dimension starting
2218 @item dimension@var{n}categories
2219 The dimension's leaf categories (@pxref{SPV Light Member Categories}).
2221 @item dimension@var{n}group0
2222 Present only if the dimension's categories are grouped, this variable
2223 holds the group labels for the categories. Grouping is inferred
2224 through adjacent identical labels. Categories that are not part of a
2225 group have empty-string data in this variable.
2227 @item dimension@var{n}group1
2228 Present only if the first-level groups are further grouped, this
2229 variable holds the labels for the second-level groups. There can be
2230 additional variables with further levels of grouping.
2232 @item dimension@var{n}
2236 Determining the data for a (non-empty) variable is a multi-step
2241 Draw initial data from its source, for a @code{sourceVariable}, or
2242 from another named variable, for a @code{derivedVariable}.
2245 Apply mappings from @code{valueMapEntry} elements within the
2246 @code{derivedVariable} element, if any.
2249 Apply mappings from @code{relabel} elements within a @code{format} or
2250 @code{stringFormat} element in the @code{sourceVariable} or
2251 @code{derivedVariable} element, if any.
2254 If the variable is a @code{sourceVariable} with a @code{labelVariable}
2255 attribute, and there were no mappings to apply in previous steps, then
2256 replace each element of the variable by the corresponding value in the
2260 A single variable's data can be modified in two of the steps, if both
2261 @code{valueMapEntry} and @code{relabel} are used. The following
2262 example from the corpus maps several integers to 2, then maps 2 in
2263 turn to the string ``Input'':
2266 <derivedVariable categorical="true" dependsOn="dimension0categories"
2267 id="dimension0group0map" value="map(dimension0group0)">
2269 <relabel from="2" to="Input"/>
2270 <relabel from="10" to="Missing Value Handling"/>
2271 <relabel from="14" to="Resources"/>
2272 <relabel from="0" to=""/>
2273 <relabel from="1" to=""/>
2274 <relabel from="13" to=""/>
2276 <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
2277 <valueMapEntry from="10;11" to="10"/>
2278 <valueMapEntry from="14;15" to="14"/>
2279 <valueMapEntry from="0" to="0"/>
2280 <valueMapEntry from="1" to="1"/>
2281 <valueMapEntry from="13" to="13"/>
2286 * SPV Detail sourceVariable Element::
2287 * SPV Detail derivedVariable Element::
2288 * SPV Detail valueMapEntry Element::
2291 @node SPV Detail sourceVariable Element
2292 @subsubsection The @code{sourceVariable} Element
2299 :domain=ref categoricalDomain?
2301 :dependsOn=ref sourceVariable?
2303 :labelVariable=ref sourceVariable?
2304 => variable_extension* (format | stringFormat)?
2307 This element defines a variable whose data comes from the
2308 @file{tableData.bin} member that corresponds to this @file{.xml}.
2310 This element has the following attributes.
2312 @defvr {Attribute} id
2313 An @code{id} is always present because this element exists to be
2314 referenced from other elements.
2317 @defvr {Attribute} categorical
2318 Always set to @code{true}.
2321 @defvr {Attribute} source
2322 Always set to @code{tableData}, the @code{source-name} in the
2323 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
2327 @defvr {Attribute} sourceName
2328 The name of a variable within the source, corresponding to the
2329 @code{variable-name} in the @file{tableData.bin} member (@pxref{SPV
2330 Legacy Member Numeric Data}).
2333 @defvr {Attribute} label
2334 The variable label, if any.
2337 @defvr {Attribute} labelVariable
2338 The @code{variable-name} of a variable whose string values correspond
2339 one-to-one with the values of this variable and are suitable for use
2343 @defvr {Attribute} dependsOn
2344 This attribute doesn't affect the display of a table.
2347 @node SPV Detail derivedVariable Element
2348 @subsubsection The @code{derivedVariable} Element
2355 :dependsOn=ref sourceVariable?
2356 => variable_extension* (format | stringFormat)? valueMapEntry*
2359 Like @code{sourceVariable}, this element defines a variable whose
2360 values can be used elsewhere in the visualization. Instead of being
2361 read from a data source, the variable's data are defined by a
2362 mathematical expression.
2364 This element has the following attributes.
2366 @defvr {Attribute} id
2367 An @code{id} is always present because this element exists to be
2368 referenced from other elements.
2371 @defvr {Attribute} categorical
2372 Always set to @code{true}.
2375 @defvr {Attribute} value
2376 An expression that defines the variable's value. In theory this could
2377 be an arbitrary expression in terms of constants, functions, and other
2378 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
2379 the corpus contains only the following forms of expressions:
2383 @itemx constant(@var{variable})
2384 All zeros. The reason why a variable is sometimes named is unknown.
2385 Sometimes the ``variable name'' has spaces in it.
2387 @item map(@var{variable})
2388 Transforms the values in the named @var{variable} using the
2389 @code{valueMapEntry}s contained within the element.
2393 @defvr {Attribute} dependsOn
2394 This attribute doesn't affect the display of a table.
2397 @node SPV Detail valueMapEntry Element
2398 @subsubsection The @code{valueMapEntry} Element
2401 valueMapEntry :from :to => EMPTY
2404 A @code{valueMapEntry} element defines a mapping from one or more
2405 values of a source expression to a target value. (In the corpus, the
2406 source expression is always just the name of a variable.) Each target
2407 value requires a separate @code{valueMapEntry}. If multiple source
2408 values map to the same target value, they can be combined or separate.
2410 In the corpus, all of the source and target values are integers.
2412 @code{valueMapEntry} has the following attributes.
2414 @defvr {Attribute} from
2415 A source value, or multiple source values separated by semicolons,
2416 e.g.@: @code{0} or @code{13;14;15;16}.
2419 @defvr {Attribute} to
2420 The target value, e.g.@: @code{0}.
2423 @node SPV Detail extension Element
2424 @subsection The @code{extension} Element
2426 This is a general-purpose ``extension'' element. Readers that don't
2427 understand a given extension should be able to safely ignore it. The
2428 attributes on this element, and their meanings, vary based on the
2429 context. Each known usage is described separately below. The current
2430 extensions use attributes exclusively, without any nested elements.
2432 @subsubheading @code{container} Parent Element
2435 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2438 With @code{container} as its parent element, @code{extension} has the
2439 following attributes.
2441 @defvr {Attribute} combinedFootnotes
2442 Always set to @code{true} in the corpus.
2445 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
2448 extension[variable_extension] :from :helpId => EMPTY
2451 With @code{sourceVariable} or @code{derivedVariable} as its parent
2452 element, @code{extension} has the following attributes. A given
2453 parent element often contains several @code{extension} elements that
2454 specify the meaning of the source data's variables or sources, e.g.@:
2457 <extension from="0" helpId="corrected_model"/>
2458 <extension from="3" helpId="error"/>
2459 <extension from="4" helpId="total_9"/>
2460 <extension from="5" helpId="corrected_total"/>
2463 More commonly they are less helpful, e.g.@:
2466 <extension from="0" helpId="notes"/>
2467 <extension from="1" helpId="notes"/>
2468 <extension from="2" helpId="notes"/>
2469 <extension from="5" helpId="notes"/>
2470 <extension from="6" helpId="notes"/>
2471 <extension from="7" helpId="notes"/>
2472 <extension from="8" helpId="notes"/>
2473 <extension from="12" helpId="notes"/>
2474 <extension from="13" helpId="no_help"/>
2475 <extension from="14" helpId="notes"/>
2478 @defvr {Attribute} from
2479 An integer or a name like ``dimension0''.
2482 @defvr {Attribute} helpId
2486 @node SPV Detail graph Element
2487 @subsection The @code{graph} Element
2491 :cellStyle=ref style
2493 => location+ coordinates faceting facetLayout interval
2495 coordinates => EMPTY
2498 @code{graph} has the following attributes.
2500 @defvr {Attribute} cellStyle
2501 @defvrx {Attribute} style
2502 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
2503 Detail style Element}). The former is the default style for
2504 individual cells, the latter for the entire table.
2507 @node SPV Detail location Element
2508 @subsection The @code{location} Element
2512 :part=(height | width | top | bottom | left | right)
2513 :method=(sizeToContent | attach | fixed | same)
2516 :target=ref (labelFrame | graph | container)?
2521 Each instance of this element specifies where some part of the table
2522 frame is located. All the examples in the corpus have four instances
2523 of this element, one for each of the parts @code{height},
2524 @code{width}, @code{left}, and @code{top}. Some examples in the
2525 corpus add a fifth for part @code{bottom}, even though it is not clear
2526 how all of @code{top}, @code{bottom}, and @code{height} can be honored
2527 at the same time. In any case, @code{location} seems to have little
2528 importance in representing tables; a reader can safely ignore it.
2530 @defvr {Attribute} part
2531 The part of the table being located.
2534 @defvr {Attribute} method
2535 How the location is determined:
2539 Based on the natural size of the table. Observed only for
2540 parts @code{height} and @code{width}.
2543 Based on the location specified in @code{target}. Observed only for
2544 parts @code{top} and @code{bottom}.
2547 Using the value in @code{value}. Observed only for parts @code{top},
2548 @code{bottom}, and @code{left}.
2551 Same as the specified @code{target}. Observed only for part
2556 @defvr {Attribute} min
2557 Minimum size. Only observed with value @code{100pt}. Only observed
2558 for part @code{width}.
2561 @defvr {Dependent} target
2562 Required when @code{method} is @code{attach} or @code{same}, not
2563 observed otherwise. This identifies an element to attach to.
2564 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
2568 @defvr {Dependent} value
2569 Required when @code{method} is @code{fixed}, not observed otherwise.
2570 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
2571 on parts @code{top} and @code{left}, and @code{100%} on part
2575 @node SPV Detail faceting Element
2576 @subsection The @code{faceting} Element
2579 faceting => layer[layers1]* cross layer[layers2]*
2581 cross => (unity | nest) (unity | nest)
2585 nest => variableReference[vars]+
2587 variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY
2590 :variable=ref (sourceVariable | derivedVariable)
2593 :method[layer_method]=(nest)?
2598 The @code{faceting} element describes the row, column, and layer
2599 structure of the table. Its @code{cross} child determines the row and
2600 column structure, and each @code{layer} child (if any) represents a
2601 layer. Layers may appear before or after @code{cross}.
2603 The @code{cross} element describes the row and column structure of the
2604 table. It has exactly two children, the first of which describes the
2605 table's columns and the second the table's rows. Each child is a
2606 @code{nest} element if the table has any dimensions along the axis in
2607 question, otherwise a @code{unity} element.
2609 A @code{nest} element contains of one or more dimensions listed from
2610 innermost to outermost, each represented by @code{variableReference}
2611 child elements. Each variable in a dimension is listed in order.
2612 @xref{SPV Detail Variable Elements}, for information on the variables
2613 that comprise a dimension.
2615 A @code{nest} can contain a single dimension, e.g.:
2619 <variableReference ref="dimension0categories"/>
2620 <variableReference ref="dimension0group0"/>
2621 <variableReference ref="dimension0"/>
2626 A @code{nest} can contain multiple dimensions, e.g.:
2630 <variableReference ref="dimension1categories"/>
2631 <variableReference ref="dimension1group0"/>
2632 <variableReference ref="dimension1"/>
2633 <variableReference ref="dimension0categories"/>
2634 <variableReference ref="dimension0"/>
2638 A @code{nest} may have no dimensions, in which case it still has one
2639 @code{variableReference} child, which references a
2640 @code{derivedVariable} whose @code{value} attribute is
2641 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
2642 @code{row} or @code{column}, respectively, as its @code{id}. This is
2643 equivalent to using a @code{unity} element in place of @code{nest}.
2645 A @code{variableReference} element refers to a variable through its
2646 @code{ref} attribute.
2648 Each @code{layer} element represents a dimension, e.g.:
2651 <layer value="0" variable="dimension0categories" visible="true"/>
2652 <layer value="dimension0" variable="dimension0" visible="false"/>
2656 @code{layer} has the following attributes.
2658 @defvr {Attribute} variable
2659 Refers to a @code{sourceVariable} or @code{derivedVariable} element.
2662 @defvr {Attribute} value
2663 The value to select. For a category variable, this is always
2664 @code{0}; for a data variable, it is the same as the @code{variable}
2668 @defvr {Attribute} visible
2669 Whether the layer is visible. Generally, category layers are visible
2670 and data layers are not, but sometimes this attribute is omitted.
2673 @defvr {Attribute} method
2674 When present, this is always @code{nest}.
2677 @node SPV Detail facetLayout Element
2678 @subsection The @code{facetLayout} Element
2681 facetLayout => tableLayout setCellProperties[scp1]*
2682 facetLevel+ setCellProperties[scp2]*
2685 :verticalTitlesInCorner=bool
2687 :fitCells=(ticks both)?
2691 The @code{facetLayout} element and its descendants control styling for
2694 Its @code{tableLayout} child has the following attributes
2696 @defvr {Attribute} verticalTitlesInCorner
2697 If true, in the absence of corner text, row headings will be displayed
2701 @defvr {Attribute} style
2702 Refers to a @code{style} element.
2705 @defvr {Attribute} fitCells
2709 @subsubheading The @code{facetLevel} Element
2712 facetLevel :level=int :gap=dimension? => axis
2714 axis :style=ref style => label? majorTicks
2720 :tickFrameStyle=ref style
2721 :labelFrequency=int?
2731 Each @code{facetLevel} describes a @code{variableReference} or
2732 @code{layer}, and a table has one @code{facetLevel} element for
2733 each such element. For example, an SPV detail member that contains
2734 four @code{variableReference} elements and two @code{layer} elements
2735 will contain six @code{facetLevel} elements.
2737 In the corpus, @code{facetLevel} elements and the elements that they
2738 describe are always in the same order. The correspondence may also be
2739 observed in two other ways. First, one may use the @code{level}
2740 attribute, described below. Second, in the corpus, a
2741 @code{facetLevel} always has an @code{id} that is the same as the
2742 @code{id} of the element it describes with @code{_facetLevel}
2743 appended. One should not formally rely on this, of course, but it is
2744 usefully indicative.
2746 @defvr {Attribute} level
2747 A 1-based index into the @code{variableReference} and @code{layer}
2748 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2749 describes the first @code{variableReference} in the SPV detail member,
2750 and in a member with four @code{variableReference} elements, a
2751 @code{facetLayout} with a @code{level} of 5 describes the first
2752 @code{layer} in the member.
2755 @defvr {Attribute} gap
2756 Always observed as @code{0pt}.
2759 Each @code{facetLevel} contains an @code{axis}, which in turn may
2760 contain a @code{label} for the @code{facetLevel} (@pxref{SPV Detail
2761 label Element}) and does contain a @code{majorTicks} element.
2763 @defvr {Attribute} labelAngle
2764 Normally 0. The value -90 causes inner column or outer row labels to
2765 be rotated vertically.
2768 @defvr {Attribute} style
2769 @defvrx {Attribute} tickFrameStyle
2770 Each refers to a @code{style} element. @code{style} is the style of
2771 the tick labels, @code{tickFrameStyle} the style for the frames around
2775 @node SPV Detail label Element
2776 @subsection The @code{label} Element
2781 :textFrameStyle=ref style?
2782 :purpose=(title | subTitle | subSubTitle | layer | footnote)?
2783 => text+ | descriptionGroup
2786 :target=ref faceting
2788 => (description | text)+
2790 description :name=(variable | value) => EMPTY
2794 :definesReference=int?
2795 :position=(subscript | superscript)?
2800 This element represents a label on some aspect of the table.
2802 @defvr {Attribute} style
2803 @defvrx {Attribute} textFrameStyle
2804 Each of these refers to a @code{style} element. @code{style} is the
2805 style of the label text, @code{textFrameStyle} the style for the frame
2809 @defvr {Attribute} purpose
2810 The kind of entity being labeled.
2813 A @code{descriptionGroup} concatenates one or more elements to form a
2814 label. Each element can be a @code{text} element, which contains
2815 literal text, or a @code{description} element that substitutes a value
2818 @defvr {Attribute} target
2819 The @code{id} of an element being described. In the corpus, this is
2820 always @code{faceting}.
2823 @defvr {Attribute} separator
2824 A string to separate the description of multiple groups, if the
2825 @code{target} has more than one. In the corpus, this is always a
2829 Typical contents for a @code{descriptionGroup} are a value by itself:
2831 <description name="value"/>
2833 @noindent or a variable and its value, separated by a colon:
2835 <description name="variable"/><text>:</text><description name="value"/>
2838 A @code{description} is like a macro that expands to some property of
2839 the target of its parent @code{descriptionGroup}. The @code{name}
2840 attribute specifies the property.
2842 @node SPV Detail setCellProperties Element
2843 @subsection The @code{setCellProperties} Element
2847 :applyToConverse=bool?
2848 => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]?
2851 The @code{setCellProperties} element sets style properties of cells or
2852 row or column labels.
2854 Interpreting @code{setCellProperties} requires answering two
2855 questions: which cells or labels to style, and what styles to use.
2857 @subsubheading Which Cells?
2862 intersect => where+ | intersectWhere | alternating | EMPTY
2865 :variable=ref (sourceVariable | derivedVariable)
2870 :variable=ref (sourceVariable | derivedVariable)
2871 :variable2=ref (sourceVariable | derivedVariable)
2874 alternating => EMPTY
2877 When @code{union} is present with @code{intersect} children, each of
2878 those children specifies a group of cells that should be styled, and
2879 the total group is all those cells taken together. When @code{union}
2880 is absent, every cell is styled. One attribute on
2881 @code{setCellProperties} affects the choice of cells:
2883 @defvr {Attribute} applyToConverse
2884 If true, this inverts the meaning of the cell selection: the selected
2885 cells are the ones @emph{not} designated. This is confusing, given
2886 the additional restrictions of @code{union}, but in the corpus
2887 @code{applyToConverse} is never present along with @code{union}.
2890 An @code{intersect} specifies restrictions on the cells to be matched.
2891 Each @code{where} child specifies which values of a given variable to
2892 include. The attributes of @code{intersect} are:
2894 @defvr {Attribute} variable
2895 Refers to a variable, e.g.@: @code{dimension0categories}. Only
2896 ``categories'' variables make sense here, but other variables, e.g.@:
2897 @code{dimension0group0map}, are sometimes seen. The reader may ignore
2901 @defvr {Attribute} include
2902 A value, or multiple values separated by semicolons,
2903 e.g.@: @code{0} or @code{13;14;15;16}.
2906 PSPP ignores @code{setCellProperties} when @code{intersectWhere} is
2909 @subsubheading What Styles?
2913 :target=ref (labeling | graph | interval | majorTicks)
2917 setMetaData :target=ref graph :key :value => EMPTY
2920 :target=ref (majorTicks | labeling)
2922 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
2926 :target=ref majorTicks
2930 The @code{set*} children of @code{setCellProperties} determine the
2933 When @code{setCellProperties} contains a @code{setFormat} whose
2934 @code{target} references a @code{labeling} element, or if it contains
2935 a @code{setStyle} that references a @code{labeling} or @code{interval}
2936 element, the @code{setCellProperties} sets the style for table cells.
2937 The format from the @code{setFormat}, if present, replaces the cells'
2938 format. The style from the @code{setStyle} that references
2939 @code{labeling}, if present, replaces the label's font and cell
2940 styles, except that the background color is taken instead from the
2941 @code{interval}'s style, if present.
2943 When @code{setCellProperties} contains a @code{setFormat} whose
2944 @code{target} references a @code{majorTicks} element, or if it
2945 contains a @code{setStyle} whose @code{target} references a
2946 @code{majorTicks}, or if it contains a @code{setFrameStyle} element,
2947 the @code{setCellProperties} sets the style for row or column labels.
2948 In this case, the @code{setCellProperties} always contains a single
2949 @code{where} element whose @code{variable} designates the variable
2950 whose labels are to be styled. The format from the @code{setFormat},
2951 if present, replaces the labels' format. The style from the
2952 @code{setStyle} that references @code{majorTicks}, if present,
2953 replaces the labels' font and cell styles, except that the background
2954 color is taken instead from the @code{setFrameStyle}'s style, if
2957 When @code{setCellProperties} contains a @code{setStyle} whose
2958 @code{target} references a @code{graph} element, and one that
2959 references a @code{labeling} element, and the @code{union} element
2960 contains @code{alternating}, the @code{setCellProperties} sets the
2961 alternate foreground and background colors for the data area. The
2962 foreground color is taken from the style referenced by the
2963 @code{setStyle} that targets the @code{graph}, the background color
2964 from the @code{setStyle} for @code{labeling}.
2966 A reader may ignore a @code{setCellProperties} that only contains
2967 @code{setMetaData}, as well as @code{setMetaData} within other
2968 @code{setCellProperties}.
2970 A reader may ignore a @code{setCellProperties} whose only @code{set*}
2971 child is a @code{setStyle} that targets the @code{graph} element.
2973 @subsubheading The @code{setStyle} Element
2977 :target=ref (labeling | graph | interval | majorTicks)
2982 This element associates a style with the target.
2984 @defvr {Attribute} target
2985 The @code{id} of an element whose style is to be set.
2988 @defvr {Attribute} style
2989 The @code{id} of a @code{style} element that identifies the style to
2993 @node SPV Detail setFormat Element
2994 @subsection The @code{setFormat} Element
2998 :target=ref (majorTicks | labeling)
3000 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
3003 This element sets the format of the target, ``format'' in this case
3004 meaning the SPSS print format for a variable.
3006 The details of this element vary depending on the schema version, as
3007 declared in the root @code{visualization} element's @code{version}
3008 attribute (@pxref{SPV Detail visualization Element}). A reader can
3009 interpret the content without knowing the schema version.
3011 The @code{setFormat} element itself has the following attributes.
3013 @defvr {Attribute} target
3014 Refers to an element whose style is to be set.
3017 @defvr {Attribute} reset
3018 If this is @code{true}, this format replaces the target's previous
3019 format. If it is @code{false}, the modifies the previous format.
3023 * SPV Detail numberFormat Element::
3024 * SPV Detail stringFormat Element::
3025 * SPV Detail dateTimeFormat Element::
3026 * SPV Detail elapsedTimeFormat Element::
3027 * SPV Detail format Element::
3028 * SPV Detail affix Element::
3031 @node SPV Detail numberFormat Element
3032 @subsubsection The @code{numberFormat} Element
3036 :minimumIntegerDigits=int?
3037 :maximumFractionDigits=int?
3038 :minimumFractionDigits=int?
3040 :scientific=(onlyForSmall | whenNeeded | true | false)?
3047 Specifies a format for displaying a number. The available options are
3048 a superset of those available from PSPP print formats. PSPP chooses a
3049 print format type for a @code{numberFormat} as follows:
3053 If @code{scientific} is @code{true}, uses @code{E} format.
3056 If @code{prefix} is @code{$}, uses @code{DOLLAR} format.
3059 If @code{suffix} is @code{%}, uses @code{PCT} format.
3062 If @code{useGrouping} is @code{true}, uses @code{COMMA} format.
3065 Otherwise, uses @code{F} format.
3068 For translating to a print format, PSPP uses
3069 @code{maximumFractionDigits} as the number of decimals, unless that
3070 attribute is missing or out of the range [0,15], in which case it uses
3073 @defvr {Attribute} minimumIntegerDigits
3074 Minimum number of digits to display before the decimal point. Always
3075 observed as @code{0}.
3078 @defvr {Attribute} maximumFractionDigits
3079 @defvrx {Attribute} minimumFractionDigits
3080 Maximum or minimum, respectively, number of digits to display after
3081 the decimal point. The observed values of each attribute range from 0
3085 @defvr {Attribute} useGrouping
3086 Whether to use the grouping character to group digits in large
3090 @defvr {Attribute} scientific
3091 This attribute controls when and whether the number is formatted in
3092 scientific notation. It takes the following values:
3096 Use scientific notation only when the number's magnitude is smaller
3097 than the value of the @code{small} attribute.
3100 Use scientific notation when the number will not otherwise fit in the
3104 Always use scientific notation. Not observed in the corpus.
3107 Never use scientific notation. A number that won't otherwise fit will
3108 be replaced by an error indication (see the @code{errorCharacter}
3109 attribute). Not observed in the corpus.
3113 @defvr {Attribute} small
3114 Only present when the @code{scientific} attribute is
3115 @code{onlyForSmall}, this is a numeric magnitude below which the
3116 number will be formatted in scientific notation. The values @code{0}
3117 and @code{0.0001} have been observed. The value @code{0} seems like a
3118 pathological choice, since no real number has a magnitude less than 0;
3119 perhaps in practice such a choice is equivalent to setting
3120 @code{scientific} to @code{false}.
3123 @defvr {Attribute} prefix
3124 @defvrx {Attribute} suffix
3125 Specifies a prefix or a suffix to apply to the formatted number. Only
3126 @code{suffix} has been observed, with value @samp{%}.
3129 @node SPV Detail stringFormat Element
3130 @subsubsection The @code{stringFormat} Element
3133 stringFormat => relabel* affix*
3135 relabel :from=real :to => EMPTY
3138 The @code{stringFormat} element specifies how to display a string. By
3139 default, a string is displayed verbatim, but @code{relabel} can change
3142 The @code{relabel} element appears as a child of @code{stringFormat}
3143 (and of @code{format}, when it is used to format strings). It
3144 specifies how to display a given value. It is used to implement value
3145 labels and to display the system-missing value in a human-readable
3146 way. It has the following attributes:
3148 @defvr {Attribute} from
3149 The value to map. In the corpus this is an integer or the
3150 system-missing value @code{-1.797693134862316E300}.
3153 @defvr {Attribute} to
3154 The string to display in place of the value of @code{from}. In the
3155 corpus this is a wide variety of value labels; the system-missing
3156 value is mapped to @samp{.}.
3159 @node SPV Detail dateTimeFormat Element
3160 @subsubsection The @code{dateTimeFormat} Element
3164 :baseFormat[dt_base_format]=(date | time | dateTime)
3166 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3168 :yearAbbreviation=bool?
3173 :monthFormat=(long | short | number | paddedNumber)?
3177 :showDayOfWeek=bool?
3178 :dayOfWeekAbbreviation=bool?
3180 :dayOfMonthPadding=bool?
3182 :minutePadding=bool?
3183 :secondPadding=bool?
3189 :dayType=(month | year)?
3190 :hourFormat=(AMPM | AS_24 | AS_12)?
3194 This element appears only in schema version 2.5 and earlier
3195 (@pxref{SPV Detail visualization Element}).
3197 Data to be formatted in date formats is stored as strings in legacy
3198 data, in the format @code{yyyy-mm-ddTHH:MM:SS.SSS} and must be parsed
3199 and reformatted by the reader.
3201 The following attribute is required.
3203 @defvr {Attribute} baseFormat
3204 Specifies whether a date and time are both to be displayed, or just
3208 Many of the attributes' meanings are obvious. The following seem to
3209 be worth documenting.
3211 @defvr {Attribute} separatorChars
3212 Exactly four characters. In order, these are used for: decimal point,
3213 grouping, date separator, time separator. Always @samp{.,-:}.
3216 @defvr {Attribute} mdyOrder
3217 Within a date, the order of the days, months, and years.
3218 @code{dayMonthYear} is the only observed value, but one would expect
3219 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
3223 @defvr {Attribute} showYear
3224 @defvrx {Attribute} yearAbbreviation
3225 Whether to include the year and, if so, whether the year should be
3226 shown abbreviated, that is, with only 2 digits. Each is @code{true}
3227 or @code{false}; only values of @code{true} and @code{false},
3228 respectively, have been observed.
3231 @defvr {Attribute} showMonth
3232 @defvrx {Attribute} monthFormat
3233 Whether to include the month (@code{true} or @code{false}) and, if so,
3234 how to format it. @code{monthFormat} is one of the following:
3238 The full name of the month, e.g.@: in an English locale,
3242 The abbreviated name of the month, e.g.@: in an English locale,
3246 The number representing the month, e.g.@: 9 for September.
3249 A two-digit number representing the month, e.g.@: 09 for September.
3252 Only values of @code{true} and @code{short}, respectively, have been
3256 @defvr {Attribute} dayType
3257 This attribute is always @code{month} in the corpus, specifying that
3258 the day of the month is to be displayed; a value of @code{year} is
3259 supposed to indicate that the day of the year, where 1 is January 1,
3260 is to be displayed instead.
3263 @defvr {Attribute} hourFormat
3264 @code{hourFormat}, if present, is one of:
3268 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
3272 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
3274 This is the only value observed in the corpus.
3277 The time is displayed in a 12-hour format, without distinguishing
3278 morning or evening, e.g.@: @code{10;15}.
3281 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
3282 which is confusing since a time duration does not have a concept of AM
3283 or PM. This might indicate a bug in the code that generated the XML
3284 in the corpus, or it might indicate that @code{elapsedTime} is
3285 sometimes used to format a time of day.
3288 For a @code{baseFormat} of @code{date}, PSPP chooses a print format
3289 type based on the following rules:
3293 If @code{showQuarter} is true: @code{QYR}.
3296 Otherwise, if @code{showWeek} is true: @code{WKYR}.
3299 Otherwise, if @code{mdyOrder} is @code{dayMonthYear}:
3303 If @code{monthFormat} is @code{number} or @code{paddedNumber}: @code{EDATE}.
3306 Otherwise: @code{DATE}.
3310 Otherwise, if @code{mdyOrder} is @code{yearMonthDay}: @code{SDATE}.
3313 Otherwise, @code{ADATE}.
3316 For a @code{baseFormat} of @code{dateTime}, PSPP uses @code{YMDHMS} if
3317 @code{mdyOrder} is @code{yearMonthDay} and @code{DATETIME} otherwise.
3318 For a @code{baseFormat} of @code{time}, PSPP uses @code{DTIME} if
3319 @code{showDay} is true, otherwise @code{TIME} if @code{showHour} is
3320 true, otherwise @code{MTIME}.
3322 For a @code{baseFormat} of @code{date}, the chosen width is the
3323 minimum for the format type, adding 2 if @code{yearAbbreviation} is
3324 false or omitted. For other base formats, the chosen width is the
3325 minimum for its type, plus 3 if @code{showSecond} is true, plus 4 more
3326 if @code{showMillis} is also true. Decimals are 0 by default, or 3
3327 if @code{showMillis} is true.
3329 @node SPV Detail elapsedTimeFormat Element
3330 @subsubsection The @code{elapsedTimeFormat} Element
3334 :baseFormat[dt_base_format]=(date | time | dateTime)
3337 :minutePadding=bool?
3338 :secondPadding=bool?
3348 This element specifies the way to display a time duration.
3350 Data to be formatted in elapsed time formats is stored as strings in
3351 legacy data, in the format @code{H:MM:SS.SSS}, with additional hour
3352 digits as needed for long durations, and must be parsed and
3353 reformatted by the reader.
3355 The following attribute is required.
3357 @defvr {Attribute} baseFormat
3358 Specifies whether a day and a time are both to be displayed, or just
3362 The remaining attributes specify exactly how to display the elapsed
3365 For @code{baseFormat} of @code{time}, PSPP converts this element to
3366 print format type @code{DTIME}; otherwise, if @code{showHour} is true,
3367 to @code{TIME}; otherwise, to @code{MTIME}. The chosen width is the
3368 minimum for the chosen type, adding 3 if @code{showSecond} is true,
3369 adding 4 more if @code{showMillis} is also true. Decimals are 0 by
3370 default, or 3 if @code{showMillis} is true.
3372 @node SPV Detail format Element
3373 @subsubsection The @code{format} Element
3377 :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)?
3380 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3385 :yearAbbreviation=bool?
3387 :monthFormat=(long | short | number | paddedNumber)?
3389 :dayOfMonthPadding=bool?
3393 :showDayOfWeek=bool?
3394 :dayOfWeekAbbreviation=bool?
3396 :minutePadding=bool?
3397 :secondPadding=bool?
3403 :dayType=(month | year)?
3404 :hourFormat=(AMPM | AS_24 | AS_12)?
3405 :minimumIntegerDigits=int?
3406 :maximumFractionDigits=int?
3407 :minimumFractionDigits=int?
3409 :scientific=(onlyForSmall | whenNeeded | true | false)?
3413 :tryStringsAsNumbers=bool?
3414 :negativesOutside=bool?
3418 This element is the union of all of the more-specific format elements.
3419 It is interpreted in the same way as one of those format elements,
3420 using @code{baseFormat} to determine which kind of format to use.
3422 There are a few attributes not present in the more specific formats:
3424 @defvr {Attribute} tryStringsAsNumbers
3425 When this is @code{true}, it is supposed to indicate that string
3426 values should be parsed as numbers and then displayed according to
3427 numeric formatting rules. However, in the corpus it is always
3431 @defvr {Attribute} negativesOutside
3432 If true, the negative sign should be shown before the prefix; if
3433 false, it should be shown after.
3436 @node SPV Detail affix Element
3437 @subsubsection The @code{affix} Element
3441 :definesReference=int
3442 :position=(subscript | superscript)
3448 This defines a suffix (or, theoretically, a prefix) for a formatted
3449 value. It is used to insert a reference to a footnote. It has the
3450 following attributes:
3452 @defvr {Attribute} definesReference
3453 This specifies the footnote number as a natural number: 1 for the
3454 first footnote, 2 for the second, and so on.
3457 @defvr {Attribute} position
3458 Position for the footnote label. Always @code{superscript}.
3461 @defvr {Attribute} suffix
3462 Whether the affix is a suffix (@code{true}) or a prefix
3463 (@code{false}). Always @code{true}.
3466 @defvr {Attribute} value
3467 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
3468 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
3469 contains other values: @code{*}, @code{**}, and a few that begin with
3470 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
3473 @node SPV Detail interval Element
3474 @subsection The @code{interval} Element
3477 interval :style=ref style => labeling footnotes?
3481 :variable=ref (sourceVariable | derivedVariable)
3482 => (formatting | format | footnotes)*
3484 formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping*
3486 formatMapping :from=int => format?
3490 :variable=ref (sourceVariable | derivedVariable)
3493 footnoteMapping :definesReference=int :from=int :to => EMPTY
3496 The @code{interval} element and its descendants determine the basic
3497 formatting and labeling for the table's cells. These basic styles are
3498 overridden by more specific styles set using @code{setCellProperties}
3499 (@pxref{SPV Detail setCellProperties Element}).
3501 The @code{style} attribute of @code{interval} itself may be ignored.
3503 The @code{labeling} element may have a single @code{formatting} child.
3504 If present, its @code{variable} attribute refers to a variable whose
3505 values are format specifiers as numbers, e.g. value 0x050802 for F8.2.
3506 However, the numbers are not actually interpreted that way. Instead,
3507 each number actually present in the variable's data is mapped by a
3508 @code{formatMapping} child of @code{formatting} to a @code{format}
3509 that specifies how to display it.
3511 The @code{labeling} element may also have a @code{footnotes} child
3512 element. The @code{variable} attribute of this element refers to a
3513 variable whose values are comma-delimited strings that list the
3514 1-based indexes of footnote references. (Cells without any footnote
3515 references are numeric 0 instead of strings.)
3517 Each @code{footnoteMapping} child of the @code{footnotes} element
3518 defines the footnote marker to be its @code{to} attribute text for the
3519 footnote whose 1-based index is given in its @code{definesReference}
3522 @node SPV Detail style Element
3523 @subsection The @code{style} Element
3530 :border-bottom=(solid | thick | thin | double | none)?
3531 :border-top=(solid | thick | thin | double | none)?
3532 :border-left=(solid | thick | thin | double | none)?
3533 :border-right=(solid | thick | thin | double | none)?
3534 :border-bottom-color?
3537 :border-right-color?
3540 :font-weight=(regular | bold)?
3541 :font-style=(regular | italic)?
3542 :font-underline=(none | underline)?
3543 :margin-bottom=dimension?
3544 :margin-left=dimension?
3545 :margin-right=dimension?
3546 :margin-top=dimension?
3547 :textAlignment=(left | right | center | decimal | mixed)?
3548 :labelLocationHorizontal=(positive | negative | center)?
3549 :labelLocationVertical=(positive | negative | center)?
3550 :decimal-offset=dimension?
3557 A @code{style} element has an effect only when it is referenced by
3558 another element to set some aspect of the table's style. Most of the
3559 attributes are self-explanatory. The rest are described below.
3561 @defvr {Attribute} {color}
3562 In some cases, the text color; in others, the background color.
3565 @defvr {Attribute} {color2}
3569 @defvr {Attribute} {labelAngle}
3570 Normally 0. The value -90 causes inner column or outer row labels to
3571 be rotated vertically.
3574 @defvr {Attribute} {labelLocationHorizontal}
3578 @defvr {Attribute} {labelLocationVertical}
3579 The value @code{positive} corresponds to vertically aligning text to
3580 the top of a cell, @code{negative} to the bottom, @code{center} to the
3584 @node SPV Detail labelFrame Element
3585 @subsection The @code{labelFrame} Element
3588 labelFrame :style=ref style => location+ label? paragraph?
3590 paragraph :hangingIndent=dimension? => EMPTY
3593 A @code{labelFrame} element specifies content and style for some
3594 aspect of a table. Only @code{labelFrame} elements that have a
3595 @code{label} child are important. The @code{purpose} attribute in the
3596 @code{label} determines what the @code{labelFrame} affects:
3600 The table's title and its style.
3603 The table's caption and its style.
3606 The table's footnotes and the style for the footer area.
3609 The style for the layer area.
3615 The @code{style} attribute references the style to use for the area.
3617 The @code{label}, if present, specifies the text to put into the title
3618 or caption or footnotes. For footnotes, the label has two @code{text}
3619 children for every footnote, each of which has a @code{usesReference}
3620 attribute identifying the 1-based index of a footnote. The first,
3621 third, fifth, @dots{} @code{text} child specifies the content for a
3622 footnote; the second, fourth, sixth, @dots{} child specifies the
3623 marker. Content tends to end in a new-line, which the reader may wish
3624 to trim; similarly, markers tend to end in @samp{.}.
3626 The @code{paragraph}, if present, may be ignored, since it is always
3629 @node SPV Detail Legacy Properties
3630 @subsection Legacy Properties
3632 The detail XML format has features for styling most of the aspects of
3633 a table. It also inherits defaults for many aspects from structure
3634 XML, which has the following @code{tableProperties} element:
3639 => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties
3642 :hideEmptyRows=bool?
3643 :maximumColumnWidth=dimension?
3644 :maximumRowWidth=dimension?
3645 :minimumColumnWidth=dimension?
3646 :minimumRowWidth=dimension?
3647 :rowDimensionLabels=(inCorner | nested)?
3651 :markerPosition=(superscript | subscript)?
3652 :numberFormat=(alphabetic | numeric)?
3655 cellFormatProperties => cell_style+
3658 :alternatingColor=color?
3659 :alternatingTextColor=color?
3667 :font-style=(regular | italic)?
3668 :font-weight=(regular | bold)?
3669 :font-underline=(none | underline)?
3670 :labelLocationVertical=(positive | negative | center)?
3671 :margin-bottom=dimension?
3672 :margin-left=dimension?
3673 :margin-right=dimension?
3674 :margin-top=dimension?
3675 :textAlignment=(left | right | center | decimal | mixed)?
3676 :decimal-offset=dimension?
3679 borderProperties => border_style+
3682 :borderStyleType=(none | solid | dashed | thick | thin | double)?
3687 :printAllLayers=bool?
3688 :rescaleLongTableToFitPage=bool?
3689 :rescaleWideTableToFitPage=bool?
3690 :windowOrphanLines=int?
3692 :continuationTextAtBottom=bool?
3693 :continuationTextAtTop=bool?
3694 :printEachLayerOnSeparatePage=bool?
3698 The @code{name} attribute appears only in standalone @file{.stt} files
3699 (@pxref{SPSS TableLook STT Format}).