From f4053e2944af0e123a37cf18e934bae33bfe934a Mon Sep 17 00:00:00 2001
From: Daniel Ellis <daniel.ellis@ext.esa.int>
Date: Mon, 2 Dec 2024 19:02:47 +0000
Subject: [PATCH] development

---
 docs/.DS_Store                   | Bin 10244 -> 10244 bytes
 docs/Explore_the_data/treemap.md |  96 +++++++++++++++++++++++++++++++
 docs/assets/.DS_Store            | Bin 6148 -> 6148 bytes
 docs/cmipld/Introduction.md      |  17 ++++++
 docs/stylesheets/extra.css       |   7 ++-
 5 files changed, 119 insertions(+), 1 deletion(-)
 create mode 100644 docs/Explore_the_data/treemap.md
 create mode 100644 docs/cmipld/Introduction.md

diff --git a/docs/.DS_Store b/docs/.DS_Store
index 1052b4c570019b6b20e4d0cc3b0e9c5b418ebd02..9bb2f84a8436a094eb67988acb385d9695aa0c70 100644
GIT binary patch
literal 10244
zcmeHM&u<$=6n>kA+E$>XQY#gqqLmO*4^Huqv}%M9Zg5n72?R#;0Lb-v-Nfp8$I9Au
zk(J^jg0>gLAHY8VClD0}5YQZuxB=qGKTwHl#R0yV*~a7XY&NM>L#r8U_pNu{+nx7)
zGjHb25|Ojo_lra>5oK|3x%enfhQjOlF;(W`J0(a5_Czh}QS0S^HN9X;+upDUSOhEr
z76FTZMd1H{0Oo97vI|n$vqiunU=i3sfX4?H2bYytj-(W!11FIJK+fZ~D7Z!*AZ*-N
zR$@7lQkdeIGJ9}hQzuR_9BGbvm#afoVmXphnv)~V$%)_W#2Jbs-VQrgsFPEX(w;2>
z7J+F5c<!E|ljI|J57hjfd8ol)n)@5_&woS_=9;!Qh`L@Nw7>PbK|AUd3covZ2j(9+
zn91Za3z_$88*EVPHG2JMwXyjw|Mxayfp_=1;l0yt4eE<WUSwgf(GFXi!l3Q9pz_}N
zcIdOgD(i=SBy4N4BA3hN>WfbfhfBrMaxw2NohfhS-C?n~d?xQMmrrkP<+4Yge)hSy
z>X(8}$gYc~lM_b|dQAS`Ip4sQ=2);^tTkDuyQ4Fu(P7nU?0UAaeYNrP*7n)y=X99A
z2d(Z#+S@MIHp760>v#kA;wY`)SEsYoq)QYMqk$lB9VB*egxHFSKx~J6xgoPd=y6#8
zq7ZtJ8qkac`O&1V^Tlqu3iaR2ocd$KVQJ-b-Yu`3;>53%3MSq^M*C3`dH)2J6aE`m
zpQu+kf9m$lA8&nni*v5&j2TbTG4MU{42|tW;Q2CmYJ=kjd4lOWRdL;;hQ`_VXwRDp
zzq{HR{M}Vw_5aoFUza|=D*Aki%@~ip+8FU^qBpmx3-5hDY6c#{2z&+jN`=9piF(z6
z3(p^U=J<!g0ZnJz;3OSG0~cwHu88I_+Qe|GgPaW^eG^f0RkZyhg{V~fhh)H|`f1=W
z)kfv@htE!|9h1E7!EVg;e(dgr|EWQJ4&9mekv@jB4COuCVF=z@Af_+TS57K@<uJV@
zLO$<f47Pm{!0Yr1)#wd+onE8rWLQ7|+4mEa{`P>+?R$VrBPR<YLa{8mVwyz-oL?z~
zWI#X@!=A?{%)FD}J9&V=i?#yv&8e9*a~~H`IV_@{z)V`k>{%|9#1g7hI%S$l`BaIL
zIF(*Qr3Qjw9BUftsQvBhJAYmLPE4m$TH`UAtYsLH+H*9D7eHB$J`j^>BqBBcex*@I
zf55Mw6rvNX6bc{Y#ZZEG8gh@*dEmttA9Zy22xlek&<k4U=L=3XcBNQ9BuJ)ssUZr8
zY_SN;6oCWsZ7$#cUrYY}KhrkZmstcX0<%THnXlHWt9U2hS27j8*Y4uDfP)vVH<D7A
z;3T%=A;oq){_ySi6F9hTflFR+U5VvLO58!2`NsgcUzttH?bR*2Bpt(QGd0(oTo>8=
kADOFhpTv+iq++XP68p*HRj&7AcQ5>FYraGDALjr60-Bl-)Bpeg

delta 145
zcmZn(XbG6$&#1OBU^hRb+GZXBH>Szq0{b`f39n$>+%A5D8OW>TGt*HpH!-QzQK&XF
zG_jbhC?zuaoP^3`TWRshMl$7$+a@PS7pjU?SDRYsC|DSR)L9xC=qQ+&nbg*Da)>JH
wTL;Bw=j7()cT7GnA<x)3*-l1jbBk;<)5eCgOq<yiez8mzln~$iO#BTK0F`DfQ~&?~

diff --git a/docs/Explore_the_data/treemap.md b/docs/Explore_the_data/treemap.md
new file mode 100644
index 0000000..622b2ed
--- /dev/null
+++ b/docs/Explore_the_data/treemap.md
@@ -0,0 +1,96 @@
+## JSON Linked-Data
+
+JSONLD is a lightweight link data format closely conforming to the JSON standards. It allows us to provide relational data, in a flat format accessible to everyone within minimal intervention. 
+
+
+### Why is this useful?
+
+The JavaScript Object Notation has been accepted as a human and machine readable and intuitive data standard for both scripting and online programs. It tends to describe items in a Key-Value pair structure and present it in plain-text. 
+This is the standard that was adopted for CMIP6 control variables and has been used since. 
+
+In converting current and future data into JSONLD we are able to provide pointers to *reusable* bits of information, thus drastically reducing duplication, and in turn human-induced error in the WCRP (and beyond) community. 
+
+
+### Existing Workflows
+In introducing any new technology, there is often a period in which existing software will need to be updated. By opting for JSONLD the interference between this should be minimal, since any produced files will still be readable by existing scripts. 
+
+### Bespoke output and Breaking Changes 
+The main merit of JSONLD comes from its framing capabilities. It allows us to take a flat JSON file and build (populate) this with all linked components without having to store them in the same file, or even location. 
+JSONLD parsers are available for all majour programming languages, and capable of extracting linked files (using their ids (URIs)) meaning that we will always have an up-to-date frame when we request it. 
+
+This also means that should a non-standard or altered format be required for your work (e.g. just the names of MIPs or Institutions in an Activity, this will be possible through either custom framing or requesting an action be added to the relevant repository to generate this. Github actions are designed to run each time the data in the repository is updated. 
+
+
+
+
+### How does it change the existing structure?
+
+JsonLD is still a valid JSON format allowing all previous tools and workflows to function. . 
+In addition to this we apply a intuitive unique id to each item, and a context file. 
+
+#### Example file change to LD
+
+```json
+{
+            "description": "CMIP DECK: 1pctCO2, abrupt-4xCO2, amip, esm-piControl, esm-historical...",
+            "activity_id": "CMIP",
+            "url": "https://gmd.copernicus.org/articles/9/1937/2016/gmd-9-1937-2016.pdf"
+}
+```
+Is now updated to have an `id`, `type` and `@context`
+
+```json
+{
+            "@context": "_context_",
+            "id": "cmip",
+            "type": "activity",
+            "description": "CMIP DECK: 1pctCO2, abrupt-4xCO2, amip, esm-piControl, esm-historical...",
+            "name": "CMIP",
+            "url": "https://gmd.copernicus.org/articles/9/1937/2016/gmd-9-1937-2016.pdf"
+}
+```
+
+#### Context files   
+The context file defines how this shall be treated, where the files are located, and if there are any additional links to the fields. An example context file is given below
+```jsonld
+
+{
+    "@context": {
+                    // define the base and prefix adresses so that we do not have to specify these in the file
+                    "@base": "https://wcrp-cmip.github.io/CMIP6Plus_CVs/",
+                    "@vocab": "https://wcrp-cmip.github.io/CMIP6Plus_CVs/",
+
+                    // map id and type to @id and @type. This is done for legibility
+                    "id": "@id",
+                    "type": "@type",
+                    
+                    // add any external prefixes. 
+                    "cmip7": "https://wcrp-cmip.github.io/CMIP7_CVs/",
+                    "wcrp-universe": "https://wcrp-cmip.github.io/WCRP-UNIVERSE/"
+
+                    // define information for fields which may be linked. 
+                    "activity": {
+                                    "@context": "https://wcrp-cmip.github.io/WCRP-UNIVERSE/activity/_context_",
+                                    "@type": "@id",
+                            }
+    },
+
+    // framing options go here, e.g. expand all links
+    "@embed": "@always"
+}
+```
+The `_context_` files in our repositories are used both to define additional `@context` information, and to provide a basic framing context should that be required by the user. 
+
+
+### Other changes to the CVs
+
+#### File hierarchy
+Instead of having one large file containing all possible sources/experiments/institutions etc., we will break these out into individual json files. 
+
+This serves to improve the workflow and usability of the directories in several ways: 
+
+1. *A better understanding of changes over time.* This way we are able to create a difference log for an individual item, without having to track the entire collection or category.
+2. *Error isolation* A mistake in a single file will not affect any of the others, and will allow us to easier identify it. 
+3. *Versioning* The changes in each file are tracked, and we know exactly when they have occured. 
+4. *Line identification* It will be easier to hilight a file or specific line, without the worry that an issue 2 weeks old will now refer to something else. 
+5. *ATTRIBUTION* by seeing who is contributing changes to certain files will allow us to credit prominent members of the community, and generate a list of specialists for specific topics should there be any queries at a later point. 
diff --git a/docs/assets/.DS_Store b/docs/assets/.DS_Store
index 07054cd433536372a817680fed56ef13df85025c..f97c3b35e425a9cb049e045eacc340bda7afa8f4 100644
GIT binary patch
delta 18
ZcmZoMXffE(&B9vFz`$U+c>+s`FaR}j1uFmm

delta 18
ZcmZoMXffE(&BD5nfq~(~<_Rn%!T>sO1>^t#

diff --git a/docs/cmipld/Introduction.md b/docs/cmipld/Introduction.md
new file mode 100644
index 0000000..c9d3672
--- /dev/null
+++ b/docs/cmipld/Introduction.md
@@ -0,0 +1,17 @@
+## CMIP Linked Data utilities Library
+
+In order to provide a set of directory utilities for creating, managing and interrogating the CVs the cmipld library was created. 
+
+
+<image src="https://wcrp-cmip.github.io/CMIP-LD/static/logo.jpg"/>
+
+## Contents
+The contents of these are as follows:
+
+- actions : The location of a collection of reusable actions to be used in repository maintainance and LD processingJSON
+- static : Visualisation templates and website functions and scripts
+- notebook : a collection of example IPython Notebooks. 
+- frames : Example frames 
+- scripts : shell scripts installed with the cmipld library. Alternative functions using python can also be found within the setup.py file. 
+
+ 
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 90d09af..dd062b5 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -1,5 +1,7 @@
 @import url("https://fonts.googleapis.com/css2?family=Akshar:wght@300..700&family=Plus+Jakarta+Sans:ital,wght@0,200..800;1,200..800&display=swap");
 
+
+/* https://coolors.co/88ccf1-c1dff0-3587a4-2d848a-2d898b */
 .md-footer {
   background-color: transparent;
   backdrop-filter: blur(10px);
@@ -51,6 +53,9 @@ body{
 }
 
 *{
- 
   font-family: "Plus Jakarta Sans", serif;
+}
+
+a{
+  color: #88ccf1;
 }
\ No newline at end of file