1 @node SPSS Viewer File Format
2 @appendix SPSS Viewer File Format
4 SPSS Viewer or @file{.spv} files, here called SPV files, are written
5 by SPSS 16 and later to represent the contents of its output editor.
6 This chapter documents the format, based on examination of a corpus of
7 about 3,000 files from a variety of sources. This description is
8 detailed enough to both read and write SPV files.
10 SPSS 15 and earlier versions instead use @file{.spo} files, which have
11 a completely different output format based on the Microsoft Compound
12 Document Format. This format is not documented here.
14 An SPV file is a Zip archive that can be read with @command{zipinfo}
15 and @command{unzip} and similar programs. The final member in the Zip
16 archive is the @dfn{manifest}, a file named
17 @file{META-INF/MANIFEST.MF}. This structure makes SPV files resemble
18 Java ``JAR'' files (and ODF files), but whereas a JAR manifest
19 contains a sequence of colon-delimited key/value pairs, an SPV
20 manifest contains the string @samp{allowPivoting=true}, without a
21 new-line. PSPP uses this string to identify an SPV file; it is
22 invariant across the corpus.
24 The rest of the members in an SPV file's Zip archive fall into two
25 categories: @dfn{structure} and @dfn{detail} members. Structure
26 member names begin with @file{outputViewer@var{nnnnnnnnnn}}, where
27 each @var{n} is a decimal digit, and end with @file{.xml}, and often
28 include the string @file{_heading} in between. Each of these members
29 represents some kind of output item (a table, a heading, a block of
30 text, etc.) or a group of them. The member whose output goes at the
31 beginning of the document is numbered 0, the next member in the output
32 is numbered 1, and so on.
34 Structure members contain XML. This XML is sometimes self-contained,
35 but it often references detail members in the Zip archive, which are
39 @item @file{@var{prefix}_table.xml} and @file{@var{prefix}_tableData.bin}
40 @itemx @file{@var{prefix}_lightTableData.bin}
41 The structure of a table plus its data. Older SPV files pair a
42 @file{@var{prefix}_table.xml} file that describes the table's
43 structure with a binary @file{@var{prefix}_tableData.bin} file that
44 gives its data. Newer SPV files (the majority of those in the corpus)
45 instead include a single @file{@var{prefix}_lightTableData.bin} file
46 that incorporates both into a single binary format.
48 @item @file{@var{prefix}_warning.xml} and @file{@var{prefix}_warningData.bin}
49 @itemx @file{@var{prefix}_lightWarningData.bin}
50 Same format used for tables, with a different name.
52 @item @file{@var{prefix}_notes.xml} and @file{@var{prefix}_notesData.bin}
53 @itemx @file{@var{prefix}_lightNotesData.bin}
54 Same format used for tables, with a different name.
56 @item @file{@var{prefix}_chartData.bin} and @file{@var{prefix}_chart.xml}
57 The structure of a chart plus its data. Charts do not have a
60 @item @file{@var{prefix}_pmml.scf}
61 @itemx @file{@var{prefix}_stats.scf}
62 @item @file{@var{prefix}_model.xml}
63 Not yet investigated. The corpus contains few examples.
66 The @file{@var{prefix}} in the names of the detail members is
67 typically an 11-digit decimal number that increases for each item,
68 tending to skip values. Older SPV files use different naming
69 conventions. Structure member refer to detail members by name, and so
70 their exact names do not matter to readers as long as they are unique.
72 SPSS tolerates corrupted Zip archives that Zip reader libraries tend
73 to reject. These can be fixed up with @command{zip -FF}.
76 * SPV Structure Member Format::
77 * SPV Light Detail Member Format::
78 * SPV Legacy Detail Member Binary Format::
79 * SPV Legacy Detail Member XML Format::
82 @node SPV Structure Member Format
83 @section Structure Member Format
85 A structure member lays out the high-level structure for a group of
86 output items such as heading, tables, and charts. Structure members
87 do not include the details of tables and charts but instead refer to
88 them by their member names.
90 Structure members' XML files claim conformance with a collection of
91 XML Schemas. These schemas are distributed, under a nonfree license,
92 with SPSS binaries. Fortunately, the schemas are not necessary to
93 understand the structure members. The schemas can even
94 be deceptive because they document elements and attributes that are
95 not in the corpus and do not document elements and attributes that are
96 commonly found in the corpus.
98 Structure members use a different XML namespace for each schema, but
99 these namespaces are not entirely consistent. In some SPV files, for
100 example, the @code{viewer-tree} schema is associated with namespace
101 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
102 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
103 additional @file{viewer/}). Under either name, the schema URIs are
104 not resolvable to obtain the schemas themselves.
106 One may ignore all of the above in interpreting a structure member.
107 The actual XML has a simple and straightforward form that does not
108 require a reader to take schemas or namespaces into account. A
109 structure member's root is @code{heading} element, which contains
110 @code{heading} or @code{container} elements (or a mix), forming a
111 tree. In turn, @code{container} holds a @code{label} and one more
112 child, usually @code{text} or @code{table}.
114 The following sections document the elements found in structure
115 members in a context-free grammar-like fashion. Consider the
116 following example, which specifies the attributes and content for the
117 @code{container} element:
121 :visibility=(visible | hidden)
122 :page-break-before=(always)?
123 :text-align=(left | center)?
125 => label (table | container_text | graph | model | object | image)
128 Each attribute specification begins with @samp{:} followed by the
129 attribute's name. If the attribute's value has an easily specified
130 form, then @samp{=} and its description follows the name. Finally, if
131 the attribute is optional, the specification ends with @samp{?}. The
132 following value specifications are defined:
135 @item (@var{a} | @var{b} | @dots{})
136 One of the listed literal strings. If only one string is listed, it
137 is the only acceptable value. If @code{OTHER} is listed, then any
138 string not explicitly listed is also accepted.
141 Either @code{true} or @code{false}.
144 A floating-point number followed by a unit, e.g.@: @code{10pt}. Units
145 in the corpus include @code{in} (inch), @code{pt} (points, 72/inch),
146 @code{px} (``device-independent pixels'', 96/inch), and @code{cm}.
147 The corpus also contains localized names for units: @code{인치} for
148 inch, @code{пт} for points, and @code{см} for centimeters. If the
149 unit is omitted then points should be assumed. The number and unit
150 may be separated by white space.
153 A floating-point number.
159 A color in one of the forms @code{#@var{rr}@var{gg}@var{bb}} or
160 @code{@var{rr}@var{gg}@var{bb}}, or the string @code{transparent}, or
161 one of the standard Web color names.
164 @item ref @var{element}
165 @itemx ref(@var{elem1} | @var{elem2} | @dots{})
166 The name from the @code{id} attribute in some element. If one or more
167 elements are named, the name must refer to one of those elements,
168 otherwise any element is acceptable.
171 All elements have an optional @code{id} attribute. If present, its
172 value must be unique. In practice many elements are assigned
173 @code{id} attributes that are never referenced.
175 The content specification for an element supports the following
182 @item @var{a} @var{b}
183 @var{a} followed by @var{b}.
185 @item @var{a} | @var{b} | @var{c}
186 One of @var{a} or @var{b} or @var{c}.
189 Zero or one instances of @var{a}.
192 Zero or more instances of @var{a}.
195 One or more instances of @var{a}.
197 @item (@var{subexpression})
198 Grouping for a subexpression.
207 Element and attribute names are sometimes suffixed by another name in
208 square brackets to distinguish different uses of the same name. For
209 example, structure XML has two @code{text} elements, one inside
210 @code{container}, the other inside @code{pageParagraph}. The former
211 is defined as @code{text[container_text]} and referenced as
212 @code{container_text}, the latter defined as
213 @code{text[pageParagraph_text]} and referenced as
214 @code{pageParagraph_text}.
216 This language is used in the PSPP source code for parsing structure
217 and detail XML members. Refer to
218 @file{src/output/spv/structure-xml.grammar} and
219 @file{src/output/spv/detail-xml.grammar} for the full grammars.
221 The following example shows the contents of a typical structure member
222 for a @cmd{DESCRIPTIVES} procedure. A real structure member is not
223 indented. This example also omits most attributes, all XML namespace
224 information, and the CSS from the embedded HTML:
227 <?xml version="1.0" encoding="utf-8"?>
229 <label>Output</label>
230 <heading commandName="Descriptives">
231 <label>Descriptives</label>
234 <text commandName="Descriptives" type="title">
236 <![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
240 <container visibility="hidden">
242 <table commandName="Descriptives" subType="Notes" type="note">
244 <dataPath>00000000001_lightNotesData.bin</dataPath>
249 <label>Descriptive Statistics</label>
250 <table commandName="Descriptives" subType="Descriptive Statistics"
253 <dataPath>00000000002_lightTableData.bin</dataPath>
262 * SPV Structure heading Element::
263 * SPV Structure label Element::
264 * SPV Structure container Element::
265 * SPV Structure text Element (Inside @code{container})::
266 * SPV Structure html Element::
267 * SPV Structure table Element::
268 * SPV Structure graph Element::
269 * SPV Structure model Element::
270 * SPV Structure dataPath and path Elements::
271 * SPV Structure pageSetup Element::
272 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
275 @node SPV Structure heading Element
276 @subsection The @code{heading} Element
279 heading[root_heading]
285 => label pageSetup? (container | heading)*
290 :visibility[heading_visibility]=(collapsed)?
293 => label (container | heading)*
296 The root of a structure member is a @code{heading}, which represents a
297 section of output beginning with a title (the @code{label}) and
298 ordinarily followed by content containers or further nested
299 (sub)-sections of output. Unlike heading elements in HTML and other
300 common document formats, which precede the content that they head,
301 @code{heading} contains the elements that appear below the heading.
303 The document root heading, only, may contain a @code{pageSetup}
306 The following attributes have been observed on both document root and
307 nested @code{heading} elements.
309 @defvr {Attribute} creator-version
310 The version of the software that created this SPV file. A string of
311 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
312 e.g.@: @code{21000001} is version 21.0.0.1. Trailing pairs of zeros
313 are sometimes omitted, so that @code{21}, @code{210000}, and
314 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
315 three of those forms).
319 The following attributes have been observed on document root
320 @code{heading} elements only:
322 @defvr {Attribute} @code{creator}
323 The directory in the file system of the software that created this SPV
327 @defvr {Attribute} @code{creation-date-time}
328 The date and time at which the SPV file was written, in a
329 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
330 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
331 December 5, 2014 5:00:19 o'clock PM EST}.
334 @defvr {Attribute} @code{lockReader}
335 Whether a reader should be allowed to edit the output. The possible
336 values are @code{true} and @code{false}, but the corpus only contains
340 @defvr {Attribute} @code{schemaLocation}
341 This is actually an XML Namespace attribute. A reader may ignore it.
345 The following attributes have been observed only on nested
346 @code{heading} elements:
348 @defvr {Attribute} @code{commandName}
349 A locale-invariant identifier for the command that produced the
350 output, e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
353 @defvr {Attribute} @code{visibility}
354 To what degree the output represented by the element is visible.
357 @defvr {Attribute} @code{locale}
358 The locale used for output, in Windows format, which is similar to the
359 format used in Unix with the underscore replaced by a hyphen, e.g.@:
360 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
363 @defvr {Attribute} @code{olang}
364 The output language, e.g.@: @code{en}, @code{it}, @code{es},
365 @code{de}, @code{pt-BR}.
368 @node SPV Structure label Element
369 @subsection The @code{label} Element
375 Every @code{heading} and @code{container} holds a @code{label} as its
376 first child. The root @code{heading} in a structure member always
377 contains the string ``Output'' (localized). Otherwise, the text in
378 @code{label} describes what it labels, often by naming the statistical
379 procedure that was executed, e.g.@: ``Frequencies'' or ``T-Test''.
380 Labels are often very generic, especially within a @code{container},
381 e.g.@: ``Title'' or ``Warnings'' or ``Notes''. Label text is
382 localized according to the output language, e.g.@: in Italian a
383 frequency table procedure is labeled ``Frequenze''.
385 The corpus contains a few examples of empty labels, ones that contain
388 @node SPV Structure container Element
389 @subsection The @code{container} Element
393 :visibility=(visible | hidden)
394 :page-break-before=(always)?
395 :text-align=(left | center)?
397 => label (table | container_text | graph | model | object | image)
400 A @code{container} serves to contain and label a @code{table},
401 @code{text}, or other kind of item.
403 This element has the following attributes.
405 @defvr {Attribute} @code{visibility}
406 Whether the container's content is displayed. ``Notes'' tables are
407 often hidden; other data is usually
410 @defvr {Attribute} @code{text-align}
411 Alignment of text within the container. Observed with nested
412 @code{table} and @code{text} elements.
415 @defvr {Attribute} @code{width}
416 The width of the container, e.g.@: @code{1097px}.
419 @node SPV Structure text Element (Inside @code{container})
420 @subsection The @code{text} Element (Inside @code{container})
424 :type[text_type]=(title | log | text | page-title)
430 This @code{text} element is nested inside a @code{container}. There
431 is a different @code{text} element that is nested inside a
432 @code{pageParagraph}.
434 This element has the following attributes.
436 @defvr {Attribute} @code{type}
437 The semantics of the text.
440 @defvr {Attribute} @code{commandName}
441 As on the @code{heading} element. For output not specific to a
442 command, this is simply @code{log}. The corpus contains one example
443 of where @code{commandName} is present but set to the empty string.
446 @defvr {Attribute} @code{creator-version}
447 As on the @code{heading} element.
450 @node SPV Structure html Element
451 @subsection The @code{html} Element
454 html :lang=(en) => TEXT
457 The element contains an HTML document as text (or, in practice, as
458 CDATA). In some cases, the document starts with @code{<html>} and
459 ends with @code{</html>}; in others the @code{html} element is
460 implied. Generally the HTML includes a @code{head} element with a CSS
461 stylesheet. The HTML body often begins with @code{<BR>}.
463 The HTML document uses only the following elements:
467 Sometimes, the document is enclosed with
468 @code{<html>}@dots{}@code{</html>}.
471 The HTML body often begins with @code{<BR>} and may contain it as well.
479 The attributes @code{face}, @code{color}, and @code{size} are
480 observed. The value of @code{color} takes one of the forms
481 @code{#@var{rr}@var{gg}@var{bb}} or @code{rgb (@var{r}, @var{g},
482 @var{b})}. The value of @code{size} is a number between 1 and 7,
486 The CSS in the corpus is simple. To understand it, a parser only
487 needs to be able to skip white space, @code{<!--}, and @code{-->}, and
488 parse style only for @code{p} elements. Only @code{font-weight},
489 @code{font-style}, @code{font-decoration}, @code{font-family}, and
490 @code{font-size} matter.
492 This element has the following attributes.
494 @defvr {Attribute} @code{lang}
495 This always contains @code{en} in the corpus.
498 @node SPV Structure table Element
499 @subsection The @code{table} Element
508 :displayFiltering=bool?
510 :orphanTolerance=int?
515 :type[table_type]=(table | note | warning)
516 => tableProperties? tableStructure
518 tableStructure => path? dataPath
521 This element has the following attributes.
523 @defvr {Attribute} @code{commandName}
524 As on the @code{heading} element.
527 @defvr {Attribute} @code{type}
528 One of @code{table}, @code{note}, or @code{warning}.
531 @defvr {Attribute} @code{subType}
532 The locale-invariant command ID for the particular kind of output that
533 this table represents in the procedure. This can be the same as
534 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
535 @code{Case Processing Summary}. Generic subtypes @code{Notes} and
536 @code{Warnings} are often used.
539 @defvr {Attribute} @code{tableId}
540 A number that uniquely identifies the table within the SPV file,
541 typically a large negative number such as @code{-4147135649387905023}.
544 @defvr {Attribute} @code{creator-version}
545 As on the @code{heading} element. In the corpus, this is only present
546 for version 21 and up and always includes all 8 digits.
549 @xref{SPV Detail Legacy Properties}, for details on the
550 @code{tableProperties} element.
552 @node SPV Structure graph Element
553 @subsection The @code{graph} Element
569 This element represents a graph. The @code{dataPath} and @code{path}
570 elements name the Zip members that give the details of the graph.
571 Normally, both elements are present; there is only one counterexample
574 @node SPV Structure model Element
575 @subsection The @code{model} Element
587 => ViZml? path | pmmlContainerPath statsContainerPath
589 pmmlContainerPath => TEXT
591 statsContainerPath => TEXT
593 ViZml :viewName? => TEXT
596 This element represents a model. The @code{dataPath} and @code{path}
597 elements name the Zip members that give the details of the model.
598 Normally, both elements are present; there is only one counterexample
601 The details are unexplored. The @code{ViZml} element contains base-64
602 encoded text, that decodes to a binary format with some embedded text
603 strings, and @code{path} names an Zip member that contains XML.
604 Alternatively, @code{pmmlContainerPath} and @code{statsContainerPath}
605 name Zip members with @file{.scf} extension.
607 @node SPV Structure dataPath and path Elements
608 @subsection The @code{dataPath} and @code{path} Elements
616 These element contain the name of the Zip members that hold details
617 for a container. For tables:
621 When a ``light'' format is used, only @code{dataPath} is present, and
622 it names a @file{.bin} member of the Zip file that has @code{light} in
623 its name, e.g.@: @code{0000000001437_lightTableData.bin} (@pxref{SPV
624 Light Detail Member Format}).
627 When the legacy format is used, both are present. In this case,
628 @code{dataPath} names a Zip member with a legacy binary format that
629 contains relevant data (@pxref{SPV Legacy Detail Member Binary
630 Format}), and @code{path} names a Zip member that uses an XML format
631 (@pxref{SPV Legacy Detail Member XML Format}).
634 Graphs normally follow the legacy approach described above. The
635 corpus contains one example of a graph with @code{path} but not
636 @code{dataPath}. The reason is unexplored.
638 Models use @code{path} but not @code{dataPath}. @xref{SPV Structure
639 graph Element}, for more information.
641 These elements have no attributes.
643 @node SPV Structure pageSetup Element
644 @subsection The @code{pageSetup} Element
648 :initial-page-number=int?
649 :chart-size=(as-is | full-height | half-height | quarter-height | OTHER)?
650 :margin-left=dimension?
651 :margin-right=dimension?
652 :margin-top=dimension?
653 :margin-bottom=dimension?
654 :paper-height=dimension?
655 :paper-width=dimension?
656 :reference-orientation?
657 :space-after=dimension?
658 => pageHeader pageFooter
660 pageHeader => pageParagraph?
662 pageFooter => pageParagraph?
664 pageParagraph => pageParagraph_text
667 The @code{pageSetup} element has the following attributes.
669 @defvr {Attribute} @code{initial-page-number}
670 The page number to put on the first page of printed output. Usually
674 @defvr {Attribute} @code{chart-size}
675 One of the listed, self-explanatory chart sizes,
676 @code{quarter-height}, or a localization (!) of one of these (e.g.@:
677 @code{dimensione attuale}, @code{Wie vorgegeben}).
680 @defvr {Attribute} @code{margin-left}
681 @defvrx {Attribute} @code{margin-right}
682 @defvrx {Attribute} @code{margin-top}
683 @defvrx {Attribute} @code{margin-bottom}
684 Margin sizes, e.g.@: @code{0.25in}.
687 @defvr {Attribute} @code{paper-height}
688 @defvrx {Attribute} @code{paper-width}
692 @defvr {Attribute} @code{reference-orientation}
693 Indicates the orientation of the output page. Either @code{0deg}
694 (portrait) or @code{90deg} (landscape),
697 @defvr {Attribute} @code{space-after}
698 The amount of space between printed objects, typically @code{12pt}.
701 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
702 @subsection The @code{text} Element (Inside @code{pageParagraph})
705 text[pageParagraph_text] :type=(title | text) => TEXT
708 This @code{text} element is nested inside a @code{pageParagraph}. There
709 is a different @code{text} element that is nested inside a
712 The element is either empty, or contains CDATA that holds almost-XHTML
713 text: in the corpus, either an @code{html} or @code{p} element. It is
714 @emph{almost}-XHTML because the @code{html} element designates the
716 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of
717 an XHTML namespace, and because the CDATA can contain substitution
718 variables. The following variables are supported:
723 The current date or time in the preferred format for the locale.
729 First-, second-, third-, or fourth-level heading.
735 Name of the output file.
741 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
744 Typical contents (indented for clarity):
747 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
750 <p style="text-align:right; margin-top: 0">Page &[Page]</p>
755 This element has the following attributes.
757 @defvr {Attribute} @code{type}
761 @node SPV Light Detail Member Format
762 @section Light Detail Member Format
764 This section describes the format of ``light'' detail @file{.bin}
765 members. These members have a binary format which we describe here in
766 terms of a context-free grammar using the following conventions:
769 @item NonTerminal @result{} @dots{}
770 Nonterminals have CamelCaps names, and @result{} indicates a
771 production. The right-hand side of a production is often broken
772 across multiple lines. Break points are chosen for aesthetics only
773 and have no semantic significance.
775 @item 00, 01, @dots{}, ff.
776 A bytes with a fixed value, written as a pair of hexadecimal digits.
778 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
779 @itemx ib0, ib1, @dots{}, ib9, ib10, ib11, @dots{}
780 A 32-bit integer in little-endian or big-endian byte order,
781 respectively, with a fixed value, written in decimal. Prefixed by
782 @samp{i} for little-endian or @samp{ib} for big-endian.
788 A byte with value 0 or 1.
792 A 16-bit integer in little-endian or big-endian byte order,
797 A 32-bit integer in little-endian or big-endian byte order,
802 A 64-bit integer in little-endian or big-endian byte order,
806 A 64-bit IEEE floating-point number.
809 A 32-bit IEEE floating-point number.
813 A 32-bit integer, in little-endian or big-endian byte order,
814 respectively, followed by the specified number of bytes of character
815 data. (The encoding is indicated by the Formats nonterminal.)
818 @var{x} is optional, e.g.@: 00? is an optional zero byte.
820 @item @var{x}*@var{n}
821 @var{x} is repeated @var{n} times, e.g.@: byte*10 for ten arbitrary bytes.
823 @item @var{x}[@var{name}]
824 Gives @var{x} the specified @var{name}. Names are used in textual
825 explanations. They are also used, also bracketed, to indicate counts,
826 e.g.@: @code{int32[n] byte*[n]} for a 32-bit integer followed by the
827 specified number of arbitrary bytes.
829 @item @var{a} @math{|} @var{b}
830 Either @var{a} or @var{b}.
833 Parentheses are used for grouping to make precedence clear, especially
834 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
838 @itemx becount(@var{x})
839 A 32-bit integer, in little-endian or big-endian byte order, respectively,
840 that indicates the number of bytes in @var{x}, followed by @var{x} itself.
843 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
844 (The @file{.bin} header indicates the version.)
847 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
850 PSPP uses this grammar to parse light detail members. See
851 @file{src/output/spv/light-binary.grammar} in the PSPP source tree for
854 Little-endian byte order is far more common in this format, but a few
855 pieces of the format use big-endian byte order.
857 Light detail members express linear units in two ways: points (pt), at
858 72/inch, and ``device-independent pixels'' (px), at 96/inch. To
859 convert from pt to px, multiply by 1.33 and round up. To convert
860 from px to pt, divide by 1.33 and round down.
862 A ``light'' detail member @file{.bin} consists of a number of sections
863 concatenated together, terminated by an optional byte 01:
867 Header Titles Footnotes
868 Areas Borders PrintSettings TableSettings Formats
869 Dimensions Axes Cells
873 The following sections go into more detail.
876 * SPV Light Member Header::
877 * SPV Light Member Titles::
878 * SPV Light Member Footnotes::
879 * SPV Light Member Areas::
880 * SPV Light Member Borders::
881 * SPV Light Member Print Settings::
882 * SPV Light Member Table Settings::
883 * SPV Light Member Formats::
884 * SPV Light Member Dimensions::
885 * SPV Light Member Categories::
886 * SPV Light Member Axes::
887 * SPV Light Member Cells::
888 * SPV Light Member Value::
889 * SPV Light Member ValueMod::
892 @node SPV Light Member Header
895 An SPV light member begins with a 39-byte header:
900 (i1 @math{|} i3)[version]
903 bool[rotate-inner-column-labels]
904 bool[rotate-outer-row-labels]
907 int32[min-col-width] int32[max-col-width]
908 int32[min-row-width] int32[max-row-width]
912 @code{version} is a version number that affects the interpretation of
913 some of the other data in the member. We will refer to ``version 1''
914 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
915 version-specific formatting (as described previously).
917 If @code{rotate-inner-column-labels} is 1, then column labels closest
918 to the data are rotated to be vertical; otherwise, they are shown
921 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
922 the data are rotated to be vertical; otherwise, they are shown in the
925 @code{table-id} is a binary version of the @code{tableId} attribute in
926 the structure member that refers to the detail member. For example,
927 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
928 would be 0xc6c99d183b300001.
930 @code{min-col-width} is the minimum width that a column will be
931 assigned automatically. @code{max-col-width} is the maximum width
932 that a column will be assigned to accommodate a long column label.
933 @code{min-row-width} and @code{max-row-width} are a similar range for
934 the width of row labels. All of these measurements are in 1/96 inch
935 units (called a ``device independent pixel'' unit in Windows).
937 The meaning of the other variable parts of the header is not known. A
938 writer may safely use version 3, true for @code{x0}, false for
939 @code{x1}, true for @code{x2}, and 0x15 for @code{x3}.
941 @node SPV Light Member Titles
947 Value[subtype] 01? 31
948 Value[user-title] 01?
949 (31 Value[corner-text] @math{|} 58)
950 (31 Value[caption] @math{|} 58)
953 The Titles follow the Header and specify the table's title, caption,
956 The @code{user-title} is shown above the title and reflects any user
957 editing of the title text or style. The @code{title} is the title
958 originally generated by the procedure. Both of these are appropriate
959 for presentation and localized to the user's language. For example,
960 for a frequency table, @code{title} and @code{user-title} normally
961 name the variable and @code{c} is simply ``Frequencies''.
963 @code{subtype} is the same as the @code{subType} attribute in the
964 @code{table} structure XML element that referred to this member.
965 @xref{SPV Structure table Element}, for details.
967 The @code{corner-text}, if present, is shown in the upper-left corner
968 of the table, above the row headings and to the left of the column
969 headings. It is usually absent. Corner text prevents row dimension
970 labels from being displayed above the dimension's group and category
971 labels (see @code{show-row-labels-in-corner}).
973 The @code{caption}, if present, is shown below the table.
974 @code{caption} reflects user editing of the caption.
976 @node SPV Light Member Footnotes
977 @subsection Footnotes
980 Footnotes => int32[n-footnotes] Footnote*[n-footnotes]
981 Footnote => Value[text] (58 @math{|} 31 Value[marker]) byte*4
984 Each footnote has @code{text} and an optional custom @code{marker}
987 @node SPV Light Member Areas
994 string[typeface] float[size] int32[style] bool[underline]
995 int32[halign] int32[valign]
996 string[fg-color] string[bg-color]
997 bool[alternate] string[alt-fg-color] string[alt-bg-color]
998 v3(int32[left-margin] int32[right-margin] int32[top-margin] int32[bottom-margin])
1001 Each Area represents the style for a different area of the table, in
1002 the following order: title, caption, footer, corner, column labels,
1003 row labels, data, and layers.
1005 @code{index} is the 1-based index of the Area, i.e. 1 for the first
1006 Area, through 8 for the final Area.
1008 @code{typeface} is the string name of the font used in the area. In
1009 the corpus, this is @code{SansSerif} in over 99% of instances and
1010 @code{Times New Roman} in the rest.
1012 @code{size} is the size of the font, in px (@pxref{SPV Light Detail
1013 Member Format}) The most common size in the corpus is 12 px. Even
1014 though @code{size} has a floating-point type, in the corpus its values
1015 are always integers.
1017 @code{style} is a bit mask. Bit 0 (with value 1) is set for bold, bit
1018 1 (with value 2) is set for italic.
1020 @code{underline} is 1 if the font is underlined, 0 otherwise.
1022 @code{halign} specifies horizontal alignment: 0 for center, 2 for
1023 left, 4 for right, 61453 for decimal, 64173 for mixed. Mixed
1024 alignment varies according to type: string data is left-justified,
1025 numbers and most other formats are right-justified.
1027 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1030 @code{fg-color} and @code{bg-color} are the foreground color and
1031 background color, respectively. In the corpus, these are always
1032 @code{#000000} and @code{#ffffff}, respectively.
1034 @code{alternate} is 1 if rows should alternate colors, 0 if all rows
1035 should be the same color. When @code{alternate} is 1,
1036 @code{alt-fg-color} and @code{alt-bg-color} specify the colors for the
1037 alternate rows; otherwise they are empty strings.
1039 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1040 @code{bottom-margin} are measured in px.
1042 @node SPV Light Member Borders
1049 be32[n-borders] Border*[n-borders]
1050 bool[show-grid-lines]
1059 The Borders reflect how borders between regions are drawn.
1061 The fixed value of @code{endian} can be used to validate the
1064 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
1066 Each Border describes one kind of border. @code{n-borders} seems to
1067 always be 19. Each @code{border-type} appears once (although in an
1068 unpredictable order) and correspond to the following borders:
1074 Left, top, right, and bottom outer frame.
1076 Left, top, right, and bottom inner frame.
1078 Left and top of data area.
1080 Horizontal and vertical dimension rows.
1082 Horizontal and vertical dimension columns.
1084 Horizontal and vertical category rows.
1086 Horizontal and vertical category columns.
1089 @code{stroke-type} describes how a border is drawn, as one of:
1106 @code{color} is an RGB color. Bits 24--31 are alpha, bits 16--23 are
1107 red, 8--15 are green, 0--7 are blue. An alpha of 255 indicates an
1108 opaque color, therefore opaque black is 0xff000000.
1110 @node SPV Light Member Print Settings
1111 @subsection Print Settings
1118 bool[paginate-layers]
1121 bool[top-continuation]
1122 bool[bottom-continuation]
1123 be32[n-orphan-lines]
1124 bestring[continuation-string])
1127 The PrintSettings reflect settings for printing. The fixed value of
1128 @code{endian} can be used to validate the endianness.
1130 @code{all-layers} is 1 to print all layers, 0 to print only the
1133 @code{paginate-layers} is 1 to print each layer at the start of a new
1134 page, 0 otherwise. (This setting is honored only @code{all-layers} is
1135 1, since otherwise only one layer is printed.)
1137 @code{fit-width} and @code{fit-length} control whether the table is
1138 shrunk to fit within a page's width or length, respectively.
1140 @code{n-orphan-lines} is the minimum number of rows or columns to put
1141 in one part of a table that is broken across pages.
1143 If @code{top-continuation} is 1, then @code{continuation-string} is
1144 printed at the top of a page when a table is broken across pages for
1145 printing; similarly for @code{bottom-continuation} and the bottom of a
1146 page. Usually, @code{continuation-string} is empty.
1148 @node SPV Light Member Table Settings
1149 @subsection Table Settings
1159 bool[show-row-labels-in-corner]
1160 bool[show-alphabetic-markers]
1161 bool[footnote-marker-superscripts]
1164 Breakpoints[row-breaks] Breakpoints[column-breaks]
1165 Keeps[row-keeps] Keeps[column-keeps]
1166 PointKeeps[row-point-keeps] PointKeeps[column-point-keeps]
1169 bestring[table-look]
1172 Breakpoints => be32[n-breaks] be32*[n-breaks]
1174 Keeps => be32[n-keeps] Keep*[n-keeps]
1175 Keep => be32[offset] be32[n]
1177 PointKeeps => be32[n-point-keeps] PointKeep*[n-point-keeps]
1178 PointKeep => be32[offset] be32 be32
1181 The TableSettings reflect display settings. The fixed value of
1182 @code{endian} can be used to validate the endianness.
1184 @code{current-layer} is the displayed layer. The interpretation when
1185 there is more than one layer dimension is not yet known.
1187 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
1188 any cell) are hidden; otherwise, they are shown.
1190 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
1191 the upper left corner; otherwise, they are shown nested.
1193 If @code{show-alphabetic-markers} is 1, markers are shown as letters
1194 (e.g.@: @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
1195 shown as numbers starting from 1.
1197 When @code{footnote-marker-superscripts} is 1, footnote markers are shown
1198 as superscripts, otherwise as subscripts.
1200 The Breakpoints are rows or columns after which there is a page break;
1201 for example, a row break of 1 requests a page break after the second
1202 row. Usually no breakpoints are specified, indicating that page
1203 breaks should be selected automatically.
1205 The Keeps are ranges of rows or columns to be kept together without a
1206 page break; for example, a row Keep with @code{offset} 1 and @code{n}
1207 10 requests that the 10 rows starting with the second row be kept
1208 together. Usually no Keeps are specified.
1210 The PointKeeps seem to be generated automatically based on
1211 user-specified Keeps. They seems to indicate a conversion from rows
1212 or columns to pixel or point offsets.
1214 @code{notes} is a text string that contains user-specified notes. It
1215 is displayed when the user hovers the cursor over the table, like
1216 ``alt text'' on a webpage. It is not printed. It is usually empty.
1218 @code{table-look} is the name of a SPSS ``TableLook'' table style,
1219 such as ``Default'' or ``Academic''; it is often empty.
1221 TableSettings ends with an arbitrary number of null bytes. A writer
1222 may safely write 82 null bytes.
1224 A writer may safely use 4 for @code{x5} and 0 for @code{x6}.
1226 @node SPV Light Member Formats
1231 int32[n-widths] int32*[n-widths]
1233 int32[current-layer]
1239 v3(count(X1 count(X2)) count(X3)))
1240 Y0 => int32[epoch] byte[decimal] byte[grouping]
1241 CustomCurrency => int32[n-ccs] string*[n-ccs]
1244 If @code{n-widths} is nonzero, then the accompanying integers are
1245 column widths as manually adjusted by the user.
1247 @code{locale} is a locale including an encoding, such as
1248 @code{en_US.windows-1252} or @code{it_IT.windows-1252}. The rest of
1249 the character strings in the member use this encoding. The encoding
1250 string is itself encoded in US-ASCII.
1252 @code{epoch} is the year that starts the epoch. A 2-digit year is
1253 interpreted as belonging to the 100 years beginning at the epoch. The
1254 default epoch year is 69 years prior to the current year; thus, in
1255 2017 this field by default contains 1948. In the corpus, @code{epoch}
1256 ranges from 1943 to 1948, plus some contain -1.
1258 @code{decimal} is the decimal point character. The observed values
1259 are @samp{.} and @samp{,}.
1261 @code{grouping} is the grouping character. Usually, it is @samp{,} if
1262 @code{decimal} is @samp{.}, and vice versa. Other observed values are
1263 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1264 indicating that digits should not be grouped).
1266 @code{n-ccs} is observed as either 0 or 5. When it is 5, the
1267 following strings are CCA through CCE format strings. @xref{Custom
1268 Currency Formats,,, pspp, PSPP}. Most commonly these are all
1269 @code{-,,,} but other strings occur.
1273 X0 only appears, optionally, in version 1 members.
1278 string[command] string[command-local]
1279 string[language] string[charset] string[locale]
1282 Y2 => CustomCurrency byte[missing] bool[x16]
1285 @code{command} describes the statistical procedure that generated the
1286 output, in English. It is not necessarily the literal syntax name of
1287 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1288 Tests.'' @code{command-local} is the procedure's name, translated
1289 into the output language; it is often empty and, when it is not,
1290 sometimes the same as @code{command}.
1292 @code{dataset} is the name of the dataset analyzed to produce the
1293 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1294 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}. The latter
1295 is sometimes the empty string.
1297 @code{missing} is the character used to indicate that a cell contains
1298 a missing value. It is always observed as @samp{.}.
1300 X0 repeats @code{decimal}, @code{grouping}, CustomCurrency, and
1301 @code{missing} already included in Formats.
1303 A writer may safely use false for @code{x16}.
1307 X1 only appears in version 3 members.
1311 00 byte[x14] bool[x15]
1313 byte[show-variables]
1315 int32[x17] int32[x18]
1321 @code{lang} may indicate the language in use. Some values seem to be
1322 0: @t{en}, 1: @t{de}, 2: @t{es}, 3: @t{it}, 5: @t{ko}, 6: @t{pl}, 8:
1323 @t{zh-tw}, 10: @t{pt_BR}, 11: @t{fr}. The @code{locale} in Formats
1324 and the @code{language}, @code{charset}, and @code{locale} in X0 are
1325 more likely to be useful in practice.
1327 @code{show-variables} determines how variables are displayed by
1328 default. A value of 1 means to display variable names, 2 to display
1329 variable labels when available, 3 to display both (name followed by
1330 label, separated by a space). The most common value is 0, which
1331 probably means to use a global default.
1333 @code{show-values} is a similar setting for values. A value of 1
1334 means to display the value, 2 to display the value label when
1335 available, 3 to display both. Again, the most common value is 0,
1336 which probably means to use a global default.
1338 A writer may safely use 1 for @code{x14}, false for @code{x15}, -1 for
1339 @code{x17} and @code{x18}, and false for @code{x19}.
1343 X2 only appears in version 3 members.
1347 int32[n-row-heights] int32*[n-row-heights]
1348 int32[n-style-map] StyleMap*[n-style-map]
1349 int32[n-styles] StylePair*[n-styles]
1351 StyleMap => int64[cell-index] int16[style-index]
1354 If present, @code{n-row-heights} and the accompanying integers are row
1355 heights as manually adjusted by the user.
1357 The rest of X2 specifies styles for data cells. At first glance this
1358 is odd, because each data cell can have its own style embedded as part
1359 of the data, but in practice X2 specifies a style for a cell only if
1360 that cell is empty (and thus does not appear in the data at all).
1361 Each StyleMap specifies the index of a blank cell, calculated the same
1362 was as in the Cells (@pxref{SPV Light Member Cells}), along with a
1363 0-based index into the accompanying StylePair array.
1365 A writer may safely omit the optional @code{i0 i0} inside the
1366 @code{count(@dots{})}.
1370 X3 only appears in version 3 members.
1374 01 00 byte[x20] 00 00 00
1377 (string[dataset] string[datafile] i0 int32[date] i0)?
1382 @code{date} is a date, as seconds since the epoch, i.e.@: since
1383 January 1, 1970. Pivot tables within an SPV file often have dates a
1384 few minutes apart, so this is probably a creation date for the table
1385 rather than for the file.
1387 X3 repeats @code{decimal}, @code{grouping}, CustomCurrency, and
1388 @code{missing} already included in Formats. @code{command},
1389 @code{command-local}, @code{language}, @code{charset}, and
1390 @code{locale} have the same meaning as in X0.
1392 @code{small} is a small real number, e.g.@: .001. Numbers smaller
1393 than this in absolute value are displayed in scientific notation.
1395 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1396 and other times they are absent. The reader can distinguish by
1397 assuming that they are present and then checking whether the
1398 presumptive @code{dataset} contains a null byte (a valid string never
1401 A writer may safely use 4 for @code{x20} and omit the optional bytes
1404 @node SPV Light Member Dimensions
1405 @subsection Dimensions
1407 A pivot table presents multidimensional data. A Dimension identifies
1408 the categories associated with each dimension.
1411 Dimensions => int32[n-dims] Dimension*[n-dims]
1413 Value[name] DimProperties
1414 int32[n-categories] Category*[n-categories]
1419 bool[hide-dim-label]
1420 bool[hide-all-labels]
1424 @code{name} is the name of the dimension, e.g.@: @code{Variables},
1425 @code{Statistics}, or a variable name.
1427 The meanings of @code{x1} and @code{x3} are unknown. @code{x1} is
1428 usually 0 but many other values have been observed. A writer may
1429 safely use 0 for @code{x1} and 2 for @code{x3}.
1431 @code{x2} is 0, 1, or 2. For a pivot table with @var{L} layer
1432 dimensions, @var{R} row dimensions, and @var{C} column dimensions,
1433 @code{x2} is 2 for the first @var{L} dimensions, 0 for the next
1434 @var{R} dimensions, and 1 for the remaining @var{C} dimensions. This
1435 does not mean that the layer dimensions must be presented first,
1436 followed by the row dimensions, followed by the column dimensions---on
1437 the contrary, they are frequently in a different order---but @code{x2}
1438 must follow this pattern to prevent the pivot table from being
1441 If @code{hide-dim-label} is 00, the pivot table displays a label for
1442 the dimension itself. Because usually the group and category labels
1443 are enough explanation, it is usually 01.
1445 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1446 the dimension, including group and category labels. It is usually 00.
1447 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1449 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1450 0 for the first dimension, 1 for the second, and so on. Sometimes it
1451 is -1. There is no visible difference.
1453 @node SPV Light Member Categories
1454 @subsection Categories
1456 Categories are arranged in a tree. Only the leaf nodes in the tree
1457 are really categories; the others just serve as grouping constructs.
1460 Category => Value[name] (Leaf @math{|} Group)
1461 Leaf => 00 00 00 i2 int32[leaf-index] i0
1463 bool[merge] 00 01 int32[x22]
1464 i-1 int32[n-subcategories] Category*[n-subcategories]
1467 @code{name} is the name of the category (or group).
1469 A Leaf represents a leaf category. The Leaf's @code{leaf-index} is a
1470 nonnegative integer unique within the Dimension and less than
1471 @code{n-categories} in the Dimension. If the user does not sort or
1472 rearrange the categories, then @code{leaf-index} starts at 0 for the
1473 first Leaf in the dimension and increments by 1 with each successive
1474 Leaf. If the user does sorts or rearrange the categories, then the
1475 order of categories in the file reflects that change and
1476 @code{leaf-index} reflects the original order.
1478 Occasionally a dimension has no leaf categories at all. A table that
1479 contains such a dimension necessarily has no data at all.
1481 A Group is a group of nested categories. Usually a Group contains at
1482 least one Category, so that @code{n-subcategories} is positive, but a
1483 few Groups with @code{n-subcategories} 0 has been observed.
1485 If a Group's @code{merge} is 00, the most common value, then the group
1486 is really a distinct group that should be represented as such in the
1487 visual representation and user interface. If @code{merge} is 01, the
1488 categories in this group should be shown and treated as if they were
1489 direct children of the group's containing group (or if it has no
1490 parent group, then direct children of the dimension), and this group's
1491 name is irrelevant and should not be displayed. (Merged groups can be
1494 (For writing an SPV file, there is no need to use the @code{merge}
1495 feature unless it is convenient.)
1497 A Group's @code{x22} appears to be i2 when all of the categories
1498 within a group are leaf categories that directly represent data values
1499 for a variable (e.g.@: in a frequency table or crosstabulation, a group
1500 of values in a variable being tabulated) and i0 otherwise. A writer
1501 may safely write a constant 0 in this field.
1503 @node SPV Light Member Axes
1506 After the dimensions come assignment of each dimension to one of the
1507 axes: layers, rows, and columns.
1511 int32[n-layers] int32[n-rows] int32[n-columns]
1512 int32*[n-layers] int32*[n-rows] int32*[n-columns]
1515 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1516 each specifies the number of dimensions displayed in layers, rows, and
1517 columns, respectively. Any of them may be zero. Their values sum to
1518 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1521 The following @code{n-dimensions} integers, in three groups, are a
1522 permutation of the 0-based dimension numbers. The first
1523 @code{n-layers} integers specify each of the dimensions represented by
1524 layers, the next @code{n-rows} integers specify the dimensions
1525 represented by rows, and the final @code{n-columns} integers specify
1526 the dimensions represented by columns. When there is more than one
1527 dimension of a given kind, the inner dimensions are given first.
1529 @node SPV Light Member Cells
1532 The final part of an SPV light member contains the actual data.
1535 Cells => int32[n-cells] Cell*[n-cells]
1536 Cell => int64[index] v1(00?) Value
1539 A Cell consists of an @code{index} and a Value. Suppose there are
1540 @math{d} dimensions, numbered 1 through @math{d} in the order given in
1541 the Dimensions previously, and that dimension @math{i}, has @math{n_i}
1542 categories. Consider the cell at coordinates @math{x_i}, @math{1 \le
1543 i \le d}, and note that @math{0 \le x_i < n_i}. Then the index is
1544 calculated by the following algorithm:
1548 for each @math{i} from 1 to @math{d}:
1549 @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1552 For example, suppose there are 3 dimensions with 3, 4, and 5
1553 categories, respectively. The cell at coordinates (1, 2, 3) has
1554 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1555 Within a given dimension, the index is the @code{leaf-index} in a Leaf.
1557 @node SPV Light Member Value
1560 Value is used throughout the SPV light member format. It boils down
1561 to a number or a string.
1564 Value => 00? 00? 00? 00? RawValue
1566 01 ValueMod int32[format] double[x]
1567 @math{|} 02 ValueMod int32[format] double[x]
1568 string[var-name] string[value-label] byte[show]
1569 @math{|} 03 string[local] ValueMod string[id] string[c] bool[fixed]
1570 @math{|} 04 ValueMod int32[format] string[value-label] string[var-name]
1571 byte[show] string[s]
1572 @math{|} 05 ValueMod string[var-name] string[var-label] byte[show]
1573 @math{|} ValueMod string[template] int32[n-args] Argument*[n-args]
1576 @math{|} int32[x] i0 Value*[x] /* x > 0 */
1579 There are several possible encodings, which one can distinguish by the
1580 first nonzero byte in the encoding.
1584 The numeric value @code{x}, intended to be presented to the user
1585 formatted according to @code{format}, which is in the format described
1586 for system files, except that format 40 is a synonym for F format
1587 instead of MTIME. @xref{System File Output Formats}, for details.
1588 Most commonly, @code{format} has width 40 (the maximum).
1590 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1591 represents the system-missing value SYSMIS. (HIGHEST and LOWEST have
1592 not been observed.) @xref{System File Format}, for more about these
1596 Similar to @code{01}, with the additional information that @code{x} is
1597 a value of variable @code{var-name} and has value label
1598 @code{value-label}. Both @code{var-name} and @code{value-label} can
1599 be the empty string, the latter very commonly.
1601 @code{show} determines whether to show the numeric value or the value
1602 label. A value of 1 means to show the value, 2 to show the label, 3
1603 to show both, and 0 means to use the default specified in
1604 @code{show-values} (@pxref{SPV Light Member Formats}).
1607 A text string, in two forms: @code{c} is in English, and sometimes
1608 abbreviated or obscure, and @code{local} is localized to the user's
1609 locale. In an English-language locale, the two strings are often the
1610 same, and in the cases where they differ, @code{local} is more
1611 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1612 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1613 where P must be greater than 1.''
1615 @code{c} and @code{local} are always either both empty or both
1618 @code{id} is a brief identifying string whose form seems to resemble a
1619 programming language identifier, e.g.@: @code{cumulative_percent} or
1620 @code{factor_14}. It is not unique.
1622 @code{fixed} is 00 for text taken from user input, such as syntax
1623 fragment, expressions, file names, data set names, and 01 for fixed
1624 text strings such as names of procedures or statistics. In the former
1625 case, @code{id} is always the empty string; in the latter case,
1626 @code{id} is still sometimes empty.
1629 The string value @code{s}, intended to be presented to the user
1630 formatted according to @code{format}. The format for a string is not
1631 too interesting, and the corpus contains many clearly invalid formats
1632 like A16.39 or A255.127 or A134.1, so readers should probably ignore
1633 the format entirely.
1635 @code{s} is a value of variable @code{var-name} and has value label
1636 @code{value-label}. @code{var-name} is never empty but
1637 @code{value-label} is commonly empty.
1639 @code{show} has the same meaning as in the encoding for 02.
1642 Variable @code{var-name}, which is rarely observed as empty in the
1643 corpus, with variable label @code{var-label}, which is often empty.
1645 @code{show} determines whether to show the variable name or the
1646 variable label. A value of 1 means to show the name, 2 to show the
1647 label, 3 to show both, and 0 means to use the default specified in
1648 @code{show-variables} (@pxref{SPV Light Member Formats}).
1651 When the first byte of a RawValue is not one of the above, the
1652 RawValue starts with a ValueMod, whose syntax is described in the next
1653 section. (A ValueMod always begins with byte 31 or 58.)
1655 This case is a template string, analogous to @code{printf}, followed
1656 by one or more Arguments, each of which has one or more values. The
1657 template string is copied directly into the output except for the
1658 following special syntax,
1665 Each of these expands to the character following @samp{\\}, to escape
1666 characters that have special meaning in template strings. These are
1667 effective inside and outside the @code{[@dots{}]} syntax forms
1671 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1675 Expands to a formatted version of argument @var{i}, which must have
1676 only a single value. For example, @code{^1} expands to the first
1677 argument's @code{value}.
1679 @item [:@var{a}:]@var{i}
1680 Expands @var{a} for each of the values in @var{i}. @var{a}
1681 should contain one or more @code{^@var{j}} conversions, which are
1682 drawn from the values for argument @var{i} in order. Some examples
1687 All of the values for the first argument, concatenated.
1690 Expands to the values for the first argument, each followed by
1694 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1695 argument's first value and @var{y} is its second value. (This would
1696 be used only if the argument has two values. If there were more
1697 values, the second and third values would be directly concatenated,
1698 which would look funny.)
1701 @item [@var{a}:@var{b}:]@var{i}
1702 This extends the previous form so that the first values are expanded
1703 using @var{a} and later values are expanded using @var{b}. For an
1704 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1705 instead written as @code{%@var{j}}. Some examples from the corpus:
1709 Expands to all of the values for the first argument, separated by
1712 @item [%1 = %2:, ^1 = ^2:]1
1713 Given appropriate values for the first argument, expands to @code{X =
1717 Given appropriate values, expands to @code{1, 2, 3}.
1721 The template string is localized to the user's locale.
1724 A writer may safely omit all of the optional 00 bytes at the beginning
1725 of a Value, except that it should write a single 00 byte before a
1728 @node SPV Light Member ValueMod
1729 @subsection ValueMod
1731 A ValueMod can specify special modifications to a Value.
1737 int32[n-refs] int16*[n-refs]
1738 (i0 | i1 string[subscript])
1739 v1(00 (i1 | i2) 00? 00? int32 00? 00?)
1740 v3(count(TemplateString StylePair))
1742 TemplateString => count((count((i0 58)?) (58 @math{|} 31 string[id]))?)
1749 bool[bold] bool[italic] bool[underline] bool[show]
1750 string[fg-color] string[bg-color]
1751 string[typeface] byte[size]
1754 int32[halign] int32[valign] double[decimal-offset]
1755 int16[left-margin] int16[right-margin]
1756 int16[top-margin] int16[bottom-margin]
1759 A ValueMod that begins with ``31'' specifies special modifications to
1762 Each of the @code{n-refs} integers is a reference to a Footnote
1763 (@pxref{SPV Light Member Footnotes}) by 0-based index. Footnote
1764 markers are shown appended to the main text of the Value, as
1767 The @code{subscript}, if present, is a string to append to the main
1768 text of the Value, as a subscript. The subscript text is a brief
1769 indicator, e.g.@: @samp{a} or @samp{a,b}, with its meaning indicated
1770 by the table caption.
1772 The @code{id} inside the TemplateString, if present, is a template
1773 string for substitutions using the syntax explained previously. It
1774 appears to be an English-language version of the localized template
1775 string in the Value in which the Template is nested. A writer may
1776 safely omit the optional fixed data in TemplateString.
1778 FontStyle and CellStyle, if present, change the style for this
1779 individual Value. In FontStyle, @code{bold}, @code{italic}, and
1780 @code{underline} control the particular style. @code{show} is
1781 ordinarily 1; if it is 0, then the cell data is not shown.
1782 @code{fg-color} and @code{bg-color} are strings in the format
1783 @code{#rrggbb}, e.g.@: @code{#ff0000} for red or @code{#ffffff} for
1784 white. The empty string is occasionally observed also. The
1785 @code{size} is a font size in units of 1/128 inch.
1787 In CellStyle, @code{halign} is 0 for center, 2 for left, 4 for right,
1788 6 for decimal, 0xffffffad for mixed. For decimal alignment,
1789 @code{decimal-offset} is the decimal point's offset from the right
1790 side of the cell, in pt (@pxref{SPV Light Detail Member Format}).
1791 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1792 for bottom. @code{left-margin}, @code{right-margin},
1793 @code{top-margin}, and @code{bottom-margin} are in pt.
1795 @node SPV Legacy Detail Member Binary Format
1796 @section Legacy Detail Member Binary Format
1798 Whereas the light binary format represents everything about a given
1799 pivot table, the legacy binary format conceptually consists of a
1800 number of named sources, each of which consists of a number of named
1801 variables, each of which is a 1-dimensional array of numbers or
1802 strings or a mix. Thus, the legacy binary member format is quite
1805 This section uses the same context-free grammar notation as in the
1806 previous section, with the following additions:
1810 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
1811 (The legacy member header indicates the version; see below.)
1814 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
1817 A legacy detail member @file{.bin} has the following overall format:
1821 00 byte[version] int16[n-sources] int32[member-size]
1822 Metadata*[n-sources]
1827 @code{version} is a version number that affects the interpretation of
1828 some of the other data in the member. Versions 0xaf and 0xb0 are
1829 known. We will refer to ``version 0xaf'' and ``version 0xb0'' members
1832 A legacy member consists of @code{n-sources} data sources, each of
1833 which has Metadata and Data.
1835 @code{member-size} is the size of the legacy binary member, in bytes.
1837 The Data and Strings above are commented out because the Metadata has
1838 some oddities that mean that the Data sometimes seems to start at
1839 an unexpected place. The following section goes into detail.
1842 * SPV Legacy Member Metadata::
1843 * SPV Legacy Member Numeric Data::
1844 * SPV Legacy Member String Data::
1847 @node SPV Legacy Member Metadata
1848 @subsection Metadata
1852 int32[n-values] int32[n-variables] int32[data-offset]
1853 vAF(byte*28[source-name])
1854 vB0(byte*64[source-name] int32[x])
1857 A data source has @code{n-variables} variables, each with
1858 @code{n-values} data values.
1860 @code{source-name} is a 28- or 64-byte string padded on the right with
1861 0-bytes. The names that appear in the corpus are very generic:
1862 usually @code{tableData} for pivot table data or @code{source0} for
1865 A given Metadata's @code{data-offset} is the offset, in bytes, from
1866 the beginning of the member to the start of the corresponding Data.
1867 This allows programs to skip to the beginning of the data for a
1868 particular source. In every case in the corpus, the Data follow the
1869 Metadata in the same order, but it is important to use
1870 @code{data-offset} instead of reading sequentially through the file
1871 because of the exception described below.
1873 One SPV file in the corpus has legacy binary members with version 0xb0
1874 but a 28-byte @code{source-name} field (and only a single source). In
1875 practice, this means that the 64-byte @code{source-name} used in
1876 version 0xb0 has a lot of 0-bytes in the middle followed by the
1877 @code{variable-name} of the following Data. As long as a reader
1878 treats the first 0-byte in the @code{source-name} as terminating the
1879 string, it can properly interpret these members.
1881 The meaning of @code{x} in version 0xb0 is unknown.
1883 @node SPV Legacy Member Numeric Data
1884 @subsection Numeric Data
1887 Data => Variable*[n-variables]
1888 Variable => byte*288[variable-name] double*[n-values]
1891 Data follow the Metadata in the legacy binary format, with sources in
1892 the same order (but readers should use the @code{data-offset} in
1893 Metadata records, rather than reading sequentially). Each Variable
1894 begins with a @code{variable-name} that generally indicates its role
1895 in the pivot table, e.g.@: ``cell'', ``cellFormat'',
1896 ``dimension0categories'', ``dimension0group0'', followed by the
1897 numeric data, one double per datum. A double with the maximum
1898 negative double @code{-DBL_MAX} represents the system-missing value
1901 @node SPV Legacy Member String Data
1902 @subsection String Data
1905 Strings => SourceMaps[maps] Labels
1907 SourceMaps => int32[n-maps] SourceMap*[n-maps]
1909 SourceMap => string[source-name] int32[n-variables] VariableMap*[n-variables]
1910 VariableMap => string[variable-name] int32[n-data] DatumMap*[n-data]
1911 DatumMap => int32[value-idx] int32[label-idx]
1913 Labels => int32[n-labels] Label*[n-labels]
1914 Label => int32[frequency] string[label]
1917 Each variable may include a mix of numeric and string data values. If
1918 a legacy binary member contains any string data, Strings is present;
1919 otherwise, it ends just after the last Data element.
1921 The string data overlays the numeric data. When a variable includes
1922 any string data, its Variable represents the string values with a
1923 SYSMIS or NaN placeholder. (Not all such values need be
1926 Each SourceMap provides a mapping between SYSMIS or NaN values in source
1927 @code{source-name} and the string data that they represent.
1928 @code{n-variables} is the number of variables in the source that
1929 include string data. More precisely, it is the 1-based index of the
1930 last variable in the source that includes any string data; thus, it
1931 would be 4 if there are 5 variables and only the fourth one includes
1934 A VariableMap repeats its variable's name, but variables are always
1935 present in the same order as the source, starting from the first
1936 variable, without skipping any even if they have no string values.
1937 Each VariableMap contains DatumMap nonterminals, each of which maps
1938 from a 0-based index within its variable's data to a 0-based label
1939 index, e.g.@: pair @code{value-idx} = 2, @code{label-idx} = 3, means
1940 that the third data value (which must be SYSMIS or NaN) is to be
1941 replaced by the string of the fourth Label.
1943 The labels themselves follow the pairs. The valuable part of each
1944 label is the string @code{label}. Each label also includes a
1945 @code{frequency} that reports the number of DatumMaps that reference
1946 it (although this is not useful).
1948 @node SPV Legacy Detail Member XML Format
1949 @section Legacy Detail Member XML Format
1951 The design of the detail XML format is not what one would end up with
1952 for describing pivot tables. This is because it is a special case
1953 of a much more general format (``visualization XML'' or ``VizML'')
1954 that can describe a wide range of visualizations. Most of this
1955 generality is overkill for tables, and so we end up with a funny
1956 subset of a general-purpose format.
1958 An XML Schema for VizML is available, distributed with SPSS binaries,
1959 under a nonfree license. It contains documentation that is
1960 occasionally helpful.
1962 See @file{src/output/spv/detail-xml.grammar} in the PSPP source tree
1963 for the full grammar that it uses for parsing.
1965 The important elements of the detail XML format are:
1969 Variables. @xref{SPV Detail Variable Elements}.
1972 Assignment of variables to axes. A variable can appear as columns, or
1973 rows, or layers. The @code{faceting} element and its sub-elements
1974 describe this assignment.
1977 Styles and other annotations.
1980 This description is not detailed enough to write legacy tables.
1981 Instead, write tables in the light binary format.
1984 * SPV Detail visualization Element::
1985 * SPV Detail Variable Elements::
1986 * SPV Detail extension Element::
1987 * SPV Detail graph Element::
1988 * SPV Detail location Element::
1989 * SPV Detail faceting Element::
1990 * SPV Detail facetLayout Element::
1991 * SPV Detail label Element::
1992 * SPV Detail setCellProperties Element::
1993 * SPV Detail setFormat Element::
1994 * SPV Detail interval Element::
1995 * SPV Detail style Element::
1996 * SPV Detail labelFrame Element::
1997 * SPV Detail Legacy Properties::
2000 @node SPV Detail visualization Element
2001 @subsection The @code{visualization} Element
2009 :style[style_ref]=ref style
2013 => visualization_extension?
2015 (sourceVariable | derivedVariable)+
2024 extension[visualization_extension]
2027 :minWidthSet=(true)?
2028 :maxWidthSet=(true)?
2031 userSource :missing=(listwise | pairwise)? => EMPTY
2033 categoricalDomain => variableReference simpleSort
2035 simpleSort :method[sort_method]=(custom) => categoryOrder
2037 container :style=ref style => container_extension? location+ labelFrame*
2039 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2047 The @code{visualization} element is the root of detail XML member. It
2048 has the following attributes:
2050 @defvr {Attribute} creator
2051 The version of the software that created this SPV file, as a string of
2052 the form @code{xxyyzz}, which represents software version xx.yy.zz,
2053 e.g.@: @code{160001} is version 16.0.1. The corpus includes major
2054 versions 16 through 19.
2057 @defvr {Attribute} date
2058 The date on the which the file was created, as a string of the form
2062 @defvr {Attribute} lang
2063 The locale used for output, in Windows format, which is similar to the
2064 format used in Unix with the underscore replaced by a hyphen, e.g.@:
2065 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
2068 @defvr {Attribute} name
2069 The title of the pivot table, localized to the output language.
2072 @defvr {Attribute} style
2073 The base style for the pivot table. In every example in the corpus,
2074 the @code{style} element has no attributes other than @code{id}.
2077 @defvr {Attribute} type
2078 A floating-point number. The meaning is unknown.
2081 @defvr {Attribute} version
2082 The visualization schema version number. In the corpus, the value is
2083 one of 2.4, 2.5, 2.7, and 2.8.
2086 The @code{userSource} element has no visible effect.
2088 The @code{extension} element as a child of @code{visualization} has
2089 the following attributes.
2091 @defvr {Attribute} numRows
2092 An integer that presumably defines the number of rows in the displayed
2096 @defvr {Attribute} showGridline
2097 Always set to @code{false} in the corpus.
2100 @defvr {Attribute} minWidthSet
2101 @defvrx {Attribute} maxWidthSet
2102 Always set to @code{true} in the corpus.
2105 The @code{extension} element as a child of @code{container} has the
2108 @defvr {Attribute} combinedFootnotes
2112 The @code{categoricalDomain} and @code{simpleSort} elements have no
2115 The @code{layerController} element has no visible effect.
2117 @node SPV Detail Variable Elements
2118 @subsection Variable Elements
2120 A ``variable'' in detail XML is a 1-dimensional array of data. Each
2121 element of the array may, independently, have string or numeric
2122 content. All of the variables in a given detail XML member either
2123 have the same number of elements or have zero elements.
2125 Two different elements define variables and their content:
2128 @item sourceVariable
2129 These variables' data comes from the associated @code{tableData.bin}
2132 @item derivedVariable
2133 These variables are defined in terms of a mapping function from a
2134 source variable, or they are empty.
2137 A variable named @code{cell} always exists. This variable holds the
2138 data displayed in the table.
2140 Variables in detail XML roughly correspond to the dimensions in a
2141 light detail member. Each dimension has the following variables with
2142 stylized names, where @var{n} is a number for the dimension starting
2146 @item dimension@var{n}categories
2147 The dimension's leaf categories (@pxref{SPV Light Member Categories}).
2149 @item dimension@var{n}group0
2150 Present only if the dimension's categories are grouped, this variable
2151 holds the group labels for the categories. Grouping is inferred
2152 through adjacent identical labels. Categories that are not part of a
2153 group have empty-string data in this variable.
2155 @item dimension@var{n}group1
2156 Present only if the first-level groups are further grouped, this
2157 variable holds the labels for the second-level groups. There can be
2158 additional variables with further levels of grouping.
2160 @item dimension@var{n}
2164 Determining the data for a (non-empty) variable is a multi-step
2169 Draw initial data from its source, for a @code{sourceVariable}, or
2170 from another named variable, for a @code{derivedVariable}.
2173 Apply mappings from @code{valueMapEntry} elements within the
2174 @code{derivedVariable} element, if any.
2177 Apply mappings from @code{relabel} elements within a @code{format} or
2178 @code{stringFormat} element in the @code{sourceVariable} or
2179 @code{derivedVariable} element, if any.
2182 If the variable is a @code{sourceVariable} with a @code{labelVariable}
2183 attribute, and there were no mappings to apply in previous steps, then
2184 replace each element of the variable by the corresponding value in the
2188 A single variable's data can be modified in two of the steps, if both
2189 @code{valueMapEntry} and @code{relabel} are used. The following
2190 example from the corpus maps several integers to 2, then maps 2 in
2191 turn to the string ``Input'':
2194 <derivedVariable categorical="true" dependsOn="dimension0categories"
2195 id="dimension0group0map" value="map(dimension0group0)">
2197 <relabel from="2" to="Input"/>
2198 <relabel from="10" to="Missing Value Handling"/>
2199 <relabel from="14" to="Resources"/>
2200 <relabel from="0" to=""/>
2201 <relabel from="1" to=""/>
2202 <relabel from="13" to=""/>
2204 <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
2205 <valueMapEntry from="10;11" to="10"/>
2206 <valueMapEntry from="14;15" to="14"/>
2207 <valueMapEntry from="0" to="0"/>
2208 <valueMapEntry from="1" to="1"/>
2209 <valueMapEntry from="13" to="13"/>
2214 * SPV Detail sourceVariable Element::
2215 * SPV Detail derivedVariable Element::
2216 * SPV Detail valueMapEntry Element::
2219 @node SPV Detail sourceVariable Element
2220 @subsubsection The @code{sourceVariable} Element
2227 :domain=ref categoricalDomain?
2229 :dependsOn=ref sourceVariable?
2231 :labelVariable=ref sourceVariable?
2232 => variable_extension* (format | stringFormat)?
2235 This element defines a variable whose data comes from the
2236 @file{tableData.bin} member that corresponds to this @file{.xml}.
2238 This element has the following attributes.
2240 @defvr {Attribute} id
2241 An @code{id} is always present because this element exists to be
2242 referenced from other elements.
2245 @defvr {Attribute} categorical
2246 Always set to @code{true}.
2249 @defvr {Attribute} source
2250 Always set to @code{tableData}, the @code{source-name} in the
2251 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
2255 @defvr {Attribute} sourceName
2256 The name of a variable within the source, corresponding to the
2257 @code{variable-name} in the @file{tableData.bin} member (@pxref{SPV
2258 Legacy Member Numeric Data}).
2261 @defvr {Attribute} label
2262 The variable label, if any.
2265 @defvr {Attribute} labelVariable
2266 The @code{variable-name} of a variable whose string values correspond
2267 one-to-one with the values of this variable and are suitable for use
2271 @defvr {Attribute} dependsOn
2272 This attribute doesn't affect the display of a table.
2275 @node SPV Detail derivedVariable Element
2276 @subsubsection The @code{derivedVariable} Element
2283 :dependsOn=ref sourceVariable?
2284 => variable_extension* (format | stringFormat)? valueMapEntry*
2287 Like @code{sourceVariable}, this element defines a variable whose
2288 values can be used elsewhere in the visualization. Instead of being
2289 read from a data source, the variable's data are defined by a
2290 mathematical expression.
2292 This element has the following attributes.
2294 @defvr {Attribute} id
2295 An @code{id} is always present because this element exists to be
2296 referenced from other elements.
2299 @defvr {Attribute} categorical
2300 Always set to @code{true}.
2303 @defvr {Attribute} value
2304 An expression that defines the variable's value. In theory this could
2305 be an arbitrary expression in terms of constants, functions, and other
2306 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}. In practice,
2307 the corpus contains only the following forms of expressions:
2311 @itemx constant(@var{variable})
2312 All zeros. The reason why a variable is sometimes named is unknown.
2313 Sometimes the ``variable name'' has spaces in it.
2315 @item map(@var{variable})
2316 Transforms the values in the named @var{variable} using the
2317 @code{valueMapEntry}s contained within the element.
2321 @defvr {Attribute} dependsOn
2322 This attribute doesn't affect the display of a table.
2325 @node SPV Detail valueMapEntry Element
2326 @subsubsection The @code{valueMapEntry} Element
2329 valueMapEntry :from :to => EMPTY
2332 A @code{valueMapEntry} element defines a mapping from one or more
2333 values of a source expression to a target value. (In the corpus, the
2334 source expression is always just the name of a variable.) Each target
2335 value requires a separate @code{valueMapEntry}. If multiple source
2336 values map to the same target value, they can be combined or separate.
2338 In the corpus, all of the source and target values are integers.
2340 @code{valueMapEntry} has the following attributes.
2342 @defvr {Attribute} from
2343 A source value, or multiple source values separated by semicolons,
2344 e.g.@: @code{0} or @code{13;14;15;16}.
2347 @defvr {Attribute} to
2348 The target value, e.g.@: @code{0}.
2351 @node SPV Detail extension Element
2352 @subsection The @code{extension} Element
2354 This is a general-purpose ``extension'' element. Readers that don't
2355 understand a given extension should be able to safely ignore it. The
2356 attributes on this element, and their meanings, vary based on the
2357 context. Each known usage is described separately below. The current
2358 extensions use attributes exclusively, without any nested elements.
2360 @subsubheading @code{container} Parent Element
2363 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2366 With @code{container} as its parent element, @code{extension} has the
2367 following attributes.
2369 @defvr {Attribute} combinedFootnotes
2370 Always set to @code{true} in the corpus.
2373 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
2376 extension[variable_extension] :from :helpId => EMPTY
2379 With @code{sourceVariable} or @code{derivedVariable} as its parent
2380 element, @code{extension} has the following attributes. A given
2381 parent element often contains several @code{extension} elements that
2382 specify the meaning of the source data's variables or sources, e.g.@:
2385 <extension from="0" helpId="corrected_model"/>
2386 <extension from="3" helpId="error"/>
2387 <extension from="4" helpId="total_9"/>
2388 <extension from="5" helpId="corrected_total"/>
2391 More commonly they are less helpful, e.g.@:
2394 <extension from="0" helpId="notes"/>
2395 <extension from="1" helpId="notes"/>
2396 <extension from="2" helpId="notes"/>
2397 <extension from="5" helpId="notes"/>
2398 <extension from="6" helpId="notes"/>
2399 <extension from="7" helpId="notes"/>
2400 <extension from="8" helpId="notes"/>
2401 <extension from="12" helpId="notes"/>
2402 <extension from="13" helpId="no_help"/>
2403 <extension from="14" helpId="notes"/>
2406 @defvr {Attribute} from
2407 An integer or a name like ``dimension0''.
2410 @defvr {Attribute} helpId
2414 @node SPV Detail graph Element
2415 @subsection The @code{graph} Element
2419 :cellStyle=ref style
2421 => location+ coordinates faceting facetLayout interval
2423 coordinates => EMPTY
2426 @code{graph} has the following attributes.
2428 @defvr {Attribute} cellStyle
2429 @defvrx {Attribute} style
2430 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
2431 Detail style Element}). The former is the default style for
2432 individual cells, the latter for the entire table.
2435 @node SPV Detail location Element
2436 @subsection The @code{location} Element
2440 :part=(height | width | top | bottom | left | right)
2441 :method=(sizeToContent | attach | fixed | same)
2444 :target=ref (labelFrame | graph | container)?
2449 Each instance of this element specifies where some part of the table
2450 frame is located. All the examples in the corpus have four instances
2451 of this element, one for each of the parts @code{height},
2452 @code{width}, @code{left}, and @code{top}. Some examples in the
2453 corpus add a fifth for part @code{bottom}, even though it is not clear
2454 how all of @code{top}, @code{bottom}, and @code{height} can be honored
2455 at the same time. In any case, @code{location} seems to have little
2456 importance in representing tables; a reader can safely ignore it.
2458 @defvr {Attribute} part
2459 The part of the table being located.
2462 @defvr {Attribute} method
2463 How the location is determined:
2467 Based on the natural size of the table. Observed only for
2468 parts @code{height} and @code{width}.
2471 Based on the location specified in @code{target}. Observed only for
2472 parts @code{top} and @code{bottom}.
2475 Using the value in @code{value}. Observed only for parts @code{top},
2476 @code{bottom}, and @code{left}.
2479 Same as the specified @code{target}. Observed only for part
2484 @defvr {Attribute} min
2485 Minimum size. Only observed with value @code{100pt}. Only observed
2486 for part @code{width}.
2489 @defvr {Dependent} target
2490 Required when @code{method} is @code{attach} or @code{same}, not
2491 observed otherwise. This identifies an element to attach to.
2492 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
2496 @defvr {Dependent} value
2497 Required when @code{method} is @code{fixed}, not observed otherwise.
2498 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
2499 on parts @code{top} and @code{left}, and @code{100%} on part
2503 @node SPV Detail faceting Element
2504 @subsection The @code{faceting} Element
2507 faceting => layer[layers1]* cross layer[layers2]*
2509 cross => (unity | nest) (unity | nest)
2513 nest => variableReference[vars]+
2515 variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY
2518 :variable=ref (sourceVariable | derivedVariable)
2521 :method[layer_method]=(nest)?
2526 The @code{faceting} element describes the row, column, and layer
2527 structure of the table. Its @code{cross} child determines the row and
2528 column structure, and each @code{layer} child (if any) represents a
2529 layer. Layers may appear before or after @code{cross}.
2531 The @code{cross} element describes the row and column structure of the
2532 table. It has exactly two children, the first of which describes the
2533 table's columns and the second the table's rows. Each child is a
2534 @code{nest} element if the table has any dimensions along the axis in
2535 question, otherwise a @code{unity} element.
2537 A @code{nest} element contains of one or more dimensions listed from
2538 innermost to outermost, each represented by @code{variableReference}
2539 child elements. Each variable in a dimension is listed in order.
2540 @xref{SPV Detail Variable Elements}, for information on the variables
2541 that comprise a dimension.
2543 A @code{nest} can contain a single dimension, e.g.:
2547 <variableReference ref="dimension0categories"/>
2548 <variableReference ref="dimension0group0"/>
2549 <variableReference ref="dimension0"/>
2554 A @code{nest} can contain multiple dimensions, e.g.:
2558 <variableReference ref="dimension1categories"/>
2559 <variableReference ref="dimension1group0"/>
2560 <variableReference ref="dimension1"/>
2561 <variableReference ref="dimension0categories"/>
2562 <variableReference ref="dimension0"/>
2566 A @code{nest} may have no dimensions, in which case it still has one
2567 @code{variableReference} child, which references a
2568 @code{derivedVariable} whose @code{value} attribute is
2569 @code{constant(0)}. In the corpus, such a @code{derivedVariable} has
2570 @code{row} or @code{column}, respectively, as its @code{id}. This is
2571 equivalent to using a @code{unity} element in place of @code{nest}.
2573 A @code{variableReference} element refers to a variable through its
2574 @code{ref} attribute.
2576 Each @code{layer} element represents a dimension, e.g.:
2579 <layer value="0" variable="dimension0categories" visible="true"/>
2580 <layer value="dimension0" variable="dimension0" visible="false"/>
2584 @code{layer} has the following attributes.
2586 @defvr {Attribute} variable
2587 Refers to a @code{sourceVariable} or @code{derivedVariable} element.
2590 @defvr {Attribute} value
2591 The value to select. For a category variable, this is always
2592 @code{0}; for a data variable, it is the same as the @code{variable}
2596 @defvr {Attribute} visible
2597 Whether the layer is visible. Generally, category layers are visible
2598 and data layers are not, but sometimes this attribute is omitted.
2601 @defvr {Attribute} method
2602 When present, this is always @code{nest}.
2605 @node SPV Detail facetLayout Element
2606 @subsection The @code{facetLayout} Element
2609 facetLayout => tableLayout setCellProperties[scp1]*
2610 facetLevel+ setCellProperties[scp2]*
2613 :verticalTitlesInCorner=bool
2615 :fitCells=(ticks both)?
2619 The @code{facetLayout} element and its descendants control styling for
2622 Its @code{tableLayout} child has the following attributes
2624 @defvr {Attribute} verticalTitlesInCorner
2625 If true, in the absence of corner text, row headings will be displayed
2629 @defvr {Attribute} style
2630 Refers to a @code{style} element.
2633 @defvr {Attribute} fitCells
2637 @subsubheading The @code{facetLevel} Element
2640 facetLevel :level=int :gap=dimension? => axis
2642 axis :style=ref style => label? majorTicks
2648 :tickFrameStyle=ref style
2649 :labelFrequency=int?
2659 Each @code{facetLevel} describes a @code{variableReference} or
2660 @code{layer}, and a table has one @code{facetLevel} element for
2661 each such element. For example, an SPV detail member that contains
2662 four @code{variableReference} elements and two @code{layer} elements
2663 will contain six @code{facetLevel} elements.
2665 In the corpus, @code{facetLevel} elements and the elements that they
2666 describe are always in the same order. The correspondence may also be
2667 observed in two other ways. First, one may use the @code{level}
2668 attribute, described below. Second, in the corpus, a
2669 @code{facetLevel} always has an @code{id} that is the same as the
2670 @code{id} of the element it describes with @code{_facetLevel}
2671 appended. One should not formally rely on this, of course, but it is
2672 usefully indicative.
2674 @defvr {Attribute} level
2675 A 1-based index into the @code{variableReference} and @code{layer}
2676 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2677 describes the first @code{variableReference} in the SPV detail member,
2678 and in a member with four @code{variableReference} elements, a
2679 @code{facetLayout} with a @code{level} of 5 describes the first
2680 @code{layer} in the member.
2683 @defvr {Attribute} gap
2684 Always observed as @code{0pt}.
2687 Each @code{facetLevel} contains an @code{axis}, which in turn may
2688 contain a @code{label} for the @code{facetLevel} (@pxref{SPV Detail
2689 label Element}) and does contain a @code{majorTicks} element.
2691 @defvr {Attribute} labelAngle
2692 Normally 0. The value -90 causes inner column or outer row labels to
2693 be rotated vertically.
2696 @defvr {Attribute} style
2697 @defvrx {Attribute} tickFrameStyle
2698 Each refers to a @code{style} element. @code{style} is the style of
2699 the tick labels, @code{tickFrameStyle} the style for the frames around
2703 @node SPV Detail label Element
2704 @subsection The @code{label} Element
2709 :textFrameStyle=ref style?
2710 :purpose=(title | subTitle | subSubTitle | layer | footnote)?
2711 => text+ | descriptionGroup
2714 :target=ref faceting
2716 => (description | text)+
2718 description :name=(variable | value) => EMPTY
2722 :definesReference=int?
2723 :position=(subscript | superscript)?
2728 This element represents a label on some aspect of the table.
2730 @defvr {Attribute} style
2731 @defvrx {Attribute} textFrameStyle
2732 Each of these refers to a @code{style} element. @code{style} is the
2733 style of the label text, @code{textFrameStyle} the style for the frame
2737 @defvr {Attribute} purpose
2738 The kind of entity being labeled.
2741 A @code{descriptionGroup} concatenates one or more elements to form a
2742 label. Each element can be a @code{text} element, which contains
2743 literal text, or a @code{description} element that substitutes a value
2746 @defvr {Attribute} target
2747 The @code{id} of an element being described. In the corpus, this is
2748 always @code{faceting}.
2751 @defvr {Attribute} separator
2752 A string to separate the description of multiple groups, if the
2753 @code{target} has more than one. In the corpus, this is always a
2757 Typical contents for a @code{descriptionGroup} are a value by itself:
2759 <description name="value"/>
2761 @noindent or a variable and its value, separated by a colon:
2763 <description name="variable"/><text>:</text><description name="value"/>
2766 A @code{description} is like a macro that expands to some property of
2767 the target of its parent @code{descriptionGroup}. The @code{name}
2768 attribute specifies the property.
2770 @node SPV Detail setCellProperties Element
2771 @subsection The @code{setCellProperties} Element
2775 :applyToConverse=bool?
2776 => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]?
2779 The @code{setCellProperties} element sets style properties of cells or
2780 row or column labels.
2782 Interpreting @code{setCellProperties} requires answering two
2783 questions: which cells or labels to style, and what styles to use.
2785 @subsubheading Which Cells?
2790 intersect => where+ | intersectWhere | alternating | EMPTY
2793 :variable=ref (sourceVariable | derivedVariable)
2798 :variable=ref (sourceVariable | derivedVariable)
2799 :variable2=ref (sourceVariable | derivedVariable)
2802 alternating => EMPTY
2805 When @code{union} is present with @code{intersect} children, each of
2806 those children specifies a group of cells that should be styled, and
2807 the total group is all those cells taken together. When @code{union}
2808 is absent, every cell is styled. One attribute on
2809 @code{setCellProperties} affects the choice of cells:
2811 @defvr {Attribute} applyToConverse
2812 If true, this inverts the meaning of the cell selection: the selected
2813 cells are the ones @emph{not} designated. This is confusing, given
2814 the additional restrictions of @code{union}, but in the corpus
2815 @code{applyToConverse} is never present along with @code{union}.
2818 An @code{intersect} specifies restrictions on the cells to be matched.
2819 Each @code{where} child specifies which values of a given variable to
2820 include. The attributes of @code{intersect} are:
2822 @defvr {Attribute} variable
2823 Refers to a variable, e.g.@: @code{dimension0categories}. Only
2824 ``categories'' variables make sense here, but other variables, e.g.@:
2825 @code{dimension0group0map}, are sometimes seen. The reader may ignore
2829 @defvr {Attribute} include
2830 A value, or multiple values separated by semicolons,
2831 e.g.@: @code{0} or @code{13;14;15;16}.
2834 PSPP ignores @code{setCellProperties} when @code{intersectWhere} is
2837 @subsubheading What Styles?
2841 :target=ref (labeling | graph | interval | majorTicks)
2845 setMetaData :target=ref graph :key :value => EMPTY
2848 :target=ref (majorTicks | labeling)
2850 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
2854 :target=ref majorTicks
2858 The @code{set*} children of @code{setCellProperties} determine the
2861 When @code{setCellProperties} contains a @code{setFormat} whose
2862 @code{target} references a @code{labeling} element, or if it contains
2863 a @code{setStyle} that references a @code{labeling} or @code{interval}
2864 element, the @code{setCellProperties} sets the style for table cells.
2865 The format from the @code{setFormat}, if present, replaces the cells'
2866 format. The style from the @code{setStyle} that references
2867 @code{labeling}, if present, replaces the label's font and cell
2868 styles, except that the background color is taken instead from the
2869 @code{interval}'s style, if present.
2871 When @code{setCellProperties} contains a @code{setFormat} whose
2872 @code{target} references a @code{majorTicks} element, or if it
2873 contains a @code{setStyle} whose @code{target} references a
2874 @code{majorTicks}, or if it contains a @code{setFrameStyle} element,
2875 the @code{setCellProperties} sets the style for row or column labels.
2876 In this case, the @code{setCellProperties} always contains a single
2877 @code{where} element whose @code{variable} designates the variable
2878 whose labels are to be styled. The format from the @code{setFormat},
2879 if present, replaces the labels' format. The style from the
2880 @code{setStyle} that references @code{majorTicks}, if present,
2881 replaces the labels' font and cell styles, except that the background
2882 color is taken instead from the @code{setFrameStyle}'s style, if
2885 When @code{setCellProperties} contains a @code{setStyle} whose
2886 @code{target} references a @code{graph} element, and one that
2887 references a @code{labeling} element, and the @code{union} element
2888 contains @code{alternating}, the @code{setCellProperties} sets the
2889 alternate foreground and background colors for the data area. The
2890 foreground color is taken from the style referenced by the
2891 @code{setStyle} that targets the @code{graph}, the background color
2892 from the @code{setStyle} for @code{labeling}.
2894 A reader may ignore a @code{setCellProperties} that only contains
2895 @code{setMetaData}, as well as @code{setMetaData} within other
2896 @code{setCellProperties}.
2898 A reader may ignore a @code{setCellProperties} whose only @code{set*}
2899 child is a @code{setStyle} that targets the @code{graph} element.
2901 @subsubheading The @code{setStyle} Element
2905 :target=ref (labeling | graph | interval | majorTicks)
2910 This element associates a style with the target.
2912 @defvr {Attribute} target
2913 The @code{id} of an element whose style is to be set.
2916 @defvr {Attribute} style
2917 The @code{id} of a @code{style} element that identifies the style to
2921 @node SPV Detail setFormat Element
2922 @subsection The @code{setFormat} Element
2926 :target=ref (majorTicks | labeling)
2928 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
2931 This element sets the format of the target, ``format'' in this case
2932 meaning the SPSS print format for a variable.
2934 The details of this element vary depending on the schema version, as
2935 declared in the root @code{visualization} element's @code{version}
2936 attribute (@pxref{SPV Detail visualization Element}). A reader can
2937 interpret the content without knowing the schema version.
2939 The @code{setFormat} element itself has the following attributes.
2941 @defvr {Attribute} target
2942 Refers to an element whose style is to be set.
2945 @defvr {Attribute} reset
2946 If this is @code{true}, this format replaces the target's previous
2947 format. If it is @code{false}, the modifies the previous format.
2951 * SPV Detail numberFormat Element::
2952 * SPV Detail stringFormat Element::
2953 * SPV Detail dateTimeFormat Element::
2954 * SPV Detail elapsedTimeFormat Element::
2955 * SPV Detail format Element::
2956 * SPV Detail affix Element::
2959 @node SPV Detail numberFormat Element
2960 @subsubsection The @code{numberFormat} Element
2964 :minimumIntegerDigits=int?
2965 :maximumFractionDigits=int?
2966 :minimumFractionDigits=int?
2968 :scientific=(onlyForSmall | whenNeeded | true | false)?
2975 Specifies a format for displaying a number. The available options are
2976 a superset of those available from PSPP print formats. PSPP chooses a
2977 print format type for a @code{numberFormat} as follows:
2981 If @code{scientific} is @code{true}, uses @code{E} format.
2984 If @code{prefix} is @code{$}, uses @code{DOLLAR} format.
2987 If @code{suffix} is @code{%}, uses @code{PCT} format.
2990 If @code{useGrouping} is @code{true}, uses @code{COMMA} format.
2993 Otherwise, uses @code{F} format.
2996 For translating to a print format, PSPP uses
2997 @code{maximumFractionDigits} as the number of decimals, unless that
2998 attribute is missing or out of the range [0,15], in which case it uses
3001 @defvr {Attribute} minimumIntegerDigits
3002 Minimum number of digits to display before the decimal point. Always
3003 observed as @code{0}.
3006 @defvr {Attribute} maximumFractionDigits
3007 @defvrx {Attribute} minimumFractionDigits
3008 Maximum or minimum, respectively, number of digits to display after
3009 the decimal point. The observed values of each attribute range from 0
3013 @defvr {Attribute} useGrouping
3014 Whether to use the grouping character to group digits in large
3018 @defvr {Attribute} scientific
3019 This attribute controls when and whether the number is formatted in
3020 scientific notation. It takes the following values:
3024 Use scientific notation only when the number's magnitude is smaller
3025 than the value of the @code{small} attribute.
3028 Use scientific notation when the number will not otherwise fit in the
3032 Always use scientific notation. Not observed in the corpus.
3035 Never use scientific notation. A number that won't otherwise fit will
3036 be replaced by an error indication (see the @code{errorCharacter}
3037 attribute). Not observed in the corpus.
3041 @defvr {Attribute} small
3042 Only present when the @code{scientific} attribute is
3043 @code{onlyForSmall}, this is a numeric magnitude below which the
3044 number will be formatted in scientific notation. The values @code{0}
3045 and @code{0.0001} have been observed. The value @code{0} seems like a
3046 pathological choice, since no real number has a magnitude less than 0;
3047 perhaps in practice such a choice is equivalent to setting
3048 @code{scientific} to @code{false}.
3051 @defvr {Attribute} prefix
3052 @defvrx {Attribute} suffix
3053 Specifies a prefix or a suffix to apply to the formatted number. Only
3054 @code{suffix} has been observed, with value @samp{%}.
3057 @node SPV Detail stringFormat Element
3058 @subsubsection The @code{stringFormat} Element
3061 stringFormat => relabel* affix*
3063 relabel :from=real :to => EMPTY
3066 The @code{stringFormat} element specifies how to display a string. By
3067 default, a string is displayed verbatim, but @code{relabel} can change
3070 The @code{relabel} element appears as a child of @code{stringFormat}
3071 (and of @code{format}, when it is used to format strings). It
3072 specifies how to display a given value. It is used to implement value
3073 labels and to display the system-missing value in a human-readable
3074 way. It has the following attributes:
3076 @defvr {Attribute} from
3077 The value to map. In the corpus this is an integer or the
3078 system-missing value @code{-1.797693134862316E300}.
3081 @defvr {Attribute} to
3082 The string to display in place of the value of @code{from}. In the
3083 corpus this is a wide variety of value labels; the system-missing
3084 value is mapped to @samp{.}.
3087 @node SPV Detail dateTimeFormat Element
3088 @subsubsection The @code{dateTimeFormat} Element
3092 :baseFormat[dt_base_format]=(date | time | dateTime)
3094 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3096 :yearAbbreviation=bool?
3101 :monthFormat=(long | short | number | paddedNumber)?
3105 :showDayOfWeek=bool?
3106 :dayOfWeekAbbreviation=bool?
3108 :dayOfMonthPadding=bool?
3110 :minutePadding=bool?
3111 :secondPadding=bool?
3117 :dayType=(month | year)?
3118 :hourFormat=(AMPM | AS_24 | AS_12)?
3122 This element appears only in schema version 2.5 and earlier
3123 (@pxref{SPV Detail visualization Element}).
3125 Data to be formatted in date formats is stored as strings in legacy
3126 data, in the format @code{yyyy-mm-ddTHH:MM:SS.SSS} and must be parsed
3127 and reformatted by the reader.
3129 The following attribute is required.
3131 @defvr {Attribute} baseFormat
3132 Specifies whether a date and time are both to be displayed, or just
3136 Many of the attributes' meanings are obvious. The following seem to
3137 be worth documenting.
3139 @defvr {Attribute} separatorChars
3140 Exactly four characters. In order, these are used for: decimal point,
3141 grouping, date separator, time separator. Always @samp{.,-:}.
3144 @defvr {Attribute} mdyOrder
3145 Within a date, the order of the days, months, and years.
3146 @code{dayMonthYear} is the only observed value, but one would expect
3147 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
3151 @defvr {Attribute} showYear
3152 @defvrx {Attribute} yearAbbreviation
3153 Whether to include the year and, if so, whether the year should be
3154 shown abbreviated, that is, with only 2 digits. Each is @code{true}
3155 or @code{false}; only values of @code{true} and @code{false},
3156 respectively, have been observed.
3159 @defvr {Attribute} showMonth
3160 @defvrx {Attribute} monthFormat
3161 Whether to include the month (@code{true} or @code{false}) and, if so,
3162 how to format it. @code{monthFormat} is one of the following:
3166 The full name of the month, e.g.@: in an English locale,
3170 The abbreviated name of the month, e.g.@: in an English locale,
3174 The number representing the month, e.g.@: 9 for September.
3177 A two-digit number representing the month, e.g.@: 09 for September.
3180 Only values of @code{true} and @code{short}, respectively, have been
3184 @defvr {Attribute} dayType
3185 This attribute is always @code{month} in the corpus, specifying that
3186 the day of the month is to be displayed; a value of @code{year} is
3187 supposed to indicate that the day of the year, where 1 is January 1,
3188 is to be displayed instead.
3191 @defvr {Attribute} hourFormat
3192 @code{hourFormat}, if present, is one of:
3196 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
3200 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
3202 This is the only value observed in the corpus.
3205 The time is displayed in a 12-hour format, without distinguishing
3206 morning or evening, e.g.@: @code{10;15}.
3209 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
3210 which is confusing since a time duration does not have a concept of AM
3211 or PM. This might indicate a bug in the code that generated the XML
3212 in the corpus, or it might indicate that @code{elapsedTime} is
3213 sometimes used to format a time of day.
3216 For a @code{baseFormat} of @code{date}, PSPP chooses a print format
3217 type based on the following rules:
3221 If @code{showQuarter} is true: @code{QYR}.
3224 Otherwise, if @code{showWeek} is true: @code{WKYR}.
3227 Otherwise, if @code{mdyOrder} is @code{dayMonthYear}:
3231 If @code{monthFormat} is @code{number} or @code{paddedNumber}: @code{EDATE}.
3234 Otherwise: @code{DATE}.
3238 Otherwise, if @code{mdyOrder} is @code{yearMonthDay}: @code{SDATE}.
3241 Otherwise, @code{ADATE}.
3244 For a @code{baseFormat} of @code{dateTime}, PSPP uses @code{YMDHMS} if
3245 @code{mdyOrder} is @code{yearMonthDay} and @code{DATETIME} otherwise.
3246 For a @code{baseFormat} of @code{time}, PSPP uses @code{DTIME} if
3247 @code{showDay} is true, otherwise @code{TIME} if @code{showHour} is
3248 true, otherwise @code{MTIME}.
3250 For a @code{baseFormat} of @code{date}, the chosen width is the
3251 minimum for the format type, adding 2 if @code{yearAbbreviation} is
3252 false or omitted. For other base formats, the chosen width is the
3253 minimum for its type, plus 3 if @code{showSecond} is true, plus 4 more
3254 if @code{showMillis} is also true. Decimals are 0 by default, or 3
3255 if @code{showMillis} is true.
3257 @node SPV Detail elapsedTimeFormat Element
3258 @subsubsection The @code{elapsedTimeFormat} Element
3262 :baseFormat[dt_base_format]=(date | time | dateTime)
3265 :minutePadding=bool?
3266 :secondPadding=bool?
3276 This element specifies the way to display a time duration.
3278 Data to be formatted in elapsed time formats is stored as strings in
3279 legacy data, in the format @code{H:MM:SS.SSS}, with additional hour
3280 digits as needed for long durations, and must be parsed and
3281 reformatted by the reader.
3283 The following attribute is required.
3285 @defvr {Attribute} baseFormat
3286 Specifies whether a day and a time are both to be displayed, or just
3290 The remaining attributes specify exactly how to display the elapsed
3293 For @code{baseFormat} of @code{time}, PSPP converts this element to
3294 print format type @code{DTIME}; otherwise, if @code{showHour} is true,
3295 to @code{TIME}; otherwise, to @code{MTIME}. The chosen width is the
3296 minimum for the chosen type, adding 3 if @code{showSecond} is true,
3297 adding 4 more if @code{showMillis} is also true. Decimals are 0 by
3298 default, or 3 if @code{showMillis} is true.
3300 @node SPV Detail format Element
3301 @subsubsection The @code{format} Element
3305 :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)?
3308 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3313 :yearAbbreviation=bool?
3315 :monthFormat=(long | short | number | paddedNumber)?
3317 :dayOfMonthPadding=bool?
3321 :showDayOfWeek=bool?
3322 :dayOfWeekAbbreviation=bool?
3324 :minutePadding=bool?
3325 :secondPadding=bool?
3331 :dayType=(month | year)?
3332 :hourFormat=(AMPM | AS_24 | AS_12)?
3333 :minimumIntegerDigits=int?
3334 :maximumFractionDigits=int?
3335 :minimumFractionDigits=int?
3337 :scientific=(onlyForSmall | whenNeeded | true | false)?
3341 :tryStringsAsNumbers=bool?
3342 :negativesOutside=bool?
3346 This element is the union of all of the more-specific format elements.
3347 It is interpreted in the same way as one of those format elements,
3348 using @code{baseFormat} to determine which kind of format to use.
3350 There are a few attributes not present in the more specific formats:
3352 @defvr {Attribute} tryStringsAsNumbers
3353 When this is @code{true}, it is supposed to indicate that string
3354 values should be parsed as numbers and then displayed according to
3355 numeric formatting rules. However, in the corpus it is always
3359 @defvr {Attribute} negativesOutside
3360 If true, the negative sign should be shown before the prefix; if
3361 false, it should be shown after.
3364 @node SPV Detail affix Element
3365 @subsubsection The @code{affix} Element
3369 :definesReference=int
3370 :position=(subscript | superscript)
3376 This defines a suffix (or, theoretically, a prefix) for a formatted
3377 value. It is used to insert a reference to a footnote. It has the
3378 following attributes:
3380 @defvr {Attribute} definesReference
3381 This specifies the footnote number as a natural number: 1 for the
3382 first footnote, 2 for the second, and so on.
3385 @defvr {Attribute} position
3386 Position for the footnote label. Always @code{superscript}.
3389 @defvr {Attribute} suffix
3390 Whether the affix is a suffix (@code{true}) or a prefix
3391 (@code{false}). Always @code{true}.
3394 @defvr {Attribute} value
3395 The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
3396 for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
3397 contains other values: @code{*}, @code{**}, and a few that begin with
3398 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
3401 @node SPV Detail interval Element
3402 @subsection The @code{interval} Element
3405 interval :style=ref style => labeling footnotes?
3409 :variable=ref (sourceVariable | derivedVariable)
3410 => (formatting | format | footnotes)*
3412 formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping*
3414 formatMapping :from=int => format?
3418 :variable=ref (sourceVariable | derivedVariable)
3421 footnoteMapping :definesReference=int :from=int :to => EMPTY
3424 The @code{interval} element and its descendants determine the basic
3425 formatting and labeling for the table's cells. These basic styles are
3426 overridden by more specific styles set using @code{setCellProperties}
3427 (@pxref{SPV Detail setCellProperties Element}).
3429 The @code{style} attribute of @code{interval} itself may be ignored.
3431 The @code{labeling} element may have a single @code{formatting} child.
3432 If present, its @code{variable} attribute refers to a variable whose
3433 values are format specifiers as numbers, e.g. value 0x050802 for F8.2.
3434 However, the numbers are not actually interpreted that way. Instead,
3435 each number actually present in the variable's data is mapped by a
3436 @code{formatMapping} child of @code{formatting} to a @code{format}
3437 that specifies how to display it.
3439 The @code{labeling} element may also have a @code{footnotes} child
3440 element. The @code{variable} attribute of this element refers to a
3441 variable whose values are comma-delimited strings that list the
3442 1-based indexes of footnote references. (Cells without any footnote
3443 references are numeric 0 instead of strings.)
3445 Each @code{footnoteMapping} child of the @code{footnotes} element
3446 defines the footnote marker to be its @code{to} attribute text for the
3447 footnote whose 1-based index is given in its @code{definesReference}
3450 @node SPV Detail style Element
3451 @subsection The @code{style} Element
3458 :border-bottom=(solid | thick | thin | double | none)?
3459 :border-top=(solid | thick | thin | double | none)?
3460 :border-left=(solid | thick | thin | double | none)?
3461 :border-right=(solid | thick | thin | double | none)?
3462 :border-bottom-color?
3465 :border-right-color?
3468 :font-weight=(regular | bold)?
3469 :font-style=(regular | italic)?
3470 :font-underline=(none | underline)?
3471 :margin-bottom=dimension?
3472 :margin-left=dimension?
3473 :margin-right=dimension?
3474 :margin-top=dimension?
3475 :textAlignment=(left | right | center | decimal | mixed)?
3476 :labelLocationHorizontal=(positive | negative | center)?
3477 :labelLocationVertical=(positive | negative | center)?
3478 :decimal-offset=dimension?
3485 A @code{style} element has an effect only when it is referenced by
3486 another element to set some aspect of the table's style. Most of the
3487 attributes are self-explanatory. The rest are described below.
3489 @defvr {Attribute} {color}
3490 In some cases, the text color; in others, the background color.
3493 @defvr {Attribute} {color2}
3497 @defvr {Attribute} {labelAngle}
3498 Normally 0. The value -90 causes inner column or outer row labels to
3499 be rotated vertically.
3502 @defvr {Attribute} {labelLocationHorizontal}
3506 @defvr {Attribute} {labelLocationVertical}
3507 The value @code{positive} corresponds to vertically aligning text to
3508 the top of a cell, @code{negative} to the bottom, @code{center} to the
3512 @node SPV Detail labelFrame Element
3513 @subsection The @code{labelFrame} Element
3516 labelFrame :style=ref style => location+ label? paragraph?
3518 paragraph :hangingIndent=dimension? => EMPTY
3521 A @code{labelFrame} element specifies content and style for some
3522 aspect of a table. Only @code{labelFrame} elements that have a
3523 @code{label} child are important. The @code{purpose} attribute in the
3524 @code{label} determines what the @code{labelFrame} affects:
3528 The table's title and its style.
3531 The table's caption and its style.
3534 The table's footnotes and the style for the footer area.
3537 The style for the layer area.
3543 The @code{style} attribute references the style to use for the area.
3545 The @code{label}, if present, specifies the text to put into the title
3546 or caption or footnotes. For footnotes, the label has two @code{text}
3547 children for every footnote, each of which has a @code{usesReference}
3548 attribute identifying the 1-based index of a footnote. The first,
3549 third, fifth, @dots{} @code{text} child specifies the content for a
3550 footnote; the second, fourth, sixth, @dots{} child specifies the
3551 marker. Content tends to end in a new-line, which the reader may wish
3552 to trim; similarly, markers tend to end in @samp{.}.
3554 The @code{paragraph}, if present, may be ignored, since it is always
3557 @node SPV Detail Legacy Properties
3558 @subsection Legacy Properties
3560 The detail XML format has features for styling most of the aspects of
3561 a table. It also inherits defaults for many aspects from structure
3562 XML, which has the following @code{tableProperties} element:
3566 => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties
3569 :hideEmptyRows=bool?
3570 :maximumColumnWidth=dimension?
3571 :maximumRowWidth=dimension?
3572 :minimumColumnWidth=dimension?
3573 :minimumRowWidth=dimension?
3574 :rowDimensionLabels=(inCorner | nested)?
3578 :markerPosition=(superscript | subscript)?
3579 :numberFormat=(alphabetic | numeric)?
3582 cellFormatProperties => cell_style+
3585 :alternatingColor=color?
3586 :alternatingTextColor=color?
3594 :font-style=(regular | italic)?
3595 :font-weight=(regular | bold)?
3596 :labelLocationVertical=(positive | negative | center)?
3597 :margin-bottom=dimension?
3598 :margin-left=dimension?
3599 :margin-right=dimension?
3600 :margin-top=dimension?
3601 :textAlignment=(left | right | center | decimal | mixed)?
3602 :decimal-offset=dimension?
3605 borderProperties => border_style+
3608 :borderStyleType=(none | solid | dashed | thick | thin | double)?
3613 :printAllLayers=bool?
3614 :rescaleLongTableToFitPage=bool?
3615 :rescaleWideTableToFitPage=bool?
3616 :windowOrphanLines=int?
3618 :continuationTextAtBottom=bool?
3619 :continuationTextAtTop=bool?
3620 :printEachLayerOnSeparatePage=bool?