From: Ben Pfaff Date: Mon, 22 Feb 2016 06:33:56 +0000 (-0800) Subject: Document faceting and work on facetLayout. X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?p=pspp;a=commitdiff_plain;h=5763c3751c67a228c6ab3e33934c66247551af52 Document faceting and work on facetLayout. --- diff --git a/spv-file-format.texi b/spv-file-format.texi index 6c6878b274..dd4b0b8f5a 100644 --- a/spv-file-format.texi +++ b/spv-file-format.texi @@ -1266,6 +1266,7 @@ elements are assigned @code{id} attributes that are never referenced. * SPV Detail graph Element:: * SPV Detail location Element:: * SPV Detail coordinates Element:: +* SPV Detail faceting Element:: @end menu @node SPV Detail visualization Element @@ -1599,5 +1600,204 @@ This element is always present and always empty, with no attributes @subsection The @code{faceting} Element Parent: @code{graph} @* -Contents: @code{cross} @code{layer}@math{+} +Contents: @code{cross} @code{layer}* +The @code{faceting} element describes the row, column, and layer +structure of the table. Its @code{cross} child determines the row and +column structure, and each @code{layer} child (if any) represents a +layer. + +@code{faceting} has no attributes (other than @code{id}). + +@subsubheading The @code{cross} Element + +Parent: @code{faceting} @* +Contents: @code{nest} @code{nest} + +The @code{cross} element describes the row and column structure of the +table. It has exactly two @code{nest} children, the first of which +describes the table's rows and the second the table's columns. + +@code{cross} has no attributes (other than @code{id}). + +@subsubheading The @code{nest} Element + +Parent: @code{cross} @* +Contents: @code{variableReference}@math{+} + +A given @code{nest} usually consists of one or more dimensions, each +of which is represented by @code{variableReference} child elements. +Minimally, a dimension has two @code{variableReference} children, one +for the categories, one for the data, e.g.: + +@example + + + + +@end example + +@noindent +Groups of categories introduce additional variable references, e.g.@: + +@example + + + + + +@end example + +@noindent +Grouping can be hierarchical, e.g.@: + +@example + + + + + + +@end example + +@noindent +XXX what are group maps? + +@example + + + + + + + + + + + +@end example + +@noindent +A @code{nest} can contain multiple dimensions: + +@example + + + + + + + +@end example + +One @code{nest} within a given @code{cross} may have no dimensions, in +which case it still has one @code{variableReference} child, which +references a @code{derivedVariable} whose @code{value} attribute is +@code{constant(0)}. In the corpus, such a @code{derivedVariable} has +@code{row} or @code{column}, respectively, as its @code{id}. + +@code{nest} has no attributes (other than @code{id}). + +@subsubheading The @code{variableReference} Element + +Parent: @code{nest} @* +Contents: empty + +@code{variableReference} has one attribute. + +@defvr {Required} ref +The @code{id} of a @code{sourceVariable} or @code{derivedVariable} +element. +@end defvr + +@subsubheading The @code{layer} Element + +Parent: @code{faceting} @* +Contents: empty + +Each layer is represented by a pair of @code{layer} elements. The +first of this pair is for a category variable, the second for the data +variable, e.g.: + +@example + + +@end example + +@noindent +@code{layer} has the following attributes. + +@defvr {Required} variable +The @code{id} of a @code{sourceVariable} or @code{derivedVariable} +element. +@end defvr + +@defvr {Required} value +The value to select. For a category variable, this is always +@code{0}; for a data variable, it is the same as the @code{variable} +attribute. +@end defvr + +@defvr {Optional} visible +Whether the layer is visible. Generally, category layers are visible +and data layers are not, but sometimes this attribute is omitted. +@end defvr + +@defvr {Optional} method +When present, this is always @code{nest}. +@end defvr + +@node SPV Detail facetLayout Element +@subsection The @code{facetLayout} Element + +Parent: @code{graph} @* +Contents: @code{tableLayout} @code{facetLevel}@math{+} @code{setCellProperties}* +@subsubheading The @code{tableLayout} Element + +Parent: @code{facetLayout} @* +Contents: empty + +@defvr {Required} verticalTitlesInCorner +Always set to @code{true}. +@end defvr + +@defvr {Optional} style +The @code{id} of a @code{style} element. +@end defvr + +@defvr {Optional} fitCells +Always set to @code{ticks}. +@end defvr + +@subsubheading The @code{facetLevel} Element + +Parent: @code{facetLayout} +Contents: @code{axis} + +Each @code{facetLevel} describes a @code{variableReference} or +@code{layer}, and thus a table has one @code{facetLevel} element for +each such element. For example, an SPV detail member that contains +four @code{variableReference} elements and two @code{layer} elements +will contain six @code{facetLevel} elements. + +In the corpus, @code{facetLevel} elements and the elements that they +describe are always in the same order. The correspondence may also be +observed in two other ways. First, one may use the @code{level} +attribute, described below. Second, in the corpus, a +@code{facetLevel} always has an @code{id} that is the same as the +@code{id} of the element it describes with @code{_facetLevel} +appended. One should not formally rely on this, of course, but it is +usefully indicative. + +@defvr {Required} level +A 1-based index into the @code{variableReference} and @code{layer} +elements, e.g.@: a @code{facetLayout} with a @code{level} of 1 +describes the first @code{variableReference} in the SPV detail member, +and in a member with four @code{variableReference} elements, a +@code{facetLayout} with a @code{level} of 5 describes the first +@code{layer} in the member. +@end defvr + +@defvr {Required} gap +Always observed as @code{0pt}. +@end defvr