Publication Table¶
A Publication Table describes a table for disseminating data: the dataflows it reads from, the header rows, and the
body rows whose cells are observation keys or calculations. It can also hold variables, observation formatting,
missing value rules and footnotes. Publication Tables are a Fusion extension to SDMX, provided by the
fusion-sdmx-publicationtable module. Documents start ref: "PublicationTable=AGENCY:ID(1.0)".
Simple form¶
The document starts with the common header, followed by the dataflows, the header rows and the body rows.
format: "fusion-yaml(1.0.0)"
ref: "PublicationTable=TEST:TEST(1.0.0)"
name: "Test PT"
dataflows:
- dataflow: "TEST:BANKING(1.0)"
header:
- row:
- cell: "Employed"
- cell: "UnEmployed"
body:
- row:
- "2010"
- "A:UK:EMP:2010"
- "A:UK:UEMP:2010"
- row:
- "2011"
- "A:UK:EMP:2011"
- "A:UK:UEMP:2011"
dataflows: an array with one object for each dataflow the table reads from.dataflowis the short URN of the Dataflow (AGENCY:ID(VERSION)); the field name gives the class.header: an array of header rows. Each row is an object with arowarray of cells, and each cell is an object with its label incell.body: an array of body rows. Each row is an object with arowholding strings: the first string is the label of the row's head cell, and the rest are the cells' observation keys (or calculations such as":=[A:UK:EMP]+10").rowfollows the value or array rule, so a row with only a head cell label is written as a string, e.g.- row: "UK Data".
Labels and keys can contain variables such as $(P) or $(REF_AREA); these are plain strings in the canonical
format.
Complete example¶
The example below shows every optional field. It is assembled from the golden files
testVariableDimensionsMultipleFlows, testFootnotesAndTimeFormat, testMissingValueRepMap,
testObservationFormatting, testExternalVariables, testConditionalVariables and testVariableMappings, with long
lists trimmed.
format: "fusion-yaml(1.0.0)"
ref: "PublicationTable=TEST:TEST(1.0.0)"
name: "Test PT"
dataflows:
- alias: "DF1"
dataflow: "TEST:BANKING1(1.0)"
- alias: "DF2"
dataflow: "TEST:BANKING2(1.0)"
timeFormat: "RepresentationMap=TEST:TIME_FORMAT(1.0)"
missingValues:
component: "OBS_STATUS"
default: "-"
representationmap: "TEST:MV_MAP(1.0)"
obsFormat:
- keys:
- "=A:UK+FR:EMP"
- "=A:+UEMP"
decimals: 2
round: "HALF_UP"
scientificNotation: true
- locale: "en"
significantFigures: 1
round: "DOWN"
normalise: true
- scalingFactor: 2
variables:
VAR_CL: "Codelist=TEST:CL_VAR(1.0)"
VAR_VL: "ValueList=TEST:VL_VAR(1.0)"
conditionalVariables:
- id: "BANKNOTE"
name: "Banknotes"
dimension: "REF_AREA"
values:
NOTE1:
UK: "£5"
FR: "5Eur"
US: "$5"
variableMappings:
- input: "REF_AREA"
output: "INDICATOR"
representationmap: "TEST:VAR_DIM_REPMAP(1.0)"
header:
- row:
- cell: "$(REF_AREA)"
colSpan: 2
- row:
- cell: "$(P)"
- cell: "$(P-1)"
body:
- row:
- "$(INDICATOR)"
- "DF1.A::"
- "DF2.A:::P-1"
footnotes:
- text: "Data are incomplete"
- text: "Provisional figures"
Simple values become richer in these cases:
- Dataflows.
aliasis written beforedataflowonly when the dataflow has a non-empty alias. Aliases are used when the table reads more than one dataflow, and prefix the observation keys (DF1.A::). - Header cells. A cell is
{cell: "label"}.rowSpanandcolSpanare added only when greater than 1. - Observation formatting. Each
obsFormatentry applies to the observations matching itskeys(a value or array).localeis a language code, or"dynamic"to use the viewer's locale. Precision is written as eitherdecimalsorsignificantFigures, andround(a JavaRoundingModename) is written only with a precision.normaliseandscientificNotationare written only when true.scalingFactoris a number. - Variable mapping output.
outputis a value or array of dimension ids. - Footnotes. Each footnote is an object of localised text:
textfor English,text-<locale>for other languages.
The references in this artifact use two styles (see references):
- Where the field name is the lower-case class of the target, the value is a short URN:
dataflows[].dataflow(dataflow: "TEST:BANKING(1.0)") and the mapping inmissingValuesandvariableMappings(representationmap: "TEST:MV_MAP(1.0)"). - Where the field name does not determine the type, the value is a canonical value with the class:
timeFormat(RepresentationMap=...) and the values ofvariables(Codelist=.../ValueList=...; a variable can reference either a Codelist or a Value List).
Field reference¶
Body fields, in written order:
| Field | Value | Written when |
|---|---|---|
dataflows |
Array of dataflow objects | The table has dataflows |
timeFormat |
Canonical value of a Representation Map | A time format mapping is set |
missingValues |
Object (below) | Missing value rules are set |
obsFormat |
Array of formatting objects | There are observation formatting rules |
variables |
Map of variable id to canonical value of a Codelist or Value List | There are variables |
conditionalVariables |
Array of conditional variable objects | There are conditional variables |
variableMappings |
Array of variable mapping objects | There are variable mappings |
header |
Array of {row: [cells]} |
There are header rows |
body |
Array of {row: string or [strings]} |
There are body rows |
footnotes |
Array of localised text objects | There are footnotes |
Nested objects, in written order:
| Field | Value | Written when |
|---|---|---|
dataflows[].alias |
String | The alias is not empty |
dataflows[].dataflow |
Short URN of the Dataflow | Always |
missingValues.component |
Component id | Set |
missingValues.default |
String | Set |
missingValues.representationmap |
Short URN | A mapping is set |
obsFormat[].keys |
Value or array of key patterns | Set |
obsFormat[].locale |
Language code, or "dynamic" |
Set |
obsFormat[].decimals |
Number | A precision is set, as decimal places |
obsFormat[].significantFigures |
Number | A precision is set, as significant figures |
obsFormat[].round |
Rounding mode name, e.g. "HALF_UP" |
A precision and a rounding mode are set |
obsFormat[].normalise |
true |
Normalise is on |
obsFormat[].scientificNotation |
true |
Scientific notation is on |
obsFormat[].scalingFactor |
Number | Set |
conditionalVariables[].id |
String | Always |
conditionalVariables[].name |
String (not localised) | Set |
conditionalVariables[].alias |
Dataflow alias | The alias is not empty |
conditionalVariables[].dimension |
Dimension id the condition is on | Always |
conditionalVariables[].values |
Map of mapped id to a map of dimension value to output | There are values |
variableMappings[].input |
Dimension id | Always |
variableMappings[].output |
Value or array of dimension ids | Set |
variableMappings[].representationmap |
Short URN | A mapping is set |
header[].row[].cell |
Label | Set |
header[].row[].rowSpan |
Number | Greater than 1 |
header[].row[].colSpan |
Number | Greater than 1 |
body[].row |
Value or array: head cell label, then observation keys | Always |
footnotes[].text, footnotes[].text-<locale> |
Localised text | Always |
Reading notes¶
-
Writing needs nothing; reading needs the module. A Publication Table writes itself like any other structure. Reading is different:
CanonicalFormatReaderfinds the reader for thePublicationTableclass through theICanonicalReaderFactoryinstances registered inFusionBeanStore, and the Publication Table factory is registered by the module. CallPublicationTableModule.register()before reading, otherwise the read fails with "there is no reader for structure type". -
When
aliasis absent, the dataflow alias is set to an empty string. - Header cells without
rowSpanorcolSpanget a span of 1. - A body row is split back into its head cell (first string, with spans of 1) and its body cells (remaining strings).