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 @chapter 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 take the form with @file{outputViewer@var{number}.xml} or
42 @file{outputViewer@var{number}_heading.xml}, where @var{number} is an
43 10-digit decimal number. Each of these members represents some kind
44 of output item (a table, a heading, a block of text, etc.) or a group
45 of them. The member whose output goes at the beginning of the
46 document is numbered 0, the next member in the output is numbered 1,
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 for detail members. Structure member refer to detail
92 members by name, and so their exact names do not matter to readers as
93 long as they are unique.
95 SPSS tolerates corrupted Zip archives that Zip reader libraries tend
96 to reject. These can be fixed up with @command{zip -FF}.
99 * SPV Structure Member Format::
100 * SPV Light Detail Member Format::
101 * SPV Legacy Detail Member Binary Format::
102 * SPV Legacy Detail Member XML Format::
105 @node SPV Structure Member Format
106 @section Structure Member Format
108 A structure member lays out the high-level structure for a group of
109 output items such as heading, tables, and charts. Structure members
110 do not include the details of tables and charts but instead refer to
111 them by their member names.
113 Structure members' XML files claim conformance with a collection of
114 XML Schemas. These schemas are distributed, under a nonfree license,
115 with SPSS binaries. Fortunately, the schemas are not necessary to
116 understand the structure members. The schemas can even
117 be deceptive because they document elements and attributes that are
118 not in the corpus and do not document elements and attributes that are
119 commonly found in the corpus.
121 Structure members use a different XML namespace for each schema, but
122 these namespaces are not entirely consistent. In some SPV files, for
123 example, the @code{viewer-tree} schema is associated with namespace
124 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
125 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
126 additional @file{viewer/}). Under either name, the schema URIs are
127 not resolvable to obtain the schemas themselves.
129 @c XXX The namespaces are important for writing SPV files, so we
132 One may ignore all of the above in interpreting a structure member.p
133 The actual XML has a simple and straightforward form that does not
134 require a reader to take schemas or namespaces into account. A
135 structure member's root is @code{heading} element, which contains
136 @code{heading} or @code{container} elements (or a mix), forming a
137 tree. In turn, @code{container} holds a @code{label} and one more
138 child, usually @code{text} or @code{table}.
140 The following sections document the elements found in structure
141 members in a context-free grammar-like fashion. Consider the
142 following example, which specifies the attributes and content for the
143 @code{container} element:
147 :visibility=(visible | hidden)
148 :page-break-before=(always)?
149 :text-align=(left | center)?
151 => label (table | container_text | graph | model | object | image | tree)
154 Each attribute specification begins with @samp{:} followed by the
155 attribute's name. If the attribute's value has an easily specified
156 form, then @samp{=} and its description follows the name. Finally, if
157 the attribute is optional, the specification ends with @samp{?}. The
158 following value specifications are defined:
161 @item (@var{a} | @var{b} | @dots{})
162 One of the listed literal strings. If only one string is listed, it
163 is the only acceptable value. If @code{OTHER} is listed, then any
164 string not explicitly listed is also accepted.
167 Either @code{true} or @code{false}.
170 A floating-point number followed by a unit, e.g.@: @code{10pt}. Units
171 in the corpus include @code{in} (inch), @code{pt} (points, 72/inch),
172 @code{px} (``device-independent pixels'', 96/inch), and @code{cm}. If
173 the unit is omitted then points should be assumed. The number and
174 unit may be separated by white space.
176 The corpus also includes localized names for units. A reader must
177 understand these to properly interpret the dimension:
181 @code{인치}, @code{pol.}, @code{cala}, @code{cali}
191 A floating-point number.
197 A color in one of the forms @code{#@var{rr}@var{gg}@var{bb}} or
198 @code{@var{rr}@var{gg}@var{bb}}, or the string @code{transparent}, or
199 one of the standard Web color names.
202 @item ref @var{element}
203 @itemx ref(@var{elem1} | @var{elem2} | @dots{})
204 The name from the @code{id} attribute in some element. If one or more
205 elements are named, the name must refer to one of those elements,
206 otherwise any element is acceptable.
209 All elements have an optional @code{id} attribute. If present, its
210 value must be unique. In practice many elements are assigned
211 @code{id} attributes that are never referenced.
213 The content specification for an element supports the following
220 @item @var{a} @var{b}
221 @var{a} followed by @var{b}.
223 @item @var{a} | @var{b} | @var{c}
224 One of @var{a} or @var{b} or @var{c}.
227 Zero or one instances of @var{a}.
230 Zero or more instances of @var{a}.
233 One or more instances of @var{a}.
235 @item (@var{subexpression})
236 Grouping for a subexpression.
245 Element and attribute names are sometimes suffixed by another name in
246 square brackets to distinguish different uses of the same name. For
247 example, structure XML has two @code{text} elements, one inside
248 @code{container}, the other inside @code{pageParagraph}. The former
249 is defined as @code{text[container_text]} and referenced as
250 @code{container_text}, the latter defined as
251 @code{text[pageParagraph_text]} and referenced as
252 @code{pageParagraph_text}.
254 This language is used in the PSPP source code for parsing structure
255 and detail XML members. Refer to
256 @file{src/output/spv/structure-xml.grammar} and
257 @file{src/output/spv/detail-xml.grammar} for the full grammars.
259 The following example shows the contents of a typical structure member
260 for a @cmd{DESCRIPTIVES} procedure. A real structure member is not
261 indented. This example also omits most attributes, all XML namespace
262 information, and the CSS from the embedded HTML:
265 <?xml version="1.0" encoding="utf-8"?>
267 <label>Output</label>
268 <heading commandName="Descriptives">
269 <label>Descriptives</label>
272 <text commandName="Descriptives" type="title">
274 <![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
278 <container visibility="hidden">
280 <table commandName="Descriptives" subType="Notes" type="note">
282 <dataPath>00000000001_lightNotesData.bin</dataPath>
287 <label>Descriptive Statistics</label>
288 <table commandName="Descriptives" subType="Descriptive Statistics"
291 <dataPath>00000000002_lightTableData.bin</dataPath>
300 * SPV Structure heading Element::
301 * SPV Structure label Element::
302 * SPV Structure container Element::
303 * SPV Structure text Element (Inside @code{container})::
304 * SPV Structure html Element::
305 * SPV Structure table Element::
306 * SPV Structure graph Element::
307 * SPV Structure model Element::
308 * SPV Structure object and image Elements::
309 * SPV Structure tree Element::
310 * SPV Structure Path Elements::
311 * SPV Structure pageSetup Element::
312 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
315 @node SPV Structure heading Element
316 @subsection The @code{heading} Element
319 heading[root_heading]
325 => label pageSetup? (container | heading)*
330 :visibility[heading_visibility]=(collapsed)?
333 => label (container | heading)*
336 A @code{heading} represents a tree of content that appears in an
337 output viewer window. It contains a @code{label} text string that is
338 shown in the outline view ordinarily followed by content containers or
339 further nested (sub)-sections of output. Unlike heading elements in
340 HTML and other common document formats, which precede the content that
341 they head, @code{heading} contains the elements that appear below the
344 The root of a structure member is a special @code{heading}. The
345 direct children of the root @code{heading} elements in all structure
346 members in an SPV file are siblings. That is, the root @code{heading}
347 in all of the structure members conceptually represent the same node.
348 The root heading's @code{label} is ignored (see @pxref{SPV Structure
349 label Element}). The root heading in the first structure member in
350 the Zip file may contain a @code{pageSetup} element.
352 The schema implies that any @code{heading} may contain a sequence of
353 any number of @code{heading} and @code{container} elements. This does
354 not work for the root @code{heading} in practice, which must actually
355 contain exactly one @code{container} or @code{heading} child element.
356 Furthermore, if the root heading's child is a @code{heading}, then the
357 structure member's name must end in @file{_heading.xml}; if it is a
358 @code{container} child, then it must not.
360 The following attributes have been observed on both document root and
361 nested @code{heading} elements.
363 @defvr {Attribute} creator-version
364 The version of the software that created this SPV file. A string of
365 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
366 e.g.@: @code{21000001} is version 21.0.0.1. Trailing pairs of zeros
367 are sometimes omitted, so that @code{21}, @code{210000}, and
368 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
369 three of those forms).
373 The following attributes have been observed on document root
374 @code{heading} elements only:
376 @defvr {Attribute} @code{creator}
377 The directory in the file system of the software that created this SPV
381 @defvr {Attribute} @code{creation-date-time}
382 The date and time at which the SPV file was written, in a
383 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
384 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
385 December 5, 2014 5:00:19 o'clock PM EST}.
388 @defvr {Attribute} @code{lockReader}
389 Whether a reader should be allowed to edit the output. The possible
390 values are @code{true} and @code{false}. The value @code{false} is by
394 @defvr {Attribute} @code{schemaLocation}
395 This is actually an XML Namespace attribute. A reader may ignore it.
399 The following attributes have been observed only on nested
400 @code{heading} elements:
402 @defvr {Attribute} @code{commandName}
403 A locale-invariant identifier for the command that produced the
404 output, e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
407 @defvr {Attribute} @code{visibility}
408 If this attribute is absent, the heading's content is expanded in the
409 outline view. If it is set to @code{collapsed}, it is collapsed.
410 (This attribute is never present in a root @code{heading} because the
411 root node is always expanded when a file is loaded, even though the UI
412 can be used to collapse it interactively.)
415 @defvr {Attribute} @code{locale}
416 The locale used for output, in Windows format, which is similar to the
417 format used in Unix with the underscore replaced by a hyphen, e.g.@:
418 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
421 @defvr {Attribute} @code{olang}
422 The output language, e.g.@: @code{en}, @code{it}, @code{es},
423 @code{de}, @code{pt-BR}.
426 @node SPV Structure label Element
427 @subsection The @code{label} Element
433 Every @code{heading} and @code{container} holds a @code{label} as its
434 first child. The label text is what appears in the outline pane of
435 the GUI's viewer window. PSPP also puts it into the outline of PDF
436 output. The label text doesn't appear in the output itself.
438 The text in @code{label} describes what it labels, often by naming the
439 statistical procedure that was executed, e.g.@: ``Frequencies'' or
440 ``T-Test''. Labels are often very generic, especially within a
441 @code{container}, e.g.@: ``Title'' or ``Warnings'' or ``Notes''.
442 Label text is localized according to the output language, e.g.@: in
443 Italian a frequency table procedure is labeled ``Frequenze''.
445 The user can edit labels to be anything they want. The corpus
446 contains a few examples of empty labels, ones that contain no text,
447 probably as a result of user editing.
449 The root @code{heading} in an SPV file has a @code{label}, like every
450 @code{heading}. It normally contains ``Output'' but its content is
451 disregarded anyway. The user cannot edit it.
453 @node SPV Structure container Element
454 @subsection The @code{container} Element
458 :visibility=(visible | hidden)
459 :page-break-before=(always)?
460 :text-align=(left | center)?
462 => label (table | container_text | graph | model | object | image | tree)
465 A @code{container} serves to contain and label a @code{table},
466 @code{text}, or other kind of item.
468 This element has the following attributes.
470 @defvr {Attribute} @code{visibility}
471 Whether the container's content is displayed. ``Notes'' tables are
472 often hidden; other data is usually visible.
475 @defvr {Attribute} @code{text-align}
476 Alignment of text within the container. Observed with nested
477 @code{table} and @code{text} elements.
480 @defvr {Attribute} @code{width}
481 The width of the container, e.g.@: @code{1097px}.
484 All of the elements that nest inside @code{container} (except the
485 @code{label}) have the following optional attribute.
487 @defvr {Attribute} @code{commandName}
488 As on the @code{heading} element. The corpus contains one example
489 of where @code{commandName} is present but set to the empty string.
492 @node SPV Structure text Element (Inside @code{container})
493 @subsection The @code{text} Element (Inside @code{container})
497 :type[text_type]=(title | log | text | page-title)
503 This @code{text} element is nested inside a @code{container}. There
504 is a different @code{text} element that is nested inside a
505 @code{pageParagraph}.
507 This element has the following attributes.
509 @defvr {Attribute} @code{commandName}
510 @xref{SPV Structure container Element}. For output not specific to a
511 command, this is simply @code{log}.
514 @defvr {Attribute} @code{type}
515 The semantics of the text.
518 @defvr {Attribute} @code{creator-version}
519 As on the @code{heading} element.
522 @node SPV Structure html Element
523 @subsection The @code{html} Element
526 html :lang=(en) => TEXT
529 The element contains an HTML document as text (or, in practice, as
530 CDATA). In some cases, the document starts with @code{<html>} and
531 ends with @code{</html>}; in others the @code{html} element is
532 implied. Generally the HTML includes a @code{head} element with a CSS
533 stylesheet. The HTML body often begins with @code{<BR>}.
535 The HTML document uses only the following elements:
539 Sometimes, the document is enclosed with
540 @code{<html>}@dots{}@code{</html>}.
543 The HTML body often begins with @code{<BR>} and may contain it as well.
551 The attributes @code{face}, @code{color}, and @code{size} are
552 observed. The value of @code{color} takes one of the forms
553 @code{#@var{rr}@var{gg}@var{bb}} or @code{rgb (@var{r}, @var{g},
554 @var{b})}. The value of @code{size} is a number between 1 and 7,
558 The CSS in the corpus is simple. To understand it, a parser only
559 needs to be able to skip white space, @code{<!--}, and @code{-->}, and
560 parse style only for @code{p} elements. Only the following properties
565 In the form @code{@var{rr}@var{gg}@var{bb}}, e.g. @code{000000}, with
569 Either @code{bold} or @code{normal}.
572 Either @code{italic} or @code{normal}.
574 @item text-decoration
575 Either @code{underline} or @code{normal}.
578 A font name, commonly @code{Monospaced} or @code{SansSerif}.
581 Values claim to be in points, e.g.@: @code{14pt}, but the values are
582 actually in ``device-independent pixels'' (px), at 96/inch.
585 This element has the following attributes.
587 @defvr {Attribute} @code{lang}
588 This always contains @code{en} in the corpus.
591 @node SPV Structure table Element
592 @subsection The @code{table} Element
601 :displayFiltering=bool?
603 :orphanTolerance=int?
608 :type[table_type]=(table | note | warning)
609 => tableProperties? tableStructure
611 tableStructure => path? dataPath csvPath?
614 This element has the following attributes.
616 @defvr {Attribute} @code{commandName}
617 @xref{SPV Structure container Element}.
620 @defvr {Attribute} @code{type}
621 One of @code{table}, @code{note}, or @code{warning}.
624 @defvr {Attribute} @code{subType}
625 The locale-invariant command ID for the particular kind of output that
626 this table represents in the procedure. This can be the same as
627 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
628 @code{Case Processing Summary}. Generic subtypes @code{Notes} and
629 @code{Warnings} are often used.
632 @defvr {Attribute} @code{tableId}
633 A number that uniquely identifies the table within the SPV file,
634 typically a large negative number such as @code{-4147135649387905023}.
637 @defvr {Attribute} @code{creator-version}
638 As on the @code{heading} element. In the corpus, this is only present
639 for version 21 and up and always includes all 8 digits.
642 @xref{SPV Detail Legacy Properties}, for details on the
643 @code{tableProperties} element.
645 @node SPV Structure graph Element
646 @subsection The @code{graph} Element
661 => dataPath? path csvPath?
664 This element represents a graph. The @code{dataPath} and @code{path}
665 elements name the Zip members that give the details of the graph.
666 Normally, both elements are present; there is only one counterexample
669 @code{csvPath} only appears in one SPV file in the corpus, for two
670 graphs. In these two cases, @code{dataPath}, @code{path}, and
671 @code{csvPath} all appear. These @code{csvPath} name Zip members with
672 names of the form @file{@var{number}_csv.bin}, where @var{number} is a
673 many-digit number and the same as the @code{csvFileIds}. The named
674 Zip members are CSV text files (despite the @file{.bin} extension).
675 The CSV files are encoded in UTF-8 and begin with a U+FEFF byte-order
678 @node SPV Structure model Element
679 @subsection The @code{model} Element
691 => ViZml? dataPath? path | pmmlContainerPath statsContainerPath
693 pmmlContainerPath => TEXT
695 statsContainerPath => TEXT
697 ViZml :viewName? => TEXT
700 This element represents a model. The @code{dataPath} and @code{path}
701 elements name the Zip members that give the details of the model.
702 Normally, both elements are present; there is only one counterexample
705 The details are unexplored. The @code{ViZml} element contains base-64
706 encoded text, that decodes to a binary format with some embedded text
707 strings, and @code{path} names an Zip member that contains XML.
708 Alternatively, @code{pmmlContainerPath} and @code{statsContainerPath}
709 name Zip members with @file{.scf} extension.
711 @node SPV Structure object and image Elements
712 @subsection The @code{object} and @code{image} Elements
717 :type[object_type]=(unknown)?
727 These two elements represent an image in PNG format. They are
728 equivalent and the corpus contains examples of both. The only
729 difference is the syntax: for @code{object}, the @code{uri} attribute
730 names the Zip member that contains a PNG file; for @code{image}, the
731 text of the inner @code{dataPath} element names the Zip member.
733 PSPP writes @code{object} in output but there is no strong reason to
736 The corpus only contains PNG image files.
738 @node SPV Structure tree Element
739 @subsection The @code{tree} Element
750 This element represents a tree. The @code{dataPath} and @code{path}
751 elements name the Zip members that give the details of the tree.
752 The details are unexplored.
754 @node SPV Structure Path Elements
755 @subsection Path Elements
765 These element contain the name of the Zip members that hold details
766 for a container. For tables:
770 When a ``light'' format is used, only @code{dataPath} is present, and
771 it names a @file{.bin} member of the Zip file that has @code{light} in
772 its name, e.g.@: @code{0000000001437_lightTableData.bin} (@pxref{SPV
773 Light Detail Member Format}).
776 When the legacy format is used, both are present. In this case,
777 @code{dataPath} names a Zip member with a legacy binary format that
778 contains relevant data (@pxref{SPV Legacy Detail Member Binary
779 Format}), and @code{path} names a Zip member that uses an XML format
780 (@pxref{SPV Legacy Detail Member XML Format}).
783 Graphs normally follow the legacy approach described above. The
784 corpus contains one example of a graph with @code{path} but not
785 @code{dataPath}. The reason is unexplored.
787 Models use @code{path} but not @code{dataPath}. @xref{SPV Structure
788 graph Element}, for more information.
790 These elements have no attributes.
792 @node SPV Structure pageSetup Element
793 @subsection The @code{pageSetup} Element
797 :initial-page-number=int?
798 :chart-size=(as-is | full-height | half-height | quarter-height | OTHER)?
799 :margin-left=dimension?
800 :margin-right=dimension?
801 :margin-top=dimension?
802 :margin-bottom=dimension?
803 :paper-height=dimension?
804 :paper-width=dimension?
805 :reference-orientation?
806 :space-after=dimension?
807 => pageHeader pageFooter
809 pageHeader => pageParagraph?
811 pageFooter => pageParagraph?
813 pageParagraph => pageParagraph_text
816 The @code{pageSetup} element has the following attributes.
818 @defvr {Attribute} @code{initial-page-number}
819 The page number to put on the first page of printed output. Usually
823 @defvr {Attribute} @code{chart-size}
824 One of the listed, self-explanatory chart sizes,
825 @code{quarter-height}, or a localization (!) of one of these (e.g.@:
826 @code{dimensione attuale}, @code{Wie vorgegeben}).
829 @defvr {Attribute} @code{margin-left}
830 @defvrx {Attribute} @code{margin-right}
831 @defvrx {Attribute} @code{margin-top}
832 @defvrx {Attribute} @code{margin-bottom}
833 Margin sizes, e.g.@: @code{0.25in}.
836 @defvr {Attribute} @code{paper-height}
837 @defvrx {Attribute} @code{paper-width}
841 @defvr {Attribute} @code{reference-orientation}
842 Indicates the orientation of the output page. Either @code{0deg}
843 (portrait) or @code{90deg} (landscape),
846 @defvr {Attribute} @code{space-after}
847 The amount of space between printed objects, typically @code{12pt}.
850 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
851 @subsection The @code{text} Element (Inside @code{pageParagraph})
854 text[pageParagraph_text] :type=(title | text) => TEXT
857 This @code{text} element is nested inside a @code{pageParagraph}. There
858 is a different @code{text} element that is nested inside a
861 The element is either empty, or contains CDATA that holds almost-XHTML
862 text: in the corpus, either an @code{html} or @code{p} element. It is
863 @emph{almost}-XHTML because the @code{html} element designates the
865 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of
866 an XHTML namespace, and because the CDATA can contain substitution
867 variables. The following variables are supported:
872 The current date or time in the preferred format for the locale.
878 First-, second-, third-, or fourth-level heading.
884 Name of the output file.
890 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
893 Typical contents (indented for clarity):
896 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
899 <p style="text-align:right; margin-top: 0">Page &[Page]</p>
904 This element has the following attributes.
906 @defvr {Attribute} @code{type}
910 @node SPV Light Detail Member Format
911 @section Light Detail Member Format
913 This section describes the format of ``light'' detail @file{.bin}
914 members. These members have a binary format which we describe here in
915 terms of a context-free grammar using the following conventions:
918 @item NonTerminal @result{} @dots{}
919 Nonterminals have CamelCaps names, and @result{} indicates a
920 production. The right-hand side of a production is often broken
921 across multiple lines. Break points are chosen for aesthetics only
922 and have no semantic significance.
924 @item 00, 01, @dots{}, ff.
925 A bytes with a fixed value, written as a pair of hexadecimal digits.
927 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
928 @itemx ib0, ib1, @dots{}, ib9, ib10, ib11, @dots{}
929 A 32-bit integer in little-endian or big-endian byte order,
930 respectively, with a fixed value, written in decimal. Prefixed by
931 @samp{i} for little-endian or @samp{ib} for big-endian.
937 A byte with value 0 or 1.
941 A 16-bit unsigned integer in little-endian or big-endian byte order,
946 A 32-bit unsigned integer in little-endian or big-endian byte order,
951 A 64-bit unsigned integer in little-endian or big-endian byte order,
955 A 64-bit IEEE floating-point number.
958 A 32-bit IEEE floating-point number.
962 A 32-bit unsigned integer, in little-endian or big-endian byte order,
963 respectively, followed by the specified number of bytes of character
964 data. (The encoding is indicated by the Formats nonterminal.)
967 @var{x} is optional, e.g.@: 00? is an optional zero byte.
969 @item @var{x}*@var{n}
970 @var{x} is repeated @var{n} times, e.g.@: byte*10 for ten arbitrary bytes.
972 @item @var{x}[@var{name}]
973 Gives @var{x} the specified @var{name}. Names are used in textual
974 explanations. They are also used, also bracketed, to indicate counts,
975 e.g.@: @code{int32[n] byte*[n]} for a 32-bit integer followed by the
976 specified number of arbitrary bytes.
978 @item @var{a} @math{|} @var{b}
979 Either @var{a} or @var{b}.
982 Parentheses are used for grouping to make precedence clear, especially
983 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
987 @itemx becount(@var{x})
988 A 32-bit unsigned integer, in little-endian or big-endian byte order,
989 respectively, that indicates the number of bytes in @var{x}, followed
993 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
994 (The @file{.bin} header indicates the version.)
997 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
1000 PSPP uses this grammar to parse light detail members. See
1001 @file{src/output/spv/light-binary.grammar} in the PSPP source tree for
1004 Little-endian byte order is far more common in this format, but a few
1005 pieces of the format use big-endian byte order.
1007 Light detail members express linear units in two ways: points (pt), at
1008 72/inch, and ``device-independent pixels'' (px), at 96/inch. To
1009 convert from pt to px, multiply by 1.33 and round up. To convert
1010 from px to pt, divide by 1.33 and round down.
1012 A ``light'' detail member @file{.bin} consists of a number of sections
1013 concatenated together, terminated by an optional byte 01:
1017 Header Titles Footnotes
1018 Areas Borders PrintSettings TableSettings Formats
1019 Dimensions Axes Cells
1023 The following sections go into more detail.
1026 * SPV Light Member Header::
1027 * SPV Light Member Titles::
1028 * SPV Light Member Footnotes::
1029 * SPV Light Member Areas::
1030 * SPV Light Member Borders::
1031 * SPV Light Member Print Settings::
1032 * SPV Light Member Table Settings::
1033 * SPV Light Member Formats::
1034 * SPV Light Member Dimensions::
1035 * SPV Light Member Categories::
1036 * SPV Light Member Axes::
1037 * SPV Light Member Cells::
1038 * SPV Light Member Value::
1039 * SPV Light Member ValueMod::
1042 @node SPV Light Member Header
1045 An SPV light member begins with a 39-byte header:
1050 (i1 @math{|} i3)[version]
1053 bool[rotate-inner-column-labels]
1054 bool[rotate-outer-row-labels]
1057 int32[min-col-heading-width] int32[max-col-heading-width]
1058 int32[min-row-heading-width] int32[max-row-heading-width]
1062 @code{version} is a version number that affects the interpretation of
1063 some of the other data in the member. We will refer to ``version 1''
1064 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
1065 version-specific formatting (as described previously).
1067 If @code{rotate-inner-column-labels} is 1, then column labels closest
1068 to the data are rotated 90° counterclockwise; otherwise, they are
1069 shown in the normal way.
1071 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
1072 the data are rotated 90° counterclockwise; otherwise, they are shown
1075 @code{min-col-heading-width}, @code{max-col-heading-width}, @code{min-row-heading-width}, and
1076 @code{max-row-heading-width} are measurements in 1/96 inch units (called
1077 ``device independent pixel'' units in Windows) whose values influence
1078 column widths. For the purpose of interpreting these values, a table
1079 is divided into the three regions shown below:
1082 +------------------+-------------------------------------------------+
1083 | | column headings |
1084 | +-------------------------------------------------+
1087 | row headings | data |
1090 +------------------+-------------------------------------------------+
1093 @code{min-col-heading-width} and @code{max-col-heading-width} apply to the columns in
1094 the column headings region. @code{min-col-heading-width} is the minimum width
1095 that any of these columns will be given automatically. In addition,
1096 @code{max-col-heading-width} is the maximum width that a column will be
1097 assigned to accommodate a long label in the column headings cells.
1098 These columns will still be made wider to accommodate wide data values
1101 @code{min-row-heading-width} is the minimum width that a column in the corner
1102 and row headings region will be given automatically.
1103 @code{max-col-heading-width} is the maximum width that a column in this region
1104 will be assigned to accomodate a long label. This region doesn't
1105 include data, so data values don't affect column widths.
1107 @code{table-id} is a binary version of the @code{tableId} attribute in
1108 the structure member that refers to the detail member. For example,
1109 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
1110 would be 0xc6c99d183b300001.
1112 The meaning of the other variable parts of the header is not known. A
1113 writer may safely use version 3, true for @code{x0}, false for
1114 @code{x1}, true for @code{x2}, and 0x15 for @code{x3}.
1116 @node SPV Light Member Titles
1122 Value[subtype] 01? 31
1123 Value[user-title] 01?
1124 (31 Value[corner-text] @math{|} 58)
1125 (31 Value[caption] @math{|} 58)
1128 The Titles follow the Header and specify the table's title, caption,
1131 The @code{user-title} reflects any user
1132 editing of the title text or style. The @code{title} is the title
1133 originally generated by the procedure. Both of these are appropriate
1134 for presentation and localized to the user's language. For example,
1135 for a frequency table, @code{title} and @code{user-title} normally
1136 name the variable and @code{c} is simply ``Frequencies''.
1138 @code{subtype} is the same as the @code{subType} attribute in the
1139 @code{table} structure XML element that referred to this member.
1140 @xref{SPV Structure table Element}, for details.
1142 The @code{corner-text}, if present, is shown in the upper-left corner
1143 of the table, above the row headings and to the left of the column
1144 headings. It is usually absent. When row dimension labels are
1145 displayed in the corner (see @code{show-row-labels-in-corner}), corner
1148 The @code{caption}, if present, is shown below the table.
1149 @code{caption} reflects user editing of the caption.
1151 @node SPV Light Member Footnotes
1152 @subsection Footnotes
1155 Footnotes => int32[n-footnotes] Footnote*[n-footnotes]
1156 Footnote => Value[text] (58 @math{|} 31 Value[marker]) int32[show]
1159 Each footnote has @code{text} and an optional custom @code{marker}
1162 The syntax for Value would allow footnotes (and their markers) to
1163 reference other footnotes, but in practice this doesn't work.
1165 @code{show} is a 32-bit signed integer. It is positive to show the
1166 footnote or negative to hide it. Its magnitude is often 1, and in
1167 other cases tends to be the number of references to the footnote.
1168 It is safe to write 1 to show a footnote and -1 to hide it.
1170 @node SPV Light Member Areas
1177 string[typeface] float[size] int32[style] bool[underline]
1178 int32[halign] int32[valign]
1179 string[fg-color] string[bg-color]
1180 bool[alternate] string[alt-fg-color] string[alt-bg-color]
1181 v3(int32[left-margin] int32[right-margin] int32[top-margin] int32[bottom-margin])
1184 Each Area represents the style for a different area of the table, in
1185 the following order: title, caption, footer, corner, column labels,
1186 row labels, data, and layers.
1188 @code{index} is the 1-based index of the Area, i.e.@: 1 for the first
1189 Area, through 8 for the final Area.
1191 @code{typeface} is the string name of the font used in the area. In
1192 the corpus, this is @code{SansSerif} in over 99% of instances and
1193 @code{Times New Roman} in the rest.
1195 @code{size} is the size of the font, in px (@pxref{SPV Light Detail
1196 Member Format}). The most common size in the corpus is 12 px. Even
1197 though @code{size} has a floating-point type, in the corpus its values
1198 are always integers.
1200 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
1201 1 (with value 2) is set for italic.
1203 @code{underline} is 1 if the font is underlined, 0 otherwise.
1205 @code{halign} specifies horizontal alignment: 0 for center, 2 for
1206 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
1207 alignment varies according to type: string data is left-justified,
1208 numbers and most other formats are right-justified.
1210 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1213 @code{fg-color} and @code{bg-color} are the foreground color and
1214 background color, respectively. In the corpus, these are always
1215 @code{#000000} and @code{#ffffff}, respectively.
1217 @code{alternate} is 1 if rows should alternate colors, 0 if all rows
1218 should be the same color. When @code{alternate} is 1,
1219 @code{alt-fg-color} and @code{alt-bg-color} specify the colors for the
1220 alternate rows; otherwise they are empty strings.
1222 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1223 @code{bottom-margin} are measured in px.
1225 @node SPV Light Member Borders
1232 be32[n-borders] Border*[n-borders]
1233 bool[show-grid-lines]
1242 The Borders reflect how borders between regions are drawn.
1244 The fixed value of @code{endian} can be used to validate the
1247 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
1249 Each Border describes one kind of border. @code{n-borders} seems to
1250 always be 19. Each @code{border-type} appears once (although in an
1251 unpredictable order) and correspond to the following borders:
1257 Left, top, right, and bottom outer frame.
1259 Left, top, right, and bottom inner frame.
1261 Left and top of data area.
1263 Horizontal and vertical dimension rows.
1265 Horizontal and vertical dimension columns.
1267 Horizontal and vertical category rows.
1269 Horizontal and vertical category columns.
1272 @code{stroke-type} describes how a border is drawn, as one of:
1289 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
1290 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
1291 opaque color, therefore opaque black is 0xff000000.
1293 @node SPV Light Member Print Settings
1294 @subsection Print Settings
1301 bool[paginate-layers]
1304 bool[top-continuation]
1305 bool[bottom-continuation]
1306 be32[n-orphan-lines]
1307 bestring[continuation-string])
1310 The PrintSettings reflect settings for printing. The fixed value of
1311 @code{endian} can be used to validate the endianness.
1313 @code{all-layers} is 1 to print all layers, 0 to print only the layer
1314 designated by @code{current-layer} in TableSettings (@pxref{SPV Light
1315 Member Table Settings}).
1317 @code{paginate-layers} is 1 to print each layer at the start of a new
1318 page, 0 otherwise. (This setting is honored only @code{all-layers} is
1319 1, since otherwise only one layer is printed.)
1321 @code{fit-width} and @code{fit-length} control whether the table is
1322 shrunk to fit within a page's width or length, respectively.
1324 @code{n-orphan-lines} is the minimum number of rows or columns to put
1325 in one part of a table that is broken across pages.
1327 If @code{top-continuation} is 1, then @code{continuation-string} is
1328 printed at the top of a page when a table is broken across pages for
1329 printing; similarly for @code{bottom-continuation} and the bottom of a
1330 page. Usually, @code{continuation-string} is empty.
1332 @node SPV Light Member Table Settings
1333 @subsection Table Settings
1343 bool[show-row-labels-in-corner]
1344 bool[show-alphabetic-markers]
1345 bool[footnote-marker-superscripts]
1348 Breakpoints[row-breaks] Breakpoints[column-breaks]
1349 Keeps[row-keeps] Keeps[column-keeps]
1350 PointKeeps[row-point-keeps] PointKeeps[column-point-keeps]
1353 bestring[table-look]
1356 Breakpoints => be32[n-breaks] be32*[n-breaks]
1358 Keeps => be32[n-keeps] Keep*[n-keeps]
1359 Keep => be32[offset] be32[n]
1361 PointKeeps => be32[n-point-keeps] PointKeep*[n-point-keeps]
1362 PointKeep => be32[offset] be32 be32
1365 The TableSettings reflect display settings. The fixed value of
1366 @code{endian} can be used to validate the endianness.
1368 @code{current-layer} is the displayed layer. Suppose there are
1369 @math{d} layers, numbered 1 through @math{d} in the order given in the
1370 Dimensions (@pxref{SPV Light Member Dimensions}), and that the
1371 displayed value of dimension @math{i} is @math{d_i}, @math{0 \le x_i <
1372 n_i}, where @math{n_i} is the number of categories in dimension
1373 @math{i}. Then @code{current-layer} is calculated by the following
1377 let @code{current-layer} = 0
1378 for each @math{i} from @math{d} downto 1:
1379 @code{current-layer} = (@math{n_i \times} @code{current-layer}) @math{+} @math{x_i}
1382 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
1383 any cell) are hidden; otherwise, they are shown.
1385 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
1386 the upper left corner; otherwise, they are shown nested.
1388 If @code{show-alphabetic-markers} is 1, markers are shown as letters
1389 (e.g.@: @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
1390 shown as numbers starting from 1.
1392 When @code{footnote-marker-superscripts} is 1, footnote markers are shown
1393 as superscripts, otherwise as subscripts.
1395 The Breakpoints are rows or columns after which there is a page break;
1396 for example, a row break of 1 requests a page break after the second
1397 row. Usually no breakpoints are specified, indicating that page
1398 breaks should be selected automatically.
1400 The Keeps are ranges of rows or columns to be kept together without a
1401 page break; for example, a row Keep with @code{offset} 1 and @code{n}
1402 10 requests that the 10 rows starting with the second row be kept
1403 together. Usually no Keeps are specified.
1405 The PointKeeps seem to be generated automatically based on
1406 user-specified Keeps. They seems to indicate a conversion from rows
1407 or columns to pixel or point offsets.
1409 @code{notes} is a text string that contains user-specified notes. It
1410 is displayed when the user hovers the cursor over the table, like text
1411 in the @code{title} attribute in HTML@. It is not printed. It is
1414 @code{table-look} is the name of a SPSS ``TableLook'' table style,
1415 such as ``Default'' or ``Academic''; it is often empty.
1417 TableSettings ends with an arbitrary number of null bytes. A writer
1418 may safely write 82 null bytes.
1420 A writer may safely use 4 for @code{x5} and 0 for @code{x6}.
1422 @node SPV Light Member Formats
1427 int32[n-widths] int32*[n-widths]
1429 int32[current-layer]
1430 bool[x7] bool[x8] bool[x9]
1435 v3(count(X1 count(X2)) count(X3)))
1436 Y0 => int32[epoch] byte[decimal] byte[grouping]
1437 CustomCurrency => int32[n-ccs] string*[n-ccs]
1440 If @code{n-widths} is nonzero, then the accompanying integers are
1441 column widths as manually adjusted by the user.
1443 @code{locale} is a locale including an encoding, such as
1444 @code{en_US.windows-1252} or @code{it_IT.windows-1252}.
1445 (@code{locale} is often duplicated in Y1, described below).
1447 @code{epoch} is the year that starts the epoch. A 2-digit year is
1448 interpreted as belonging to the 100 years beginning at the epoch. The
1449 default epoch year is 69 years prior to the current year; thus, in
1450 2017 this field by default contains 1948. In the corpus, @code{epoch}
1451 ranges from 1943 to 1948, plus some contain -1.
1453 @code{decimal} is the decimal point character. The observed values
1454 are @samp{.} and @samp{,}.
1456 @code{grouping} is the grouping character. Usually, it is @samp{,} if
1457 @code{decimal} is @samp{.}, and vice versa. Other observed values are
1458 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1459 indicating that digits should not be grouped).
1461 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
1462 following strings are CCA through CCE format strings. @xref{Custom
1463 Currency Formats,,, pspp, PSPP}. Most commonly these are all
1464 @code{-,,,} but other strings occur.
1466 A writer may safely use false for @code{x7}, @code{x8}, and @code{x9}.
1470 X0 only appears, optionally, in version 1 members.
1475 string[command] string[command-local]
1476 string[language] string[charset] string[locale]
1477 bool[x10] bool[include-leading-zero] bool[x12] bool[x13]
1479 Y2 => CustomCurrency byte[missing] bool[x17]
1482 @code{command} describes the statistical procedure that generated the
1483 output, in English. It is not necessarily the literal syntax name of
1484 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1485 Tests.'' @code{command-local} is the procedure's name, translated
1486 into the output language; it is often empty and, when it is not,
1487 sometimes the same as @code{command}.
1489 @code{include-leading-zero} is the @code{LEADZERO} setting for the
1490 table, where false is @code{OFF} (the default) and true is @code{ON}.
1491 @xref{SET LEADZERO,,, pspp, PSPP}.
1493 @code{missing} is the character used to indicate that a cell contains
1494 a missing value. It is always observed as @samp{.}.
1496 A writer may safely use false for @code{x10} and @code{x17} and true
1497 for @code{x12} and @code{x13}.
1501 X1 only appears in version 3 members.
1509 byte[show-variables]
1511 int32[x18] int32[x19]
1517 @code{lang} may indicate the language in use. Some values seem to be
1518 0: @t{en}, 1: @t{de}, 2: @t{es}, 3: @t{it}, 5: @t{ko}, 6: @t{pl}, 8:
1519 @t{zh-tw}, 10: @t{pt_BR}, 11: @t{fr}.
1521 @code{show-variables} determines how variables are displayed by
1522 default. A value of 1 means to display variable names, 2 to display
1523 variable labels when available, 3 to display both (name followed by
1524 label, separated by a space). The most common value is 0, which
1525 probably means to use a global default.
1527 @code{show-values} is a similar setting for values. A value of 1
1528 means to display the value, 2 to display the value label when
1529 available, 3 to display both. Again, the most common value is 0,
1530 which probably means to use a global default.
1532 @code{show-title} is 1 to show the caption, 10 to hide it.
1534 @code{show-caption} is true to show the caption, false to hide it.
1536 A writer may safely use false for @code{x14}, false for @code{x16}, 0
1537 for @code{lang}, -1 for @code{x18} and @code{x19}, and false for
1542 X2 only appears in version 3 members.
1546 int32[n-row-heights] int32*[n-row-heights]
1547 int32[n-style-map] StyleMap*[n-style-map]
1548 int32[n-styles] StylePair*[n-styles]
1550 StyleMap => int64[cell-index] int16[style-index]
1553 If present, @code{n-row-heights} and the accompanying integers are row
1554 heights as manually adjusted by the user.
1556 The rest of X2 specifies styles for data cells. At first glance this
1557 is odd, because each data cell can have its own style embedded as part
1558 of the data, but in practice X2 specifies a style for a cell only if
1559 that cell is empty (and thus does not appear in the data at all).
1560 Each StyleMap specifies the index of a blank cell, calculated the same
1561 was as in the Cells (@pxref{SPV Light Member Cells}), along with a
1562 0-based index into the accompanying StylePair array.
1564 A writer may safely omit the optional @code{i0 i0} inside the
1565 @code{count(@dots{})}.
1569 X3 only appears in version 3 members.
1573 01 00 byte[x21] 00 00 00
1576 (string[dataset] string[datafile] i0 int32[date] i0)?
1578 (int32[x22] i0 01?)?
1581 @code{small} is a small real number. In the corpus, it overwhelmingly
1582 takes the value 0.0001, with zero occasionally seen. Nonzero numbers
1583 with format 40 (@pxref{SPV Light Member Value}) whose magnitudes are
1584 smaller than displayed in scientific notation. (Thus, a @code{small}
1585 of zero prevents scientific notation from being chosen.)
1587 @code{dataset} is the name of the dataset analyzed to produce the
1588 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1589 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}. The latter
1590 is sometimes the empty string.
1592 @code{date} is a date, as seconds since the epoch, i.e.@: since
1593 January 1, 1970. Pivot tables within an SPV file often have dates a
1594 few minutes apart, so this is probably a creation date for the table
1595 rather than for the file.
1597 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1598 and other times they are absent. The reader can distinguish by
1599 assuming that they are present and then checking whether the
1600 presumptive @code{dataset} contains a null byte (a valid string never
1603 @code{x22} is usually 0 or 2000000.
1605 A writer may safely use 4 for @code{x21} and omit @code{x22} and the
1606 other optional bytes at the end.
1608 @subsubheading Encoding
1610 Formats contains several indications of character encoding:
1614 @code{locale} in Formats itself.
1617 @code{locale} in Y1 (in version 1, Y1 is optionally nested inside X0;
1618 in version 3, Y1 is nested inside X3).
1621 @code{charset} in version 3, in Y1.
1624 @code{lang} in X1, in version 3.
1627 @code{charset}, if present, is a good indication of character
1628 encoding, and in its absence the encoding suffix on @code{locale} in
1631 @code{locale} in Y1 can be disregarded: it is normally the same as
1632 @code{locale} in Formats, and it is only present if @code{charset} is
1635 @code{lang} is not helpful and should be ignored for character
1638 However, the corpus contains many examples of light members whose
1639 strings are encoded in UTF-8 despite declaring some other character
1640 set. Furthermore, the corpus contains several examples of light
1641 members in which some strings are encoded in UTF-8 (and contain
1642 multibyte characters) and other strings are encoded in another
1643 character set (and contain non-ASCII characters). PSPP treats any
1644 valid UTF-8 string as UTF-8 and only falls back to the declared
1645 encoding for strings that are not valid UTF-8.
1647 The @command{pspp-output} program's @command{strings} command can help
1648 analyze the encoding in an SPV light member. Use @code{pspp-output
1649 --help-dev} to see its usage.
1651 @node SPV Light Member Dimensions
1652 @subsection Dimensions
1654 A pivot table presents multidimensional data. A Dimension identifies
1655 the categories associated with each dimension.
1658 Dimensions => int32[n-dims] Dimension*[n-dims]
1660 Value[name] DimProperties
1661 int32[n-categories] Category*[n-categories]
1666 bool[hide-dim-label]
1667 bool[hide-all-labels]
1671 @code{name} is the name of the dimension, e.g.@: @code{Variables},
1672 @code{Statistics}, or a variable name.
1674 The meanings of @code{x1} and @code{x3} are unknown. @code{x1} is
1675 usually 0 but many other values have been observed. A writer may
1676 safely use 0 for @code{x1} and 2 for @code{x3}.
1678 @code{x2} is 0, 1, or 2. For a pivot table with @var{L} layer
1679 dimensions, @var{R} row dimensions, and @var{C} column dimensions,
1680 @code{x2} is 2 for the first @var{L} dimensions, 0 for the next
1681 @var{R} dimensions, and 1 for the remaining @var{C} dimensions. This
1682 does not mean that the layer dimensions must be presented first,
1683 followed by the row dimensions, followed by the column dimensions---on
1684 the contrary, they are frequently in a different order---but @code{x2}
1685 must follow this pattern to prevent the pivot table from being
1688 If @code{hide-dim-label} is 00, the pivot table displays a label for
1689 the dimension itself. Because usually the group and category labels
1690 are enough explanation, it is usually 01.
1692 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1693 the dimension, including group and category labels. It is usually 00.
1694 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1696 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1697 0 for the first dimension, 1 for the second, and so on. Sometimes it
1698 is -1. There is no visible difference. A writer may safely use the
1701 @node SPV Light Member Categories
1702 @subsection Categories
1704 Categories are arranged in a tree. Only the leaf nodes in the tree
1705 are really categories; the others just serve as grouping constructs.
1708 Category => Value[name] (Leaf @math{|} Group)
1709 Leaf => 00 00 00 i2 int32[leaf-index] i0
1711 bool[merge] 00 01 int32[x23]
1712 i-1 int32[n-subcategories] Category*[n-subcategories]
1715 @code{name} is the name of the category (or group).
1717 A Leaf represents a leaf category. The Leaf's @code{leaf-index} is a
1718 nonnegative integer unique within the Dimension and less than
1719 @code{n-categories} in the Dimension. If the user does not sort or
1720 rearrange the categories, then @code{leaf-index} starts at 0 for the
1721 first Leaf in the dimension and increments by 1 with each successive
1722 Leaf. If the user does sorts or rearrange the categories, then the
1723 order of categories in the file reflects that change and
1724 @code{leaf-index} reflects the original order.
1726 A dimension can have no leaf categories at all. A table that
1727 contains such a dimension necessarily has no data at all.
1729 A Group is a group of nested categories. Usually a Group contains at
1730 least one Category, so that @code{n-subcategories} is positive, but
1731 Groups with zero subcategories have been observed.
1733 If a Group's @code{merge} is 00, the most common value, then the group
1734 is really a distinct group that should be represented as such in the
1735 visual representation and user interface. If @code{merge} is 01, the
1736 categories in this group should be shown and treated as if they were
1737 direct children of the group's containing group (or if it has no
1738 parent group, then direct children of the dimension), and this group's
1739 name is irrelevant and should not be displayed. (Merged groups can be
1742 Writers need not use merged groups.
1744 A Group's @code{x23} appears to be i2 when all of the categories
1745 within a group are leaf categories that directly represent data values
1746 for a variable (e.g.@: in a frequency table or crosstabulation, a group
1747 of values in a variable being tabulated) and i0 otherwise. A writer
1748 may safely write a constant 0 in this field.
1750 @node SPV Light Member Axes
1753 After the dimensions come assignment of each dimension to one of the
1754 axes: layers, rows, and columns.
1758 int32[n-layers] int32[n-rows] int32[n-columns]
1759 int32*[n-layers] int32*[n-rows] int32*[n-columns]
1762 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1763 each specifies the number of dimensions displayed in layers, rows, and
1764 columns, respectively. Any of them may be zero. Their values sum to
1765 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1768 The following @code{n-dimensions} integers, in three groups, are a
1769 permutation of the 0-based dimension numbers. The first
1770 @code{n-layers} integers specify each of the dimensions represented by
1771 layers, the next @code{n-rows} integers specify the dimensions
1772 represented by rows, and the final @code{n-columns} integers specify
1773 the dimensions represented by columns. When there is more than one
1774 dimension of a given kind, the inner dimensions are given first. (For
1775 the layer axis, this means that the first dimension is at the bottom
1776 of the list and the last dimension is at the top when the current
1777 layer is displayed.)
1779 @node SPV Light Member Cells
1782 The final part of an SPV light member contains the actual data.
1785 Cells => int32[n-cells] Cell*[n-cells]
1786 Cell => int64[index] v1(00?) Value
1789 A Cell consists of an @code{index} and a Value. Suppose there are
1790 @math{d} dimensions, numbered 1 through @math{d} in the order given in
1791 the Dimensions previously, and that dimension @math{i} has @math{n_i}
1792 categories. Consider the cell at coordinates @math{x_i}, @math{1 \le
1793 i \le d}, and note that @math{0 \le x_i < n_i}. Then the index is
1794 calculated by the following algorithm:
1798 for each @math{i} from 1 to @math{d}:
1799 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1802 For example, suppose there are 3 dimensions with 3, 4, and 5
1803 categories, respectively. The cell at coordinates (1, 2, 3) has
1804 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1805 Within a given dimension, the index is the @code{leaf-index} in a Leaf.
1807 @node SPV Light Member Value
1810 Value is used throughout the SPV light member format. It boils down
1811 to a number or a string.
1814 Value => 00? 00? 00? 00? RawValue
1816 01 ValueMod int32[format] double[x]
1817 @math{|} 02 ValueMod int32[format] double[x]
1818 string[var-name] string[value-label] byte[show]
1819 @math{|} 03 string[local] ValueMod string[id] string[c] bool[fixed]
1820 @math{|} 04 ValueMod int32[format] string[value-label] string[var-name]
1821 byte[show] string[s]
1822 @math{|} 05 ValueMod string[var-name] string[var-label] byte[show]
1823 @math{|} 06 string[local] ValueMod string[id] string[c]
1824 @math{|} ValueMod string[template] int32[n-args] Argument*[n-args]
1827 @math{|} int32[x] i0 Value*[x] /* x > 0 */
1830 There are several possible encodings, which one can distinguish by the
1831 first nonzero byte in the encoding.
1835 The numeric value @code{x}, intended to be presented to the user
1836 formatted according to @code{format}, which is about the same as the
1837 format described for system files (@pxref{System File Output
1838 Formats}). The exception is that format 40 is not MTIME but instead
1839 approximately a synonym for F format with a different rule for whether
1840 a value is shown in scientific notation: a value in format 40 is shown
1841 in scientific notation if and only if it is nonzero and its magnitude
1842 is less than @code{small} (@pxref{SPV Light Member Formats}).
1844 Most commonly, @code{format} has width 40 (the maximum).
1846 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1847 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1848 not been observed.) See @ref{System File Format}, for more about
1849 these special values.
1852 Similar to @code{01}, with the additional information that @code{x} is
1853 a value of variable @code{var-name} and has value label
1854 @code{value-label}. Both @code{var-name} and @code{value-label} can
1855 be the empty string, the latter very commonly.
1857 @code{show} determines whether to show the numeric value or the value
1858 label. A value of 1 means to show the value, 2 to show the label, 3
1859 to show both, and 0 means to use the default specified in
1860 @code{show-values} (@pxref{SPV Light Member Formats}).
1863 A text string, in two forms: @code{c} is in English, and sometimes
1864 abbreviated or obscure, and @code{local} is localized to the user's
1865 locale. In an English-language locale, the two strings are often the
1866 same, and in the cases where they differ, @code{local} is more
1867 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1868 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1869 where P must be greater than 1.''
1871 @code{c} and @code{local} are always either both empty or both
1874 @code{id} is a brief identifying string whose form seems to resemble a
1875 programming language identifier, e.g.@: @code{cumulative_percent} or
1876 @code{factor_14}. It is not unique.
1878 @code{fixed} is 00 for text taken from user input, such as syntax
1879 fragment, expressions, file names, data set names, and 01 for fixed
1880 text strings such as names of procedures or statistics. In the former
1881 case, @code{id} is always the empty string; in the latter case,
1882 @code{id} is still sometimes empty.
1885 The string value @code{s}, intended to be presented to the user
1886 formatted according to @code{format}. The format for a string is not
1887 too interesting, and the corpus contains many clearly invalid formats
1888 like A16.39 or A255.127 or A134.1, so readers should probably entirely
1889 disregard the format. PSPP only checks @code{format} to distinguish
1892 @code{s} is a value of variable @code{var-name} and has value label
1893 @code{value-label}. @code{var-name} is never empty but
1894 @code{value-label} is commonly empty.
1896 @code{show} has the same meaning as in the encoding for 02.
1899 Variable @code{var-name} with variable label @code{var-label}. In the
1900 corpus, @code{var-name} is rarely empty and @code{var-label} is often
1903 @code{show} determines whether to show the variable name or the
1904 variable label. A value of 1 means to show the name, 2 to show the
1905 label, 3 to show both, and 0 means to use the default specified in
1906 @code{show-variables} (@pxref{SPV Light Member Formats}).
1909 Similar to type 03, with @code{fixed} assumed to be true.
1912 When the first byte of a RawValue is not one of the above, the
1913 RawValue starts with a ValueMod, whose syntax is described in the next
1914 section. (A ValueMod always begins with byte 31 or 58.)
1916 This case is a template string, analogous to @code{printf}, followed
1917 by one or more Arguments, each of which has one or more values. The
1918 template string is copied directly into the output except for the
1919 following special syntax,
1926 Each of these expands to the character following @samp{\\}, to escape
1927 characters that have special meaning in template strings. These are
1928 effective inside and outside the @code{[@dots{}]} syntax forms
1932 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1936 Expands to a formatted version of argument @var{i}, which must have
1937 only a single value. For example, @code{^1} expands to the first
1938 argument's @code{value}.
1940 @item [:@var{a}:]@var{i}
1941 Expands @var{a} for each of the values in @var{i}. @var{a}
1942 should contain one or more @code{^@var{j}} conversions, which are
1943 drawn from the values for argument @var{i} in order. Some examples
1948 All of the values for the first argument, concatenated.
1951 Expands to the values for the first argument, each followed by
1955 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1956 argument's first value and @var{y} is its second value. (This would
1957 be used only if the argument has two values. If there were more
1958 values, the second and third values would be directly concatenated,
1959 which would look funny.)
1962 @item [@var{a}:@var{b}:]@var{i}
1963 This extends the previous form so that the first values are expanded
1964 using @var{a} and later values are expanded using @var{b}. For an
1965 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1966 instead written as @code{%@var{j}}. Some examples from the corpus:
1970 Expands to all of the values for the first argument, separated by
1973 @item [%1 = %2:, ^1 = ^2:]1
1974 Given appropriate values for the first argument, expands to @code{X =
1978 Given appropriate values, expands to @code{1, 2, 3}.
1982 The template string is localized to the user's locale.
1985 A writer may safely omit all of the optional 00 bytes at the beginning
1986 of a Value, except that it should write a single 00 byte before a
1989 @node SPV Light Member ValueMod
1990 @subsection ValueMod
1992 A ValueMod can specify special modifications to a Value.
1998 int32[n-refs] int16*[n-refs]
1999 int32[n-subscripts] string*[n-subscripts]
2000 v1(00 (i1 | i2) 00? 00? int32 00? 00?)
2001 v3(count(TemplateString StylePair))
2003 TemplateString => count((count((i0 (58 @math{|} 31 55))?) (58 @math{|} 31 string[id]))?)
2010 bool[bold] bool[italic] bool[underline] bool[show]
2011 string[fg-color] string[bg-color]
2012 string[typeface] byte[size]
2015 int32[halign] int32[valign] double[decimal-offset]
2016 int16[left-margin] int16[right-margin]
2017 int16[top-margin] int16[bottom-margin]
2020 A ValueMod that begins with ``31'' specifies special modifications to
2023 Each of the @code{n-refs} integers is a reference to a Footnote
2024 (@pxref{SPV Light Member Footnotes}) by 0-based index. Footnote
2025 markers are shown appended to the main text of the Value, as
2026 superscripts or subscripts.
2028 The @code{subscripts}, if present, are strings to append to the main
2029 text of the Value, as subscripts. Each subscript text is a brief
2030 indicator, e.g.@: @samp{a} or @samp{b}, with its meaning indicated by
2031 the table caption. When multiple subscripts are present, they are
2032 displayed separated by commas.
2034 The @code{id} inside the TemplateString, if present, is a template
2035 string for substitutions using the syntax explained previously. It
2036 appears to be an English-language version of the localized template
2037 string in the Value in which the Template is nested. A writer may
2038 safely omit the optional fixed data in TemplateString.
2040 FontStyle and CellStyle, if present, change the style for this
2041 individual Value. In FontStyle, @code{bold}, @code{italic}, and
2042 @code{underline} control the particular style. @code{show} is
2043 ordinarily 1; if it is 0, then the cell data is not shown.
2044 @code{fg-color} and @code{bg-color} are strings in the format
2045 @code{#rrggbb}, e.g.@: @code{#ff0000} for red or @code{#ffffff} for
2046 white. The empty string is occasionally observed also. The
2047 @code{size} is a font size in units of 1/128 inch.
2049 In CellStyle, @code{halign} is 0 for center, 2 for left, 4 for right,
2050 6 for decimal, 0xffffffad for mixed. For decimal alignment,
2051 @code{decimal-offset} is the decimal point's offset from the right
2052 side of the cell, in pt (@pxref{SPV Light Detail Member Format}).
2053 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
2054 for bottom. @code{left-margin}, @code{right-margin},
2055 @code{top-margin}, and @code{bottom-margin} are in pt.
2057 @node SPV Legacy Detail Member Binary Format
2058 @section Legacy Detail Member Binary Format
2060 Whereas the light binary format represents everything about a given
2061 pivot table, the legacy binary format conceptually consists of a
2062 number of named sources, each of which consists of a number of named
2063 variables, each of which is a 1-dimensional array of numbers or
2064 strings or a mix. Thus, the legacy binary member format is quite
2067 This section uses the same context-free grammar notation as in the
2068 previous section, with the following additions:
2072 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
2073 (The legacy member header indicates the version; see below.)
2076 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
2079 A legacy detail member @file{.bin} has the following overall format:
2083 00 byte[version] int16[n-sources] int32[member-size]
2084 Metadata*[n-sources]
2089 @code{version} is a version number that affects the interpretation of
2090 some of the other data in the member. Versions 0xaf and 0xb0 are
2091 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
2094 A legacy member consists of @code{n-sources} data sources, each of
2095 which has Metadata and Data.
2097 @code{member-size} is the size of the legacy binary member, in bytes.
2099 The Data and Strings above are commented out because the Metadata has
2100 some oddities that mean that the Data sometimes seems to start at
2101 an unexpected place. The following section goes into detail.
2104 * SPV Legacy Member Metadata::
2105 * SPV Legacy Member Numeric Data::
2106 * SPV Legacy Member String Data::
2109 @node SPV Legacy Member Metadata
2110 @subsection Metadata
2114 int32[n-values] int32[n-variables] int32[data-offset]
2115 vAF(byte*28[source-name])
2116 vB0(byte*64[source-name] int32[x])
2119 A data source has @code{n-variables} variables, each with
2120 @code{n-values} data values.
2122 @code{source-name} is a 28- or 64-byte string padded on the right with
2123 0-bytes. The names that appear in the corpus are very generic:
2124 usually @code{tableData} for pivot table data or @code{source0} for
2127 A given Metadata's @code{data-offset} is the offset, in bytes, from
2128 the beginning of the member to the start of the corresponding Data.
2129 This allows programs to skip to the beginning of the data for a
2130 particular source. In every case in the corpus, the Data follow the
2131 Metadata in the same order, but it is important to use
2132 @code{data-offset} instead of reading sequentially through the file
2133 because of the exception described below.
2135 One SPV file in the corpus has legacy binary members with version 0xb0
2136 but a 28-byte @code{source-name} field (and only a single source). In
2137 practice, this means that the 64-byte @code{source-name} used in
2138 version 0xb0 has a lot of 0-bytes in the middle followed by the
2139 @code{variable-name} of the following Data. As long as a reader
2140 treats the first 0-byte in the @code{source-name} as terminating the
2141 string, it can properly interpret these members.
2143 The meaning of @code{x} in version 0xb0 is unknown.
2145 @node SPV Legacy Member Numeric Data
2146 @subsection Numeric Data
2149 Data => Variable*[n-variables]
2150 Variable => byte*288[variable-name] double*[n-values]
2153 Data follow the Metadata in the legacy binary format, with sources in
2154 the same order (but readers should use the @code{data-offset} in
2155 Metadata records, rather than reading sequentially). Each Variable
2156 begins with a @code{variable-name} that generally indicates its role
2157 in the pivot table, e.g.@: ``cell'', ``cellFormat'',
2158 ``dimension0categories'', ``dimension0group0'', followed by the
2159 numeric data, one double per datum. A double with the maximum
2160 negative double @code{-DBL_MAX} represents the system-missing value
2163 @node SPV Legacy Member String Data
2164 @subsection String Data
2167 Strings => SourceMaps[maps] Labels
2169 SourceMaps => int32[n-maps] SourceMap*[n-maps]
2171 SourceMap => string[source-name] int32[n-variables] VariableMap*[n-variables]
2172 VariableMap => string[variable-name] int32[n-data] DatumMap*[n-data]
2173 DatumMap => int32[value-idx] int32[label-idx]
2175 Labels => int32[n-labels] Label*[n-labels]
2176 Label => int32[frequency] string[label]
2179 Each variable may include a mix of numeric and string data values. If
2180 a legacy binary member contains any string data, Strings is present;
2181 otherwise, it ends just after the last Data element.
2183 The string data overlays the numeric data. When a variable includes
2184 any string data, its Variable represents the string values with a
2185 SYSMIS or NaN placeholder. (Not all such values need be
2188 Each SourceMap provides a mapping between SYSMIS or NaN values in source
2189 @code{source-name} and the string data that they represent.
2190 @code{n-variables} is the number of variables in the source that
2191 include string data. More precisely, it is the 1-based index of the
2192 last variable in the source that includes any string data; thus, it
2193 would be 4 if there are 5 variables and only the fourth one includes
2196 A VariableMap repeats its variable's name, but variables are always
2197 present in the same order as the source, starting from the first
2198 variable, without skipping any even if they have no string values.
2199 Each VariableMap contains DatumMap nonterminals, each of which maps
2200 from a 0-based index within its variable's data to a 0-based label
2201 index, e.g.@: pair @code{value-idx} = 2, @code{label-idx} = 3, means
2202 that the third data value (which must be SYSMIS or NaN) is to be
2203 replaced by the string of the fourth Label.
2205 The labels themselves follow the pairs. The valuable part of each
2206 label is the string @code{label}. Each label also includes a
2207 @code{frequency} that reports the number of DatumMaps that reference
2208 it (although this is not useful).
2210 @node SPV Legacy Detail Member XML Format
2211 @section Legacy Detail Member XML Format
2213 The design of the detail XML format is not what one would end up with
2214 for describing pivot tables. This is because it is a special case
2215 of a much more general format (``visualization XML'' or ``VizML'')
2216 that can describe a wide range of visualizations. Most of this
2217 generality is overkill for tables, and so we end up with a funny
2218 subset of a general-purpose format.
2220 An XML Schema for VizML is available, distributed with SPSS binaries,
2221 under a nonfree license. It contains documentation that is
2222 occasionally helpful.
2224 This section describes the detail XML format using the same notation
2225 already used for the structure XML format (@pxref{SPV Structure Member
2226 Format}). See @file{src/output/spv/detail-xml.grammar} in the PSPP
2227 source tree for the full grammar that it uses for parsing.
2229 The important elements of the detail XML format are:
2233 Variables. @xref{SPV Detail Variable Elements}.
2236 Assignment of variables to axes. A variable can appear as columns, or
2237 rows, or layers. The @code{faceting} element and its sub-elements
2238 describe this assignment.
2241 Styles and other annotations.
2244 This description is not detailed enough to write legacy tables.
2245 Instead, write tables in the light binary format.
2248 * SPV Detail visualization Element::
2249 * SPV Detail Variable Elements::
2250 * SPV Detail extension Element::
2251 * SPV Detail graph Element::
2252 * SPV Detail location Element::
2253 * SPV Detail faceting Element::
2254 * SPV Detail facetLayout Element::
2255 * SPV Detail label Element::
2256 * SPV Detail setCellProperties Element::
2257 * SPV Detail setFormat Element::
2258 * SPV Detail interval Element::
2259 * SPV Detail style Element::
2260 * SPV Detail labelFrame Element::
2261 * SPV Detail Legacy Properties::
2264 @node SPV Detail visualization Element
2265 @subsection The @code{visualization} Element
2273 :style[style_ref]=ref style
2277 => visualization_extension?
2279 (sourceVariable | derivedVariable)+
2288 extension[visualization_extension]
2291 :minWidthSet=(true)?
2292 :maxWidthSet=(true)?
2295 userSource :missing=(listwise | pairwise)? => EMPTY
2297 categoricalDomain => variableReference simpleSort
2299 simpleSort :method[sort_method]=(custom) => categoryOrder
2301 container :style=ref style => container_extension? location+ labelFrame*
2303 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2311 The @code{visualization} element is the root of detail XML member. It
2312 has the following attributes:
2314 @defvr {Attribute} creator
2315 The version of the software that created this SPV file, as a string of
2316 the form @code{xxyyzz}, which represents software version xx.yy.zz,
2317 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
2318 versions 16 through 19.
2321 @defvr {Attribute} date
2322 The date on the which the file was created, as a string of the form
2326 @defvr {Attribute} lang
2327 The locale used for output, in Windows format, which is similar to the
2328 format used in Unix with the underscore replaced by a hyphen, e.g.@:
2329 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
2332 @defvr {Attribute} name
2333 The title of the pivot table, localized to the output language.
2336 @defvr {Attribute} style
2337 The base style for the pivot table. In every example in the corpus,
2338 the @code{style} element has no attributes other than @code{id}.
2341 @defvr {Attribute} type
2342 A floating-point number. The meaning is unknown.
2345 @defvr {Attribute} version
2346 The visualization schema version number. In the corpus, the value is
2347 one of 2.4, 2.5, 2.7, and 2.8.
2350 The @code{userSource} element has no visible effect.
2352 The @code{extension} element as a child of @code{visualization} has
2353 the following attributes.
2355 @defvr {Attribute} numRows
2356 An integer that presumably defines the number of rows in the displayed
2360 @defvr {Attribute} showGridline
2361 Always set to @code{false} in the corpus.
2364 @defvr {Attribute} minWidthSet
2365 @defvrx {Attribute} maxWidthSet
2366 Always set to @code{true} in the corpus.
2369 The @code{extension} element as a child of @code{container} has the
2372 @defvr {Attribute} combinedFootnotes
2376 The @code{categoricalDomain} and @code{simpleSort} elements have no
2379 The @code{layerController} element has no visible effect.
2381 @node SPV Detail Variable Elements
2382 @subsection Variable Elements
2384 A ``variable'' in detail XML is a 1-dimensional array of data. Each
2385 element of the array may, independently, have string or numeric
2386 content. All of the variables in a given detail XML member either
2387 have the same number of elements or have zero elements.
2389 Two different elements define variables and their content:
2392 @item sourceVariable
2393 These variables' data comes from the associated @code{tableData.bin}
2396 @item derivedVariable
2397 These variables are defined in terms of a mapping function from a
2398 source variable, or they are empty.
2401 A variable named @code{cell} always exists. This variable holds the
2402 data displayed in the table.
2404 Variables in detail XML roughly correspond to the dimensions in a
2405 light detail member. Each dimension has the following variables with
2406 stylized names, where @var{n} is a number for the dimension starting
2410 @item dimension@var{n}categories
2411 The dimension's leaf categories (@pxref{SPV Light Member Categories}).
2413 @item dimension@var{n}group0
2414 Present only if the dimension's categories are grouped, this variable
2415 holds the group labels for the categories. Grouping is inferred
2416 through adjacent identical labels. Categories that are not part of a
2417 group have empty-string data in this variable.
2419 @item dimension@var{n}group1
2420 Present only if the first-level groups are further grouped, this
2421 variable holds the labels for the second-level groups. There can be
2422 additional variables with further levels of grouping.
2424 @item dimension@var{n}
2428 Determining the data for a (non-empty) variable is a multi-step
2433 Draw initial data from its source, for a @code{sourceVariable}, or
2434 from another named variable, for a @code{derivedVariable}.
2437 Apply mappings from @code{valueMapEntry} elements within the
2438 @code{derivedVariable} element, if any.
2441 Apply mappings from @code{relabel} elements within a @code{format} or
2442 @code{stringFormat} element in the @code{sourceVariable} or
2443 @code{derivedVariable} element, if any.
2446 If the variable is a @code{sourceVariable} with a @code{labelVariable}
2447 attribute, and there were no mappings to apply in previous steps, then
2448 replace each element of the variable by the corresponding value in the
2452 A single variable's data can be modified in two of the steps, if both
2453 @code{valueMapEntry} and @code{relabel} are used. The following
2454 example from the corpus maps several integers to 2, then maps 2 in
2455 turn to the string ``Input'':
2458 <derivedVariable categorical="true" dependsOn="dimension0categories"
2459 id="dimension0group0map" value="map(dimension0group0)">
2461 <relabel from="2" to="Input"/>
2462 <relabel from="10" to="Missing Value Handling"/>
2463 <relabel from="14" to="Resources"/>
2464 <relabel from="0" to=""/>
2465 <relabel from="1" to=""/>
2466 <relabel from="13" to=""/>
2468 <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
2469 <valueMapEntry from="10;11" to="10"/>
2470 <valueMapEntry from="14;15" to="14"/>
2471 <valueMapEntry from="0" to="0"/>
2472 <valueMapEntry from="1" to="1"/>
2473 <valueMapEntry from="13" to="13"/>
2478 * SPV Detail sourceVariable Element::
2479 * SPV Detail derivedVariable Element::
2480 * SPV Detail valueMapEntry Element::
2483 @node SPV Detail sourceVariable Element
2484 @subsubsection The @code{sourceVariable} Element
2491 :domain=ref categoricalDomain?
2493 :dependsOn=ref sourceVariable?
2495 :labelVariable=ref sourceVariable?
2496 => variable_extension* (format | stringFormat)?
2499 This element defines a variable whose data comes from the
2500 @file{tableData.bin} member that corresponds to this @file{.xml}.
2502 This element has the following attributes.
2504 @defvr {Attribute} id
2505 An @code{id} is always present because this element exists to be
2506 referenced from other elements.
2509 @defvr {Attribute} categorical
2510 Always set to @code{true}.
2513 @defvr {Attribute} source
2514 Always set to @code{tableData}, the @code{source-name} in the
2515 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
2519 @defvr {Attribute} sourceName
2520 The name of a variable within the source, corresponding to the
2521 @code{variable-name} in the @file{tableData.bin} member (@pxref{SPV
2522 Legacy Member Numeric Data}).
2525 @defvr {Attribute} label
2526 The variable label, if any.
2529 @defvr {Attribute} labelVariable
2530 The @code{variable-name} of a variable whose string values correspond
2531 one-to-one with the values of this variable and are suitable for use
2535 @defvr {Attribute} dependsOn
2536 This attribute doesn't affect the display of a table.
2539 @node SPV Detail derivedVariable Element
2540 @subsubsection The @code{derivedVariable} Element
2547 :dependsOn=ref sourceVariable?
2548 => variable_extension* (format | stringFormat)? valueMapEntry*
2551 Like @code{sourceVariable}, this element defines a variable whose
2552 values can be used elsewhere in the visualization. Instead of being
2553 read from a data source, the variable's data are defined by a
2554 mathematical expression.
2556 This element has the following attributes.
2558 @defvr {Attribute} id
2559 An @code{id} is always present because this element exists to be
2560 referenced from other elements.
2563 @defvr {Attribute} categorical
2564 Always set to @code{true}.
2567 @defvr {Attribute} value
2568 An expression that defines the variable's value. In theory this could
2569 be an arbitrary expression in terms of constants, functions, and other
2570 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
2571 the corpus contains only the following forms of expressions:
2575 @itemx constant(@var{variable})
2576 All zeros. The reason why a variable is sometimes named is unknown.
2577 Sometimes the ``variable name'' has spaces in it.
2579 @item map(@var{variable})
2580 Transforms the values in the named @var{variable} using the
2581 @code{valueMapEntry}s contained within the element.
2585 @defvr {Attribute} dependsOn
2586 This attribute doesn't affect the display of a table.
2589 @node SPV Detail valueMapEntry Element
2590 @subsubsection The @code{valueMapEntry} Element
2593 valueMapEntry :from :to => EMPTY
2596 A @code{valueMapEntry} element defines a mapping from one or more
2597 values of a source expression to a target value. (In the corpus, the
2598 source expression is always just the name of a variable.) Each target
2599 value requires a separate @code{valueMapEntry}. If multiple source
2600 values map to the same target value, they can be combined or separate.
2602 In the corpus, all of the source and target values are integers.
2604 @code{valueMapEntry} has the following attributes.
2606 @defvr {Attribute} from
2607 A source value, or multiple source values separated by semicolons,
2608 e.g.@: @code{0} or @code{13;14;15;16}.
2611 @defvr {Attribute} to
2612 The target value, e.g.@: @code{0}.
2615 @node SPV Detail extension Element
2616 @subsection The @code{extension} Element
2618 This is a general-purpose ``extension'' element. Readers that don't
2619 understand a given extension should be able to safely ignore it. The
2620 attributes on this element, and their meanings, vary based on the
2621 context. Each known usage is described separately below. The current
2622 extensions use attributes exclusively, without any nested elements.
2624 @subsubheading @code{container} Parent Element
2627 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2630 With @code{container} as its parent element, @code{extension} has the
2631 following attributes.
2633 @defvr {Attribute} combinedFootnotes
2634 Always set to @code{true} in the corpus.
2637 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
2640 extension[variable_extension] :from :helpId => EMPTY
2643 With @code{sourceVariable} or @code{derivedVariable} as its parent
2644 element, @code{extension} has the following attributes. A given
2645 parent element often contains several @code{extension} elements that
2646 specify the meaning of the source data's variables or sources, e.g.@:
2649 <extension from="0" helpId="corrected_model"/>
2650 <extension from="3" helpId="error"/>
2651 <extension from="4" helpId="total_9"/>
2652 <extension from="5" helpId="corrected_total"/>
2655 More commonly they are less helpful, e.g.@:
2658 <extension from="0" helpId="notes"/>
2659 <extension from="1" helpId="notes"/>
2660 <extension from="2" helpId="notes"/>
2661 <extension from="5" helpId="notes"/>
2662 <extension from="6" helpId="notes"/>
2663 <extension from="7" helpId="notes"/>
2664 <extension from="8" helpId="notes"/>
2665 <extension from="12" helpId="notes"/>
2666 <extension from="13" helpId="no_help"/>
2667 <extension from="14" helpId="notes"/>
2670 @defvr {Attribute} from
2671 An integer or a name like ``dimension0''.
2674 @defvr {Attribute} helpId
2678 @node SPV Detail graph Element
2679 @subsection The @code{graph} Element
2683 :cellStyle=ref style
2685 => location+ coordinates faceting facetLayout interval
2687 coordinates => EMPTY
2690 @code{graph} has the following attributes.
2692 @defvr {Attribute} cellStyle
2693 @defvrx {Attribute} style
2694 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
2695 Detail style Element}). The former is the default style for
2696 individual cells, the latter for the entire table.
2699 @node SPV Detail location Element
2700 @subsection The @code{location} Element
2704 :part=(height | width | top | bottom | left | right)
2705 :method=(sizeToContent | attach | fixed | same)
2708 :target=ref (labelFrame | graph | container)?
2713 Each instance of this element specifies where some part of the table
2714 frame is located. All the examples in the corpus have four instances
2715 of this element, one for each of the parts @code{height},
2716 @code{width}, @code{left}, and @code{top}. Some examples in the
2717 corpus add a fifth for part @code{bottom}, even though it is not clear
2718 how all of @code{top}, @code{bottom}, and @code{height} can be honored
2719 at the same time. In any case, @code{location} seems to have little
2720 importance in representing tables; a reader can safely ignore it.
2722 @defvr {Attribute} part
2723 The part of the table being located.
2726 @defvr {Attribute} method
2727 How the location is determined:
2731 Based on the natural size of the table. Observed only for
2732 parts @code{height} and @code{width}.
2735 Based on the location specified in @code{target}. Observed only for
2736 parts @code{top} and @code{bottom}.
2739 Using the value in @code{value}. Observed only for parts @code{top},
2740 @code{bottom}, and @code{left}.
2743 Same as the specified @code{target}. Observed only for part
2748 @defvr {Attribute} min
2749 Minimum size. Only observed with value @code{100pt}. Only observed
2750 for part @code{width}.
2753 @defvr {Dependent} target
2754 Required when @code{method} is @code{attach} or @code{same}, not
2755 observed otherwise. This identifies an element to attach to.
2756 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
2760 @defvr {Dependent} value
2761 Required when @code{method} is @code{fixed}, not observed otherwise.
2762 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
2763 on parts @code{top} and @code{left}, and @code{100%} on part
2767 @node SPV Detail faceting Element
2768 @subsection The @code{faceting} Element
2771 faceting => layer[layers1]* cross layer[layers2]*
2773 cross => (unity | nest) (unity | nest)
2777 nest => variableReference[vars]+
2779 variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY
2782 :variable=ref (sourceVariable | derivedVariable)
2785 :method[layer_method]=(nest)?
2790 The @code{faceting} element describes the row, column, and layer
2791 structure of the table. Its @code{cross} child determines the row and
2792 column structure, and each @code{layer} child (if any) represents a
2793 layer. Layers may appear before or after @code{cross}.
2795 The @code{cross} element describes the row and column structure of the
2796 table. It has exactly two children, the first of which describes the
2797 table's columns and the second the table's rows. Each child is a
2798 @code{nest} element if the table has any dimensions along the axis in
2799 question, otherwise a @code{unity} element.
2801 A @code{nest} element contains of one or more dimensions listed from
2802 innermost to outermost, each represented by @code{variableReference}
2803 child elements. Each variable in a dimension is listed in order.
2804 @xref{SPV Detail Variable Elements}, for information on the variables
2805 that comprise a dimension.
2807 A @code{nest} can contain a single dimension, e.g.:
2811 <variableReference ref="dimension0categories"/>
2812 <variableReference ref="dimension0group0"/>
2813 <variableReference ref="dimension0"/>
2818 A @code{nest} can contain multiple dimensions, e.g.:
2822 <variableReference ref="dimension1categories"/>
2823 <variableReference ref="dimension1group0"/>
2824 <variableReference ref="dimension1"/>
2825 <variableReference ref="dimension0categories"/>
2826 <variableReference ref="dimension0"/>
2830 A @code{nest} may have no dimensions, in which case it still has one
2831 @code{variableReference} child, which references a
2832 @code{derivedVariable} whose @code{value} attribute is
2833 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
2834 @code{row} or @code{column}, respectively, as its @code{id}. This is
2835 equivalent to using a @code{unity} element in place of @code{nest}.
2837 A @code{variableReference} element refers to a variable through its
2838 @code{ref} attribute.
2840 Each @code{layer} element represents a dimension, e.g.:
2843 <layer value="0" variable="dimension0categories" visible="true"/>
2844 <layer value="dimension0" variable="dimension0" visible="false"/>
2848 @code{layer} has the following attributes.
2850 @defvr {Attribute} variable
2851 Refers to a @code{sourceVariable} or @code{derivedVariable} element.
2854 @defvr {Attribute} value
2855 The value to select. For a category variable, this is always
2856 @code{0}; for a data variable, it is the same as the @code{variable}
2860 @defvr {Attribute} visible
2861 Whether the layer is visible. Generally, category layers are visible
2862 and data layers are not, but sometimes this attribute is omitted.
2865 @defvr {Attribute} method
2866 When present, this is always @code{nest}.
2869 @node SPV Detail facetLayout Element
2870 @subsection The @code{facetLayout} Element
2873 facetLayout => tableLayout setCellProperties[scp1]*
2874 facetLevel+ setCellProperties[scp2]*
2877 :verticalTitlesInCorner=bool
2879 :fitCells=(ticks both)?
2883 The @code{facetLayout} element and its descendants control styling for
2886 Its @code{tableLayout} child has the following attributes
2888 @defvr {Attribute} verticalTitlesInCorner
2889 If true, in the absence of corner text, row headings will be displayed
2893 @defvr {Attribute} style
2894 Refers to a @code{style} element.
2897 @defvr {Attribute} fitCells
2901 @subsubheading The @code{facetLevel} Element
2904 facetLevel :level=int :gap=dimension? => axis
2906 axis :style=ref style => label? majorTicks
2912 :tickFrameStyle=ref style
2913 :labelFrequency=int?
2923 Each @code{facetLevel} describes a @code{variableReference} or
2924 @code{layer}, and a table has one @code{facetLevel} element for
2925 each such element. For example, an SPV detail member that contains
2926 four @code{variableReference} elements and two @code{layer} elements
2927 will contain six @code{facetLevel} elements.
2929 In the corpus, @code{facetLevel} elements and the elements that they
2930 describe are always in the same order. The correspondence may also be
2931 observed in two other ways. First, one may use the @code{level}
2932 attribute, described below. Second, in the corpus, a
2933 @code{facetLevel} always has an @code{id} that is the same as the
2934 @code{id} of the element it describes with @code{_facetLevel}
2935 appended. One should not formally rely on this, of course, but it is
2936 usefully indicative.
2938 @defvr {Attribute} level
2939 A 1-based index into the @code{variableReference} and @code{layer}
2940 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2941 describes the first @code{variableReference} in the SPV detail member,
2942 and in a member with four @code{variableReference} elements, a
2943 @code{facetLayout} with a @code{level} of 5 describes the first
2944 @code{layer} in the member.
2947 @defvr {Attribute} gap
2948 Always observed as @code{0pt}.
2951 Each @code{facetLevel} contains an @code{axis}, which in turn may
2952 contain a @code{label} for the @code{facetLevel} (@pxref{SPV Detail
2953 label Element}) and does contain a @code{majorTicks} element.
2955 @defvr {Attribute} labelAngle
2956 Normally 0. The value -90 causes inner column or outer row labels to
2957 be rotated vertically.
2960 @defvr {Attribute} style
2961 @defvrx {Attribute} tickFrameStyle
2962 Each refers to a @code{style} element. @code{style} is the style of
2963 the tick labels, @code{tickFrameStyle} the style for the frames around
2967 @node SPV Detail label Element
2968 @subsection The @code{label} Element
2973 :textFrameStyle=ref style?
2974 :purpose=(title | subTitle | subSubTitle | layer | footnote)?
2975 => text+ | descriptionGroup
2978 :target=ref faceting
2980 => (description | text)+
2982 description :name=(variable | value) => EMPTY
2986 :definesReference=int?
2987 :position=(subscript | superscript)?
2992 This element represents a label on some aspect of the table.
2994 @defvr {Attribute} style
2995 @defvrx {Attribute} textFrameStyle
2996 Each of these refers to a @code{style} element. @code{style} is the
2997 style of the label text, @code{textFrameStyle} the style for the frame
3001 @defvr {Attribute} purpose
3002 The kind of entity being labeled.
3005 A @code{descriptionGroup} concatenates one or more elements to form a
3006 label. Each element can be a @code{text} element, which contains
3007 literal text, or a @code{description} element that substitutes a value
3010 @defvr {Attribute} target
3011 The @code{id} of an element being described. In the corpus, this is
3012 always @code{faceting}.
3015 @defvr {Attribute} separator
3016 A string to separate the description of multiple groups, if the
3017 @code{target} has more than one. In the corpus, this is always a
3021 Typical contents for a @code{descriptionGroup} are a value by itself:
3023 <description name="value"/>
3025 @noindent or a variable and its value, separated by a colon:
3027 <description name="variable"/><text>:</text><description name="value"/>
3030 A @code{description} is like a macro that expands to some property of
3031 the target of its parent @code{descriptionGroup}. The @code{name}
3032 attribute specifies the property.
3034 @node SPV Detail setCellProperties Element
3035 @subsection The @code{setCellProperties} Element
3039 :applyToConverse=bool?
3040 => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]?
3043 The @code{setCellProperties} element sets style properties of cells or
3044 row or column labels.
3046 Interpreting @code{setCellProperties} requires answering two
3047 questions: which cells or labels to style, and what styles to use.
3049 @subsubheading Which Cells?
3054 intersect => where+ | intersectWhere | alternating | EMPTY
3057 :variable=ref (sourceVariable | derivedVariable)
3062 :variable=ref (sourceVariable | derivedVariable)
3063 :variable2=ref (sourceVariable | derivedVariable)
3066 alternating => EMPTY
3069 When @code{union} is present with @code{intersect} children, each of
3070 those children specifies a group of cells that should be styled, and
3071 the total group is all those cells taken together. When @code{union}
3072 is absent, every cell is styled. One attribute on
3073 @code{setCellProperties} affects the choice of cells:
3075 @defvr {Attribute} applyToConverse
3076 If true, this inverts the meaning of the cell selection: the selected
3077 cells are the ones @emph{not} designated. This is confusing, given
3078 the additional restrictions of @code{union}, but in the corpus
3079 @code{applyToConverse} is never present along with @code{union}.
3082 An @code{intersect} specifies restrictions on the cells to be matched.
3083 Each @code{where} child specifies which values of a given variable to
3084 include. The attributes of @code{intersect} are:
3086 @defvr {Attribute} variable
3087 Refers to a variable, e.g.@: @code{dimension0categories}. Only
3088 ``categories'' variables make sense here, but other variables, e.g.@:
3089 @code{dimension0group0map}, are sometimes seen. The reader may ignore
3093 @defvr {Attribute} include
3094 A value, or multiple values separated by semicolons,
3095 e.g.@: @code{0} or @code{13;14;15;16}.
3098 PSPP ignores @code{setCellProperties} when @code{intersectWhere} is
3101 @subsubheading What Styles?
3105 :target=ref (labeling | graph | interval | majorTicks)
3109 setMetaData :target=ref graph :key :value => EMPTY
3112 :target=ref (majorTicks | labeling)
3114 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
3118 :target=ref majorTicks
3122 The @code{set*} children of @code{setCellProperties} determine the
3125 When @code{setCellProperties} contains a @code{setFormat} whose
3126 @code{target} references a @code{labeling} element, or if it contains
3127 a @code{setStyle} that references a @code{labeling} or @code{interval}
3128 element, the @code{setCellProperties} sets the style for table cells.
3129 The format from the @code{setFormat}, if present, replaces the cells'
3130 format. The style from the @code{setStyle} that references
3131 @code{labeling}, if present, replaces the label's font and cell
3132 styles, except that the background color is taken instead from the
3133 @code{interval}'s style, if present.
3135 When @code{setCellProperties} contains a @code{setFormat} whose
3136 @code{target} references a @code{majorTicks} element, or if it
3137 contains a @code{setStyle} whose @code{target} references a
3138 @code{majorTicks}, or if it contains a @code{setFrameStyle} element,
3139 the @code{setCellProperties} sets the style for row or column labels.
3140 In this case, the @code{setCellProperties} always contains a single
3141 @code{where} element whose @code{variable} designates the variable
3142 whose labels are to be styled. The format from the @code{setFormat},
3143 if present, replaces the labels' format. The style from the
3144 @code{setStyle} that references @code{majorTicks}, if present,
3145 replaces the labels' font and cell styles, except that the background
3146 color is taken instead from the @code{setFrameStyle}'s style, if
3149 When @code{setCellProperties} contains a @code{setStyle} whose
3150 @code{target} references a @code{graph} element, and one that
3151 references a @code{labeling} element, and the @code{union} element
3152 contains @code{alternating}, the @code{setCellProperties} sets the
3153 alternate foreground and background colors for the data area. The
3154 foreground color is taken from the style referenced by the
3155 @code{setStyle} that targets the @code{graph}, the background color
3156 from the @code{setStyle} for @code{labeling}.
3158 A reader may ignore a @code{setCellProperties} that only contains
3159 @code{setMetaData}, as well as @code{setMetaData} within other
3160 @code{setCellProperties}.
3162 A reader may ignore a @code{setCellProperties} whose only @code{set*}
3163 child is a @code{setStyle} that targets the @code{graph} element.
3165 @subsubheading The @code{setStyle} Element
3169 :target=ref (labeling | graph | interval | majorTicks)
3174 This element associates a style with the target.
3176 @defvr {Attribute} target
3177 The @code{id} of an element whose style is to be set.
3180 @defvr {Attribute} style
3181 The @code{id} of a @code{style} element that identifies the style to
3185 @node SPV Detail setFormat Element
3186 @subsection The @code{setFormat} Element
3190 :target=ref (majorTicks | labeling)
3192 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
3195 This element sets the format of the target, ``format'' in this case
3196 meaning the SPSS print format for a variable.
3198 The details of this element vary depending on the schema version, as
3199 declared in the root @code{visualization} element's @code{version}
3200 attribute (@pxref{SPV Detail visualization Element}). A reader can
3201 interpret the content without knowing the schema version.
3203 The @code{setFormat} element itself has the following attributes.
3205 @defvr {Attribute} target
3206 Refers to an element whose style is to be set.
3209 @defvr {Attribute} reset
3210 If this is @code{true}, this format replaces the target's previous
3211 format. If it is @code{false}, the modifies the previous format.
3215 * SPV Detail numberFormat Element::
3216 * SPV Detail stringFormat Element::
3217 * SPV Detail dateTimeFormat Element::
3218 * SPV Detail elapsedTimeFormat Element::
3219 * SPV Detail format Element::
3220 * SPV Detail affix Element::
3223 @node SPV Detail numberFormat Element
3224 @subsubsection The @code{numberFormat} Element
3228 :minimumIntegerDigits=int?
3229 :maximumFractionDigits=int?
3230 :minimumFractionDigits=int?
3232 :scientific=(onlyForSmall | whenNeeded | true | false)?
3239 Specifies a format for displaying a number. The available options are
3240 a superset of those available from PSPP print formats. PSPP chooses a
3241 print format type for a @code{numberFormat} as follows:
3245 If @code{scientific} is @code{true}, uses @code{E} format.
3248 If @code{prefix} is @code{$}, uses @code{DOLLAR} format.
3251 If @code{suffix} is @code{%}, uses @code{PCT} format.
3254 If @code{useGrouping} is @code{true}, uses @code{COMMA} format.
3257 Otherwise, uses @code{F} format.
3260 For translating to a print format, PSPP uses
3261 @code{maximumFractionDigits} as the number of decimals, unless that
3262 attribute is missing or out of the range [0,15], in which case it uses
3265 @defvr {Attribute} minimumIntegerDigits
3266 Minimum number of digits to display before the decimal point. Always
3267 observed as @code{0}.
3270 @defvr {Attribute} maximumFractionDigits
3271 @defvrx {Attribute} minimumFractionDigits
3272 Maximum or minimum, respectively, number of digits to display after
3273 the decimal point. The observed values of each attribute range from 0
3277 @defvr {Attribute} useGrouping
3278 Whether to use the grouping character to group digits in large
3282 @defvr {Attribute} scientific
3283 This attribute controls when and whether the number is formatted in
3284 scientific notation. It takes the following values:
3288 Use scientific notation only when the number's magnitude is smaller
3289 than the value of the @code{small} attribute.
3292 Use scientific notation when the number will not otherwise fit in the
3296 Always use scientific notation. Not observed in the corpus.
3299 Never use scientific notation. A number that won't otherwise fit will
3300 be replaced by an error indication (see the @code{errorCharacter}
3301 attribute). Not observed in the corpus.
3305 @defvr {Attribute} small
3306 Only present when the @code{scientific} attribute is
3307 @code{onlyForSmall}, this is a numeric magnitude below which the
3308 number will be formatted in scientific notation. The values @code{0}
3309 and @code{0.0001} have been observed. The value @code{0} seems like a
3310 pathological choice, since no real number has a magnitude less than 0;
3311 perhaps in practice such a choice is equivalent to setting
3312 @code{scientific} to @code{false}.
3315 @defvr {Attribute} prefix
3316 @defvrx {Attribute} suffix
3317 Specifies a prefix or a suffix to apply to the formatted number. Only
3318 @code{suffix} has been observed, with value @samp{%}.
3321 @node SPV Detail stringFormat Element
3322 @subsubsection The @code{stringFormat} Element
3325 stringFormat => relabel* affix*
3327 relabel :from=real :to => EMPTY
3330 The @code{stringFormat} element specifies how to display a string. By
3331 default, a string is displayed verbatim, but @code{relabel} can change
3334 The @code{relabel} element appears as a child of @code{stringFormat}
3335 (and of @code{format}, when it is used to format strings). It
3336 specifies how to display a given value. It is used to implement value
3337 labels and to display the system-missing value in a human-readable
3338 way. It has the following attributes:
3340 @defvr {Attribute} from
3341 The value to map. In the corpus this is an integer or the
3342 system-missing value @code{-1.797693134862316E300}.
3345 @defvr {Attribute} to
3346 The string to display in place of the value of @code{from}. In the
3347 corpus this is a wide variety of value labels; the system-missing
3348 value is mapped to @samp{.}.
3351 @node SPV Detail dateTimeFormat Element
3352 @subsubsection The @code{dateTimeFormat} Element
3356 :baseFormat[dt_base_format]=(date | time | dateTime)
3358 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3360 :yearAbbreviation=bool?
3365 :monthFormat=(long | short | number | paddedNumber)?
3369 :showDayOfWeek=bool?
3370 :dayOfWeekAbbreviation=bool?
3372 :dayOfMonthPadding=bool?
3374 :minutePadding=bool?
3375 :secondPadding=bool?
3381 :dayType=(month | year)?
3382 :hourFormat=(AMPM | AS_24 | AS_12)?
3386 This element appears only in schema version 2.5 and earlier
3387 (@pxref{SPV Detail visualization Element}).
3389 Data to be formatted in date formats is stored as strings in legacy
3390 data, in the format @code{yyyy-mm-ddTHH:MM:SS.SSS} and must be parsed
3391 and reformatted by the reader.
3393 The following attribute is required.
3395 @defvr {Attribute} baseFormat
3396 Specifies whether a date and time are both to be displayed, or just
3400 Many of the attributes' meanings are obvious. The following seem to
3401 be worth documenting.
3403 @defvr {Attribute} separatorChars
3404 Exactly four characters. In order, these are used for: decimal point,
3405 grouping, date separator, time separator. Always @samp{.,-:}.
3408 @defvr {Attribute} mdyOrder
3409 Within a date, the order of the days, months, and years.
3410 @code{dayMonthYear} is the only observed value, but one would expect
3411 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
3415 @defvr {Attribute} showYear
3416 @defvrx {Attribute} yearAbbreviation
3417 Whether to include the year and, if so, whether the year should be
3418 shown abbreviated, that is, with only 2 digits. Each is @code{true}
3419 or @code{false}; only values of @code{true} and @code{false},
3420 respectively, have been observed.
3423 @defvr {Attribute} showMonth
3424 @defvrx {Attribute} monthFormat
3425 Whether to include the month (@code{true} or @code{false}) and, if so,
3426 how to format it. @code{monthFormat} is one of the following:
3430 The full name of the month, e.g.@: in an English locale,
3434 The abbreviated name of the month, e.g.@: in an English locale,
3438 The number representing the month, e.g.@: 9 for September.
3441 A two-digit number representing the month, e.g.@: 09 for September.
3444 Only values of @code{true} and @code{short}, respectively, have been
3448 @defvr {Attribute} dayType
3449 This attribute is always @code{month} in the corpus, specifying that
3450 the day of the month is to be displayed; a value of @code{year} is
3451 supposed to indicate that the day of the year, where 1 is January 1,
3452 is to be displayed instead.
3455 @defvr {Attribute} hourFormat
3456 @code{hourFormat}, if present, is one of:
3460 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
3464 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
3466 This is the only value observed in the corpus.
3469 The time is displayed in a 12-hour format, without distinguishing
3470 morning or evening, e.g.@: @code{10;15}.
3473 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
3474 which is confusing since a time duration does not have a concept of AM
3475 or PM. This might indicate a bug in the code that generated the XML
3476 in the corpus, or it might indicate that @code{elapsedTime} is
3477 sometimes used to format a time of day.
3480 For a @code{baseFormat} of @code{date}, PSPP chooses a print format
3481 type based on the following rules:
3485 If @code{showQuarter} is true: @code{QYR}.
3488 Otherwise, if @code{showWeek} is true: @code{WKYR}.
3491 Otherwise, if @code{mdyOrder} is @code{dayMonthYear}:
3495 If @code{monthFormat} is @code{number} or @code{paddedNumber}: @code{EDATE}.
3498 Otherwise: @code{DATE}.
3502 Otherwise, if @code{mdyOrder} is @code{yearMonthDay}: @code{SDATE}.
3505 Otherwise, @code{ADATE}.
3508 For a @code{baseFormat} of @code{dateTime}, PSPP uses @code{YMDHMS} if
3509 @code{mdyOrder} is @code{yearMonthDay} and @code{DATETIME} otherwise.
3510 For a @code{baseFormat} of @code{time}, PSPP uses @code{DTIME} if
3511 @code{showDay} is true, otherwise @code{TIME} if @code{showHour} is
3512 true, otherwise @code{MTIME}.
3514 For a @code{baseFormat} of @code{date}, the chosen width is the
3515 minimum for the format type, adding 2 if @code{yearAbbreviation} is
3516 false or omitted. For other base formats, the chosen width is the
3517 minimum for its type, plus 3 if @code{showSecond} is true, plus 4 more
3518 if @code{showMillis} is also true. Decimals are 0 by default, or 3
3519 if @code{showMillis} is true.
3521 @node SPV Detail elapsedTimeFormat Element
3522 @subsubsection The @code{elapsedTimeFormat} Element
3526 :baseFormat[dt_base_format]=(date | time | dateTime)
3529 :minutePadding=bool?
3530 :secondPadding=bool?
3540 This element specifies the way to display a time duration.
3542 Data to be formatted in elapsed time formats is stored as strings in
3543 legacy data, in the format @code{H:MM:SS.SSS}, with additional hour
3544 digits as needed for long durations, and must be parsed and
3545 reformatted by the reader.
3547 The following attribute is required.
3549 @defvr {Attribute} baseFormat
3550 Specifies whether a day and a time are both to be displayed, or just
3554 The remaining attributes specify exactly how to display the elapsed
3557 For @code{baseFormat} of @code{time}, PSPP converts this element to
3558 print format type @code{DTIME}; otherwise, if @code{showHour} is true,
3559 to @code{TIME}; otherwise, to @code{MTIME}. The chosen width is the
3560 minimum for the chosen type, adding 3 if @code{showSecond} is true,
3561 adding 4 more if @code{showMillis} is also true. Decimals are 0 by
3562 default, or 3 if @code{showMillis} is true.
3564 @node SPV Detail format Element
3565 @subsubsection The @code{format} Element
3569 :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)?
3572 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3577 :yearAbbreviation=bool?
3579 :monthFormat=(long | short | number | paddedNumber)?
3581 :dayOfMonthPadding=bool?
3585 :showDayOfWeek=bool?
3586 :dayOfWeekAbbreviation=bool?
3588 :minutePadding=bool?
3589 :secondPadding=bool?
3595 :dayType=(month | year)?
3596 :hourFormat=(AMPM | AS_24 | AS_12)?
3597 :minimumIntegerDigits=int?
3598 :maximumFractionDigits=int?
3599 :minimumFractionDigits=int?
3601 :scientific=(onlyForSmall | whenNeeded | true | false)?
3605 :tryStringsAsNumbers=bool?
3606 :negativesOutside=bool?
3610 This element is the union of all of the more-specific format elements.
3611 It is interpreted in the same way as one of those format elements,
3612 using @code{baseFormat} to determine which kind of format to use.
3614 There are a few attributes not present in the more specific formats:
3616 @defvr {Attribute} tryStringsAsNumbers
3617 When this is @code{true}, it is supposed to indicate that string
3618 values should be parsed as numbers and then displayed according to
3619 numeric formatting rules. However, in the corpus it is always
3623 @defvr {Attribute} negativesOutside
3624 If true, the negative sign should be shown before the prefix; if
3625 false, it should be shown after.
3628 @node SPV Detail affix Element
3629 @subsubsection The @code{affix} Element
3633 :definesReference=int
3634 :position=(subscript | superscript)
3640 This defines a suffix (or, theoretically, a prefix) for a formatted
3641 value. It is used to insert a reference to a footnote. It has the
3642 following attributes:
3644 @defvr {Attribute} definesReference
3645 This specifies the footnote number as a natural number: 1 for the
3646 first footnote, 2 for the second, and so on.
3649 @defvr {Attribute} position
3650 Position for the footnote label. Always @code{superscript}.
3653 @defvr {Attribute} suffix
3654 Whether the affix is a suffix (@code{true}) or a prefix
3655 (@code{false}). Always @code{true}.
3658 @defvr {Attribute} value
3659 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
3660 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
3661 contains other values: @code{*}, @code{**}, and a few that begin with
3662 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
3665 @node SPV Detail interval Element
3666 @subsection The @code{interval} Element
3669 interval :style=ref style => labeling footnotes?
3673 :variable=ref (sourceVariable | derivedVariable)
3674 => (formatting | format | footnotes)*
3676 formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping*
3678 formatMapping :from=int => format?
3682 :variable=ref (sourceVariable | derivedVariable)
3685 footnoteMapping :definesReference=int :from=int :to => EMPTY
3688 The @code{interval} element and its descendants determine the basic
3689 formatting and labeling for the table's cells. These basic styles are
3690 overridden by more specific styles set using @code{setCellProperties}
3691 (@pxref{SPV Detail setCellProperties Element}).
3693 The @code{style} attribute of @code{interval} itself may be ignored.
3695 The @code{labeling} element may have a single @code{formatting} child.
3696 If present, its @code{variable} attribute refers to a variable whose
3697 values are format specifiers as numbers, e.g. value 0x050802 for F8.2.
3698 However, the numbers are not actually interpreted that way. Instead,
3699 each number actually present in the variable's data is mapped by a
3700 @code{formatMapping} child of @code{formatting} to a @code{format}
3701 that specifies how to display it.
3703 The @code{labeling} element may also have a @code{footnotes} child
3704 element. The @code{variable} attribute of this element refers to a
3705 variable whose values are comma-delimited strings that list the
3706 1-based indexes of footnote references. (Cells without any footnote
3707 references are numeric 0 instead of strings.)
3709 Each @code{footnoteMapping} child of the @code{footnotes} element
3710 defines the footnote marker to be its @code{to} attribute text for the
3711 footnote whose 1-based index is given in its @code{definesReference}
3714 @node SPV Detail style Element
3715 @subsection The @code{style} Element
3722 :border-bottom=(solid | thick | thin | double | none)?
3723 :border-top=(solid | thick | thin | double | none)?
3724 :border-left=(solid | thick | thin | double | none)?
3725 :border-right=(solid | thick | thin | double | none)?
3726 :border-bottom-color?
3729 :border-right-color?
3732 :font-weight=(regular | bold)?
3733 :font-style=(regular | italic)?
3734 :font-underline=(none | underline)?
3735 :margin-bottom=dimension?
3736 :margin-left=dimension?
3737 :margin-right=dimension?
3738 :margin-top=dimension?
3739 :textAlignment=(left | right | center | decimal | mixed)?
3740 :labelLocationHorizontal=(positive | negative | center)?
3741 :labelLocationVertical=(positive | negative | center)?
3742 :decimal-offset=dimension?
3749 A @code{style} element has an effect only when it is referenced by
3750 another element to set some aspect of the table's style. Most of the
3751 attributes are self-explanatory. The rest are described below.
3753 @defvr {Attribute} {color}
3754 In some cases, the text color; in others, the background color.
3757 @defvr {Attribute} {color2}
3761 @defvr {Attribute} {labelAngle}
3762 Normally 0. The value -90 causes inner column or outer row labels to
3763 be rotated vertically.
3766 @defvr {Attribute} {labelLocationHorizontal}
3770 @defvr {Attribute} {labelLocationVertical}
3771 The value @code{positive} corresponds to vertically aligning text to
3772 the top of a cell, @code{negative} to the bottom, @code{center} to the
3776 @node SPV Detail labelFrame Element
3777 @subsection The @code{labelFrame} Element
3780 labelFrame :style=ref style => location+ label? paragraph?
3782 paragraph :hangingIndent=dimension? => EMPTY
3785 A @code{labelFrame} element specifies content and style for some
3786 aspect of a table. Only @code{labelFrame} elements that have a
3787 @code{label} child are important. The @code{purpose} attribute in the
3788 @code{label} determines what the @code{labelFrame} affects:
3792 The table's title and its style.
3795 The table's caption and its style.
3798 The table's footnotes and the style for the footer area.
3801 The style for the layer area.
3807 The @code{style} attribute references the style to use for the area.
3809 The @code{label}, if present, specifies the text to put into the title
3810 or caption or footnotes. For footnotes, the label has two @code{text}
3811 children for every footnote, each of which has a @code{usesReference}
3812 attribute identifying the 1-based index of a footnote. The first,
3813 third, fifth, @dots{} @code{text} child specifies the content for a
3814 footnote; the second, fourth, sixth, @dots{} child specifies the
3815 marker. Content tends to end in a new-line, which the reader may wish
3816 to trim; similarly, markers tend to end in @samp{.}.
3818 The @code{paragraph}, if present, may be ignored, since it is always
3821 @node SPV Detail Legacy Properties
3822 @subsection Legacy Properties
3824 The detail XML format has features for styling most of the aspects of
3825 a table. It also inherits defaults for many aspects from structure
3826 XML, which has the following @code{tableProperties} element:
3831 => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties
3834 :hideEmptyRows=bool?
3835 :maximumColumnWidth=dimension?
3836 :maximumRowWidth=dimension?
3837 :minimumColumnWidth=dimension?
3838 :minimumRowWidth=dimension?
3839 :rowDimensionLabels=(inCorner | nested)?
3843 :markerPosition=(superscript | subscript)?
3844 :numberFormat=(alphabetic | numeric)?
3847 cellFormatProperties => cell_style+
3850 :alternatingColor=color?
3851 :alternatingTextColor=color?
3859 :font-style=(regular | italic)?
3860 :font-weight=(regular | bold)?
3861 :font-underline=(none | underline)?
3862 :labelLocationVertical=(positive | negative | center)?
3863 :margin-bottom=dimension?
3864 :margin-left=dimension?
3865 :margin-right=dimension?
3866 :margin-top=dimension?
3867 :textAlignment=(left | right | center | decimal | mixed)?
3868 :decimal-offset=dimension?
3871 borderProperties => border_style+
3874 :borderStyleType=(none | solid | dashed | thick | thin | double)?
3879 :printAllLayers=bool?
3880 :rescaleLongTableToFitPage=bool?
3881 :rescaleWideTableToFitPage=bool?
3882 :windowOrphanLines=int?
3884 :continuationTextAtBottom=bool?
3885 :continuationTextAtTop=bool?
3886 :printEachLayerOnSeparatePage=bool?
3890 The @code{name} attribute appears only in standalone @file{.stt} files
3891 (@pxref{SPSS TableLook STT Format}).