-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy path08_chapter08_indicators.Rmd
1524 lines (1278 loc) · 83.5 KB
/
08_chapter08_indicators.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
output: html_document
---
# Indicators and time series {#chapter08}
<center>
{width=25%}
</center>
## Indicators, time series, database, and scope of the schema
**Indicators** are summary measures related to key issues or phenomena, derived from observed facts. Indicators form **time series** when they are provided with a temporal ordering, i.e. when their values are provided with an ordered annual, quarterly, monthly, daily, or other time reference. Time series are usually published with equal intervals between values. In the context of this Guide, we however consider as time series all indicators provided for a given geographic area with an associated time reference, whether this time represents a regular, continuous succession of time stamps or not. For example, the indicators provided by the Demographic and Health Surveys (DHS) [StatCompiler](https://www.statcompiler.com/en/), which are only available for the years when DHS are conducted in countries (which for some countries can be a single year), would be considered here as "time series".
Time series are often contained in multi-indicators databases, like the World Bank's [World Development Indicators - WDI](https://datatopics.worldbank.org/world-development-indicators/), whose on-line version contains series for 1,430 indicators (as of 2021). To document not only the series but also the databases they belong to, we propose two metadata schemas: one to document the series/indicators, the other one to document the databases they belong to.
In the NADA application, a series can be documented and published without an associated database, but information on a database will only be published in association with a series. The information on a database is thus treated as an "attachment" to the information on a series. A **SERIES DESCRIPTION** tab will display all metadata related to the series, i.e. all content entered in the *series schema*.
----------
<center>
{width=100%}
</center>
----------
The (optional) **SOURCE DATABASE** tab will display the metadata related to the database, i.e. all content entered in the *series database schema*. This information is displayed for information, but not indexed in the NADA catalog (i.e. not searchable).
----------
<center>
{width=100%}
</center>
----------
:::idea
**Suggestions and recommendations to data curators**
- Indicators and time series often come with metadata limited to the indicators/series name and a brief definition. This significantly reduces the discoverability of the indicators, and the possibility to implement semantic searchability and recommender systems. It is therefore highly recommended to generate more detailed metadata for each time series, including information on the purpose and typical use of the indicators, of its relevancy to different audiences, of its limitations, and more.
- When documenting an indicator or time series, attention should be paid to include keywords and phrases in the metadata that reflect how data users are likely to formulate their queries when searching data catalogs. Subject-matter expertise, combined with an analysis of queries submitted to data catalogs, can help to identify such keywords. For example, the metadata related to an indicator "Prevalence of stunting" should contain the keyword "malnutrition", and the metadata related to "GDP per capita" should include keywords like "economic growth" or "national income". By doing so, data curators will provide richer input to search engines and recommender systems, and will have a significant and direct impact on the discoverability of the data. The use of AI tools can considerabli facilitate the process of identifying related keywords. We provide in the chapter an example of use of chatGPT for such purpose.
:::
## Schema description
An indicator or time series is documented using the **time series /indicators** schema. The **database** schema is optional, and used to document the database, if any, that the indicator belongs to. When multiple series of a same database are documented, the metadata related to the database only needs to be generated once, then applied to all series. One metadata element in the **time series /indicators** schema is used to link an indicator to the corresponding database.
### The time series (indicators) schema
The time series schema is used to document an indicator or a time series. In NADA, the data and metadata of an indicator can (but does not have to) be published with information on the database it belongs to (if any). A metadata element is provided to indicate the identifier of that database (if any), and to establish the link between the indicator metadata and the database metadata generated using the schema described above.
<br>
```json
{
"repositoryid": "string",
"access_policy": "na",
"data_remote_url": "string",
"published": 0,
"overwrite": "no",
"metadata_information": {},
"series_description": {},
"provenance": [],
"tags": [],
"lda_topics": [],
"embeddings": [],
"additional": { }
}
```
<br>
#### Cataloguing parameters
The first elements of the schema (`repositoryid`, `access_policy`, `data_remote_url`, `published`, and `overwrite`) are not part of the series metadata. They are parameters used to indicate how the series will be published in a NADA catalog.
**`repositoryid`** identifies the collection in which the metadata will be published. By default, the metadata will be published in the central catalog. To publish them in a collection, the collection must have been previously created in NADA.
**`access_policy`** indicates the access policy to be applied to the data: direct access, open access, public use files, licensed access, data accessible from an external repository, and data not accessible. A controlled vocabulary is provided and must be used, with the following respective options: {`direct; open; public; licensed; remote; data_na`}.
**`data_remote_url`** provides the link to an external website where the data can be obtained, if the `access_policy` has been set to `remote`.
**`published`**: Indicates whether the metadata must be made visible to visitors of the catalog. By default, the value is 0 (unpublished). This value must be set to 1 (published) to make the metadata visible.
**`overwrite`**: Indicates whether metadata that may have been previously uploaded for the same series can be overwritten. By default, the value is "no". It must be set to "yes" to overwrite existing information. Note that a series will be considered as being the same as a previously uploaded one if the identifier provided in the metadata element `series_description > idno` is the same.
#### Metadata information
**`metadata_information`** *[Optional, Not Repeatable]* <br>
The set of elements in `metadata_information` is used to provide information on the production of the indicator metadata. This information is used mostly for administrative purposes by data curators and catalog administrators.
<br>
```json
"metadata_information": {
"title": "string",
"idno": "string",
"producers": [
{
"name": "string",
"abbr": "string",
"affiliation": "string",
"role": "string"
}
],
"prod_date": "string",
"version": "string"
}
```
<br>
- **`title`** *[Optional ; Not repeatable ; String]* <br>
The title of the metadata document containing the indicator metadata.<br>
- **`idno`** *[Required ; Not repeatable ; String]* <br>
A unique identifier of the indicator metadata document. It can be for example the identifier of the indicator preceded by a prefix identifying the metadata producer.<br>
- **`producers`** *[Optional ; Repeatable]* <br>
This is a list of producers involved in the documentation (production of the metadata) of the series.
- **`name`** *[Optional ; Not repeatable, String]* <br>
The name of the agency that is responsible for the documentation of the series.
- **`abbr`** *[Optional ; Not repeatable, String]* <br>
Abbreviation (acronym) of the agency mentioned in `name`.
- **`affiliation`** *[Optional ; Not repeatable, String]* <br>
Affiliation of the agency mentioned in `name`.
- **`role`** *[Optional ; Not repeatable, String]* <br>
The specific role of the agency mentioned in `name` in the production of the metadata. This element will be used when more than one person or organization is listed in the `producers` element to distinguish the specific contribution of each metadata producer.<br><br>
- **`prod_date`** *[Optional ; Not repeatable, String]* <br>
The date the metadata was generated. The date should be entered in ISO 8601 format (YYYY-MM-DD or YYYY-MM or YYYY).
- **`version`** *[Optional ; Not repeatable, String]* <br>
The version of the metadata on this series. This element will rarely be used.
```{r, indent=" ", eval=F, echo=T}
metadata_creation = list(
producers = list(list(name = "Development Data Group",
abbr = "DECDG",
affiliation = "World Bank")),
prod_date = "2021-10-15"
)
```
#### Series description
**`series_description`** *[Required ; Repeatable]* <br>
This section contains all elements used to describe a specific series or indicator.
<br>
```json
"series_description": {
"idno": "string",
"doi": "string",
"name": "string",
"database_id": "string",
"aliases": [],
"alternate_identifiers": [],
"languages": [],
"measurement_unit": "string",
"dimensions": [],
"periodicity": "string",
"base_period": "string",
"definition_short": "string",
"definition_long": "string",
"definition_references": [],
"statistical_concept": "string",
"concepts": [],
"methodology": "string",
"derivation": "string",
"imputation": "string",
"missing": "string",
"quality_checks": "string",
"quality_note": "string",
"sources_discrepancies": "string",
"series_break": "string",
"limitation": "string",
"themes": [],
"topics": [],
"disciplines": [],
"relevance": "string",
"time_periods": [],
"ref_country": [],
"geographic_units": [],
"bbox": [],
"aggregation_method": "string",
"disaggregation": "string",
"license": [],
"confidentiality": "string",
"confidentiality_status": "string",
"confidentiality_note": "string",
"links": [],
"api_documentation": [],
"authoring_entity": [],
"sources": [],
"sources_note": "string",
"keywords": [],
"acronyms": [],
"errata": [],
"notes": [],
"related_indicators": [],
"compliance": [],
"framework": [],
"series_groups": []
}
```
<br>
- **`idno`** *[Required ; Not repeatable ; String]* <br>
A unique identifier (ID) for the series. Most agencies and databases will have a coherent coding convention to generate their series IDs. For example, the name of the series in the World Bank's World Development Indicators series are composed of the following elements, separated by a dot:
- Topic code (2 digits).
- General subject code (3 digits)
- Specific subject code (4 digits)
- Extensions (2 digits each) <br>
For example, the series with identifier "DT.DIS.PRVT.CD" is the series containing data on "External debt disbursements by private creditors in current US dollars" (for more information, see [*How does the World Bank code its indicators?*]( https://datahelpdesk.worldbank.org/knowledgebase/articles/201175-how-does-the-world-bank-code-its-indicators).<br>
- **`doi`** *[Optional ; Not repeatable ; String]* <br>
A Digital Object Identifier (DOI) for the the series.
- **`name`** *[Required ; Not repeatable ; String]* <br>
The name (label) of the series. Note that a field `alias` is provided (see below) to capture alternative names for the series.
- **`database_id`** *[Optional ; Not repeatable ; String]* <br>
The unique identifier of the database the series belongs to. This field must correspond to the element `database_description > title_statement > idno` of the database schema described above. This is the only field that is needed to establish the link between the database metadata and the indicator metadata.
- **`aliases`** *[Optional ; Repeatable]* <br>
A series or an indicator can be referred to using different names. The `aliases` element is provided to capture the multiple names and labels that may be associated with (i.e synomyms of) the documented series or indicator.
<br>
```json
"aliases": [
{
"alias": "string"
}
]
```
<br>
- **`alias`** *[Optional ; Not repeatable ; String]* <br>
An alternative name for the indicator or series being documented. <br><br>
- **`alternate_identifiers`** *[Optional ; Not repeatable ; String]*<br>
The element `idno` described above is the reference unique identifier for the catalog in which the metadata is intended to be published. But the same indicator/metadata may be published in other catalogs. For example, a data catalog may publish metadata for series extracted from the World Bank World Development Indicators (WDI) database. And the WDI itself contains series generated and published by other organizations, such as the World Health Organization or UNICEF. Catalog administrators may want to assign a unique identifier specific to their catalog (the `idno` element), but keep track of the identifier of the series or indicator in other catalogs or databases. The `alternate_identifiers` element serves that purpose.
<br>
```json
"alternate_identifiers": [
{
"identifier": "string",
"name": "string",
"database": "string",
"uri": "string",
"notes": "string"
}
]
```
<br>
- **`identifier`** *[Required ; Not repeatable ; String]* <br>
An identifier for the series other than the identifier entered in `idno` (note that the identifier entered in `idno` can be included in this list, if it is useful to provide it with a type identifier (see `name` element below) which is not provided in `idno`. This can be the identifier of the indicator in another database/catalog, or a global unique identifier.
- **`name`** <br>
This element will be used to define the type of identifier. This will typically be used to flag DOIs by entering "Digital Object Identifier (DOI)".
- **`database`** <br>
The name of the database (or catalog) where this alternative identifier is used, e.g. "IMF, International Financial Statistics (IFS)".<br>
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
A link (URL) to the database mentioned in `database`. <br>
- **`notes`** *[Optional ; Not repeatable ; String]* <br>
Any additional information on the alternate identifier. <br><br>
- **`languages`** *[Optional ; Repeatable]* <br>
An indicator or time series can be made available at different levels of disaggregation. For example, an indicator containing estimates of the "Population" of a country by year can be available by sex. The data curators in such case will have two options: (i) create and document three separate indicators, namely "Population, Total", "Population, Female", and "Population, Male"; or create a single indicator "Population" and attach a *dimension* "sex" to it, with values "Total", "Female", and "Male". The `dimensions` are features (or "variables") that define the different levels of disaggregation within an indicator/series. The element `dimensions` is used to provide an itemized list of disaggregations that correspond exactly to the published data. Note that when an indicator is available at two "non-overlapping" levels of disaggregation, it should be split into two indicators. For example, if the Population indicator is available by male/female and by urban/rural, but not by male/urban/male/rural/female urban/female rural, it should be treated as two separate indicators ("Population by sex" with dimension sex = "male / female" and "Population by area of residence" with dimension area = "urban / rural".) Note also that another element in the schema, `disaggregation`, is also provided, in which a narrative description of the actual or recommended disaggregations can be documented.<br>
<br>
```json
"alternate_identifiers": [
{
"identifier": "string",
"name": "string",
"database": "string",
"uri": "string",
"notes": "string"
}
]
```
<br>
- **`name`** *[Required ; Not repeatable ; String]* <br>
The name of the language.
- **`code`** *[Optional ; Not repeatable ; String]* <br>
The code of the language, preferably the ISO code.<br><br>
- **`measurement_unit`** *[Optional ; Not repeatable ; String]* <br>
The unit of measurement. Note that in many databases the measurement unit will be included in the series name/label. In the World Bank's World Development Indicators for example, series are named as follows:
- CO2 emissions (kg per 2010 US$ of GDP)
- GDP per capita (current US$)
- GDP per capita (current LCU)
- Population density (people per sq. km of land area)
In such case, the name of the series should not be changed, but the measurement unit may be extracted from it and stored in element `measurement_unit`. <br>
- **`dimensions`** *[Optional ; Repeatable]* <br>
An indicator or time series can be made available at different levels of disaggregation. For example, a time series containing annual estimates of the indicator "Resident population (mid-year)" can be provided by country, by urban/rural area of residence, by sex, by age group. The data curator has to make a decision on how to organize such data. One option is to create an indicator "Resident population (mid-year)" and to define a set of "dimensions" for the breakdowns. The dimensions would in such case be the year, the country, the area of residence, the sex, and the age group. Some of the dimensions would have to be provided with a code list (or 'controlled vocabulary", for example stating that F means "Female", M" means male, and T means "Total" for the dimension *sex*). Another option would be to create multiple indicators (e.g., creating three distinct indicators "Resident population, male (mid-year)", "Resident population, female (mid-year)", "Resident population, total (mid-year)" and using year, country, area of residence, and age group as dimensions). The element `dimensions` is used to provide an itemized list of disaggregations that correspond to the published data. Note that another element in the schema, `disaggregation`, is also provided, in which a narrative description of the actual or recommended disaggregations can be documented. Note also that in the SDMX standard, dimensions are listed in the *Data Structure Definition" and are complemented by *code lists* that provide the related controlled vocabularies.<br>
<br>
```json
"dimensions": [
{
"name": "string",
"label": "string",
"description": "string"
}
]
```
<br>
- **`name`** *[Required ; Not repeatable ; String]* <br>
The name of the dimension.
- **`label`** *[Required ; Not repeatable ; String]* <br>
The label of the dimension, for example "sex", or "urban/rural".
- **`description`** *[Optional ; Not repeatable ; String]* <br>
A description of the dimension (for example, if the label was "age group", the description can provide detailed information on the age groups, e.g. "The age groups in the database are 0-14, 15-49, 50-64, and 65+ years old".)<br><br>
- **`release_calendar`** *[Optional ; Not repeatable ; String]* <br>
Information on when updates for the indicators can be expected. This will usually not consist of exact dates (which would have to be updated regularly), but of more general information like "Every first Monday of the Month", or "Every year on June 30", or "The last week of each quarter".
- **`periodicity`** *[Optional ; Not repeatable ; String]* <br>
The periodicity of the series. It is recommended to use a controlled vocabulary with values like *annual*, *quarterly*, *monthly*, *daily*, etc.
- **`base_period`** *[Optional ; Not repeatable ; String]* <br>
The base period for the series. This field will only apply to series that require a base year (or other reference time) used as a benchmark, like a Consumer Price Index (CPI) which will have a value of 100 for a reference base year.
- **`definition_short`** *[Optional ; Not repeatable ; String]* <br>
A short definition of the series. The short definition captures the essence of the series.<br>
- **`definition_long`** *[Optional ; Not repeatable ; String]* <br>
A long(er) version of the definition of the series. If only one definition is available (not a short/long version), it is recommended to capture it in the `definition_short` element. ALternatively, the same definition can be stored in both `definition_short` and `definition_long`.
- **`definition_references`** *[Optional ; Repeatable]* <br>
This element is provided to link to an external resources from which the definition was extracted.
<br>
```json
"definition_references": [
{
"source": "string",
"uri": "string",
"note": "string"
}
]
```
<br>
- **`source`** *[Optional ; Not repeatable ; String]* <br>
The source of the definition (title, or label).
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
A link (URL) to the source of the definition.
- **`note`** *[Optional ; Not repeatable ; String]* <br>
This element provides for annotating or explaining the reason the reference has been included as part of the metadata.<br><br>
- **`statistical_concept`** *[Optional ; Not repeatable ; String]* <br>
This element allows to insert a reference of the series with content of a statistical character. This can include coding concepts or standards that are applied to render the data statistically relevant.
- **`concepts`** *[Optional ; Repeatable]* <br>
This repeatable element can be used to document concepts related to the indicators or time series (other than the main statistical concept that may have been entered in `statisticsl_concept`). For example, the concept of *malnutrition* could be documented in relation to the indicators "Prevalence of stunting" and "Prevalence of wasting".
<br>
```json
"concepts": [
{
"name": "string",
"definition": "string",
"uri": "string"
}
]
```
<br>
- **`name`** *[Required ; Not repeatable ; String]* <br>
A concise and standardized name (label) for the concept.
- **`definition`** *[Required ; Not repeatable ; String]* <br>
The definition of the concept.
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
A link (URL) to a resource providing more detailed information on the concept. <br><br>
- **`data_collection`** *[Optional ; Not repeatable]* <br>
This group of elements can be used to document data collection activities that led to or allowed the production of the indicator. This element will typically be used for the description of surveys or censuses.
Note: the schema also contains an element "sources". That element will be used to document the organization and/or main data production program from which the indicator is derived.
<br>
```json
"data_collection": [
{
"data_source": "string",
"method": "string",
"period": "string",
"note": "string"
"uri": "string"
}
]
```
<br>
- **`data_source`** *[Required ; Not repeatable ; String]* <br>
A concise and standardized name (label) for the data source, e.g. "National Labor Force Survey, 1st quarter 2022". If multiple data sources were used, they can all be listed here. Note that is a time series has values obtained from many different sources, the source for each value (or group of values) will not be part of the indicator/series metadata, but will be stored as an attribute in the data file where the information can be associated with a specific observation ("cell note" or group of observation (e.g. attached to an indicator for avv values for a same year or for a same area).
- **`method`** *[Required ; Not repeatable ; String]* <br>
Brief information on the data collection method, e.g. :Sample household survey".
- **`period`** *[Optional ; Not repeatable ; String]* <br>
Information on the period of the data collection, e.g. "January to March 2022". <br>
- **`note`** *[Optional ; Not repeatable ; String]* <br>
Additional information on the data collection.
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
A link to a resource (website, document) where more information on the data collection can be found.
- **`imputation`** *[Optional ; Not repeatable ; String]* <br>
Data may have been imputed to account for data gaps or for other reasons (harmonization/standardization, and others). If imputations have been made, this element provides the space for their description.
- **`adjustments`** *[Optional ; Repeatable ; String]* <br>
Description of any adjustments with respect to use of standard classifications and harmonization of breakdowns for age group and other dimensions, or adjustments made for compliance with specific international or national definitions.
- **`missing`** *[Optional ; Not repeatable ; String]*<br>
Information on missing values in the series or indicator. This information can be related to treatment of missing values, to the cause(s) of missing values, and others.
- **`validation_rules`** *[Optional ; Repeatable ; String]*<br>
Description of the set of rules (itemized) used to validate values for the indicator, e.g. "Is within range 0-100", or "Is the sum of indicatorX + indicator Y".
- **`quality_checks`** *[Optional ; Not repeatable ; String]* <br>
Data may have gone through data quality checks to assure that the values are reasonable and coherent, which can be described in this element. These quality checks may include checking for outlying values or other. A brief description of such quality control procedures will contribute to reinforcing the credibility of the data being disseminated.
- **`quality_note`** *[Optional ; Not repeatable ; String]* <br>
Additional notes or an overall statement on data quality. These could for example cover non-standard quality notes and/or information on independent reviews on the data quality.
- **`sources_discrepancies`** *[Optional ; Not repeatable ; String]*<br>
This element is used to describe and explain why the data in the series may be different from the data for the same series published in other sources. International organizations, for example, may apply different techniques to make data obtained from national sources comparable across countries, in which cases the data published in international databases may differ from the data published in national, official databases.
- **`series_break`** *[Optional ; Not repeatable ; String]* <br>
Breaks in statistical series occur when there is a change in the standards, sources of data, or reference year used in the compilation of a series. Breaks in series must be well documented. The documentation should include the reason(s) for the break, the time it occured, and information on the impact on comparability of data over time.
- **`limitation`** *[Optional ; Not repeatable ; String]* <br>
This element is used to communicate to the user any limitations or exceptions in using the data. The limitations may result from the methodology, from issues of quality or consistency in the data source, or other.
- **`themes`** *[Optional ; Repeatable]* <br>
Themes provide a general idea of the research that might guide the creation and/or demand for the series. A theme is broad and is likely also subject to a community based definition or list. A controlled vocabulary should be used. This element will rarely be used (the element `topics` described below will be used more often).
<br>
```json
"themes": [
{
"id": "string",
"name": "string",
"parent_id": "string",
"vocabulary": "string",
"uri": "string"
}
]
```
<br>
- **`id`** *[Optional ; Not repeatable ; String]*<br>
The unique identifier of the theme. It can be a sequential number, or the ID of the theme in a controlled vocabulary.
- **`name`** *[Required ; Not repeatable ; String]* <br>
The label of the theme associated with the data.
- **`parent_id`** *[Optional ; Not repeatable ; String]*<br>
When a hierarchical (nested) controlled vocabulary is used, the `parent_id` field can be used to indicate a higher-level theme to which this theme belongs.
- **`vocabulary`** *[Optional ; Not repeatable ; String]* <br>
The name of the controlled vocabulary used, if any.
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
A link to the controlled vocabulary mentioned in field `vocabulary'.
- **`topics`** *[Optional ; Repeatable]*<br>
The `topics` field indicates the broad substantive topic(s) that the indicator/series covers. A topic classification facilitates referencing and searches in electronic survey catalogs. Topics should be selected from a standard controlled vocabulary such as the [Council of European Social Science Data Archives (CESSDA) topics classification](https://vocabularies.cessda.eu/vocabulary/TopicClassification). <br>
<br>
```json
"topics": [
{
"id": "string",
"name": "string",
"parent_id": "string",
"vocabulary": "string",
"uri": "string"
}
]
```
<br>
- **`id`** *[Optional ; Not repeatable ; String]* <br>
The unique identifier of the topic. It can be a sequential number, or the ID of the topic in a controlled vocabulary.
- **`name`** *[Required ; Not repeatable ; String]* <br>
The label of the topic associated with the data.
- **`parent_id`** *[Optional ; Not repeatable ; String]* <br>
When a hierarchical (nested) controlled vocabulary is used, the `parent_id` field can be used to indicate a higher-level topic to which this topic belongs.
- **`vocabulary`** *[Optional ; Not repeatable ; String]* <br>
The name of the controlled vocabulary used, if any.
- **`uri`** <br>
A link to the controlled vocabulary mentioned in field `vocabulary`.<br><br>
- **`disciplines`** *[Optional ; Repeatable]* <br>
Information on the academic disciplines related to the content of the document. A controlled vocabulary will preferably be used, for example the one provided by the list of academic fields in [Wikipedia](https://en.wikipedia.org/wiki/List_of_academic_fields).
<br>
```json
"disciplines": [
{
"id": "string",
"name": "string",
"parent_id": "string",
"vocabulary": "string",
"uri": "string"
}
]
```
<br>
This is a block of five elements:
- **`id`** *[Optional ; Not repeatable ; String]* <br>
The ID of the discipline, preferably taken from a controlled vocabulary.
- **`name`** *[Optional ; Not repeatable ; String]* <br>
The name (label) of the discipline, preferably taken from a controlled vocabulary.
- **`parent_id`** *[Optional ; Not repeatable ; String]* <br>
The parent ID of the discipline (ID of the item one level up in the hierarchy), if a hierarchical controlled vocabulary is used.
- **`vocabulary`** *[Optional ; Not repeatable ; String]* <br>
The name (including version number) of the controlled vocabulary used, if any.
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
The URL to the controlled vocabulary used, if any.<br><br>
- **`relevance`** *[Optional ; Not repeatable ; String]* <br>
This field documents the relevance of an indicator or series in relation to a social imperative or policy objective.<br>
- **`mandate`** *[Optional ; Not repeatable ; String]* <br>
- **`mandate`** *[Optional ; Not repeatable ; String]* <br>
Description of the institutional mandate or of a set of rules or other formal set of instructions assigning responsibility as well as the authority to an organization for the collection, processing, and dissemination of statistics for this indicator.<br>
- **`URI`** *[Optional ; Not repeatable ; String]* <br>
A link to a resource (document, website) describing the mandate.<br>
- **`time_periods`** *[Optional ; Repeatable]* <br>
The time period covers the entire span of data available for the series. The time period has a start and an end and is reported according to the periodicity provided in a previous element.
<br>
```json
"time_periods": [
{
"start": "string",
"end": "string",
"notes": "string"
}
]
```
<br>
- **`start`** *[Required ; Not repeatable ; String]* <br>
The initial date of the series in the dataset. The start date should be entered in ISO 8601 format (YYYY-MM-DD or YYYY-MM or YYYY).
- **`end`** *[Required ; Not repeatable ; String]* <br>
The end date is the latest date for which an estimate for the indicator is available. The end date should be entered in ISO 8601 format (YYYY-MM-DD or YYYY-MM or YYYY).<br>
- **`notes`** *[Optional ; Not repeatable ; String]* <br>
Additional information on the time period.<br><br>
- **`ref_country`** *[Optional ; Repeatable]* <br>
A list of countries for which data are available in the series. This element is somewhat redundant with the next element (`geographic_units`) which may also contain a list of countries. Identifying geographic areas of type "country" is important to enable filters and facets in data catalogs (country names are among the most frequent queries submitted to catalogs).
<br>
```json
"ref_country": [
{
"name": "string",
"code": "string"
}
]
```
<br>
- **`name`** *[Required ; Not repeatable ; String]* <br>
The name of the country.
- **`code`** *[Optional ; Not repeatable ; String]* <br>
The code of the country. The use of the [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) codes is recommended.
- **`geographic_units`** *[Optional ; Repeatable]* <br>
List of geographic units (regions, countries, states, provinces, etc.) for which data are available for the series.
<br>
```json
"geographic_units": [
{
"name": "string",
"code": "string",
"type": "string"
}
]
```
<br>
- **`name`** *[Required ; Not repeatable ; String]* <br>
Name of the geographic unit e.g. "World, "Africa", "Afghanistan", "OECD countries", "Bangkok".
- **`code`** *[Optional ; Not repeatable ; String]* <br>
Code of the geographic unit. The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code is preferred when the unit is a country.
- **`type`** *[Optional ; Not repeatable ; String]* <br>
Type of geographic unit e.g. "country", "state", "region", "province", "city", etc. <br><br>
- **`bbox`** *[Optional ; Repeatable]* <br>
This element is used to define one or multiple bounding box(es), which are the rectangular fundamental geometric description of the geographic coverage of the data. A bounding box is defined by west and east longitudes and north and south latitudes, and includes the largest geographic extent of the dataset's geographic coverage. The bounding box provides the geographic coordinates of the top left (north/west) and bottom-right (south/east) corners of a rectangular area. This element can be used in catalogs as the first pass of a coordinate-based search. This element is optional, but if the `bound_poly` element (see below) is used, then the `bbox` element must be included.<br>
<br>
```json
"bbox": [
{
"west": "string",
"east": "string",
"south": "string",
"north": "string"
}
]
```
<br>
- **`west`** *[Required ; Not repeatable ; String]* <br>
West longitude of the bounding box. <br>
- **`east`** *[Required ; Not repeatable ; String]* <br>
East longitude of the bounding box. <br>
- **`south`** *[Required ; Not repeatable ; String]* <br>
South latitude of the bounding box. <br>
- **`north`** *[Required ; Not repeatable ; String]* <br>
North latitude of the bounding box. <br>
This example is for a study covering the islands of Madagascar and Mauritius
<center>
{width=45%}
</center>
```{r, indent=" ", eval=F, echo=T}
my_indicator <- list(
metadata_information = list(
# ...
),
series_description = list(
# ... ,
study_info = list(
# ... ,
ref_country = list(
list(name = "Madagascar", code = "MDG"),
list(name = "Mauritius", code = "MUS")
),
bbox = list(
list(name = "Madagascar",
west = "43.2541870461",
east = "50.4765368996",
south = "-25.6014344215",
north = "-12.0405567359"),
list(name = "Mauritius",
west = "56.6",
east = "72.466667",
south = "-20.516667",
north = "-5.25")
),
# ...
),
# ...
)
```
<br>
- **`aggregation_method`** *[Optional ; Not repeatable ; String]* <br>
The `aggregation_method` element describes how values can be aggregated from one geographic level (for example, a country) to a higher-level geographic area (for example, a group of country defined based on a geographic criteria (region, world) or another criteria (low/medium/high-income countries, island countries, OECD countries, etc.). The aggregation method can be simple (like "sum" or "population-weighted average") or more complex, involving weighting of values.<br>
- **`disaggregation`** *[Optional ; Not repeatable ; String]* <br>
This element is intended to inform users that an indicator or series is available at various levels of disaggregation. The related series should be listed (by andme and/or identifier). For indicator "Population, total" for example, one may inform the user that the indicator is also available (in other series) by sex, urban/rural, and age group (in series "Population, male" and "Population, female", etc.).
- **`license`** *[Optional ; Repeatable]* <br>
The license refers to the accessibility and terms of use associated with the data. Providing a license and a link to the terms of the license allos data users to determine, with full clarity, what they can and cannot do with the data.
<br>
```json
"license": [
{
"name": "string",
"uri": "string",
"note": "string"
}
]
```
<br>
- **`name`** *[Required ; Not repeatable ; String]*<br>
The name of the license, e.g. "Creative Commons Attribution 4.0 International license (CC-BY 4.0)".
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
The URL of a website where the licensed is described in detail, for example "https://creativecommons.org/licenses/by/4.0/".<br>
- **`note`** *[Optional ; Not repeatable ; String]* <br>
Any additional information on the license.<br><br>
- **`confidentiality`** *[Optional ; Not repeatable ; String]* <br>
A statement of confidentiality for the series.
- **`confidentiality_status`** *[Optional ; Not repeatable ; String]* <br>
This indicates a confidentiality status for the series. A controlled vocabulary should be used with possible options "public", "official use only", "confidential", "strictly confidential". When all series are made publicly available, and belong to a database that has an open or public access policy, this element can be ignored.
- **`confidentiality_note`** *[Optional ; Not repeatable ; String]* <br>
This element is reserved for additional notes regarding confidentiality of the data. This could involve references to specific laws and circumstances regarding the use of data.<br>
- **`links`** *[Optional ; Repeatable]* <br>
This element provides links to online resources of any type that could be useful to the data users. This can be links to description of methods and reference documents, analytics tools, visualizations, data sources, or other.
<br>
```json
"links": [
{
"type": "string",
"description": "string",
"uri": "string"
}
]
```
<br>
- **`type`** *[Optional ; Not repeatable ; String]* <br>
This element allows to classify the link that is provided.
- **`description`** *[Optional ; Not repeatable ; String]* <br>
A description of the link that is provided.
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
The uri (URL) to the described resource.<br><br>
- **`api_documentation`** *[Optional ; Repeatable]* <br>
Increasingly, data are made accessible via Application Programming Interfaces (APIs). The API associated with a series must be documented. The documentation will usually not be specific to a series, but apply to all series in a same database.
<br>
```json
"api_documentation": [
{
"description": "string",
"uri": "string"
}
]
```
<br>
- **`description`** *[Optional ; Not repeatable ; String]* <br>
This element will not contain the API documentation itself, but information on what documentation is available.
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
The URL of the API documentation.<br><br>
- **`authoring_entity`** *[Optional ; Repeatable]* <br>
This set of five elements is used to identify the organization(s) or person(s) who are the main producers/curators of the indicator. Note that a similar element is provided at the database level. The authoring_entity for the indicator can be different from the authoring_entity of the database. For example, the World Bank is the authoring entity for the World Development Indicators database, which contains indicators obtained from the International Monetary Fund, World Health Organization, and other organizations that are thus the authoring entitis for specific indicators.
<br>
```json
"authoring_entity": [
{
"name": "string",
"affiliation": "string",
"abbreviation": null,
"email": null,
"uri": "string"
}
]
```
<br>
- **`name`** *[Optional ; Not repeatable ; String]* <br>
The name of the person or organization who is responsible for the production of the indicator or series. Write the name in full (use the element `abbreviation` to capture the acronym of the organization, if relevant).
- **`affiliation`** *[Optional ; Not repeatable ; String]* <br>
The affiliation of the person or organization mentioned in `name`.
- **`abbreviation`** *[Optional ; Not repeatable ; String]* <br>
Abbreviated name (acronym) of the organization mentioned in `name`.
- **`email`** *[Optional ; Not repeatable ; String]* <br>
The public email contact of the person or organizations mentioned in `name`. It is good practice to provide a service account email address, not a personal one.
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
A link (URL) to the website of the entity mentioned in `name`. <br><br>
- **`sources`** *[Optional ; Not repeatable ; String]* <br>
This element provides information on the source(s) of data that were used to generate the indicator. A source can refer to an organization (e.g., "Source: World Health Organization"), or to a dataset (e.g., for a national poverty headcount indicator, the sources will likely be a list of sample household surveys). In `sources`, we are mainly interested in the latter. When a series in a database is a series extracted from another database (e.g., when the World Bank World Development Indicators include a series from the World Health Organization in its database), the source organization should be mentioned in the `authoring_entity` element of the schema. The `sources` element is a repeatable element.
Note 1: In some cases, the source of a specific value in a database will be stored as an attribute of the data file (e.g., as a "footnote" attached to a specific cell. If the sources are listed in the data file, they may but do not need to be stored in the metadata.
Note 2: the schema also contains an element "data_collection" that would be used to describe a specific data collection activity from which an indicator is derived.
<br>
```json
"sources": [
{
"id": "string",
"name": "string",
"organization": "string",
"type": "string",
"note": "string"
}
]
```
<br>
- **`id`** *[Required ; String]* <br>
This element records the unique identifier of a source. It is a required element. If the source does not have a specific unique identifier, a sequential number can be used. If the source is a dataset or database that has its own unique identifier (possibly a DOI), this identifier should be used.
- **`name`** *[Optional ; String]* <br>
The name (title, or label) of the source.
- **`organization`** *[Optional ; String]* <br>
The organization responsible for the source data.
- **`type`** *[Optional ; String]* <br>
The type of source, e.g. "household survey", "administrative data", or "external database".
- **`note`** *[Optional ; String]* <br>
This element can be used to provide additional information regarding the source data.<br><br>
- **`sources_note`** *[Optional ; Not repeatable ; String]*<br>
Additional information on the source(s) of data used to generate the series or indicator.
- **`keywords`** *[Optional ; Repeatable]* <br>
Words or phrases that describe salient aspects of a data collection's content. Can be used for building keyword indexes and for classification and retrieval purposes. A controlled vocabulary can be employed. Keywords should be selected from a standard thesaurus, preferably an international, multilingual thesaurus. <br>
<br>
```json
"keywords": [
{
"name": "string",
"vocabulary": "string",
"uri": "string"
}
]
```
<br>
- **`name`** *[Required ; String ; Non repeatable]* <br>
Keyword (or phrase). Keywords summarize the content or subject matter of the study.
- **`vocabulary`** *[Optional ; Not repeatable ; String]* <br>
Controlled vocabulary from which the keyword is extracted, if any.
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
The URI of the controlled vocabulary used, if any.
- **`acronyms`** *[Optional ; Repeatable]* <br>
The `acronyms` element is used to document the meaning of all acronyms used in the metadata of a series. If some acronyms are well known (like "GDP", or "IMF" for example), others may be less obvious or could be uncertain (does "PPP" mean "public-private partnership", or "purchasing power parity"?). In any case, providing a list of acronyms with their meaning will help users and make your metadata more discoverable. Note that acronyms should not include country codes used in the documentation of the geographic coverage of the data.
<br>
```json
"acronyms": [
{
"acronym": "string",
"expansion": "string",
"occurrence": 0
}
]
```
<br>
- **`acronym`** *[Required ; Not repeatable ; String]* <br>
An acronym referenced in the series metadata (e.g. "GDP").
- **`expansion`** *[Required ; Not repeatable ; String]* <br>
The expansion of the acronym, i.e. the full name or title that it represents (e.g., "Gross Domestic Product").
- **`occurrence`** *[Optional ; Not repeatable ; Numeric]* <br>
This numeric element can be used to indicate the number of times the acronym is mentioned in the metadata. The element will rarely be used.<br><br>
- **`errata`** *[Optional ; Repeatable]* <br>
This element is used to provide information on detected errors in the data or metadata for the series, and on the measures taken to remedy them.
<br>
```json
"errata": [
{
"date": "string",
"description": "string"
}
]
```
<br>
- **`date`** *[Required ; Repeatable ; String]* <br>
The date the erratum was published.<br>
- **`description`** *[Required ; Repeatable ; String]* <br>
A description of the error and remedy measures.<br><br>
- **`notes`** *[Optional ; Repeatable]* <br>
This element is open and reserved for explanatory notes deemed useful to the users of the data. Notes should account for additional information that might help: replicate the series; access the data and research area, or discoverability in general.
<br>
```json
"notes": [
{
"note": "string"
}
]
```
<br>
- **`note`** *[Required ; Repeatable ; String]* <br>
The note itself.<br><br>
- **`related_indicators`** *[Optional ; Repeatable]* <br>
This element allows to reference indicators that are often associated with the indicator being documented.
<br>
```json
"related_indicators": [
{
"code": "string",
"label": "string",
"uri": "string"
}
]
```
<br>
- **`code`** *[Optional ; Not repeatable ; String]* <br>
The code for the indicator that is referenced in the document. It will likely be an ID that is used by that indicator.
- **`label`** *[Optional ; Not repeatable ; String]* <br>
The name or label of the indicator that is associated with the indicator being documented.
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
A link to the related indicator.<br><br>
- **`compliance`** *[Optional ; Repeatable]* <br>
For some indicators, international standards have been established. This is for example the case of indicators like the unemployment or unemployment rate, for which the International Conference of Labour Statisticians defines the standards concepts and methods. The `compliance` element is used to document the compliance of a series with one or multiple national or international standards.
<br>
```json
"compliance": [
{
"standard": "string",
"abbreviation": "string",
"custodian": "string",
"uri": "string"
}
]
```
<br>
- **`standard`** *[Optional ; Not repeatable ; String]* <br>
The name of the standard that the series complies with. This name will ideally include a label and a version or a date. For example: "International Standard Industrial Classification of All Economic Activities (ISIC) Revision 4, published in 2007"
- **`abbreviation`** *[Optional ; Not repeatable ; String]* <br>
The acronym of the standard that the series complies with.
- **`custodian`** *[Optional ; Not repeatable ; String]* <br>
The organization that maintains the standard that is being used for compliance. For example: "United Nations Statistics Division".
- **`uri`** *[Optional ; Not repeatable ; String]* <br>
A link to a public website site where information on the compliance standard can be obtained. For example: "https://unstats.un.org/unsd/classifications/Family/Detail/27<br><br>
- **`framework`** *[Optional ; Repeatable]* <br>
Some national, regional, and international agencies develop monitoring frameworks, with goals, targets, and indicators. Some well-known examples are the [Millennium Development Goals](https://www.un.org/millenniumgoals/) and the [Sustainable Development Goals](https://sdgs.un.org/goals) which establish international goals for human development, or the World Summit for Children (1990) which set international goals in the areas of child survival, development and protection, supporting sector goals such as women’s health and education, nutrition, child health, water and sanitation, basic education, and children in difficult circumstances. The `framework` element is used to link an indicator or series to the framework, goal, and target associated with it.
<br>
```json
"framework": [
{
"name": "string",
"abbreviation": "string",
"custodian": "string",
"description": "string",
"goal_id": "string",
"goal_name": "string",
"goal_description": "string",
"target_id": "string",
"target_name": "string",
"target_description": "string",
"indicator_id": "string",
"indicator_name": "string",
"indicator_description": "string",
"uri": "string",
"notes": "string"
}
]
```
<br>
- **`name`** *[Optional ; Not repeatable ; String]*<br>
The name of the framework.
- **`abbreviation`** *[Optional ; Not repeatable ; String]*<br>
The abreviation of the name of the framework.
- **`custodian`** *[Optional ; Not repeatable ; String]*<br>
The name of the organization that is the official custodian of the framework.
- **`description`** *[Optional ; Not repeatable ; String]*<br>
A brief description of the framework.
- **`goal_id`** *[Optional ; Not repeatable ; String]*<br>
The identifier of the Goal that the indicator or series is associated with.
- **`goal_name`** *[Optional ; Not repeatable ; String]*<br>
The name (label) of the Goal that the indicator or series is associated with.
- **`goal_description`** *[Optional ; Not repeatable ; String]*<br>
A brief description of the Goal that the indicator or series is associated with.
- **`target_id`** *[Optional ; Not repeatable ; String]*<br>
The identifier of the Target that the indicator or series is associated with.
- **`target_name`** *[Optional ; Not repeatable ; String]*<br>
The name (label) of the Target that the indicator or series is associated with.
- **`target_description`** *[Optional ; Not repeatable ; String]*<br>
A brief description of the Target that the indicator or series is associated with.
- **`indicator_id`** *[Optional ; Not repeatable ; String]*<br>
The identifier of the indicator, as provided in the framework (this is not the `idno` identifier).
- **`indicator_name`** *[Optional ; Not repeatable ; String]*<br>
The name of the indicator, as provided in the framework (which may be different from the name provided in `name`)
- **`indicator_description`** *[Optional ; Not repeatable ; String]*<br>
A brief description of the indicator, as provided in the framework.
- **`uri`** *[Optional ; Not repeatable ; String]*<br>
A link to a website providing detailed information on the framework, its goals, targets, and indicators.
- **`notes`** *[Optional ; Not repeatable ; String]*<br>
Any additional information on the relationship between the indicator/series and the framework.<br><br>
- **`series_group`** *[Optional ; Repeatable]* <br>
The group(s) the indicator belongs to. Groups can be create to organize indicators/series by theme, producer, or other.
<br>
```json'
"series_groups": [
{
"name": "string",
"description": "string",
"version": "string",
"uri": "string"