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.}@footnote{SPSS
35 writes @file{META-INF/MANIFEST.MF} to every SPV file, but it does not
36 read it or even require it to exist, so using different contents,
37 e.g.@: as @samp{allowingPivot=false} has no effect.}
39 The rest of the members in an SPV file's Zip archive fall into two
40 categories: @dfn{structure} and @dfn{detail} members. Structure
41 member names begin with @file{outputViewer@var{nnnnnnnnnn}}, where
42 each @var{n} is a decimal digit, and end with @file{.xml}, and often
43 include the string @file{_heading} in between. Each of these members
44 represents some kind of output item (a table, a heading, a block of
45 text, etc.) or a group of them. The member whose output goes at the
46 beginning of the document is numbered 0, the next member in the output
47 is numbered 1, and so on.
49 Structure members contain XML. This XML is sometimes self-contained,
50 but it often references detail members in the Zip archive, which are
54 @item @file{@var{prefix}_table.xml} and @file{@var{prefix}_tableData.bin}
55 @itemx @file{@var{prefix}_lightTableData.bin}
56 The structure of a table plus its data. Older SPV files pair a
57 @file{@var{prefix}_table.xml} file that describes the table's
58 structure with a binary @file{@var{prefix}_tableData.bin} file that
59 gives its data. Newer SPV files (the majority of those in the corpus)
60 instead include a single @file{@var{prefix}_lightTableData.bin} file
61 that incorporates both into a single binary format.
63 @item @file{@var{prefix}_warning.xml} and @file{@var{prefix}_warningData.bin}
64 @itemx @file{@var{prefix}_lightWarningData.bin}
65 Same format used for tables, with a different name.
67 @item @file{@var{prefix}_notes.xml} and @file{@var{prefix}_notesData.bin}
68 @itemx @file{@var{prefix}_lightNotesData.bin}
69 Same format used for tables, with a different name.
71 @item @file{@var{prefix}_chartData.bin} and @file{@var{prefix}_chart.xml}
72 The structure of a chart plus its data. Charts do not have a
75 @item @file{@var{prefix}_Imagegeneric.png}
76 @itemx @file{@var{prefix}_PastedObjectgeneric.png}
77 @itemx @file{@var{prefix}_imageData.bin}
78 A PNG image referenced by an @code{object} element (in the first two
79 cases) or an @code{image} element (in the final case). @xref{SPV
80 Structure object and image Elements}.
82 @item @file{@var{prefix}_pmml.scf}
83 @itemx @file{@var{prefix}_stats.scf}
84 @item @file{@var{prefix}_model.xml}
85 Not yet investigated. The corpus contains few examples.
88 The @file{@var{prefix}} in the names of the detail members is
89 typically an 11-digit decimal number that increases for each item,
90 tending to skip values. Older SPV files use different naming
91 conventions. Structure member refer to detail members by name, and so
92 their exact names do not matter to readers as long as they are unique.
94 SPSS tolerates corrupted Zip archives that Zip reader libraries tend
95 to reject. These can be fixed up with @command{zip -FF}.
98 * SPV Structure Member Format::
99 * SPV Light Detail Member Format::
100 * SPV Legacy Detail Member Binary Format::
101 * SPV Legacy Detail Member XML Format::
104 @node SPV Structure Member Format
105 @section Structure Member Format
107 A structure member lays out the high-level structure for a group of
108 output items such as heading, tables, and charts. Structure members
109 do not include the details of tables and charts but instead refer to
110 them by their member names.
112 Structure members' XML files claim conformance with a collection of
113 XML Schemas. These schemas are distributed, under a nonfree license,
114 with SPSS binaries. Fortunately, the schemas are not necessary to
115 understand the structure members. The schemas can even
116 be deceptive because they document elements and attributes that are
117 not in the corpus and do not document elements and attributes that are
118 commonly found in the corpus.
120 Structure members use a different XML namespace for each schema, but
121 these namespaces are not entirely consistent. In some SPV files, for
122 example, the @code{viewer-tree} schema is associated with namespace
123 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
124 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
125 additional @file{viewer/}). Under either name, the schema URIs are
126 not resolvable to obtain the schemas themselves.
128 One may ignore all of the above in interpreting a structure member.
129 The actual XML has a simple and straightforward form that does not
130 require a reader to take schemas or namespaces into account. A
131 structure member's root is @code{heading} element, which contains
132 @code{heading} or @code{container} elements (or a mix), forming a
133 tree. In turn, @code{container} holds a @code{label} and one more
134 child, usually @code{text} or @code{table}.
136 The following sections document the elements found in structure
137 members in a context-free grammar-like fashion. Consider the
138 following example, which specifies the attributes and content for the
139 @code{container} element:
143 :visibility=(visible | hidden)
144 :page-break-before=(always)?
145 :text-align=(left | center)?
147 => label (table | container_text | graph | model | object | image | tree)
150 Each attribute specification begins with @samp{:} followed by the
151 attribute's name. If the attribute's value has an easily specified
152 form, then @samp{=} and its description follows the name. Finally, if
153 the attribute is optional, the specification ends with @samp{?}. The
154 following value specifications are defined:
157 @item (@var{a} | @var{b} | @dots{})
158 One of the listed literal strings. If only one string is listed, it
159 is the only acceptable value. If @code{OTHER} is listed, then any
160 string not explicitly listed is also accepted.
163 Either @code{true} or @code{false}.
166 A floating-point number followed by a unit, e.g.@: @code{10pt}. Units
167 in the corpus include @code{in} (inch), @code{pt} (points, 72/inch),
168 @code{px} (``device-independent pixels'', 96/inch), and @code{cm}. If
169 the unit is omitted then points should be assumed. The number and
170 unit may be separated by white space.
172 The corpus also includes localized names for units. A reader must
173 understand these to properly interpret the dimension:
177 @code{인치}, @code{pol.}, @code{cala}, @code{cali}
187 A floating-point number.
193 A color in one of the forms @code{#@var{rr}@var{gg}@var{bb}} or
194 @code{@var{rr}@var{gg}@var{bb}}, or the string @code{transparent}, or
195 one of the standard Web color names.
198 @item ref @var{element}
199 @itemx ref(@var{elem1} | @var{elem2} | @dots{})
200 The name from the @code{id} attribute in some element. If one or more
201 elements are named, the name must refer to one of those elements,
202 otherwise any element is acceptable.
205 All elements have an optional @code{id} attribute. If present, its
206 value must be unique. In practice many elements are assigned
207 @code{id} attributes that are never referenced.
209 The content specification for an element supports the following
216 @item @var{a} @var{b}
217 @var{a} followed by @var{b}.
219 @item @var{a} | @var{b} | @var{c}
220 One of @var{a} or @var{b} or @var{c}.
223 Zero or one instances of @var{a}.
226 Zero or more instances of @var{a}.
229 One or more instances of @var{a}.
231 @item (@var{subexpression})
232 Grouping for a subexpression.
241 Element and attribute names are sometimes suffixed by another name in
242 square brackets to distinguish different uses of the same name. For
243 example, structure XML has two @code{text} elements, one inside
244 @code{container}, the other inside @code{pageParagraph}. The former
245 is defined as @code{text[container_text]} and referenced as
246 @code{container_text}, the latter defined as
247 @code{text[pageParagraph_text]} and referenced as
248 @code{pageParagraph_text}.
250 This language is used in the PSPP source code for parsing structure
251 and detail XML members. Refer to
252 @file{src/output/spv/structure-xml.grammar} and
253 @file{src/output/spv/detail-xml.grammar} for the full grammars.
255 The following example shows the contents of a typical structure member
256 for a @cmd{DESCRIPTIVES} procedure. A real structure member is not
257 indented. This example also omits most attributes, all XML namespace
258 information, and the CSS from the embedded HTML:
261 <?xml version="1.0" encoding="utf-8"?>
263 <label>Output</label>
264 <heading commandName="Descriptives">
265 <label>Descriptives</label>
268 <text commandName="Descriptives" type="title">
270 <![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
274 <container visibility="hidden">
276 <table commandName="Descriptives" subType="Notes" type="note">
278 <dataPath>00000000001_lightNotesData.bin</dataPath>
283 <label>Descriptive Statistics</label>
284 <table commandName="Descriptives" subType="Descriptive Statistics"
287 <dataPath>00000000002_lightTableData.bin</dataPath>
296 * SPV Structure heading Element::
297 * SPV Structure label Element::
298 * SPV Structure container Element::
299 * SPV Structure text Element (Inside @code{container})::
300 * SPV Structure html Element::
301 * SPV Structure table Element::
302 * SPV Structure graph Element::
303 * SPV Structure model Element::
304 * SPV Structure object and image Elements::
305 * SPV Structure tree Element::
306 * SPV Structure Path Elements::
307 * SPV Structure pageSetup Element::
308 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
311 @node SPV Structure heading Element
312 @subsection The @code{heading} Element
315 heading[root_heading]
321 => label pageSetup? (container | heading)*
326 :visibility[heading_visibility]=(collapsed)?
329 => label (container | heading)*
332 The root of a structure member is a @code{heading}, which represents a
333 section of output beginning with a @code{label} and
334 ordinarily followed by content containers or further nested
335 (sub)-sections of output. Unlike heading elements in HTML and other
336 common document formats, which precede the content that they head,
337 @code{heading} contains the elements that appear below the heading.
339 The document root heading, only, may contain a @code{pageSetup}
342 The following attributes have been observed on both document root and
343 nested @code{heading} elements.
345 @defvr {Attribute} creator-version
346 The version of the software that created this SPV file. A string of
347 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
348 e.g.@: @code{21000001} is version 21.0.0.1. Trailing pairs of zeros
349 are sometimes omitted, so that @code{21}, @code{210000}, and
350 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
351 three of those forms).
355 The following attributes have been observed on document root
356 @code{heading} elements only:
358 @defvr {Attribute} @code{creator}
359 The directory in the file system of the software that created this SPV
363 @defvr {Attribute} @code{creation-date-time}
364 The date and time at which the SPV file was written, in a
365 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
366 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
367 December 5, 2014 5:00:19 o'clock PM EST}.
370 @defvr {Attribute} @code{lockReader}
371 Whether a reader should be allowed to edit the output. The possible
372 values are @code{true} and @code{false}. The value @code{false} is by
376 @defvr {Attribute} @code{schemaLocation}
377 This is actually an XML Namespace attribute. A reader may ignore it.
381 The following attributes have been observed only on nested
382 @code{heading} elements:
384 @defvr {Attribute} @code{commandName}
385 A locale-invariant identifier for the command that produced the
386 output, e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
389 @defvr {Attribute} @code{visibility}
390 To what degree the output represented by the element is visible.
393 @defvr {Attribute} @code{locale}
394 The locale used for output, in Windows format, which is similar to the
395 format used in Unix with the underscore replaced by a hyphen, e.g.@:
396 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
399 @defvr {Attribute} @code{olang}
400 The output language, e.g.@: @code{en}, @code{it}, @code{es},
401 @code{de}, @code{pt-BR}.
404 @node SPV Structure label Element
405 @subsection The @code{label} Element
411 Every @code{heading} and @code{container} holds a @code{label} as its
412 first child. The label text is what appears in the outline pane of
413 the GUI's viewer window. PSPP also puts it into the outline of PDF
414 output. The label text doesn't appear in the output itself.
416 The text in @code{label} describes what it labels, often by naming the
417 statistical procedure that was executed, e.g.@: ``Frequencies'' or
418 ``T-Test''. The root @code{heading} in a structure member is normally
419 ``Output''. Labels are often very generic, especially within a
420 @code{container}, e.g.@: ``Title'' or ``Warnings'' or ``Notes''.
421 Label text is localized according to the output language, e.g.@: in
422 Italian a frequency table procedure is labeled ``Frequenze''.
424 The user can edit labels to be anything they want. The corpus
425 contains a few examples of empty labels, ones that contain no text,
426 probably as a result of user editing.
428 @node SPV Structure container Element
429 @subsection The @code{container} Element
433 :visibility=(visible | hidden)
434 :page-break-before=(always)?
435 :text-align=(left | center)?
437 => label (table | container_text | graph | model | object | image | tree)
440 A @code{container} serves to contain and label a @code{table},
441 @code{text}, or other kind of item.
443 This element has the following attributes.
445 @defvr {Attribute} @code{visibility}
446 Whether the container's content is displayed. ``Notes'' tables are
447 often hidden; other data is usually
450 @defvr {Attribute} @code{text-align}
451 Alignment of text within the container. Observed with nested
452 @code{table} and @code{text} elements.
455 @defvr {Attribute} @code{width}
456 The width of the container, e.g.@: @code{1097px}.
459 @node SPV Structure text Element (Inside @code{container})
460 @subsection The @code{text} Element (Inside @code{container})
464 :type[text_type]=(title | log | text | page-title)
470 This @code{text} element is nested inside a @code{container}. There
471 is a different @code{text} element that is nested inside a
472 @code{pageParagraph}.
474 This element has the following attributes.
476 @defvr {Attribute} @code{type}
477 The semantics of the text.
480 @defvr {Attribute} @code{commandName}
481 As on the @code{heading} element. For output not specific to a
482 command, this is simply @code{log}. The corpus contains one example
483 of where @code{commandName} is present but set to the empty string.
486 @defvr {Attribute} @code{creator-version}
487 As on the @code{heading} element.
490 @node SPV Structure html Element
491 @subsection The @code{html} Element
494 html :lang=(en) => TEXT
497 The element contains an HTML document as text (or, in practice, as
498 CDATA). In some cases, the document starts with @code{<html>} and
499 ends with @code{</html>}; in others the @code{html} element is
500 implied. Generally the HTML includes a @code{head} element with a CSS
501 stylesheet. The HTML body often begins with @code{<BR>}.
503 The HTML document uses only the following elements:
507 Sometimes, the document is enclosed with
508 @code{<html>}@dots{}@code{</html>}.
511 The HTML body often begins with @code{<BR>} and may contain it as well.
519 The attributes @code{face}, @code{color}, and @code{size} are
520 observed. The value of @code{color} takes one of the forms
521 @code{#@var{rr}@var{gg}@var{bb}} or @code{rgb (@var{r}, @var{g},
522 @var{b})}. The value of @code{size} is a number between 1 and 7,
526 The CSS in the corpus is simple. To understand it, a parser only
527 needs to be able to skip white space, @code{<!--}, and @code{-->}, and
528 parse style only for @code{p} elements. Only the following properties
533 In the form @code{@var{rr}@var{gg}@var{bb}}, e.g. @code{000000}, with
537 Either @code{bold} or @code{normal}.
540 Either @code{italic} or @code{normal}.
542 @item text-decoration
543 Either @code{underline} or @code{normal}.
546 A font name, commonly @code{Monospaced} or @code{SansSerif}.
549 Values claim to be in points, e.g.@: @code{14pt}, but the values are
550 actually in ``device-independent pixels'' (px), at 96/inch.
553 This element has the following attributes.
555 @defvr {Attribute} @code{lang}
556 This always contains @code{en} in the corpus.
559 @node SPV Structure table Element
560 @subsection The @code{table} Element
569 :displayFiltering=bool?
571 :orphanTolerance=int?
576 :type[table_type]=(table | note | warning)
577 => tableProperties? tableStructure
579 tableStructure => path? dataPath csvPath?
582 This element has the following attributes.
584 @defvr {Attribute} @code{commandName}
585 As on the @code{heading} element.
588 @defvr {Attribute} @code{type}
589 One of @code{table}, @code{note}, or @code{warning}.
592 @defvr {Attribute} @code{subType}
593 The locale-invariant command ID for the particular kind of output that
594 this table represents in the procedure. This can be the same as
595 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
596 @code{Case Processing Summary}. Generic subtypes @code{Notes} and
597 @code{Warnings} are often used.
600 @defvr {Attribute} @code{tableId}
601 A number that uniquely identifies the table within the SPV file,
602 typically a large negative number such as @code{-4147135649387905023}.
605 @defvr {Attribute} @code{creator-version}
606 As on the @code{heading} element. In the corpus, this is only present
607 for version 21 and up and always includes all 8 digits.
610 @xref{SPV Detail Legacy Properties}, for details on the
611 @code{tableProperties} element.
613 @node SPV Structure graph Element
614 @subsection The @code{graph} Element
629 => dataPath? path csvPath?
632 This element represents a graph. The @code{dataPath} and @code{path}
633 elements name the Zip members that give the details of the graph.
634 Normally, both elements are present; there is only one counterexample
637 @code{csvPath} only appears in one SPV file in the corpus, for two
638 graphs. In these two cases, @code{dataPath}, @code{path}, and
639 @code{csvPath} all appear. These @code{csvPath} name Zip members with
640 names of the form @file{@var{number}_csv.bin}, where @var{number} is a
641 many-digit number and the same as the @code{csvFileIds}. The named
642 Zip members are CSV text files (despite the @file{.bin} extension).
643 The CSV files are encoded in UTF-8 and begin with a U+FEFF byte-order
646 @node SPV Structure model Element
647 @subsection The @code{model} Element
659 => ViZml? dataPath? path | pmmlContainerPath statsContainerPath
661 pmmlContainerPath => TEXT
663 statsContainerPath => TEXT
665 ViZml :viewName? => TEXT
668 This element represents a model. The @code{dataPath} and @code{path}
669 elements name the Zip members that give the details of the model.
670 Normally, both elements are present; there is only one counterexample
673 The details are unexplored. The @code{ViZml} element contains base-64
674 encoded text, that decodes to a binary format with some embedded text
675 strings, and @code{path} names an Zip member that contains XML.
676 Alternatively, @code{pmmlContainerPath} and @code{statsContainerPath}
677 name Zip members with @file{.scf} extension.
679 @node SPV Structure object and image Elements
680 @subsection The @code{object} and @code{image} Elements
683 object :type[object_type]=(unknown)? :uri => EMPTY
685 image :VDPId :commandName => dataPath
688 These two elements represent an image in PNG format. They are
689 equivalent and the corpus contains examples of both. The only
690 difference is the syntax: for @code{object}, the @code{uri} attribute
691 names the Zip member that contains a PNG file; for @code{image}, the
692 text of the inner @code{dataPath} element names the Zip member.
694 PSPP writes @code{object} in output but there is no strong reason to
697 The corpus only contains PNG image files.
699 @node SPV Structure tree Element
700 @subsection The @code{tree} Element
711 This element represents a tree. The @code{dataPath} and @code{path}
712 elements name the Zip members that give the details of the tree.
713 The details are unexplored.
715 @node SPV Structure Path Elements
716 @subsection Path Elements
726 These element contain the name of the Zip members that hold details
727 for a container. For tables:
731 When a ``light'' format is used, only @code{dataPath} is present, and
732 it names a @file{.bin} member of the Zip file that has @code{light} in
733 its name, e.g.@: @code{0000000001437_lightTableData.bin} (@pxref{SPV
734 Light Detail Member Format}).
737 When the legacy format is used, both are present. In this case,
738 @code{dataPath} names a Zip member with a legacy binary format that
739 contains relevant data (@pxref{SPV Legacy Detail Member Binary
740 Format}), and @code{path} names a Zip member that uses an XML format
741 (@pxref{SPV Legacy Detail Member XML Format}).
744 Graphs normally follow the legacy approach described above. The
745 corpus contains one example of a graph with @code{path} but not
746 @code{dataPath}. The reason is unexplored.
748 Models use @code{path} but not @code{dataPath}. @xref{SPV Structure
749 graph Element}, for more information.
751 These elements have no attributes.
753 @node SPV Structure pageSetup Element
754 @subsection The @code{pageSetup} Element
758 :initial-page-number=int?
759 :chart-size=(as-is | full-height | half-height | quarter-height | OTHER)?
760 :margin-left=dimension?
761 :margin-right=dimension?
762 :margin-top=dimension?
763 :margin-bottom=dimension?
764 :paper-height=dimension?
765 :paper-width=dimension?
766 :reference-orientation?
767 :space-after=dimension?
768 => pageHeader pageFooter
770 pageHeader => pageParagraph?
772 pageFooter => pageParagraph?
774 pageParagraph => pageParagraph_text
777 The @code{pageSetup} element has the following attributes.
779 @defvr {Attribute} @code{initial-page-number}
780 The page number to put on the first page of printed output. Usually
784 @defvr {Attribute} @code{chart-size}
785 One of the listed, self-explanatory chart sizes,
786 @code{quarter-height}, or a localization (!) of one of these (e.g.@:
787 @code{dimensione attuale}, @code{Wie vorgegeben}).
790 @defvr {Attribute} @code{margin-left}
791 @defvrx {Attribute} @code{margin-right}
792 @defvrx {Attribute} @code{margin-top}
793 @defvrx {Attribute} @code{margin-bottom}
794 Margin sizes, e.g.@: @code{0.25in}.
797 @defvr {Attribute} @code{paper-height}
798 @defvrx {Attribute} @code{paper-width}
802 @defvr {Attribute} @code{reference-orientation}
803 Indicates the orientation of the output page. Either @code{0deg}
804 (portrait) or @code{90deg} (landscape),
807 @defvr {Attribute} @code{space-after}
808 The amount of space between printed objects, typically @code{12pt}.
811 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
812 @subsection The @code{text} Element (Inside @code{pageParagraph})
815 text[pageParagraph_text] :type=(title | text) => TEXT
818 This @code{text} element is nested inside a @code{pageParagraph}. There
819 is a different @code{text} element that is nested inside a
822 The element is either empty, or contains CDATA that holds almost-XHTML
823 text: in the corpus, either an @code{html} or @code{p} element. It is
824 @emph{almost}-XHTML because the @code{html} element designates the
826 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of
827 an XHTML namespace, and because the CDATA can contain substitution
828 variables. The following variables are supported:
833 The current date or time in the preferred format for the locale.
839 First-, second-, third-, or fourth-level heading.
845 Name of the output file.
851 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
854 Typical contents (indented for clarity):
857 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
860 <p style="text-align:right; margin-top: 0">Page &[Page]</p>
865 This element has the following attributes.
867 @defvr {Attribute} @code{type}
871 @node SPV Light Detail Member Format
872 @section Light Detail Member Format
874 This section describes the format of ``light'' detail @file{.bin}
875 members. These members have a binary format which we describe here in
876 terms of a context-free grammar using the following conventions:
879 @item NonTerminal @result{} @dots{}
880 Nonterminals have CamelCaps names, and @result{} indicates a
881 production. The right-hand side of a production is often broken
882 across multiple lines. Break points are chosen for aesthetics only
883 and have no semantic significance.
885 @item 00, 01, @dots{}, ff.
886 A bytes with a fixed value, written as a pair of hexadecimal digits.
888 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
889 @itemx ib0, ib1, @dots{}, ib9, ib10, ib11, @dots{}
890 A 32-bit integer in little-endian or big-endian byte order,
891 respectively, with a fixed value, written in decimal. Prefixed by
892 @samp{i} for little-endian or @samp{ib} for big-endian.
898 A byte with value 0 or 1.
902 A 16-bit unsigned integer in little-endian or big-endian byte order,
907 A 32-bit unsigned integer in little-endian or big-endian byte order,
912 A 64-bit unsigned integer in little-endian or big-endian byte order,
916 A 64-bit IEEE floating-point number.
919 A 32-bit IEEE floating-point number.
923 A 32-bit unsigned integer, in little-endian or big-endian byte order,
924 respectively, followed by the specified number of bytes of character
925 data. (The encoding is indicated by the Formats nonterminal.)
928 @var{x} is optional, e.g.@: 00? is an optional zero byte.
930 @item @var{x}*@var{n}
931 @var{x} is repeated @var{n} times, e.g.@: byte*10 for ten arbitrary bytes.
933 @item @var{x}[@var{name}]
934 Gives @var{x} the specified @var{name}. Names are used in textual
935 explanations. They are also used, also bracketed, to indicate counts,
936 e.g.@: @code{int32[n] byte*[n]} for a 32-bit integer followed by the
937 specified number of arbitrary bytes.
939 @item @var{a} @math{|} @var{b}
940 Either @var{a} or @var{b}.
943 Parentheses are used for grouping to make precedence clear, especially
944 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
948 @itemx becount(@var{x})
949 A 32-bit unsigned integer, in little-endian or big-endian byte order,
950 respectively, that indicates the number of bytes in @var{x}, followed
954 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
955 (The @file{.bin} header indicates the version.)
958 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
961 PSPP uses this grammar to parse light detail members. See
962 @file{src/output/spv/light-binary.grammar} in the PSPP source tree for
965 Little-endian byte order is far more common in this format, but a few
966 pieces of the format use big-endian byte order.
968 Light detail members express linear units in two ways: points (pt), at
969 72/inch, and ``device-independent pixels'' (px), at 96/inch. To
970 convert from pt to px, multiply by 1.33 and round up. To convert
971 from px to pt, divide by 1.33 and round down.
973 A ``light'' detail member @file{.bin} consists of a number of sections
974 concatenated together, terminated by an optional byte 01:
978 Header Titles Footnotes
979 Areas Borders PrintSettings TableSettings Formats
980 Dimensions Axes Cells
984 The following sections go into more detail.
987 * SPV Light Member Header::
988 * SPV Light Member Titles::
989 * SPV Light Member Footnotes::
990 * SPV Light Member Areas::
991 * SPV Light Member Borders::
992 * SPV Light Member Print Settings::
993 * SPV Light Member Table Settings::
994 * SPV Light Member Formats::
995 * SPV Light Member Dimensions::
996 * SPV Light Member Categories::
997 * SPV Light Member Axes::
998 * SPV Light Member Cells::
999 * SPV Light Member Value::
1000 * SPV Light Member ValueMod::
1003 @node SPV Light Member Header
1006 An SPV light member begins with a 39-byte header:
1011 (i1 @math{|} i3)[version]
1014 bool[rotate-inner-column-labels]
1015 bool[rotate-outer-row-labels]
1018 int32[min-col-width] int32[max-col-width]
1019 int32[min-row-width] int32[max-row-width]
1023 @code{version} is a version number that affects the interpretation of
1024 some of the other data in the member. We will refer to ``version 1''
1025 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
1026 version-specific formatting (as described previously).
1028 If @code{rotate-inner-column-labels} is 1, then column labels closest
1029 to the data are rotated 90° counterclockwise; otherwise, they are
1030 shown in the normal way.
1032 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
1033 the data are rotated 90° counterclockwise; otherwise, they are shown
1036 @code{min-col-width} is the minimum width that a column will be
1037 assigned automatically. @code{max-col-width} is the maximum width
1038 that a column will be assigned to accommodate a long column label.
1039 @code{min-row-width} and @code{max-row-width} are a similar range for
1040 the width of row labels. All of these measurements are in 1/96 inch
1041 units (called a ``device independent pixel'' unit in Windows).
1043 @code{table-id} is a binary version of the @code{tableId} attribute in
1044 the structure member that refers to the detail member. For example,
1045 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
1046 would be 0xc6c99d183b300001.
1048 The meaning of the other variable parts of the header is not known. A
1049 writer may safely use version 3, true for @code{x0}, false for
1050 @code{x1}, true for @code{x2}, and 0x15 for @code{x3}.
1052 @node SPV Light Member Titles
1058 Value[subtype] 01? 31
1059 Value[user-title] 01?
1060 (31 Value[corner-text] @math{|} 58)
1061 (31 Value[caption] @math{|} 58)
1064 The Titles follow the Header and specify the table's title, caption,
1067 The @code{user-title} reflects any user
1068 editing of the title text or style. The @code{title} is the title
1069 originally generated by the procedure. Both of these are appropriate
1070 for presentation and localized to the user's language. For example,
1071 for a frequency table, @code{title} and @code{user-title} normally
1072 name the variable and @code{c} is simply ``Frequencies''.
1074 @code{subtype} is the same as the @code{subType} attribute in the
1075 @code{table} structure XML element that referred to this member.
1076 @xref{SPV Structure table Element}, for details.
1078 The @code{corner-text}, if present, is shown in the upper-left corner
1079 of the table, above the row headings and to the left of the column
1080 headings. It is usually absent. When row dimension labels are
1081 displayed in the corner (see @code{show-row-labels-in-corner}), corner
1084 The @code{caption}, if present, is shown below the table.
1085 @code{caption} reflects user editing of the caption.
1087 @node SPV Light Member Footnotes
1088 @subsection Footnotes
1091 Footnotes => int32[n-footnotes] Footnote*[n-footnotes]
1092 Footnote => Value[text] (58 @math{|} 31 Value[marker]) int32[show]
1095 Each footnote has @code{text} and an optional custom @code{marker}
1098 The syntax for Value would allow footnotes (and their markers) to
1099 reference other footnotes, but in practice this doesn't work.
1101 @code{show} is a 32-bit signed integer. It is positive to show the
1102 footnote or negative to hide it. Its magnitude is often 1, and in
1103 other cases tends to be the number of references to the footnote.
1104 It is safe to write 1 to show a footnote and -1 to hide it.
1106 @node SPV Light Member Areas
1113 string[typeface] float[size] int32[style] bool[underline]
1114 int32[halign] int32[valign]
1115 string[fg-color] string[bg-color]
1116 bool[alternate] string[alt-fg-color] string[alt-bg-color]
1117 v3(int32[left-margin] int32[right-margin] int32[top-margin] int32[bottom-margin])
1120 Each Area represents the style for a different area of the table, in
1121 the following order: title, caption, footer, corner, column labels,
1122 row labels, data, and layers.
1124 @code{index} is the 1-based index of the Area, i.e.@: 1 for the first
1125 Area, through 8 for the final Area.
1127 @code{typeface} is the string name of the font used in the area. In
1128 the corpus, this is @code{SansSerif} in over 99% of instances and
1129 @code{Times New Roman} in the rest.
1131 @code{size} is the size of the font, in px (@pxref{SPV Light Detail
1132 Member Format}). The most common size in the corpus is 12 px. Even
1133 though @code{size} has a floating-point type, in the corpus its values
1134 are always integers.
1136 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
1137 1 (with value 2) is set for italic.
1139 @code{underline} is 1 if the font is underlined, 0 otherwise.
1141 @code{halign} specifies horizontal alignment: 0 for center, 2 for
1142 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
1143 alignment varies according to type: string data is left-justified,
1144 numbers and most other formats are right-justified.
1146 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1149 @code{fg-color} and @code{bg-color} are the foreground color and
1150 background color, respectively. In the corpus, these are always
1151 @code{#000000} and @code{#ffffff}, respectively.
1153 @code{alternate} is 1 if rows should alternate colors, 0 if all rows
1154 should be the same color. When @code{alternate} is 1,
1155 @code{alt-fg-color} and @code{alt-bg-color} specify the colors for the
1156 alternate rows; otherwise they are empty strings.
1158 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1159 @code{bottom-margin} are measured in px.
1161 @node SPV Light Member Borders
1168 be32[n-borders] Border*[n-borders]
1169 bool[show-grid-lines]
1178 The Borders reflect how borders between regions are drawn.
1180 The fixed value of @code{endian} can be used to validate the
1183 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
1185 Each Border describes one kind of border. @code{n-borders} seems to
1186 always be 19. Each @code{border-type} appears once (although in an
1187 unpredictable order) and correspond to the following borders:
1193 Left, top, right, and bottom outer frame.
1195 Left, top, right, and bottom inner frame.
1197 Left and top of data area.
1199 Horizontal and vertical dimension rows.
1201 Horizontal and vertical dimension columns.
1203 Horizontal and vertical category rows.
1205 Horizontal and vertical category columns.
1208 @code{stroke-type} describes how a border is drawn, as one of:
1225 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
1226 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
1227 opaque color, therefore opaque black is 0xff000000.
1229 @node SPV Light Member Print Settings
1230 @subsection Print Settings
1237 bool[paginate-layers]
1240 bool[top-continuation]
1241 bool[bottom-continuation]
1242 be32[n-orphan-lines]
1243 bestring[continuation-string])
1246 The PrintSettings reflect settings for printing. The fixed value of
1247 @code{endian} can be used to validate the endianness.
1249 @code{all-layers} is 1 to print all layers, 0 to print only the layer
1250 designated by @code{current-layer} in TableSettings (@pxref{SPV Light
1251 Member Table Settings}).
1253 @code{paginate-layers} is 1 to print each layer at the start of a new
1254 page, 0 otherwise. (This setting is honored only @code{all-layers} is
1255 1, since otherwise only one layer is printed.)
1257 @code{fit-width} and @code{fit-length} control whether the table is
1258 shrunk to fit within a page's width or length, respectively.
1260 @code{n-orphan-lines} is the minimum number of rows or columns to put
1261 in one part of a table that is broken across pages.
1263 If @code{top-continuation} is 1, then @code{continuation-string} is
1264 printed at the top of a page when a table is broken across pages for
1265 printing; similarly for @code{bottom-continuation} and the bottom of a
1266 page. Usually, @code{continuation-string} is empty.
1268 @node SPV Light Member Table Settings
1269 @subsection Table Settings
1279 bool[show-row-labels-in-corner]
1280 bool[show-alphabetic-markers]
1281 bool[footnote-marker-superscripts]
1284 Breakpoints[row-breaks] Breakpoints[column-breaks]
1285 Keeps[row-keeps] Keeps[column-keeps]
1286 PointKeeps[row-point-keeps] PointKeeps[column-point-keeps]
1289 bestring[table-look]
1292 Breakpoints => be32[n-breaks] be32*[n-breaks]
1294 Keeps => be32[n-keeps] Keep*[n-keeps]
1295 Keep => be32[offset] be32[n]
1297 PointKeeps => be32[n-point-keeps] PointKeep*[n-point-keeps]
1298 PointKeep => be32[offset] be32 be32
1301 The TableSettings reflect display settings. The fixed value of
1302 @code{endian} can be used to validate the endianness.
1304 @code{current-layer} is the displayed layer. Suppose there are
1305 @math{d} layers, numbered 1 through @math{d} in the order given in the
1306 Dimensions (@pxref{SPV Light Member Dimensions}), and that the
1307 displayed value of dimension @math{i} is @math{d_i}, @math{0 \le x_i <
1308 n_i}, where @math{n_i} is the number of categories in dimension
1309 @math{i}. Then @code{current-layer} is calculated by the following
1313 let @code{current-layer} = 0
1314 for each @math{i} from @math{d} downto 1:
1315 @code{current-layer} = (@math{n_i \times} @code{current-layer}) @math{+} @math{x_i}
1318 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
1319 any cell) are hidden; otherwise, they are shown.
1321 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
1322 the upper left corner; otherwise, they are shown nested.
1324 If @code{show-alphabetic-markers} is 1, markers are shown as letters
1325 (e.g.@: @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
1326 shown as numbers starting from 1.
1328 When @code{footnote-marker-superscripts} is 1, footnote markers are shown
1329 as superscripts, otherwise as subscripts.
1331 The Breakpoints are rows or columns after which there is a page break;
1332 for example, a row break of 1 requests a page break after the second
1333 row. Usually no breakpoints are specified, indicating that page
1334 breaks should be selected automatically.
1336 The Keeps are ranges of rows or columns to be kept together without a
1337 page break; for example, a row Keep with @code{offset} 1 and @code{n}
1338 10 requests that the 10 rows starting with the second row be kept
1339 together. Usually no Keeps are specified.
1341 The PointKeeps seem to be generated automatically based on
1342 user-specified Keeps. They seems to indicate a conversion from rows
1343 or columns to pixel or point offsets.
1345 @code{notes} is a text string that contains user-specified notes. It
1346 is displayed when the user hovers the cursor over the table, like text
1347 in the @code{title} attribute in HTML@. It is not printed. It is
1350 @code{table-look} is the name of a SPSS ``TableLook'' table style,
1351 such as ``Default'' or ``Academic''; it is often empty.
1353 TableSettings ends with an arbitrary number of null bytes. A writer
1354 may safely write 82 null bytes.
1356 A writer may safely use 4 for @code{x5} and 0 for @code{x6}.
1358 @node SPV Light Member Formats
1363 int32[n-widths] int32*[n-widths]
1365 int32[current-layer]
1366 bool[x7] bool[x8] bool[x9]
1371 v3(count(X1 count(X2)) count(X3)))
1372 Y0 => int32[epoch] byte[decimal] byte[grouping]
1373 CustomCurrency => int32[n-ccs] string*[n-ccs]
1376 If @code{n-widths} is nonzero, then the accompanying integers are
1377 column widths as manually adjusted by the user.
1379 @code{locale} is a locale including an encoding, such as
1380 @code{en_US.windows-1252} or @code{it_IT.windows-1252}.
1381 (@code{locale} is often duplicated in Y1, described below).
1383 @code{epoch} is the year that starts the epoch. A 2-digit year is
1384 interpreted as belonging to the 100 years beginning at the epoch. The
1385 default epoch year is 69 years prior to the current year; thus, in
1386 2017 this field by default contains 1948. In the corpus, @code{epoch}
1387 ranges from 1943 to 1948, plus some contain -1.
1389 @code{decimal} is the decimal point character. The observed values
1390 are @samp{.} and @samp{,}.
1392 @code{grouping} is the grouping character. Usually, it is @samp{,} if
1393 @code{decimal} is @samp{.}, and vice versa. Other observed values are
1394 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1395 indicating that digits should not be grouped).
1397 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
1398 following strings are CCA through CCE format strings. @xref{Custom
1399 Currency Formats,,, pspp, PSPP}. Most commonly these are all
1400 @code{-,,,} but other strings occur.
1402 A writer may safely use false for @code{x7}, @code{x8}, and @code{x9}.
1406 X0 only appears, optionally, in version 1 members.
1411 string[command] string[command-local]
1412 string[language] string[charset] string[locale]
1415 Y2 => CustomCurrency byte[missing] bool[x17]
1418 @code{command} describes the statistical procedure that generated the
1419 output, in English. It is not necessarily the literal syntax name of
1420 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1421 Tests.'' @code{command-local} is the procedure's name, translated
1422 into the output language; it is often empty and, when it is not,
1423 sometimes the same as @code{command}.
1425 @code{missing} is the character used to indicate that a cell contains
1426 a missing value. It is always observed as @samp{.}.
1428 A writer may safely use false for @code{x17}.
1432 X1 only appears in version 3 members.
1440 byte[show-variables]
1442 int32[x18] int32[x19]
1448 @code{lang} may indicate the language in use. Some values seem to be
1449 0: @t{en}, 1: @t{de}, 2: @t{es}, 3: @t{it}, 5: @t{ko}, 6: @t{pl}, 8:
1450 @t{zh-tw}, 10: @t{pt_BR}, 11: @t{fr}.
1452 @code{show-variables} determines how variables are displayed by
1453 default. A value of 1 means to display variable names, 2 to display
1454 variable labels when available, 3 to display both (name followed by
1455 label, separated by a space). The most common value is 0, which
1456 probably means to use a global default.
1458 @code{show-values} is a similar setting for values. A value of 1
1459 means to display the value, 2 to display the value label when
1460 available, 3 to display both. Again, the most common value is 0,
1461 which probably means to use a global default.
1463 @code{show-title} is 1 to show the caption, 10 to hide it.
1465 @code{show-caption} is true to show the caption, false to hide it.
1467 A writer may safely use false for @code{x14}, false for @code{x16}, 0
1468 for @code{lang}, -1 for @code{x18} and @code{x19}, and false for
1473 X2 only appears in version 3 members.
1477 int32[n-row-heights] int32*[n-row-heights]
1478 int32[n-style-map] StyleMap*[n-style-map]
1479 int32[n-styles] StylePair*[n-styles]
1481 StyleMap => int64[cell-index] int16[style-index]
1484 If present, @code{n-row-heights} and the accompanying integers are row
1485 heights as manually adjusted by the user.
1487 The rest of X2 specifies styles for data cells. At first glance this
1488 is odd, because each data cell can have its own style embedded as part
1489 of the data, but in practice X2 specifies a style for a cell only if
1490 that cell is empty (and thus does not appear in the data at all).
1491 Each StyleMap specifies the index of a blank cell, calculated the same
1492 was as in the Cells (@pxref{SPV Light Member Cells}), along with a
1493 0-based index into the accompanying StylePair array.
1495 A writer may safely omit the optional @code{i0 i0} inside the
1496 @code{count(@dots{})}.
1500 X3 only appears in version 3 members.
1504 01 00 byte[x21] 00 00 00
1507 (string[dataset] string[datafile] i0 int32[date] i0)?
1512 @code{small} is a small real number. In the corpus, it overwhelmingly
1513 takes the value 0.0001, with zero occasionally seen. Nonzero numbers
1514 with format 40 (@pxref{SPV Light Member Value}) whose magnitudes are
1515 smaller than displayed in scientific notation. (Thus, a @code{small}
1516 of zero prevents scientific notation from being chosen.)
1518 @code{dataset} is the name of the dataset analyzed to produce the
1519 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1520 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}. The latter
1521 is sometimes the empty string.
1523 @code{date} is a date, as seconds since the epoch, i.e.@: since
1524 January 1, 1970. Pivot tables within an SPV file often have dates a
1525 few minutes apart, so this is probably a creation date for the table
1526 rather than for the file.
1528 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1529 and other times they are absent. The reader can distinguish by
1530 assuming that they are present and then checking whether the
1531 presumptive @code{dataset} contains a null byte (a valid string never
1534 @code{x22} is usually 0 or 2000000.
1536 A writer may safely use 4 for @code{x21} and omit @code{x22} and the
1537 other optional bytes at the end.
1539 @subsubheading Encoding
1541 Formats contains several indications of character encoding:
1545 @code{locale} in Formats itself.
1548 @code{locale} in Y1 (in version 1, Y1 is optionally nested inside X0;
1549 in version 3, Y1 is nested inside X3).
1552 @code{charset} in version 3, in Y1.
1555 @code{lang} in X1, in version 3.
1558 @code{charset}, if present, is a good indication of character
1559 encoding, and in its absence the encoding suffix on @code{locale} in
1562 @code{locale} in Y1 can be disregarded: it is normally the same as
1563 @code{locale} in Formats, and it is only present if @code{charset} is
1566 @code{lang} is not helpful and should be ignored for character
1569 However, the corpus contains many examples of light members whose
1570 strings are encoded in UTF-8 despite declaring some other character
1571 set. Furthermore, the corpus contains several examples of light
1572 members in which some strings are encoded in UTF-8 (and contain
1573 multibyte characters) and other strings are encoded in another
1574 character set (and contain non-ASCII characters). PSPP treats any
1575 valid UTF-8 string as UTF-8 and only falls back to the declared
1576 encoding for strings that are not valid UTF-8.
1578 The @command{pspp-output} program's @command{strings} command can help
1579 analyze the encoding in an SPV light member. Use @code{pspp-output
1580 --help-dev} to see its usage.
1582 @node SPV Light Member Dimensions
1583 @subsection Dimensions
1585 A pivot table presents multidimensional data. A Dimension identifies
1586 the categories associated with each dimension.
1589 Dimensions => int32[n-dims] Dimension*[n-dims]
1591 Value[name] DimProperties
1592 int32[n-categories] Category*[n-categories]
1597 bool[hide-dim-label]
1598 bool[hide-all-labels]
1602 @code{name} is the name of the dimension, e.g.@: @code{Variables},
1603 @code{Statistics}, or a variable name.
1605 The meanings of @code{x1} and @code{x3} are unknown. @code{x1} is
1606 usually 0 but many other values have been observed. A writer may
1607 safely use 0 for @code{x1} and 2 for @code{x3}.
1609 @code{x2} is 0, 1, or 2. For a pivot table with @var{L} layer
1610 dimensions, @var{R} row dimensions, and @var{C} column dimensions,
1611 @code{x2} is 2 for the first @var{L} dimensions, 0 for the next
1612 @var{R} dimensions, and 1 for the remaining @var{C} dimensions. This
1613 does not mean that the layer dimensions must be presented first,
1614 followed by the row dimensions, followed by the column dimensions---on
1615 the contrary, they are frequently in a different order---but @code{x2}
1616 must follow this pattern to prevent the pivot table from being
1619 If @code{hide-dim-label} is 00, the pivot table displays a label for
1620 the dimension itself. Because usually the group and category labels
1621 are enough explanation, it is usually 01.
1623 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1624 the dimension, including group and category labels. It is usually 00.
1625 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1627 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1628 0 for the first dimension, 1 for the second, and so on. Sometimes it
1629 is -1. There is no visible difference. A writer may safely use the
1632 @node SPV Light Member Categories
1633 @subsection Categories
1635 Categories are arranged in a tree. Only the leaf nodes in the tree
1636 are really categories; the others just serve as grouping constructs.
1639 Category => Value[name] (Leaf @math{|} Group)
1640 Leaf => 00 00 00 i2 int32[leaf-index] i0
1642 bool[merge] 00 01 int32[x23]
1643 i-1 int32[n-subcategories] Category*[n-subcategories]
1646 @code{name} is the name of the category (or group).
1648 A Leaf represents a leaf category. The Leaf's @code{leaf-index} is a
1649 nonnegative integer unique within the Dimension and less than
1650 @code{n-categories} in the Dimension. If the user does not sort or
1651 rearrange the categories, then @code{leaf-index} starts at 0 for the
1652 first Leaf in the dimension and increments by 1 with each successive
1653 Leaf. If the user does sorts or rearrange the categories, then the
1654 order of categories in the file reflects that change and
1655 @code{leaf-index} reflects the original order.
1657 A dimension can have no leaf categories at all. A table that
1658 contains such a dimension necessarily has no data at all.
1660 A Group is a group of nested categories. Usually a Group contains at
1661 least one Category, so that @code{n-subcategories} is positive, but
1662 Groups with zero subcategories have been observed.
1664 If a Group's @code{merge} is 00, the most common value, then the group
1665 is really a distinct group that should be represented as such in the
1666 visual representation and user interface. If @code{merge} is 01, the
1667 categories in this group should be shown and treated as if they were
1668 direct children of the group's containing group (or if it has no
1669 parent group, then direct children of the dimension), and this group's
1670 name is irrelevant and should not be displayed. (Merged groups can be
1673 Writers need not use merged groups.
1675 A Group's @code{x23} appears to be i2 when all of the categories
1676 within a group are leaf categories that directly represent data values
1677 for a variable (e.g.@: in a frequency table or crosstabulation, a group
1678 of values in a variable being tabulated) and i0 otherwise. A writer
1679 may safely write a constant 0 in this field.
1681 @node SPV Light Member Axes
1684 After the dimensions come assignment of each dimension to one of the
1685 axes: layers, rows, and columns.
1689 int32[n-layers] int32[n-rows] int32[n-columns]
1690 int32*[n-layers] int32*[n-rows] int32*[n-columns]
1693 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1694 each specifies the number of dimensions displayed in layers, rows, and
1695 columns, respectively. Any of them may be zero. Their values sum to
1696 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1699 The following @code{n-dimensions} integers, in three groups, are a
1700 permutation of the 0-based dimension numbers. The first
1701 @code{n-layers} integers specify each of the dimensions represented by
1702 layers, the next @code{n-rows} integers specify the dimensions
1703 represented by rows, and the final @code{n-columns} integers specify
1704 the dimensions represented by columns. When there is more than one
1705 dimension of a given kind, the inner dimensions are given first. (For
1706 the layer axis, this means that the first dimension is at the bottom
1707 of the list and the last dimension is at the top when the current
1708 layer is displayed.)
1710 @node SPV Light Member Cells
1713 The final part of an SPV light member contains the actual data.
1716 Cells => int32[n-cells] Cell*[n-cells]
1717 Cell => int64[index] v1(00?) Value
1720 A Cell consists of an @code{index} and a Value. Suppose there are
1721 @math{d} dimensions, numbered 1 through @math{d} in the order given in
1722 the Dimensions previously, and that dimension @math{i} has @math{n_i}
1723 categories. Consider the cell at coordinates @math{x_i}, @math{1 \le
1724 i \le d}, and note that @math{0 \le x_i < n_i}. Then the index is
1725 calculated by the following algorithm:
1729 for each @math{i} from 1 to @math{d}:
1730 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1733 For example, suppose there are 3 dimensions with 3, 4, and 5
1734 categories, respectively. The cell at coordinates (1, 2, 3) has
1735 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1736 Within a given dimension, the index is the @code{leaf-index} in a Leaf.
1738 @node SPV Light Member Value
1741 Value is used throughout the SPV light member format. It boils down
1742 to a number or a string.
1745 Value => 00? 00? 00? 00? RawValue
1747 01 ValueMod int32[format] double[x]
1748 @math{|} 02 ValueMod int32[format] double[x]
1749 string[var-name] string[value-label] byte[show]
1750 @math{|} 03 string[local] ValueMod string[id] string[c] bool[fixed]
1751 @math{|} 04 ValueMod int32[format] string[value-label] string[var-name]
1752 byte[show] string[s]
1753 @math{|} 05 ValueMod string[var-name] string[var-label] byte[show]
1754 @math{|} 06 string[local] ValueMod string[id] string[c]
1755 @math{|} ValueMod string[template] int32[n-args] Argument*[n-args]
1758 @math{|} int32[x] i0 Value*[x] /* x > 0 */
1761 There are several possible encodings, which one can distinguish by the
1762 first nonzero byte in the encoding.
1766 The numeric value @code{x}, intended to be presented to the user
1767 formatted according to @code{format}, which is about the same as the
1768 format described for system files (@pxref{System File Output
1769 Formats}). The exception is that format 40 is not MTIME but instead
1770 approximately a synonym for F format with a different rule for whether
1771 a value is shown in scientific notation: a value in format 40 is shown
1772 in scientific notation if and only if it is nonzero and its magnitude
1773 is less than @code{small} (@pxref{SPV Light Member Formats}).
1775 Most commonly, @code{format} has width 40 (the maximum).
1777 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1778 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1779 not been observed.) See @ref{System File Format}, for more about
1780 these special values.
1783 Similar to @code{01}, with the additional information that @code{x} is
1784 a value of variable @code{var-name} and has value label
1785 @code{value-label}. Both @code{var-name} and @code{value-label} can
1786 be the empty string, the latter very commonly.
1788 @code{show} determines whether to show the numeric value or the value
1789 label. A value of 1 means to show the value, 2 to show the label, 3
1790 to show both, and 0 means to use the default specified in
1791 @code{show-values} (@pxref{SPV Light Member Formats}).
1794 A text string, in two forms: @code{c} is in English, and sometimes
1795 abbreviated or obscure, and @code{local} is localized to the user's
1796 locale. In an English-language locale, the two strings are often the
1797 same, and in the cases where they differ, @code{local} is more
1798 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1799 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1800 where P must be greater than 1.''
1802 @code{c} and @code{local} are always either both empty or both
1805 @code{id} is a brief identifying string whose form seems to resemble a
1806 programming language identifier, e.g.@: @code{cumulative_percent} or
1807 @code{factor_14}. It is not unique.
1809 @code{fixed} is 00 for text taken from user input, such as syntax
1810 fragment, expressions, file names, data set names, and 01 for fixed
1811 text strings such as names of procedures or statistics. In the former
1812 case, @code{id} is always the empty string; in the latter case,
1813 @code{id} is still sometimes empty.
1816 The string value @code{s}, intended to be presented to the user
1817 formatted according to @code{format}. The format for a string is not
1818 too interesting, and the corpus contains many clearly invalid formats
1819 like A16.39 or A255.127 or A134.1, so readers should probably entirely
1820 disregard the format. PSPP only checks @code{format} to distinguish
1823 @code{s} is a value of variable @code{var-name} and has value label
1824 @code{value-label}. @code{var-name} is never empty but
1825 @code{value-label} is commonly empty.
1827 @code{show} has the same meaning as in the encoding for 02.
1830 Variable @code{var-name} with variable label @code{var-label}. In the
1831 corpus, @code{var-name} is rarely empty and @code{var-label} is often
1834 @code{show} determines whether to show the variable name or the
1835 variable label. A value of 1 means to show the name, 2 to show the
1836 label, 3 to show both, and 0 means to use the default specified in
1837 @code{show-variables} (@pxref{SPV Light Member Formats}).
1840 Similar to type 03, with @code{fixed} assumed to be true.
1843 When the first byte of a RawValue is not one of the above, the
1844 RawValue starts with a ValueMod, whose syntax is described in the next
1845 section. (A ValueMod always begins with byte 31 or 58.)
1847 This case is a template string, analogous to @code{printf}, followed
1848 by one or more Arguments, each of which has one or more values. The
1849 template string is copied directly into the output except for the
1850 following special syntax,
1857 Each of these expands to the character following @samp{\\}, to escape
1858 characters that have special meaning in template strings. These are
1859 effective inside and outside the @code{[@dots{}]} syntax forms
1863 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1867 Expands to a formatted version of argument @var{i}, which must have
1868 only a single value. For example, @code{^1} expands to the first
1869 argument's @code{value}.
1871 @item [:@var{a}:]@var{i}
1872 Expands @var{a} for each of the values in @var{i}. @var{a}
1873 should contain one or more @code{^@var{j}} conversions, which are
1874 drawn from the values for argument @var{i} in order. Some examples
1879 All of the values for the first argument, concatenated.
1882 Expands to the values for the first argument, each followed by
1886 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1887 argument's first value and @var{y} is its second value. (This would
1888 be used only if the argument has two values. If there were more
1889 values, the second and third values would be directly concatenated,
1890 which would look funny.)
1893 @item [@var{a}:@var{b}:]@var{i}
1894 This extends the previous form so that the first values are expanded
1895 using @var{a} and later values are expanded using @var{b}. For an
1896 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1897 instead written as @code{%@var{j}}. Some examples from the corpus:
1901 Expands to all of the values for the first argument, separated by
1904 @item [%1 = %2:, ^1 = ^2:]1
1905 Given appropriate values for the first argument, expands to @code{X =
1909 Given appropriate values, expands to @code{1, 2, 3}.
1913 The template string is localized to the user's locale.
1916 A writer may safely omit all of the optional 00 bytes at the beginning
1917 of a Value, except that it should write a single 00 byte before a
1920 @node SPV Light Member ValueMod
1921 @subsection ValueMod
1923 A ValueMod can specify special modifications to a Value.
1929 int32[n-refs] int16*[n-refs]
1930 int32[n-subscripts] string*[n-subscripts]
1931 v1(00 (i1 | i2) 00? 00? int32 00? 00?)
1932 v3(count(TemplateString StylePair))
1934 TemplateString => count((count((i0 (58 @math{|} 31 55))?) (58 @math{|} 31 string[id]))?)
1941 bool[bold] bool[italic] bool[underline] bool[show]
1942 string[fg-color] string[bg-color]
1943 string[typeface] byte[size]
1946 int32[halign] int32[valign] double[decimal-offset]
1947 int16[left-margin] int16[right-margin]
1948 int16[top-margin] int16[bottom-margin]
1951 A ValueMod that begins with ``31'' specifies special modifications to
1954 Each of the @code{n-refs} integers is a reference to a Footnote
1955 (@pxref{SPV Light Member Footnotes}) by 0-based index. Footnote
1956 markers are shown appended to the main text of the Value, as
1957 superscripts or subscripts.
1959 The @code{subscripts}, if present, are strings to append to the main
1960 text of the Value, as subscripts. Each subscript text is a brief
1961 indicator, e.g.@: @samp{a} or @samp{b}, with its meaning indicated by
1962 the table caption. When multiple subscripts are present, they are
1963 displayed separated by commas.
1965 The @code{id} inside the TemplateString, if present, is a template
1966 string for substitutions using the syntax explained previously. It
1967 appears to be an English-language version of the localized template
1968 string in the Value in which the Template is nested. A writer may
1969 safely omit the optional fixed data in TemplateString.
1971 FontStyle and CellStyle, if present, change the style for this
1972 individual Value. In FontStyle, @code{bold}, @code{italic}, and
1973 @code{underline} control the particular style. @code{show} is
1974 ordinarily 1; if it is 0, then the cell data is not shown.
1975 @code{fg-color} and @code{bg-color} are strings in the format
1976 @code{#rrggbb}, e.g.@: @code{#ff0000} for red or @code{#ffffff} for
1977 white. The empty string is occasionally observed also. The
1978 @code{size} is a font size in units of 1/128 inch.
1980 In CellStyle, @code{halign} is 0 for center, 2 for left, 4 for right,
1981 6 for decimal, 0xffffffad for mixed. For decimal alignment,
1982 @code{decimal-offset} is the decimal point's offset from the right
1983 side of the cell, in pt (@pxref{SPV Light Detail Member Format}).
1984 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1985 for bottom. @code{left-margin}, @code{right-margin},
1986 @code{top-margin}, and @code{bottom-margin} are in pt.
1988 @node SPV Legacy Detail Member Binary Format
1989 @section Legacy Detail Member Binary Format
1991 Whereas the light binary format represents everything about a given
1992 pivot table, the legacy binary format conceptually consists of a
1993 number of named sources, each of which consists of a number of named
1994 variables, each of which is a 1-dimensional array of numbers or
1995 strings or a mix. Thus, the legacy binary member format is quite
1998 This section uses the same context-free grammar notation as in the
1999 previous section, with the following additions:
2003 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
2004 (The legacy member header indicates the version; see below.)
2007 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
2010 A legacy detail member @file{.bin} has the following overall format:
2014 00 byte[version] int16[n-sources] int32[member-size]
2015 Metadata*[n-sources]
2020 @code{version} is a version number that affects the interpretation of
2021 some of the other data in the member. Versions 0xaf and 0xb0 are
2022 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
2025 A legacy member consists of @code{n-sources} data sources, each of
2026 which has Metadata and Data.
2028 @code{member-size} is the size of the legacy binary member, in bytes.
2030 The Data and Strings above are commented out because the Metadata has
2031 some oddities that mean that the Data sometimes seems to start at
2032 an unexpected place. The following section goes into detail.
2035 * SPV Legacy Member Metadata::
2036 * SPV Legacy Member Numeric Data::
2037 * SPV Legacy Member String Data::
2040 @node SPV Legacy Member Metadata
2041 @subsection Metadata
2045 int32[n-values] int32[n-variables] int32[data-offset]
2046 vAF(byte*28[source-name])
2047 vB0(byte*64[source-name] int32[x])
2050 A data source has @code{n-variables} variables, each with
2051 @code{n-values} data values.
2053 @code{source-name} is a 28- or 64-byte string padded on the right with
2054 0-bytes. The names that appear in the corpus are very generic:
2055 usually @code{tableData} for pivot table data or @code{source0} for
2058 A given Metadata's @code{data-offset} is the offset, in bytes, from
2059 the beginning of the member to the start of the corresponding Data.
2060 This allows programs to skip to the beginning of the data for a
2061 particular source. In every case in the corpus, the Data follow the
2062 Metadata in the same order, but it is important to use
2063 @code{data-offset} instead of reading sequentially through the file
2064 because of the exception described below.
2066 One SPV file in the corpus has legacy binary members with version 0xb0
2067 but a 28-byte @code{source-name} field (and only a single source). In
2068 practice, this means that the 64-byte @code{source-name} used in
2069 version 0xb0 has a lot of 0-bytes in the middle followed by the
2070 @code{variable-name} of the following Data. As long as a reader
2071 treats the first 0-byte in the @code{source-name} as terminating the
2072 string, it can properly interpret these members.
2074 The meaning of @code{x} in version 0xb0 is unknown.
2076 @node SPV Legacy Member Numeric Data
2077 @subsection Numeric Data
2080 Data => Variable*[n-variables]
2081 Variable => byte*288[variable-name] double*[n-values]
2084 Data follow the Metadata in the legacy binary format, with sources in
2085 the same order (but readers should use the @code{data-offset} in
2086 Metadata records, rather than reading sequentially). Each Variable
2087 begins with a @code{variable-name} that generally indicates its role
2088 in the pivot table, e.g.@: ``cell'', ``cellFormat'',
2089 ``dimension0categories'', ``dimension0group0'', followed by the
2090 numeric data, one double per datum. A double with the maximum
2091 negative double @code{-DBL_MAX} represents the system-missing value
2094 @node SPV Legacy Member String Data
2095 @subsection String Data
2098 Strings => SourceMaps[maps] Labels
2100 SourceMaps => int32[n-maps] SourceMap*[n-maps]
2102 SourceMap => string[source-name] int32[n-variables] VariableMap*[n-variables]
2103 VariableMap => string[variable-name] int32[n-data] DatumMap*[n-data]
2104 DatumMap => int32[value-idx] int32[label-idx]
2106 Labels => int32[n-labels] Label*[n-labels]
2107 Label => int32[frequency] string[label]
2110 Each variable may include a mix of numeric and string data values. If
2111 a legacy binary member contains any string data, Strings is present;
2112 otherwise, it ends just after the last Data element.
2114 The string data overlays the numeric data. When a variable includes
2115 any string data, its Variable represents the string values with a
2116 SYSMIS or NaN placeholder. (Not all such values need be
2119 Each SourceMap provides a mapping between SYSMIS or NaN values in source
2120 @code{source-name} and the string data that they represent.
2121 @code{n-variables} is the number of variables in the source that
2122 include string data. More precisely, it is the 1-based index of the
2123 last variable in the source that includes any string data; thus, it
2124 would be 4 if there are 5 variables and only the fourth one includes
2127 A VariableMap repeats its variable's name, but variables are always
2128 present in the same order as the source, starting from the first
2129 variable, without skipping any even if they have no string values.
2130 Each VariableMap contains DatumMap nonterminals, each of which maps
2131 from a 0-based index within its variable's data to a 0-based label
2132 index, e.g.@: pair @code{value-idx} = 2, @code{label-idx} = 3, means
2133 that the third data value (which must be SYSMIS or NaN) is to be
2134 replaced by the string of the fourth Label.
2136 The labels themselves follow the pairs. The valuable part of each
2137 label is the string @code{label}. Each label also includes a
2138 @code{frequency} that reports the number of DatumMaps that reference
2139 it (although this is not useful).
2141 @node SPV Legacy Detail Member XML Format
2142 @section Legacy Detail Member XML Format
2144 The design of the detail XML format is not what one would end up with
2145 for describing pivot tables. This is because it is a special case
2146 of a much more general format (``visualization XML'' or ``VizML'')
2147 that can describe a wide range of visualizations. Most of this
2148 generality is overkill for tables, and so we end up with a funny
2149 subset of a general-purpose format.
2151 An XML Schema for VizML is available, distributed with SPSS binaries,
2152 under a nonfree license. It contains documentation that is
2153 occasionally helpful.
2155 This section describes the detail XML format using the same notation
2156 already used for the structure XML format (@pxref{SPV Structure Member
2157 Format}). See @file{src/output/spv/detail-xml.grammar} in the PSPP
2158 source tree for the full grammar that it uses for parsing.
2160 The important elements of the detail XML format are:
2164 Variables. @xref{SPV Detail Variable Elements}.
2167 Assignment of variables to axes. A variable can appear as columns, or
2168 rows, or layers. The @code{faceting} element and its sub-elements
2169 describe this assignment.
2172 Styles and other annotations.
2175 This description is not detailed enough to write legacy tables.
2176 Instead, write tables in the light binary format.
2179 * SPV Detail visualization Element::
2180 * SPV Detail Variable Elements::
2181 * SPV Detail extension Element::
2182 * SPV Detail graph Element::
2183 * SPV Detail location Element::
2184 * SPV Detail faceting Element::
2185 * SPV Detail facetLayout Element::
2186 * SPV Detail label Element::
2187 * SPV Detail setCellProperties Element::
2188 * SPV Detail setFormat Element::
2189 * SPV Detail interval Element::
2190 * SPV Detail style Element::
2191 * SPV Detail labelFrame Element::
2192 * SPV Detail Legacy Properties::
2195 @node SPV Detail visualization Element
2196 @subsection The @code{visualization} Element
2204 :style[style_ref]=ref style
2208 => visualization_extension?
2210 (sourceVariable | derivedVariable)+
2219 extension[visualization_extension]
2222 :minWidthSet=(true)?
2223 :maxWidthSet=(true)?
2226 userSource :missing=(listwise | pairwise)? => EMPTY
2228 categoricalDomain => variableReference simpleSort
2230 simpleSort :method[sort_method]=(custom) => categoryOrder
2232 container :style=ref style => container_extension? location+ labelFrame*
2234 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2242 The @code{visualization} element is the root of detail XML member. It
2243 has the following attributes:
2245 @defvr {Attribute} creator
2246 The version of the software that created this SPV file, as a string of
2247 the form @code{xxyyzz}, which represents software version xx.yy.zz,
2248 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
2249 versions 16 through 19.
2252 @defvr {Attribute} date
2253 The date on the which the file was created, as a string of the form
2257 @defvr {Attribute} lang
2258 The locale used for output, in Windows format, which is similar to the
2259 format used in Unix with the underscore replaced by a hyphen, e.g.@:
2260 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
2263 @defvr {Attribute} name
2264 The title of the pivot table, localized to the output language.
2267 @defvr {Attribute} style
2268 The base style for the pivot table. In every example in the corpus,
2269 the @code{style} element has no attributes other than @code{id}.
2272 @defvr {Attribute} type
2273 A floating-point number. The meaning is unknown.
2276 @defvr {Attribute} version
2277 The visualization schema version number. In the corpus, the value is
2278 one of 2.4, 2.5, 2.7, and 2.8.
2281 The @code{userSource} element has no visible effect.
2283 The @code{extension} element as a child of @code{visualization} has
2284 the following attributes.
2286 @defvr {Attribute} numRows
2287 An integer that presumably defines the number of rows in the displayed
2291 @defvr {Attribute} showGridline
2292 Always set to @code{false} in the corpus.
2295 @defvr {Attribute} minWidthSet
2296 @defvrx {Attribute} maxWidthSet
2297 Always set to @code{true} in the corpus.
2300 The @code{extension} element as a child of @code{container} has the
2303 @defvr {Attribute} combinedFootnotes
2307 The @code{categoricalDomain} and @code{simpleSort} elements have no
2310 The @code{layerController} element has no visible effect.
2312 @node SPV Detail Variable Elements
2313 @subsection Variable Elements
2315 A ``variable'' in detail XML is a 1-dimensional array of data. Each
2316 element of the array may, independently, have string or numeric
2317 content. All of the variables in a given detail XML member either
2318 have the same number of elements or have zero elements.
2320 Two different elements define variables and their content:
2323 @item sourceVariable
2324 These variables' data comes from the associated @code{tableData.bin}
2327 @item derivedVariable
2328 These variables are defined in terms of a mapping function from a
2329 source variable, or they are empty.
2332 A variable named @code{cell} always exists. This variable holds the
2333 data displayed in the table.
2335 Variables in detail XML roughly correspond to the dimensions in a
2336 light detail member. Each dimension has the following variables with
2337 stylized names, where @var{n} is a number for the dimension starting
2341 @item dimension@var{n}categories
2342 The dimension's leaf categories (@pxref{SPV Light Member Categories}).
2344 @item dimension@var{n}group0
2345 Present only if the dimension's categories are grouped, this variable
2346 holds the group labels for the categories. Grouping is inferred
2347 through adjacent identical labels. Categories that are not part of a
2348 group have empty-string data in this variable.
2350 @item dimension@var{n}group1
2351 Present only if the first-level groups are further grouped, this
2352 variable holds the labels for the second-level groups. There can be
2353 additional variables with further levels of grouping.
2355 @item dimension@var{n}
2359 Determining the data for a (non-empty) variable is a multi-step
2364 Draw initial data from its source, for a @code{sourceVariable}, or
2365 from another named variable, for a @code{derivedVariable}.
2368 Apply mappings from @code{valueMapEntry} elements within the
2369 @code{derivedVariable} element, if any.
2372 Apply mappings from @code{relabel} elements within a @code{format} or
2373 @code{stringFormat} element in the @code{sourceVariable} or
2374 @code{derivedVariable} element, if any.
2377 If the variable is a @code{sourceVariable} with a @code{labelVariable}
2378 attribute, and there were no mappings to apply in previous steps, then
2379 replace each element of the variable by the corresponding value in the
2383 A single variable's data can be modified in two of the steps, if both
2384 @code{valueMapEntry} and @code{relabel} are used. The following
2385 example from the corpus maps several integers to 2, then maps 2 in
2386 turn to the string ``Input'':
2389 <derivedVariable categorical="true" dependsOn="dimension0categories"
2390 id="dimension0group0map" value="map(dimension0group0)">
2392 <relabel from="2" to="Input"/>
2393 <relabel from="10" to="Missing Value Handling"/>
2394 <relabel from="14" to="Resources"/>
2395 <relabel from="0" to=""/>
2396 <relabel from="1" to=""/>
2397 <relabel from="13" to=""/>
2399 <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
2400 <valueMapEntry from="10;11" to="10"/>
2401 <valueMapEntry from="14;15" to="14"/>
2402 <valueMapEntry from="0" to="0"/>
2403 <valueMapEntry from="1" to="1"/>
2404 <valueMapEntry from="13" to="13"/>
2409 * SPV Detail sourceVariable Element::
2410 * SPV Detail derivedVariable Element::
2411 * SPV Detail valueMapEntry Element::
2414 @node SPV Detail sourceVariable Element
2415 @subsubsection The @code{sourceVariable} Element
2422 :domain=ref categoricalDomain?
2424 :dependsOn=ref sourceVariable?
2426 :labelVariable=ref sourceVariable?
2427 => variable_extension* (format | stringFormat)?
2430 This element defines a variable whose data comes from the
2431 @file{tableData.bin} member that corresponds to this @file{.xml}.
2433 This element has the following attributes.
2435 @defvr {Attribute} id
2436 An @code{id} is always present because this element exists to be
2437 referenced from other elements.
2440 @defvr {Attribute} categorical
2441 Always set to @code{true}.
2444 @defvr {Attribute} source
2445 Always set to @code{tableData}, the @code{source-name} in the
2446 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
2450 @defvr {Attribute} sourceName
2451 The name of a variable within the source, corresponding to the
2452 @code{variable-name} in the @file{tableData.bin} member (@pxref{SPV
2453 Legacy Member Numeric Data}).
2456 @defvr {Attribute} label
2457 The variable label, if any.
2460 @defvr {Attribute} labelVariable
2461 The @code{variable-name} of a variable whose string values correspond
2462 one-to-one with the values of this variable and are suitable for use
2466 @defvr {Attribute} dependsOn
2467 This attribute doesn't affect the display of a table.
2470 @node SPV Detail derivedVariable Element
2471 @subsubsection The @code{derivedVariable} Element
2478 :dependsOn=ref sourceVariable?
2479 => variable_extension* (format | stringFormat)? valueMapEntry*
2482 Like @code{sourceVariable}, this element defines a variable whose
2483 values can be used elsewhere in the visualization. Instead of being
2484 read from a data source, the variable's data are defined by a
2485 mathematical expression.
2487 This element has the following attributes.
2489 @defvr {Attribute} id
2490 An @code{id} is always present because this element exists to be
2491 referenced from other elements.
2494 @defvr {Attribute} categorical
2495 Always set to @code{true}.
2498 @defvr {Attribute} value
2499 An expression that defines the variable's value. In theory this could
2500 be an arbitrary expression in terms of constants, functions, and other
2501 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
2502 the corpus contains only the following forms of expressions:
2506 @itemx constant(@var{variable})
2507 All zeros. The reason why a variable is sometimes named is unknown.
2508 Sometimes the ``variable name'' has spaces in it.
2510 @item map(@var{variable})
2511 Transforms the values in the named @var{variable} using the
2512 @code{valueMapEntry}s contained within the element.
2516 @defvr {Attribute} dependsOn
2517 This attribute doesn't affect the display of a table.
2520 @node SPV Detail valueMapEntry Element
2521 @subsubsection The @code{valueMapEntry} Element
2524 valueMapEntry :from :to => EMPTY
2527 A @code{valueMapEntry} element defines a mapping from one or more
2528 values of a source expression to a target value. (In the corpus, the
2529 source expression is always just the name of a variable.) Each target
2530 value requires a separate @code{valueMapEntry}. If multiple source
2531 values map to the same target value, they can be combined or separate.
2533 In the corpus, all of the source and target values are integers.
2535 @code{valueMapEntry} has the following attributes.
2537 @defvr {Attribute} from
2538 A source value, or multiple source values separated by semicolons,
2539 e.g.@: @code{0} or @code{13;14;15;16}.
2542 @defvr {Attribute} to
2543 The target value, e.g.@: @code{0}.
2546 @node SPV Detail extension Element
2547 @subsection The @code{extension} Element
2549 This is a general-purpose ``extension'' element. Readers that don't
2550 understand a given extension should be able to safely ignore it. The
2551 attributes on this element, and their meanings, vary based on the
2552 context. Each known usage is described separately below. The current
2553 extensions use attributes exclusively, without any nested elements.
2555 @subsubheading @code{container} Parent Element
2558 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2561 With @code{container} as its parent element, @code{extension} has the
2562 following attributes.
2564 @defvr {Attribute} combinedFootnotes
2565 Always set to @code{true} in the corpus.
2568 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
2571 extension[variable_extension] :from :helpId => EMPTY
2574 With @code{sourceVariable} or @code{derivedVariable} as its parent
2575 element, @code{extension} has the following attributes. A given
2576 parent element often contains several @code{extension} elements that
2577 specify the meaning of the source data's variables or sources, e.g.@:
2580 <extension from="0" helpId="corrected_model"/>
2581 <extension from="3" helpId="error"/>
2582 <extension from="4" helpId="total_9"/>
2583 <extension from="5" helpId="corrected_total"/>
2586 More commonly they are less helpful, e.g.@:
2589 <extension from="0" helpId="notes"/>
2590 <extension from="1" helpId="notes"/>
2591 <extension from="2" helpId="notes"/>
2592 <extension from="5" helpId="notes"/>
2593 <extension from="6" helpId="notes"/>
2594 <extension from="7" helpId="notes"/>
2595 <extension from="8" helpId="notes"/>
2596 <extension from="12" helpId="notes"/>
2597 <extension from="13" helpId="no_help"/>
2598 <extension from="14" helpId="notes"/>
2601 @defvr {Attribute} from
2602 An integer or a name like ``dimension0''.
2605 @defvr {Attribute} helpId
2609 @node SPV Detail graph Element
2610 @subsection The @code{graph} Element
2614 :cellStyle=ref style
2616 => location+ coordinates faceting facetLayout interval
2618 coordinates => EMPTY
2621 @code{graph} has the following attributes.
2623 @defvr {Attribute} cellStyle
2624 @defvrx {Attribute} style
2625 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
2626 Detail style Element}). The former is the default style for
2627 individual cells, the latter for the entire table.
2630 @node SPV Detail location Element
2631 @subsection The @code{location} Element
2635 :part=(height | width | top | bottom | left | right)
2636 :method=(sizeToContent | attach | fixed | same)
2639 :target=ref (labelFrame | graph | container)?
2644 Each instance of this element specifies where some part of the table
2645 frame is located. All the examples in the corpus have four instances
2646 of this element, one for each of the parts @code{height},
2647 @code{width}, @code{left}, and @code{top}. Some examples in the
2648 corpus add a fifth for part @code{bottom}, even though it is not clear
2649 how all of @code{top}, @code{bottom}, and @code{height} can be honored
2650 at the same time. In any case, @code{location} seems to have little
2651 importance in representing tables; a reader can safely ignore it.
2653 @defvr {Attribute} part
2654 The part of the table being located.
2657 @defvr {Attribute} method
2658 How the location is determined:
2662 Based on the natural size of the table. Observed only for
2663 parts @code{height} and @code{width}.
2666 Based on the location specified in @code{target}. Observed only for
2667 parts @code{top} and @code{bottom}.
2670 Using the value in @code{value}. Observed only for parts @code{top},
2671 @code{bottom}, and @code{left}.
2674 Same as the specified @code{target}. Observed only for part
2679 @defvr {Attribute} min
2680 Minimum size. Only observed with value @code{100pt}. Only observed
2681 for part @code{width}.
2684 @defvr {Dependent} target
2685 Required when @code{method} is @code{attach} or @code{same}, not
2686 observed otherwise. This identifies an element to attach to.
2687 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
2691 @defvr {Dependent} value
2692 Required when @code{method} is @code{fixed}, not observed otherwise.
2693 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
2694 on parts @code{top} and @code{left}, and @code{100%} on part
2698 @node SPV Detail faceting Element
2699 @subsection The @code{faceting} Element
2702 faceting => layer[layers1]* cross layer[layers2]*
2704 cross => (unity | nest) (unity | nest)
2708 nest => variableReference[vars]+
2710 variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY
2713 :variable=ref (sourceVariable | derivedVariable)
2716 :method[layer_method]=(nest)?
2721 The @code{faceting} element describes the row, column, and layer
2722 structure of the table. Its @code{cross} child determines the row and
2723 column structure, and each @code{layer} child (if any) represents a
2724 layer. Layers may appear before or after @code{cross}.
2726 The @code{cross} element describes the row and column structure of the
2727 table. It has exactly two children, the first of which describes the
2728 table's columns and the second the table's rows. Each child is a
2729 @code{nest} element if the table has any dimensions along the axis in
2730 question, otherwise a @code{unity} element.
2732 A @code{nest} element contains of one or more dimensions listed from
2733 innermost to outermost, each represented by @code{variableReference}
2734 child elements. Each variable in a dimension is listed in order.
2735 @xref{SPV Detail Variable Elements}, for information on the variables
2736 that comprise a dimension.
2738 A @code{nest} can contain a single dimension, e.g.:
2742 <variableReference ref="dimension0categories"/>
2743 <variableReference ref="dimension0group0"/>
2744 <variableReference ref="dimension0"/>
2749 A @code{nest} can contain multiple dimensions, e.g.:
2753 <variableReference ref="dimension1categories"/>
2754 <variableReference ref="dimension1group0"/>
2755 <variableReference ref="dimension1"/>
2756 <variableReference ref="dimension0categories"/>
2757 <variableReference ref="dimension0"/>
2761 A @code{nest} may have no dimensions, in which case it still has one
2762 @code{variableReference} child, which references a
2763 @code{derivedVariable} whose @code{value} attribute is
2764 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
2765 @code{row} or @code{column}, respectively, as its @code{id}. This is
2766 equivalent to using a @code{unity} element in place of @code{nest}.
2768 A @code{variableReference} element refers to a variable through its
2769 @code{ref} attribute.
2771 Each @code{layer} element represents a dimension, e.g.:
2774 <layer value="0" variable="dimension0categories" visible="true"/>
2775 <layer value="dimension0" variable="dimension0" visible="false"/>
2779 @code{layer} has the following attributes.
2781 @defvr {Attribute} variable
2782 Refers to a @code{sourceVariable} or @code{derivedVariable} element.
2785 @defvr {Attribute} value
2786 The value to select. For a category variable, this is always
2787 @code{0}; for a data variable, it is the same as the @code{variable}
2791 @defvr {Attribute} visible
2792 Whether the layer is visible. Generally, category layers are visible
2793 and data layers are not, but sometimes this attribute is omitted.
2796 @defvr {Attribute} method
2797 When present, this is always @code{nest}.
2800 @node SPV Detail facetLayout Element
2801 @subsection The @code{facetLayout} Element
2804 facetLayout => tableLayout setCellProperties[scp1]*
2805 facetLevel+ setCellProperties[scp2]*
2808 :verticalTitlesInCorner=bool
2810 :fitCells=(ticks both)?
2814 The @code{facetLayout} element and its descendants control styling for
2817 Its @code{tableLayout} child has the following attributes
2819 @defvr {Attribute} verticalTitlesInCorner
2820 If true, in the absence of corner text, row headings will be displayed
2824 @defvr {Attribute} style
2825 Refers to a @code{style} element.
2828 @defvr {Attribute} fitCells
2832 @subsubheading The @code{facetLevel} Element
2835 facetLevel :level=int :gap=dimension? => axis
2837 axis :style=ref style => label? majorTicks
2843 :tickFrameStyle=ref style
2844 :labelFrequency=int?
2854 Each @code{facetLevel} describes a @code{variableReference} or
2855 @code{layer}, and a table has one @code{facetLevel} element for
2856 each such element. For example, an SPV detail member that contains
2857 four @code{variableReference} elements and two @code{layer} elements
2858 will contain six @code{facetLevel} elements.
2860 In the corpus, @code{facetLevel} elements and the elements that they
2861 describe are always in the same order. The correspondence may also be
2862 observed in two other ways. First, one may use the @code{level}
2863 attribute, described below. Second, in the corpus, a
2864 @code{facetLevel} always has an @code{id} that is the same as the
2865 @code{id} of the element it describes with @code{_facetLevel}
2866 appended. One should not formally rely on this, of course, but it is
2867 usefully indicative.
2869 @defvr {Attribute} level
2870 A 1-based index into the @code{variableReference} and @code{layer}
2871 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2872 describes the first @code{variableReference} in the SPV detail member,
2873 and in a member with four @code{variableReference} elements, a
2874 @code{facetLayout} with a @code{level} of 5 describes the first
2875 @code{layer} in the member.
2878 @defvr {Attribute} gap
2879 Always observed as @code{0pt}.
2882 Each @code{facetLevel} contains an @code{axis}, which in turn may
2883 contain a @code{label} for the @code{facetLevel} (@pxref{SPV Detail
2884 label Element}) and does contain a @code{majorTicks} element.
2886 @defvr {Attribute} labelAngle
2887 Normally 0. The value -90 causes inner column or outer row labels to
2888 be rotated vertically.
2891 @defvr {Attribute} style
2892 @defvrx {Attribute} tickFrameStyle
2893 Each refers to a @code{style} element. @code{style} is the style of
2894 the tick labels, @code{tickFrameStyle} the style for the frames around
2898 @node SPV Detail label Element
2899 @subsection The @code{label} Element
2904 :textFrameStyle=ref style?
2905 :purpose=(title | subTitle | subSubTitle | layer | footnote)?
2906 => text+ | descriptionGroup
2909 :target=ref faceting
2911 => (description | text)+
2913 description :name=(variable | value) => EMPTY
2917 :definesReference=int?
2918 :position=(subscript | superscript)?
2923 This element represents a label on some aspect of the table.
2925 @defvr {Attribute} style
2926 @defvrx {Attribute} textFrameStyle
2927 Each of these refers to a @code{style} element. @code{style} is the
2928 style of the label text, @code{textFrameStyle} the style for the frame
2932 @defvr {Attribute} purpose
2933 The kind of entity being labeled.
2936 A @code{descriptionGroup} concatenates one or more elements to form a
2937 label. Each element can be a @code{text} element, which contains
2938 literal text, or a @code{description} element that substitutes a value
2941 @defvr {Attribute} target
2942 The @code{id} of an element being described. In the corpus, this is
2943 always @code{faceting}.
2946 @defvr {Attribute} separator
2947 A string to separate the description of multiple groups, if the
2948 @code{target} has more than one. In the corpus, this is always a
2952 Typical contents for a @code{descriptionGroup} are a value by itself:
2954 <description name="value"/>
2956 @noindent or a variable and its value, separated by a colon:
2958 <description name="variable"/><text>:</text><description name="value"/>
2961 A @code{description} is like a macro that expands to some property of
2962 the target of its parent @code{descriptionGroup}. The @code{name}
2963 attribute specifies the property.
2965 @node SPV Detail setCellProperties Element
2966 @subsection The @code{setCellProperties} Element
2970 :applyToConverse=bool?
2971 => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]?
2974 The @code{setCellProperties} element sets style properties of cells or
2975 row or column labels.
2977 Interpreting @code{setCellProperties} requires answering two
2978 questions: which cells or labels to style, and what styles to use.
2980 @subsubheading Which Cells?
2985 intersect => where+ | intersectWhere | alternating | EMPTY
2988 :variable=ref (sourceVariable | derivedVariable)
2993 :variable=ref (sourceVariable | derivedVariable)
2994 :variable2=ref (sourceVariable | derivedVariable)
2997 alternating => EMPTY
3000 When @code{union} is present with @code{intersect} children, each of
3001 those children specifies a group of cells that should be styled, and
3002 the total group is all those cells taken together. When @code{union}
3003 is absent, every cell is styled. One attribute on
3004 @code{setCellProperties} affects the choice of cells:
3006 @defvr {Attribute} applyToConverse
3007 If true, this inverts the meaning of the cell selection: the selected
3008 cells are the ones @emph{not} designated. This is confusing, given
3009 the additional restrictions of @code{union}, but in the corpus
3010 @code{applyToConverse} is never present along with @code{union}.
3013 An @code{intersect} specifies restrictions on the cells to be matched.
3014 Each @code{where} child specifies which values of a given variable to
3015 include. The attributes of @code{intersect} are:
3017 @defvr {Attribute} variable
3018 Refers to a variable, e.g.@: @code{dimension0categories}. Only
3019 ``categories'' variables make sense here, but other variables, e.g.@:
3020 @code{dimension0group0map}, are sometimes seen. The reader may ignore
3024 @defvr {Attribute} include
3025 A value, or multiple values separated by semicolons,
3026 e.g.@: @code{0} or @code{13;14;15;16}.
3029 PSPP ignores @code{setCellProperties} when @code{intersectWhere} is
3032 @subsubheading What Styles?
3036 :target=ref (labeling | graph | interval | majorTicks)
3040 setMetaData :target=ref graph :key :value => EMPTY
3043 :target=ref (majorTicks | labeling)
3045 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
3049 :target=ref majorTicks
3053 The @code{set*} children of @code{setCellProperties} determine the
3056 When @code{setCellProperties} contains a @code{setFormat} whose
3057 @code{target} references a @code{labeling} element, or if it contains
3058 a @code{setStyle} that references a @code{labeling} or @code{interval}
3059 element, the @code{setCellProperties} sets the style for table cells.
3060 The format from the @code{setFormat}, if present, replaces the cells'
3061 format. The style from the @code{setStyle} that references
3062 @code{labeling}, if present, replaces the label's font and cell
3063 styles, except that the background color is taken instead from the
3064 @code{interval}'s style, if present.
3066 When @code{setCellProperties} contains a @code{setFormat} whose
3067 @code{target} references a @code{majorTicks} element, or if it
3068 contains a @code{setStyle} whose @code{target} references a
3069 @code{majorTicks}, or if it contains a @code{setFrameStyle} element,
3070 the @code{setCellProperties} sets the style for row or column labels.
3071 In this case, the @code{setCellProperties} always contains a single
3072 @code{where} element whose @code{variable} designates the variable
3073 whose labels are to be styled. The format from the @code{setFormat},
3074 if present, replaces the labels' format. The style from the
3075 @code{setStyle} that references @code{majorTicks}, if present,
3076 replaces the labels' font and cell styles, except that the background
3077 color is taken instead from the @code{setFrameStyle}'s style, if
3080 When @code{setCellProperties} contains a @code{setStyle} whose
3081 @code{target} references a @code{graph} element, and one that
3082 references a @code{labeling} element, and the @code{union} element
3083 contains @code{alternating}, the @code{setCellProperties} sets the
3084 alternate foreground and background colors for the data area. The
3085 foreground color is taken from the style referenced by the
3086 @code{setStyle} that targets the @code{graph}, the background color
3087 from the @code{setStyle} for @code{labeling}.
3089 A reader may ignore a @code{setCellProperties} that only contains
3090 @code{setMetaData}, as well as @code{setMetaData} within other
3091 @code{setCellProperties}.
3093 A reader may ignore a @code{setCellProperties} whose only @code{set*}
3094 child is a @code{setStyle} that targets the @code{graph} element.
3096 @subsubheading The @code{setStyle} Element
3100 :target=ref (labeling | graph | interval | majorTicks)
3105 This element associates a style with the target.
3107 @defvr {Attribute} target
3108 The @code{id} of an element whose style is to be set.
3111 @defvr {Attribute} style
3112 The @code{id} of a @code{style} element that identifies the style to
3116 @node SPV Detail setFormat Element
3117 @subsection The @code{setFormat} Element
3121 :target=ref (majorTicks | labeling)
3123 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
3126 This element sets the format of the target, ``format'' in this case
3127 meaning the SPSS print format for a variable.
3129 The details of this element vary depending on the schema version, as
3130 declared in the root @code{visualization} element's @code{version}
3131 attribute (@pxref{SPV Detail visualization Element}). A reader can
3132 interpret the content without knowing the schema version.
3134 The @code{setFormat} element itself has the following attributes.
3136 @defvr {Attribute} target
3137 Refers to an element whose style is to be set.
3140 @defvr {Attribute} reset
3141 If this is @code{true}, this format replaces the target's previous
3142 format. If it is @code{false}, the modifies the previous format.
3146 * SPV Detail numberFormat Element::
3147 * SPV Detail stringFormat Element::
3148 * SPV Detail dateTimeFormat Element::
3149 * SPV Detail elapsedTimeFormat Element::
3150 * SPV Detail format Element::
3151 * SPV Detail affix Element::
3154 @node SPV Detail numberFormat Element
3155 @subsubsection The @code{numberFormat} Element
3159 :minimumIntegerDigits=int?
3160 :maximumFractionDigits=int?
3161 :minimumFractionDigits=int?
3163 :scientific=(onlyForSmall | whenNeeded | true | false)?
3170 Specifies a format for displaying a number. The available options are
3171 a superset of those available from PSPP print formats. PSPP chooses a
3172 print format type for a @code{numberFormat} as follows:
3176 If @code{scientific} is @code{true}, uses @code{E} format.
3179 If @code{prefix} is @code{$}, uses @code{DOLLAR} format.
3182 If @code{suffix} is @code{%}, uses @code{PCT} format.
3185 If @code{useGrouping} is @code{true}, uses @code{COMMA} format.
3188 Otherwise, uses @code{F} format.
3191 For translating to a print format, PSPP uses
3192 @code{maximumFractionDigits} as the number of decimals, unless that
3193 attribute is missing or out of the range [0,15], in which case it uses
3196 @defvr {Attribute} minimumIntegerDigits
3197 Minimum number of digits to display before the decimal point. Always
3198 observed as @code{0}.
3201 @defvr {Attribute} maximumFractionDigits
3202 @defvrx {Attribute} minimumFractionDigits
3203 Maximum or minimum, respectively, number of digits to display after
3204 the decimal point. The observed values of each attribute range from 0
3208 @defvr {Attribute} useGrouping
3209 Whether to use the grouping character to group digits in large
3213 @defvr {Attribute} scientific
3214 This attribute controls when and whether the number is formatted in
3215 scientific notation. It takes the following values:
3219 Use scientific notation only when the number's magnitude is smaller
3220 than the value of the @code{small} attribute.
3223 Use scientific notation when the number will not otherwise fit in the
3227 Always use scientific notation. Not observed in the corpus.
3230 Never use scientific notation. A number that won't otherwise fit will
3231 be replaced by an error indication (see the @code{errorCharacter}
3232 attribute). Not observed in the corpus.
3236 @defvr {Attribute} small
3237 Only present when the @code{scientific} attribute is
3238 @code{onlyForSmall}, this is a numeric magnitude below which the
3239 number will be formatted in scientific notation. The values @code{0}
3240 and @code{0.0001} have been observed. The value @code{0} seems like a
3241 pathological choice, since no real number has a magnitude less than 0;
3242 perhaps in practice such a choice is equivalent to setting
3243 @code{scientific} to @code{false}.
3246 @defvr {Attribute} prefix
3247 @defvrx {Attribute} suffix
3248 Specifies a prefix or a suffix to apply to the formatted number. Only
3249 @code{suffix} has been observed, with value @samp{%}.
3252 @node SPV Detail stringFormat Element
3253 @subsubsection The @code{stringFormat} Element
3256 stringFormat => relabel* affix*
3258 relabel :from=real :to => EMPTY
3261 The @code{stringFormat} element specifies how to display a string. By
3262 default, a string is displayed verbatim, but @code{relabel} can change
3265 The @code{relabel} element appears as a child of @code{stringFormat}
3266 (and of @code{format}, when it is used to format strings). It
3267 specifies how to display a given value. It is used to implement value
3268 labels and to display the system-missing value in a human-readable
3269 way. It has the following attributes:
3271 @defvr {Attribute} from
3272 The value to map. In the corpus this is an integer or the
3273 system-missing value @code{-1.797693134862316E300}.
3276 @defvr {Attribute} to
3277 The string to display in place of the value of @code{from}. In the
3278 corpus this is a wide variety of value labels; the system-missing
3279 value is mapped to @samp{.}.
3282 @node SPV Detail dateTimeFormat Element
3283 @subsubsection The @code{dateTimeFormat} Element
3287 :baseFormat[dt_base_format]=(date | time | dateTime)
3289 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3291 :yearAbbreviation=bool?
3296 :monthFormat=(long | short | number | paddedNumber)?
3300 :showDayOfWeek=bool?
3301 :dayOfWeekAbbreviation=bool?
3303 :dayOfMonthPadding=bool?
3305 :minutePadding=bool?
3306 :secondPadding=bool?
3312 :dayType=(month | year)?
3313 :hourFormat=(AMPM | AS_24 | AS_12)?
3317 This element appears only in schema version 2.5 and earlier
3318 (@pxref{SPV Detail visualization Element}).
3320 Data to be formatted in date formats is stored as strings in legacy
3321 data, in the format @code{yyyy-mm-ddTHH:MM:SS.SSS} and must be parsed
3322 and reformatted by the reader.
3324 The following attribute is required.
3326 @defvr {Attribute} baseFormat
3327 Specifies whether a date and time are both to be displayed, or just
3331 Many of the attributes' meanings are obvious. The following seem to
3332 be worth documenting.
3334 @defvr {Attribute} separatorChars
3335 Exactly four characters. In order, these are used for: decimal point,
3336 grouping, date separator, time separator. Always @samp{.,-:}.
3339 @defvr {Attribute} mdyOrder
3340 Within a date, the order of the days, months, and years.
3341 @code{dayMonthYear} is the only observed value, but one would expect
3342 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
3346 @defvr {Attribute} showYear
3347 @defvrx {Attribute} yearAbbreviation
3348 Whether to include the year and, if so, whether the year should be
3349 shown abbreviated, that is, with only 2 digits. Each is @code{true}
3350 or @code{false}; only values of @code{true} and @code{false},
3351 respectively, have been observed.
3354 @defvr {Attribute} showMonth
3355 @defvrx {Attribute} monthFormat
3356 Whether to include the month (@code{true} or @code{false}) and, if so,
3357 how to format it. @code{monthFormat} is one of the following:
3361 The full name of the month, e.g.@: in an English locale,
3365 The abbreviated name of the month, e.g.@: in an English locale,
3369 The number representing the month, e.g.@: 9 for September.
3372 A two-digit number representing the month, e.g.@: 09 for September.
3375 Only values of @code{true} and @code{short}, respectively, have been
3379 @defvr {Attribute} dayType
3380 This attribute is always @code{month} in the corpus, specifying that
3381 the day of the month is to be displayed; a value of @code{year} is
3382 supposed to indicate that the day of the year, where 1 is January 1,
3383 is to be displayed instead.
3386 @defvr {Attribute} hourFormat
3387 @code{hourFormat}, if present, is one of:
3391 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
3395 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
3397 This is the only value observed in the corpus.
3400 The time is displayed in a 12-hour format, without distinguishing
3401 morning or evening, e.g.@: @code{10;15}.
3404 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
3405 which is confusing since a time duration does not have a concept of AM
3406 or PM. This might indicate a bug in the code that generated the XML
3407 in the corpus, or it might indicate that @code{elapsedTime} is
3408 sometimes used to format a time of day.
3411 For a @code{baseFormat} of @code{date}, PSPP chooses a print format
3412 type based on the following rules:
3416 If @code{showQuarter} is true: @code{QYR}.
3419 Otherwise, if @code{showWeek} is true: @code{WKYR}.
3422 Otherwise, if @code{mdyOrder} is @code{dayMonthYear}:
3426 If @code{monthFormat} is @code{number} or @code{paddedNumber}: @code{EDATE}.
3429 Otherwise: @code{DATE}.
3433 Otherwise, if @code{mdyOrder} is @code{yearMonthDay}: @code{SDATE}.
3436 Otherwise, @code{ADATE}.
3439 For a @code{baseFormat} of @code{dateTime}, PSPP uses @code{YMDHMS} if
3440 @code{mdyOrder} is @code{yearMonthDay} and @code{DATETIME} otherwise.
3441 For a @code{baseFormat} of @code{time}, PSPP uses @code{DTIME} if
3442 @code{showDay} is true, otherwise @code{TIME} if @code{showHour} is
3443 true, otherwise @code{MTIME}.
3445 For a @code{baseFormat} of @code{date}, the chosen width is the
3446 minimum for the format type, adding 2 if @code{yearAbbreviation} is
3447 false or omitted. For other base formats, the chosen width is the
3448 minimum for its type, plus 3 if @code{showSecond} is true, plus 4 more
3449 if @code{showMillis} is also true. Decimals are 0 by default, or 3
3450 if @code{showMillis} is true.
3452 @node SPV Detail elapsedTimeFormat Element
3453 @subsubsection The @code{elapsedTimeFormat} Element
3457 :baseFormat[dt_base_format]=(date | time | dateTime)
3460 :minutePadding=bool?
3461 :secondPadding=bool?
3471 This element specifies the way to display a time duration.
3473 Data to be formatted in elapsed time formats is stored as strings in
3474 legacy data, in the format @code{H:MM:SS.SSS}, with additional hour
3475 digits as needed for long durations, and must be parsed and
3476 reformatted by the reader.
3478 The following attribute is required.
3480 @defvr {Attribute} baseFormat
3481 Specifies whether a day and a time are both to be displayed, or just
3485 The remaining attributes specify exactly how to display the elapsed
3488 For @code{baseFormat} of @code{time}, PSPP converts this element to
3489 print format type @code{DTIME}; otherwise, if @code{showHour} is true,
3490 to @code{TIME}; otherwise, to @code{MTIME}. The chosen width is the
3491 minimum for the chosen type, adding 3 if @code{showSecond} is true,
3492 adding 4 more if @code{showMillis} is also true. Decimals are 0 by
3493 default, or 3 if @code{showMillis} is true.
3495 @node SPV Detail format Element
3496 @subsubsection The @code{format} Element
3500 :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)?
3503 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3508 :yearAbbreviation=bool?
3510 :monthFormat=(long | short | number | paddedNumber)?
3512 :dayOfMonthPadding=bool?
3516 :showDayOfWeek=bool?
3517 :dayOfWeekAbbreviation=bool?
3519 :minutePadding=bool?
3520 :secondPadding=bool?
3526 :dayType=(month | year)?
3527 :hourFormat=(AMPM | AS_24 | AS_12)?
3528 :minimumIntegerDigits=int?
3529 :maximumFractionDigits=int?
3530 :minimumFractionDigits=int?
3532 :scientific=(onlyForSmall | whenNeeded | true | false)?
3536 :tryStringsAsNumbers=bool?
3537 :negativesOutside=bool?
3541 This element is the union of all of the more-specific format elements.
3542 It is interpreted in the same way as one of those format elements,
3543 using @code{baseFormat} to determine which kind of format to use.
3545 There are a few attributes not present in the more specific formats:
3547 @defvr {Attribute} tryStringsAsNumbers
3548 When this is @code{true}, it is supposed to indicate that string
3549 values should be parsed as numbers and then displayed according to
3550 numeric formatting rules. However, in the corpus it is always
3554 @defvr {Attribute} negativesOutside
3555 If true, the negative sign should be shown before the prefix; if
3556 false, it should be shown after.
3559 @node SPV Detail affix Element
3560 @subsubsection The @code{affix} Element
3564 :definesReference=int
3565 :position=(subscript | superscript)
3571 This defines a suffix (or, theoretically, a prefix) for a formatted
3572 value. It is used to insert a reference to a footnote. It has the
3573 following attributes:
3575 @defvr {Attribute} definesReference
3576 This specifies the footnote number as a natural number: 1 for the
3577 first footnote, 2 for the second, and so on.
3580 @defvr {Attribute} position
3581 Position for the footnote label. Always @code{superscript}.
3584 @defvr {Attribute} suffix
3585 Whether the affix is a suffix (@code{true}) or a prefix
3586 (@code{false}). Always @code{true}.
3589 @defvr {Attribute} value
3590 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
3591 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
3592 contains other values: @code{*}, @code{**}, and a few that begin with
3593 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
3596 @node SPV Detail interval Element
3597 @subsection The @code{interval} Element
3600 interval :style=ref style => labeling footnotes?
3604 :variable=ref (sourceVariable | derivedVariable)
3605 => (formatting | format | footnotes)*
3607 formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping*
3609 formatMapping :from=int => format?
3613 :variable=ref (sourceVariable | derivedVariable)
3616 footnoteMapping :definesReference=int :from=int :to => EMPTY
3619 The @code{interval} element and its descendants determine the basic
3620 formatting and labeling for the table's cells. These basic styles are
3621 overridden by more specific styles set using @code{setCellProperties}
3622 (@pxref{SPV Detail setCellProperties Element}).
3624 The @code{style} attribute of @code{interval} itself may be ignored.
3626 The @code{labeling} element may have a single @code{formatting} child.
3627 If present, its @code{variable} attribute refers to a variable whose
3628 values are format specifiers as numbers, e.g. value 0x050802 for F8.2.
3629 However, the numbers are not actually interpreted that way. Instead,
3630 each number actually present in the variable's data is mapped by a
3631 @code{formatMapping} child of @code{formatting} to a @code{format}
3632 that specifies how to display it.
3634 The @code{labeling} element may also have a @code{footnotes} child
3635 element. The @code{variable} attribute of this element refers to a
3636 variable whose values are comma-delimited strings that list the
3637 1-based indexes of footnote references. (Cells without any footnote
3638 references are numeric 0 instead of strings.)
3640 Each @code{footnoteMapping} child of the @code{footnotes} element
3641 defines the footnote marker to be its @code{to} attribute text for the
3642 footnote whose 1-based index is given in its @code{definesReference}
3645 @node SPV Detail style Element
3646 @subsection The @code{style} Element
3653 :border-bottom=(solid | thick | thin | double | none)?
3654 :border-top=(solid | thick | thin | double | none)?
3655 :border-left=(solid | thick | thin | double | none)?
3656 :border-right=(solid | thick | thin | double | none)?
3657 :border-bottom-color?
3660 :border-right-color?
3663 :font-weight=(regular | bold)?
3664 :font-style=(regular | italic)?
3665 :font-underline=(none | underline)?
3666 :margin-bottom=dimension?
3667 :margin-left=dimension?
3668 :margin-right=dimension?
3669 :margin-top=dimension?
3670 :textAlignment=(left | right | center | decimal | mixed)?
3671 :labelLocationHorizontal=(positive | negative | center)?
3672 :labelLocationVertical=(positive | negative | center)?
3673 :decimal-offset=dimension?
3680 A @code{style} element has an effect only when it is referenced by
3681 another element to set some aspect of the table's style. Most of the
3682 attributes are self-explanatory. The rest are described below.
3684 @defvr {Attribute} {color}
3685 In some cases, the text color; in others, the background color.
3688 @defvr {Attribute} {color2}
3692 @defvr {Attribute} {labelAngle}
3693 Normally 0. The value -90 causes inner column or outer row labels to
3694 be rotated vertically.
3697 @defvr {Attribute} {labelLocationHorizontal}
3701 @defvr {Attribute} {labelLocationVertical}
3702 The value @code{positive} corresponds to vertically aligning text to
3703 the top of a cell, @code{negative} to the bottom, @code{center} to the
3707 @node SPV Detail labelFrame Element
3708 @subsection The @code{labelFrame} Element
3711 labelFrame :style=ref style => location+ label? paragraph?
3713 paragraph :hangingIndent=dimension? => EMPTY
3716 A @code{labelFrame} element specifies content and style for some
3717 aspect of a table. Only @code{labelFrame} elements that have a
3718 @code{label} child are important. The @code{purpose} attribute in the
3719 @code{label} determines what the @code{labelFrame} affects:
3723 The table's title and its style.
3726 The table's caption and its style.
3729 The table's footnotes and the style for the footer area.
3732 The style for the layer area.
3738 The @code{style} attribute references the style to use for the area.
3740 The @code{label}, if present, specifies the text to put into the title
3741 or caption or footnotes. For footnotes, the label has two @code{text}
3742 children for every footnote, each of which has a @code{usesReference}
3743 attribute identifying the 1-based index of a footnote. The first,
3744 third, fifth, @dots{} @code{text} child specifies the content for a
3745 footnote; the second, fourth, sixth, @dots{} child specifies the
3746 marker. Content tends to end in a new-line, which the reader may wish
3747 to trim; similarly, markers tend to end in @samp{.}.
3749 The @code{paragraph}, if present, may be ignored, since it is always
3752 @node SPV Detail Legacy Properties
3753 @subsection Legacy Properties
3755 The detail XML format has features for styling most of the aspects of
3756 a table. It also inherits defaults for many aspects from structure
3757 XML, which has the following @code{tableProperties} element:
3762 => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties
3765 :hideEmptyRows=bool?
3766 :maximumColumnWidth=dimension?
3767 :maximumRowWidth=dimension?
3768 :minimumColumnWidth=dimension?
3769 :minimumRowWidth=dimension?
3770 :rowDimensionLabels=(inCorner | nested)?
3774 :markerPosition=(superscript | subscript)?
3775 :numberFormat=(alphabetic | numeric)?
3778 cellFormatProperties => cell_style+
3781 :alternatingColor=color?
3782 :alternatingTextColor=color?
3790 :font-style=(regular | italic)?
3791 :font-weight=(regular | bold)?
3792 :font-underline=(none | underline)?
3793 :labelLocationVertical=(positive | negative | center)?
3794 :margin-bottom=dimension?
3795 :margin-left=dimension?
3796 :margin-right=dimension?
3797 :margin-top=dimension?
3798 :textAlignment=(left | right | center | decimal | mixed)?
3799 :decimal-offset=dimension?
3802 borderProperties => border_style+
3805 :borderStyleType=(none | solid | dashed | thick | thin | double)?
3810 :printAllLayers=bool?
3811 :rescaleLongTableToFitPage=bool?
3812 :rescaleWideTableToFitPage=bool?
3813 :windowOrphanLines=int?
3815 :continuationTextAtBottom=bool?
3816 :continuationTextAtTop=bool?
3817 :printEachLayerOnSeparatePage=bool?
3821 The @code{name} attribute appears only in standalone @file{.stt} files
3822 (@pxref{SPSS TableLook STT Format}).