From a6002980a18f05611fb520c3b20537c19174fa2c Mon Sep 17 00:00:00 2001 From: Ben Cuff Date: Fri, 30 Aug 2024 16:11:13 +0100 Subject: [PATCH 1/5] Moved js scripts and added new permalinks script, see #4 --- docs/_layouts/guidance-page.html | 5 +-- docs/assets/img/permalink.png | Bin 0 -> 10489 bytes .../scripts}/expandable-sections.js | 0 docs/assets/scripts/permalinks.js | 32 ++++++++++++++++++ docs/assets/styles.css | 23 ++++++++++++- 5 files changed, 57 insertions(+), 3 deletions(-) create mode 100644 docs/assets/img/permalink.png rename docs/{_includes => assets/scripts}/expandable-sections.js (100%) create mode 100644 docs/assets/scripts/permalinks.js diff --git a/docs/_layouts/guidance-page.html b/docs/_layouts/guidance-page.html index 029f38d..219383b 100644 --- a/docs/_layouts/guidance-page.html +++ b/docs/_layouts/guidance-page.html @@ -24,7 +24,8 @@ - + + @@ -57,4 +58,4 @@

{{ page.title }}

- \ No newline at end of file + diff --git a/docs/assets/img/permalink.png b/docs/assets/img/permalink.png new file mode 100644 index 0000000000000000000000000000000000000000..47b2e8f6ba1dc120d9a1880a6df45b04aeb2db59 GIT binary patch literal 10489 zcmZ{Kc|4R~^#3!%FwMx4$=H_`Buj-T%Zz+fDod6~7*v+*W#4AV5Q<6*lA$bVu@ps? z(by8A@S&_jA?qm1V9fmP^!a^%ukSy<`DdQz-gD1A_bm6k@3~KsrTK~NC`l9qLEBAF z{$m9}aPSC+kbK~8IjnaB{7D3v*aunry9b53UcC$%UGjIkEN|-T>T%iXvg@Vrz_!c! z5TyLb^dBReu&0k~-rnvghy4HDvB3-X z4poh>d?R*O$M>xLpm*MC$qD+fcO_%2B41DB`Lp9YBKFz-j5O>z5`JoVNW|nv`yxf; z&YkmIss4Yzp^i93=o!_&zOHVE;e*1hQO?qOkL8Oz2zuu6Oz3M`dY7CznI%6(^~3q_ z|C)L?#U6}N78jfoK|s(tIZ9ypK4yB9{EEV^wP`HXJA?S(U#xqB{Nbas4FnyC9vCeR z?C!D>pDW7YF^Ppk_%RA<(+I^<7cY1sFUD((0ByPGJh|&^qgFWadz_2LPTomTWe9Qz zd`JyZS$m3dAiTsP_m{DUVvBjoQ!WobT3ffXnJ@ z_hMpN>%QgS#fKhBs{;0ACt;9f2&1)uc<(25Oi)MjR2^I|0)c@b6LL&#Bk^t=wbbOw z-UN={z}t?Ufa#B&tb=npZhgmCFbSyT39}xfHBwCEJd$WefDP3gE_3u}_j zpKGMv1~WBn;gOdZXjg zI7BMVlz$t{-X6d754gYdw)j^%OLK@CMg$&M)6-?q5H9bE{XXtaRTp z1g&i2-0z4p#OycR$0$vy8^NWf3F;Ael_Ap6cw+4Y2bXCQtvoVc_DW*M0ba;Pjve@9 z^!uxemw#BA**DzS=V?QhhdZnS*t zCJ0Q!Y}IB>T%y)ET$fDx0~Z5RC88h_s}VPHxw$RoT_vBk7SaTd!@we)n5|hn(7m1P zuGdR<>n%gev16`-O8hDi=@4!73^A*4#e!=ax{!=2Tps};iB$t_Ju1J7cN##DH80hJ z<&}P}WG66KJT9mV2~16sJ8BPB1xEBpk>{PI6#24vkw{{OGfsB)S4KY%U_rNN)nbbn z89*dP;-i#S)~q6jrxpzfvkyFqNgtK@%dF#zXm{^BqzaeOpCo?~mT)rZxPh$a4taT& zg4|kG#c>iGjJTb~{HNinb&dc7193aj|Ky8wz<@A6ru;zbUwM94evLPco#cx4+inxf z4{V1dekAB8I{&+lmV^Uh%oJ4B3HAmV2?G)wE zg$cVfQG$=GpcY|Wxi9kZ5LxvU?@f@0@F zzo2I8x|p=}bw+vStwfZksRl4iJnqOy8|WB*AWPU^e8Oe8#4qN*_VuA9oUb>7V1@LV z74Z!DuklUF@a6^jldamPtxl@Yc;v#SAbD~HZjTa=$Gu6)oEg}ekeuHJ^D`6C2>!>i$NL=3#l{na)7f_hCrJOr+RP`FSVH@JApSog)W}=99cPgGi~QX8cp_H6 zkJm$ht5^}X(=_77X3&Y#tYWzmwdnubAGT}krDMr{uE*0Tipy|;$|lOfeh|i?j~V^w zTz;41|H2^psEw2YD^$z4=<~r@_#XNIMUNVpC30#z=j`_<1JPT92+kw=J)$osE`?6` z9Gw`;D7st+4QA1QWc5%&jpPlW+g)u;^(fVXfHbGCau(z*qrTzZV*L3dc9P1B>|6{6x^?ECBfGS#NW>s7J7?M8wv(a6X>xcx1)Yfh{ zepo-W+{x5{7nk3qk^-k&R1`tF2iKB;Zb*+tV$D#oo4>A^GOfp#Jj7jm#6Ks2pzofH z!!xh3Gc*NmcXIXsRe#(Zmrfz^7mH_v#^o`lo?M(Wo%AA2o9p5PF%VuxqjxK)D1?}x zcbMLFxz$!xb<`^PS6UH*sORWWiUZXI}5Zs6BT zJv#q!>E(g&qT%QtATA&+^9Yu2?~;3l_l|rxL@Jz#fVu3DhaO)N$HO2ze{?S|fRD=% z*qw5D1mBN9zXDGJNX2~}KAy!TX=N>~r^CS$1dPGuB~vKqkv$ADhk3t zmeEzE`7RuV=n<_SrLV(3j7HY$ij(J!H>CIN@XTD)0+{MKYQr>F=xg&cN=(W3vE)T* zG-<0M`lQK+?va0l@b6ST;ZeoowgCgYqDetTDE%;dp_YGr6_HszB8idC7a(`t3)dZjhu zgP#gAq;qdBAHuu8Ggwds65g2TYmzO{i^AT2fsR|Ls1ukMi{xLmI(Xo#zA|)b?GYSu z7upI79qiwwDUt81SK%Qo3!q}|KWo|_qRzncPv_yPuSfq_$g>R0aM8fP^|IpNT~ov> zWS`(1r7#Q>L_by@GUG@2eP&Xi_CW0I?5F;GC?Fni(*mMGJd(!0M7{v#;H zKQT?o$v-i`u=7401$_^3z2QpDq)|2`E>Bd$y9`Vkq^H(vIu48&=_W2HLjgwOq1#%< zer~T5M!TW~$E|*nTa% zWl}wRCxnc7UMM`KDC-p`Du)4Y-|dn12`iHSE>Tjevg-loIlx z+~*A9cnKvtl4qnK^jLSvYLXjYFup zh$JcIbnpLF0`}?r&I&)$nCDwxI_LhDzEYhEq`aS{>!bI=VD9~mB2)Z{VG;Q&#>Q%|0&W|mP@ln1ST?BVQ$b|AS&;%FiYU4YV z)u|%e|Sdo4}5wTbR9UJz?I7ezp~S(TqvBlCh>?16eki z*5)j*oP3JY?QcdDTSk{kZJp`o*slI&lM^82U987Vz2~z{>NZ-ZEH<;A9PZ!VNbavm zUwhpj0e$?lXGDyx)nGNV&AuN~S+2$^t+>#nr-1>d7xqEst>G{EyT%H3<%;#EdSsqp zm%OoS($MC`JJT0=3ya645Fjh;?N1FG?)DC=(~E$f4Yo;9mWXOBFI@u|jrutxIpSxq z#o!@tribEucgZgK9#MIgw`b`yf)5g4T!OfuFgy6}<~XiM0*+@ke#;>RcLIVZ-EKi= zH+Qkn_aR z8E(5w0J|eiPTk|13!Okdt2_B1g?)M%WI_7XCF!tvwKy8pHogzq1LwT=)9D7nxY3`tUq7{kLtI{FvdtF-*K9NJ_T@G||+7*=T(L zyKMn5$-Z}ZwUnQW_P;Isjslr>u7>kbnhU92LmoTI;h9r@)yeP%VG@JiJv6ku{{k1U zn=mz>z7l5F*s_`5_0^b^~jC zePx|FU3R|?Ks({3TST1QIzj-3B+BE~zOT*zMP+o=d2;$ zcDNCZdLXcas4cyl@|?YkJMZn%&O!?$hE4wdyghQyGMHDM@b01ozN&Fhl%1_9K39oylI63aD2&4SipKr zs67M1q$b6vpcaa{>W8^d@^Wia-TUFK{Xo{{$BdeNjL_Kw6Kgg`40#{#kUIb>7JNgt zHkr#%Gl1`a-PHf4E z73WRU{KFTI3;%A>YT{dp24ZyiBzy}yw^(Miq~A?#JIC{{YxOzwQAk!#c)xj zwVeS1EzYF*j@|Jz$_qcS1?^uEdBA%eEt@?i4%SASE%hx`J)q^M)WK+!f2F1F^uy4^ z&%-ON>iTqIxfbSi_ATtutFc)2P3_+aA7)8p96_By^rdwSKbMh{i9ro=oaR;x6L9Q3 zEHahBS*Dn=#uI?nw%eCIZE2l3b@bfe(LDh4pUU37Tv1GLhRL&PN)D#Y>AC~*(D{$) zMb^w-UZfrKg^LOjdn%=_YB9b5w~I2IA1ZzK(PY!(dTV6pt{il24N+N3W#^J zc5)H(Q=~9E=n!jn8t^f?#h2F2*_ZW;K-d4P?eJG}?~(#omMlas)pi`x3z=JMY^`}| zxStP2JSxKmjtsCi#+7iB)@t0E2%KWYbw@7vyEo394yYKIZFX*roiGNWIwJwXh(>wc zl@z-3u@Fs;PE1zd2I{`S#tN#m91zFuBZyNlat0Jg!*0G2wLnw+%fm6JQ{%BdmUF2BrQF;f-GD z%Bla4f(1D}`a6NRRE8aJ8Tx2BgHn;V{@3rSE~w$SllWUPJ$}{HnzyQRy)mO% zj8Y38fL@grS~^u?!Shq#1vIK29asK(V0L9E?0+?tg5aac{WZDFcA^Pafyz)JyLCB& zV*#WRBXa{4O~gRf*$qoSw%XKpvenT4Lsznm6I^4>e5b|g!oXZ3rBJaJf~}6JX-f17 zqSrS1s0mt4Hx@{^c#K(d`+bP6`&lUaXe@=CW>#~S8LG^ZsmzC-o(n1m? z9igCQxCTo`s%Ng$o_FqOkcPgx^ZQvWTdN8>c`klO{H zgty@o#rBYWOn%qMbQ*Qh5^Udoc?wFwwKvWep9Tv1c9ZsY=jy!qqw6@S&=sLMKf1+f z6od_@FIHJ1kujirh=R}|z>|%k^}fR}mEStHLQw zg$$LB7If|0v}5)x!R70QE)AB50H?WA$M+P?-n?5APEUi6y-$h8^{i;HsPz}3F0REg zln9j$sIc<>loz4rXY809ZUA9YQ+Bo@ki_4%j|xcE{hS7M5jJ+>?xEbEmv98 zZc=?8B01;?m?0=xQ5w^5-wNbeUUowGsFBesU?>}AsJ;bu4;YXDmpA+U`;$2xcWZl% zSUhh1Srig%%71P=WKg(8wb90<9TZ220RT5MEeg_L5t9UFSJ+T(S1m6{?47F6*Cy)P z0-MYcXf>aMl^q5#G->%wxWTP-Z87uwFpbFPVSxIO7b(qeHS+N(av| zr)+syGfseEb+y$LB)*AdBV_EBOz-N-<(6vWnVOGZ|JPc58v7>E0UnRjo`VIfX|PV~ zw*32MDRM8!l-j2r@wm(pnAmxsO`NnxbgM*mxoC+D@s@vIFXr9|k4qnpPPl48T7iw7 zW=1+bK;PHqA4>v}yVqg+;7LueTj2VzP?}aHL!-UeG`2-ggl%aHyRGQHq79m=kpo@& z5&#~biiC!?KvgZ7!}=Wb>}RksvnL*oU*q)cWS!JhhL7>l<>W+1`Y>8~khtf+XoJul{q;!QlZ~1S z70<5Q-&Bu0lW`majYdW4B~Sx} zA3sMC;YgU9KWXdu&VDpP`PP1jFKc;!SC6-sm$OK~SA^8z&9p-|-M)Cemb=_Ge-NL> zaZ(;JP_NnauMddAq2(Sq#Kq0IN1(g{gus!v)b~iAz%2&o+eu(x%cO~ zf56A;C-pC0s-*tA6V~XXuhGyW{e%AFi*^6DWvHUd+N}H2E_p*0aqP8-j7<5Db8o+@ z64RJxGaV-(aSrFxf$V`7S$V@>1La1QJy%ZqUG1kTFukmW8j=h3C&-H3QqaQ2uVb(S z-S>!+=a)*ak?}*LOMylgs~s<8+@kPB6z=o92y=mt6{`?LgWl@Mf8MNmcwUDTq;*Ntd0X9RpIA-z=$s3hmQM0K)H%T3UB!%91*G z82-#U-&e#d$TRa!Bk%;x9LBU9D%LN1 zDvomQ<3&M|64WxxS(7&J2or4nGi5p;tM~BAez7YT64twU0v@2xJ(%}`Pfm;Io_y1? z7>{eof$eYZGZxsadfWJT;Nou97oLFC&zEn9!{xuqoE)ixbMFJp?l`?4=;VA#&QS*C zvYw$2YP$E7%f#)4|-P*U$cZTKjjVH zBg~YMF&|s5@qgDM%8z_$En$uF8s57AvEEF~V>NVN2=11&#|T&{2&crwY*a58AQ~}D zxvyQD5u+|4im=bbHQ256g?oup$#DfX$mO0@rwvDy;(nKVZ?6ZPAl_bBIMK3T1hdqU z(}Jm~pafrg%X%Bw?#Vu!q40yldK18pAjv|W?spFK9_rTDq@v}`RKcA%{vnFg@umgp zZi9n+B~ZnD-}+-O&>{p%xDdGTfe&Gd7z&!_E2}RmUeMcBo;KgInBpy&34Jw7EYr!S9K{pBtdIg2O*w)G8 zGUFDw*JqLTR_1NJ7;G8R8jLn;(4xy3j^xKJnGTE;xs4_5Er?YVgEq6k^@MdI=PRQ1 zbI3r95a&_9>jgUj=<@lDKeWRqv2ROi)<7X9S;21y+wNOuOQUxUy-L!{BsUd-uYI;v zBJrk(er(H8^R_XQfwDxAzu8C$ZJUD=q1Im5Eug*^Qjq>ox*SBe8kTO1U#| zdFLN|S%+#w)j#rQ#m3PHM$nJv4|_~*s9r!1rh=NtUNZ3kJGHW+nW}dhVWi3%lR`;` z=YE8by=y}}n~+roS4l~9Vy02Z^Aig;XAgj@x3(@tEIeEQ*2Eyb+GiooC(JgBxT&!! z*fbIRI=4UI_vj15RO`r=w{t~m_2Jj{Zbb>#j~bkiu^~WBqQC13_32*Vymq+p8ltiF z8fWe7_ril!W7MsH=fjGwM5iyWpLZunVxV8}X;V_rK>=*xWsrvV#WND6e^z1`me#3@ zF16Ap0muchNy=;?_*{Vl^qp9Ofksfw=7vWj04mEZL(>TE0Vpp-?DvKVohDA<4Vc<& ze(mv!40^wh@Ca|$o|4eejs>vT7>k1bK%XVU{vIBUgz!4P-hWvhb?BJIfT1NS z`aO@K?Y_ScR&7*_V;yhi1YxZ@&!A$j5_waG1X&jiVv z-ddBjHoi-~qARi6e1yVH!QIbgNz?ZW>%N|T0pLGfsG=M?AP`X3uZZ~j_8dCt|DmTj zx>8)Ie}OWHJdxOk0sNCPmF-RCQ+Xz z6aFof8bOTyZ;rdVjU&$Dly8PogD3Z^{r)*1d1)dkCi;~E zD>h;U`sW;9_9))JfgHN!4eJS}0l*j!6J*TE~^3b*4p}sH{pfJiR@gg^@|zoJ z4F2z+D2RAgD;_5G*0rk4ZlfgD2H7$n+l^)8Ls6u#*0mA!XT8c!(-#5${!tsNl|#J? z=hTl|FnMIuAS>mj)@s!&*3>61R^m}-DCzP8R8@?XQNIN-o5gb4xcR|f73dK~(hMb! zV35F&-`wsK*8$co0!7qo%q687fEv5+$darLV9ui`K=9>NR#aM12*BLA`YFN89pD`L zwAoqXGY|8NI*cxa@y}By>@h>$G=@djAi&sISyC@rScx|ViDSPQhSTJxPr_~|lc?lf z^5%T3krM70k32uZM@s;gbHm=vtdhSrdo}*oUY<($WDNjdteaZzdi!~KWIWFD<^^p| zOrUZD84c=*Z<>!1tGVA5XskwXkhqd>wtzSl0~I3&bmRcUyIo2yj5_-VR8@J_tNU^n z-)CiVE5Xy}V7Jw;ya zeN_mB{gjS&A2=SOvHjg{7R&(BS=`15f^G?NgjrHqFiS`ol$W6D>b^SR89>kn-G;NldX1 zLiAScnw%_f^;W9DO3Z>Q_Z-7=zWj^IRn(slvY9*wUc6qBes(WhB2+g<{iDs{KzI*qsu~k&f$lUEA$GU3`OyG`zU1x}31!ugs zPaf!Knb=y`i2Yt&u&w?bU;?_&ZbcuE>Wnp{S~pfH!#QHHlOd%sB(Y^9yN21P*cze#m>wWNWY%;QQvXC7go1q#%7w;!6d1Zb-VRS!$E(;SW8llKALo(F z)@gWEUVTG*je~O&ZWfAbFn~n%^SUuhi=1QY#fp0m@KJSEK;tKMK0f-ySrw%6iQ2}r zSk5sWTrQL=SO@nmwre=l*nA_8iajSdG zlYum^rrUC;Xb6FSlpG80qR%A9)}K34j@uTk@e_DdP;uy3V(L!b^ai37Zuln;K%Kl3 zM|jqHrg9OSm)9{&f9vT*bQD-p4;Hb%xX7irko;lK^a0LM1zbD$>=8~D3 MnEz99%q8ys0KuKbW&i*H literal 0 HcmV?d00001 diff --git a/docs/_includes/expandable-sections.js b/docs/assets/scripts/expandable-sections.js similarity index 100% rename from docs/_includes/expandable-sections.js rename to docs/assets/scripts/expandable-sections.js diff --git a/docs/assets/scripts/permalinks.js b/docs/assets/scripts/permalinks.js new file mode 100644 index 0000000..d2371f6 --- /dev/null +++ b/docs/assets/scripts/permalinks.js @@ -0,0 +1,32 @@ +// Function to copy link to clipboard +function copylink(text) { + navigator.clipboard.writeText(text).then(() => { + alert(`Link copied to clipboard: ${text}`); + }).catch(err => { + console.error('Failed to copy link', err); + }); +} + +// Add copy link icons to all heading elements +document.querySelectorAll('h1, h2, h3, h4, h5').forEach(heading => { + // Ensure the heading has an ID for the anchor link + if (!heading.id) { + heading.id = heading.textContent.trim().toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, ''); + } + + // Create the icon element + const iconWrapper = document.createElement('span'); + iconWrapper.className = 'permalink'; + iconWrapper.title = 'Permalink'; + iconWrapper.innerHTML = ' '; + + // Append the icon to the heading + heading.appendChild(iconWrapper); + + // Add event listener for copying the link + iconWrapper.addEventListener('click', (e) => { + e.stopPropagation(); // Prevent the click event from bubbling up + const url = `${window.location.origin}${window.location.pathname}#${heading.id}`; + copylink(url); + }); +}); diff --git a/docs/assets/styles.css b/docs/assets/styles.css index bd132af..89dad5a 100644 --- a/docs/assets/styles.css +++ b/docs/assets/styles.css @@ -143,6 +143,27 @@ ul, ol{ } +/*Permalinks*/ +.permalink{ + background-image: url('img/permalink.png'); + width: 18px; + height: 18px; + opacity: 0; + margin-left: 5px; + display: inline-block; + background-size: cover; +} + +h1 span, h2 span, h3 span, h4 span, h5 span { + transition: opacity 0.3s ease-in-out; +} + +h1:hover span, h2:hover span, h3:hover span, h4:hover span, h5:hover span{ + opacity: 0.5; +} + + + /*Fancy elements*/ blockquote{ margin: 1em 0 2em 0; @@ -342,4 +363,4 @@ td:first-child { @media only screen and (max-width: 985px) { #copyright-block{display:block;} #copyright-notice{margin-left:0; padding-left:0;} -} \ No newline at end of file +} From e2acc2979b191554fb8a4cd88711f7e8098e363c Mon Sep 17 00:00:00 2001 From: Ben Cuff Date: Tue, 3 Sep 2024 10:06:59 +0100 Subject: [PATCH 2/5] Change name to section-links and added pointer effect --- docs/_layouts/guidance-page.html | 2 +- docs/assets/scripts/{permalinks.js => section-links.js} | 6 +++--- docs/assets/styles.css | 9 ++++++--- 3 files changed, 10 insertions(+), 7 deletions(-) rename docs/assets/scripts/{permalinks.js => section-links.js} (87%) diff --git a/docs/_layouts/guidance-page.html b/docs/_layouts/guidance-page.html index 219383b..ad32a58 100644 --- a/docs/_layouts/guidance-page.html +++ b/docs/_layouts/guidance-page.html @@ -25,7 +25,7 @@ - + diff --git a/docs/assets/scripts/permalinks.js b/docs/assets/scripts/section-links.js similarity index 87% rename from docs/assets/scripts/permalinks.js rename to docs/assets/scripts/section-links.js index d2371f6..5d9051e 100644 --- a/docs/assets/scripts/permalinks.js +++ b/docs/assets/scripts/section-links.js @@ -1,7 +1,7 @@ // Function to copy link to clipboard function copylink(text) { navigator.clipboard.writeText(text).then(() => { - alert(`Link copied to clipboard: ${text}`); + alert(`Link copied to clipboard:\n${text}`); }).catch(err => { console.error('Failed to copy link', err); }); @@ -16,8 +16,8 @@ document.querySelectorAll('h1, h2, h3, h4, h5').forEach(heading => { // Create the icon element const iconWrapper = document.createElement('span'); - iconWrapper.className = 'permalink'; - iconWrapper.title = 'Permalink'; + iconWrapper.className = 'section-link'; + iconWrapper.title = 'Section link'; iconWrapper.innerHTML = ' '; // Append the icon to the heading diff --git a/docs/assets/styles.css b/docs/assets/styles.css index 89dad5a..187016d 100644 --- a/docs/assets/styles.css +++ b/docs/assets/styles.css @@ -143,8 +143,8 @@ ul, ol{ } -/*Permalinks*/ -.permalink{ +/*Section links*/ +.section-link{ background-image: url('img/permalink.png'); width: 18px; height: 18px; @@ -154,6 +154,10 @@ ul, ol{ background-size: cover; } +.section-link:hover{ + cursor: pointer; +} + h1 span, h2 span, h3 span, h4 span, h5 span { transition: opacity 0.3s ease-in-out; } @@ -163,7 +167,6 @@ h1:hover span, h2:hover span, h3:hover span, h4:hover span, h5:hover span{ } - /*Fancy elements*/ blockquote{ margin: 1em 0 2em 0; From 967c76b582a520bb9c21efde46ea47c63359f832 Mon Sep 17 00:00:00 2001 From: Ben Cuff Date: Wed, 4 Sep 2024 15:23:29 +0100 Subject: [PATCH 3/5] Rolling back earlier changes --- docs/quality-assurance.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/quality-assurance.md b/docs/quality-assurance.md index b5e1082..d43864a 100644 --- a/docs/quality-assurance.md +++ b/docs/quality-assurance.md @@ -8,8 +8,8 @@ layout: guidance-page >- Quality assurance should be planned in advance, with roles, responsibilities, and the extent of assurance activities understood fully by the entire team. >- Quality assurance should be appropriate and proportionate to the scope, risks, methodology, and data source of a piece of analysis. >- Understanding user needs is important when measuring the quality of your data. Perfect data quality may not always be achievable and therefore focus should be given to ensuring the data is as fit for purpose as it can be. ->- Teams should hold discussions to review quality and plan quality assurance on a semi-regular basis, identifying gaps in current procedures (our [quality review conversation tool](https://github.com/BenCuff/github-pages-test/blob/main/docs/assets/downloads/QA%20review%20conversation%20tool.xlsx) can help facilitate this). ->- A quality assurance log should be created and maintained (see our [QA log template](https://github.com/BenCuff/github-pages-test/blob/main/docs/assets/downloads/QA%20log%20template.xlsx)). This is a crucial tool to help teams plan, record, and sign off on quality; it provides an audit trail of everything that was checked and what the outcomes were. +>- Teams should hold discussions to review quality and plan quality assurance on a semi-regular basis, identifying gaps in current procedures (our [quality review conversation tool](https://github.com/ukhsa-collaboration/statistics-production-hub/raw/main/docs/assets/downloads/QA%20review%20conversation%20tool.xlsx) can help facilitate this). +>- A quality assurance log should be created and maintained (see our [QA log template](https://github.com/ukhsa-collaboration/statistics-production-hub/raw/main/docs/assets/downloads/QA%20log%20template.xlsx)). This is a crucial tool to help teams plan, record, and sign off on quality; it provides an audit trail of everything that was checked and what the outcomes were. >- The quality assurance process and any outstanding quality concerns should be clearly communicated alongside the final results of the analysis. @@ -27,7 +27,7 @@ The quality of an analytical output may be thought of in simple terms as its “ 4. Comparability and Coherence 5. Accessibility and Clarity -All quality assessments of official statistics should be conducted in line with these dimensions and both our [QA review conversation tool](https://github.com/BenCuff/github-pages-test/blob/main/docs/assets/downloads/QA%20review%20conversation%20tool.xlsx) and [QA log template](https://github.com/BenCuff/github-pages-test/blob/main/docs/assets/downloads/QA%20log%20template.xlsx) sets out these dimensions for you to consider. +All quality assessments of official statistics should be conducted in line with these dimensions and both our [QA review conversation tool](https://github.com/ukhsa-collaboration/statistics-production-hub/raw/main/docs/assets/downloads/QA%20review%20conversation%20tool.xlsx) and [QA log template](https://github.com/ukhsa-collaboration/statistics-production-hub/raw/main/docs/assets/downloads/QA%20log%20template.xlsx) sets out these dimensions for you to consider. See inside the expandable sections below for example questions you might consider as part of each dimension. @@ -136,7 +136,7 @@ It is our role as analysts to explain how any limitations in our outputs might i -These key stages along the data journey, alongside the 5 Dimensions of Quality of the European Statistical System (ESS), form the basis of our [QA review conversation tool](https://github.com/BenCuff/github-pages-test/blob/main/docs/assets/downloads/QA%20review%20conversation%20tool.xlsx) and [QA log template](https://github.com/BenCuff/github-pages-test/blob/main/docs/assets/downloads/QA%20log%20template.xlsx). +These key stages along the data journey, alongside the 5 Dimensions of Quality of the European Statistical System (ESS), form the basis of our [QA review conversation tool](https://github.com/ukhsa-collaboration/statistics-production-hub/raw/main/docs/assets/downloads/QA%20review%20conversation%20tool.xlsx) and [QA log template](https://github.com/ukhsa-collaboration/statistics-production-hub/raw/main/docs/assets/downloads/QA%20log%20template.xlsx). ## Roles and responsibilities @@ -204,18 +204,18 @@ If the work is being used for a new purpose, the analytical assurer should obtai 2. QA log template
- -
### What is the QA review conversation tool? -Our [QA review conversation tool](https://github.com/BenCuff/github-pages-test/blob/main/docs/assets/downloads/QA%20review%20conversation%20tool.xlsx) was created to provide a useful starting point for thinking about the QA of statistical outputs in line with the five European Statistical System (ESS) Quality Dimensions. It has been designed to facilitate team discussions about quality at either the start of a new project or at regular intervals for cyclical releases to help teams plan QA, identifying gaps in current procedures. We have compiled discussion questions that teams can use to reflect on the quality of their analysis, identify areas for improvement, and consider how to communicate quality to users. The outcomes of these discussions should inform QA plans and QA logs which teams should be using during QA activities. +Our [QA review conversation tool](https://github.com/ukhsa-collaboration/statistics-production-hub/raw/main/docs/assets/downloads/QA%20review%20conversation%20tool.xlsx) was created to provide a useful starting point for thinking about the QA of statistical outputs in line with the five European Statistical System (ESS) Quality Dimensions. It has been designed to facilitate team discussions about quality at either the start of a new project or at regular intervals for cyclical releases to help teams plan QA, identifying gaps in current procedures. We have compiled discussion questions that teams can use to reflect on the quality of their analysis, identify areas for improvement, and consider how to communicate quality to users. The outcomes of these discussions should inform QA plans and QA logs which teams should be using during QA activities. ### What is the QA log template? -To help teams record and sign off on quality, we have also created a [QA log template](https://github.com/BenCuff/github-pages-test/blob/main/docs/assets/downloads/QA%20log%20template.xlsx). This approach is standard practice across government statistics and should ensure that a QA mindset is present when conducting analytical projects. A QA log should be used every time you are producing a publication. +To help teams record and sign off on quality, we have also created a [QA log template](https://github.com/ukhsa-collaboration/statistics-production-hub/raw/main/docs/assets/downloads/QA%20log%20template.xlsx). This approach is standard practice across government statistics and should ensure that a QA mindset is present when conducting analytical projects. A QA log should be used every time you are producing a publication. A QA log will: @@ -248,9 +248,9 @@ The table below gives some considerations when completing this section of the re | Guiding questions | Specific considerations | Why do I need to know the answer to this? | What help is available? | |-------------------|-------------------------|-------------------------------------------|-------------------------| -| What is the need for this analysis or statistical release? | Does the output contribute something new that cannot be found in existing research or literature?

Has there been a clear user need for this analysis shown through user consultation? | Understanding why the analysis is needed and what it will be used for is critical for understanding whether what you have done is fit for purpose.

If you are responsible for part of an analytical process, understanding the end use will help you to make sure that your part of the output does what is needed to meet user needs. | [Guidance: The Aqua Book (HM Treasury)](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf)


[Guidance: Analysis Functional Standard (Government Analysis Function)](https://www.gov.uk/government/publications/government-analysis-functional-standard--2) | +| What is the need for this analysis or statistical release? | Does the output contribute something new that cannot be found in existing research or literature?

Has there been a clear user need for this analysis shown through user consultation? | Understanding why the analysis is needed and what it will be used for is critical for understanding whether what you have done is fit for purpose.

If you are responsible for part of an analytical process, understanding the end use will help you to make sure that your part of the output does what is needed to meet user needs. | [Guidance: The Aqua Book (HM Treasury)](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf)

[Guidance: Analysis Functional Standard (Government Analysis Function)](https://www.gov.uk/government/publications/government-analysis-functional-standard--2) | | Who uses your analysis or statistical release? | Does the work meet user needs appropriately?

Have you addressed feedback obtained from recent user consultations?

What are the expectations of my users?

Are the length and content of the publication appropriate for its users?

Are terms defined for your less-technical users? | Understanding who uses your analytical output will help you to make sure that it meets their needs.

It also helps you to tailor your outputs to make sure all your users are fully supported in using the outputs effectively. | [Guidance: User engagement top tips (Government Analysis Function)](https://analysisfunction.civilservice.gov.uk/policy-store/user-engagement-top-tips/) | - | What analytical question you are addressing? | Are questions suitably explicit and do they clearly reflect the evidence gaps the analysis is intended to fill?

Will the output align with overarching departmental or programme goals? | Having a clear understanding of the problem your team is trying to solve ensures that the analysis you design is fit for purpose.

If you do not know how your work is contributing to answering an analytical need, you may be unaware of important requirements or limitations for your part of the work. | [Guidance: The Aqua Book (HM Treasury) ](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf)


[Guidance: Analysis Functional Standard (Government Analysis Function)](https://www.gov.uk/government/publications/government-analysis-functional-standard--2)


[UKHSA Data Strategy (UK Health Security Agency)](https://intranet.ukhsa.gov.uk/sites/data-analytics-and-surveillance/SitePageModern/49668/data-strategy) | + | What analytical question you are addressing? | Are questions suitably explicit and do they clearly reflect the evidence gaps the analysis is intended to fill?

Will the output align with overarching departmental or programme goals? | Having a clear understanding of the problem your team is trying to solve ensures that the analysis you design is fit for purpose.

If you do not know how your work is contributing to answering an analytical need, you may be unaware of important requirements or limitations for your part of the work. | [Guidance: The Aqua Book (HM Treasury) ](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf)

[Guidance: Analysis Functional Standard (Government Analysis Function)](https://www.gov.uk/government/publications/government-analysis-functional-standard--2)

[UKHSA Data Strategy (UK Health Security Agency)](https://intranet.ukhsa.gov.uk/sites/data-analytics-and-surveillance/SitePageModern/49668/data-strategy) | | Is everyone aware of their role and responsibility in the process? | Is a Senior Responsible Officer (SRO) required as the analysis is business critical?

What is the role of the commissioner in your project? Are there any key changes to the publications that need flagging?

Does the assurer understand the analytical methods used in the project? Are there any skills gaps? | For effective quality assurance, you need to be clear on roles and responsibilities throughout the chain of production. It is not enough to say that an individual will carry out some QA.

Assigning the roles set out in the AQUA book provide a useful framework for considering the different ways QA should be built into the life cycle of a project.

For more information, see Roles and responsibilities section of this guidance. | [Guidance: The Aqua Book (HM Treasury)](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf) {% endcapture %} @@ -266,7 +266,7 @@ The table below gives some considerations when completing this section of the re |Guiding questions | Specific considerations | Why do I need to know the answer to this? | What help is available? | |------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Is all of your documentation about the project easy to find? | Is there a single location (for example, on GitHub or SharePoint) where all project documentation is either stored or linked?

Have you got a link to your project code repository within the documentation? | Your analysis must be well documented so that somebody new can understand it and pick it up. Poor documentation means that other people will not understand why the process is configured as it is, how the process works or how to run the process safely, potentially leading to errors. | [Guidance: The Aqua Book (HM Treasury)](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf)

[Guidance: QA of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html) | -| Have you got a consistent project structure set up? | Does the project structure align with other analytical projects in your organisation?

Is there a clear system to track version control within your project? | All projects should have appropriate version control including a clear system for version labelling and a version control log.

It is recommended to use a project template such as the [UKHSA Project Template](https://confluence.collab.test-and-trace.nhs.uk/display/QA/UKHSA+Project+Template). A template provides a consistent project structure and some built-in automated QA. | [UKHSA Project Template (GitHub link)](https://confluence.collab.test-and-trace.nhs.uk/display/QA/UKHSA+Project+Template)

[Guidance: GitHub docs (GitHub)](https://docs.github.com/en/get-started/start-your-journey/hello-world) | +| Have you got a consistent project structure set up? | Does the project structure align with other analytical projects in your organisation?

Is there a clear system to track version control within your project? | All projects should have appropriate version control including a clear system for version labelling and a version control log.

It is recommended to use a project template such as [govcookiecutter](https://github.com/best-practice-and-impact/govcookiecutter). A template provides a consistent project structure and some built-in automated QA. | [govcookiecutter (GitHub link)](https://github.com/best-practice-and-impact/govcookiecutter)

[Guidance: GitHub docs (GitHub)](https://docs.github.com/en/get-started/start-your-journey/hello-world) | | Is there a recorded plan for the analysis? | Has an appropriate plan been agreed with adequate consideration of time, resource quantity and skills required?

Will the proposed time frames allow for adequate quality assurance?

Where are the highest risk points for errors in the process? What measures do you or could you take to mitigate risk at these points? | Analysis will often involve a trade off between time, resource and quality.

Discussions about the desired and achievable levels of QA should take place at the very start of a project. The reality is that most analysis will be carried out under time and resource pressure and we will not be able to carry out all the QA activity we would ideally like to. In these circumstances, QA activities will need to be prioritised based on the risk of not carrying them out. | [Guidance: The Aqua Book (HM Treasury)](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf)

[The Government Data Quality Framework (Government Data Quality Hub)](https://www.gov.uk/government/publications/the-government-data-quality-framework/the-government-data-quality-framework)

[Guidance: Tips for urgent quality assurance of data (Government Analysis Function)](https://analysisfunction.civilservice.gov.uk/policy-store/tips-for-urgent-quality-assurance-of-data) | | Can you summarise and explain the end-to-end process of your analysis? | How does your work feed in to the bigger analytical picture? | Having an overview of the analysis (especially if you only work on part of it) ensures that you and your team understand how your work feeds into the wider product.

It can help you to identify potential quality risks or issues, both upstream and downstream of your own work as well as how your activity supports and underpins downstream processing. | [Generic Statistical Business Process Model (GSBPM; United Nations Economic Commision for Europe)](https://unece.org/statistics/modernstats/gsbpm) @@ -284,7 +284,7 @@ The table below gives some considerations when completing this section of the re | Guiding questions | Specific considerations | Why do I need to know the answer to this? | What help is available? | |-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Is the input data quality well-understood and sufficient for project needs? | Are the source, collection methods, size, accuracy, and precision of the data known? Have you checked for missing and duplicated data? Have you addressed these? Have the data been checked for any extreme or implausible values? Do any data quality concerns pose a risk for the final outcomes of the analysis? | The quality of input data directly affects the validity of any results or conclusions drawn from it. Understanding the data quality helps you assess the reliability and trustworthiness of findings. You should assess your datasets for missing values to understand which variables and records are affected, how much is missing and whether there might be bias in the missingness. Always tell your users about the prevalence and treatment of missing data. | [Guidance: Missing data (internal link)](missing-data) [Guidance: Quality statistics in government (Government Analysis Function)](https://analysisfunction.civilservice.gov.uk/policy-store/quality-statistics-in-government/) | +| Is the input data quality well-understood and sufficient for project needs? | Are the source, collection methods, size, accuracy, and precision of the data known? Have you checked for missing and duplicated data? Have you addressed these? Have the data been checked for any extreme or implausible values? Do any data quality concerns pose a risk for the final outcomes of the analysis? | The quality of input data directly affects the validity of any results or conclusions drawn from it. Understanding the data quality helps you assess the reliability and trustworthiness of findings. You should assess your datasets for missing values to understand which variables and records are affected, how much is missing and whether there might be bias in the missingness. Always tell your users about the prevalence and treatment of missing data. | [Guidance: Missing data (internal link)](missing-data)

[Guidance: Quality statistics in government (Government Analysis Function)](https://analysisfunction.civilservice.gov.uk/policy-store/quality-statistics-in-government/) | | How do you know the method you are using is appropriate? | Are the methods agreed to be the most suited for the project needs compared to other potential alternatives? Does the methodology deliver the required degree of certainty and precision? When changes have been made to methodologies, are they justified, well-documented, and clearly communicated? | You should be able to explain why the method(s) you use are suitable for this analysis and be able to support your choice with evidence. This might include reference to academic peer-reviewed publications or other projects that are similar. If you cannot explain why you chose the methods you use and why they are right for your analysis and the data you are using, you cannot be sure that your approach is sound. | | | Is the code or software functioning as expected? | Have an appropriate range of automated checks been built into the analytical pipeline? Has the code or other implementation of the analysis been checked by an independent analyst? Have intermediate outputs from every stage of analysis been checked? | You need to be sure that your analysis produces the outputs that you think it should and that the processes you run work as expected. If you cannot demonstrate that code and processes you have set up are functioning correctly, you cannot confirm the quality of the results. | [Guidance: RAP Framework - Bronze, Silver and Gold standards (internal link)](rap-framework) | | Do the outputs appear realistic? | Are there any anomalies or unexpected trends in the data? Have they been sufficiently investigated? Does the output appear realistic for the real-world behaviour that is being analysed? Are outputs consistent with results from historical data or other data from other regions? Have the methodology and outputs been peer reviewed to ensure they appear reasonable? | Stakeholders rely on analytical outputs to make informed decisions. You need to ensure that these decisions are based on accurate and plausible data, and so if the data looks different to previous trends this should be investigated and communicated clearly to users. | | @@ -302,10 +302,10 @@ The table below gives some considerations when completing this section of the re | Guiding questions | Specific considerations | Why do I need to know the answer to this? | What help is available? | |---------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Has the code been properly documented? | Has version control software such as Git and GitHub been used to track and manage changes? Is code documentation embedded in the project rather than saved elsewhere? Have functions been documented and wrapped up in a package where useful to do so? | Your code must be well documented so that somebody new can understand it and pick it up. Poor documentation means that other people will not understand why the process is configured as it is, how the process works or how to run the process safely, potentially leading to errors. Good version control ensures that you have a full understanding of when, why and how changes were made to your analysis process. If it is hard to track changes, this makes it hard to retrace steps if there is a problem and means you do not fully understand the process. | [Guidance: GitHub docs (GitHub)](https://docs.github.com/en/get-started/start-your-journey/hello-world) [Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html) | -| Is the process from initial data extraction to final report fully reproducible? | Without any input from the analytical project team, could a third party reproduce our results? Have manual steps in data extraction, analysis, and report creation been automated where possible? If mathematical formulas have been used to describe methodology, have these been presented with all terms and steps defined? Where manual steps were involved, have these been thoroughly documented? Has a standard operating procedure (SOP) been produced if necessary? Have the documentation and quality assurance logs been peer reviewed to ensure that the process is reproducible? If we repeat our processes with different software, will we get the same results? | If the process from initial extraction to the final report contains manual steps, then these steps need to be documented so that the team can understand the process. Manual steps can lead to a higher risk of human error, so they need to be clearly understood. | [Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html) [Guidance: The Aqua Book (HM Treasury)](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf) [Guidance: Reproducible Analytical Pipelines (RAP): an introduction (internal link)](rap) | -| Have best practices for coding been followed? | Has an agreed-upon style guide been followed in all of the code written for analysis? Does code adhere to best practice standards? Are there plans in place to ensure there is sufficient capability within the team to use and modify the pipeline as needed in the future? | If best practices have not been followed, there may be a higher risk of error. By understanding the team's agree-upon styles and standards, you can ensure consistency when modifying the pipeline. | [Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html) [Guidance: The Aqua Book (HM Treasury)](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf) [Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html) | -| Do you consistently use peer review to check scripts and code, documentation, implementation of methods, processes and outputs? | Have the methodology and outputs been peer reviewed to ensure they appear reasonable? Is your code or analysis ever peer reviewed by someone outside your team? | Peer review is a standard part of analysis best practice. It is helpful because it helps to identify where steps are unclear, documents are hard to understand or there might be problems with calculations or implementation of methods. Routine peer review helps to improve the quality of processes and to reduce risk by identifying potential problems. | [Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html) [Guidance: Quality statistics in government (Government Analysis Function)](https://analysisfunction.civilservice.gov.uk/policy-store/quality-statistics-in-government/#quality-assurance) | +| Has the code been properly documented? | Has version control software such as Git and GitHub been used to track and manage changes? Is code documentation embedded in the project rather than saved elsewhere? Have functions been documented and wrapped up in a package where useful to do so? | Your code must be well documented so that somebody new can understand it and pick it up. Poor documentation means that other people will not understand why the process is configured as it is, how the process works or how to run the process safely, potentially leading to errors. Good version control ensures that you have a full understanding of when, why and how changes were made to your analysis process. If it is hard to track changes, this makes it hard to retrace steps if there is a problem and means you do not fully understand the process. | [Guidance: GitHub docs (GitHub)](https://docs.github.com/en/get-started/start-your-journey/hello-world)

[Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html) | +| Is the process from initial data extraction to final report fully reproducible? | Without any input from the analytical project team, could a third party reproduce our results? Have manual steps in data extraction, analysis, and report creation been automated where possible? If mathematical formulas have been used to describe methodology, have these been presented with all terms and steps defined? Where manual steps were involved, have these been thoroughly documented? Has a standard operating procedure (SOP) been produced if necessary? Have the documentation and quality assurance logs been peer reviewed to ensure that the process is reproducible? If we repeat our processes with different software, will we get the same results? | If the process from initial extraction to the final report contains manual steps, then these steps need to be documented so that the team can understand the process. Manual steps can lead to a higher risk of human error, so they need to be clearly understood. | [Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html)

[Guidance: The Aqua Book (HM Treasury)](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf)

[Guidance: Reproducible Analytical Pipelines (RAP): an introduction (internal link)](rap) | +| Have best practices for coding been followed? | Has an agreed-upon style guide been followed in all of the code written for analysis? Does code adhere to best practice standards? Are there plans in place to ensure there is sufficient capability within the team to use and modify the pipeline as needed in the future? | If best practices have not been followed, there may be a higher risk of error. By understanding the team's agree-upon styles and standards, you can ensure consistency when modifying the pipeline. | [Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html)

[Guidance: The Aqua Book (HM Treasury)](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/416478/aqua_book_final_web.pdf)

[Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html) | +| Do you consistently use peer review to check scripts and code, documentation, implementation of methods, processes and outputs? | Have the methodology and outputs been peer reviewed to ensure they appear reasonable? Is your code or analysis ever peer reviewed by someone outside your team? | Peer review is a standard part of analysis best practice. It is helpful because it helps to identify where steps are unclear, documents are hard to understand or there might be problems with calculations or implementation of methods. Routine peer review helps to improve the quality of processes and to reduce risk by identifying potential problems. | [Guidance: Quality Assurance of Code for Analysis and Research (Government Analysis Function)](https://best-practice-and-impact.github.io/qa-of-code-guidance/intro.html)

[Guidance: Quality statistics in government (Government Analysis Function)](https://analysisfunction.civilservice.gov.uk/policy-store/quality-statistics-in-government/#quality-assurance) | {% endcapture %} @@ -397,4 +397,4 @@ Below is a summary of five key documents as they relate to QA. This is not a com 1. [Government Analysis Function: Communicating quality, uncertainty and change](https://analysisfunction.civilservice.gov.uk/policy-store/communicating-quality-uncertainty-and-change/) 1. [Office for Statistics Regulation: Regulatory guidance - thinking about quality when producing statistics](https://osr.statisticsauthority.gov.uk/publication/regulatory-guidance-thinking-about-quality-when-producing-statistics/pages/2/) 1. [The Aqua Book: guidance on producing quality analysis for government](https://www.gov.uk/government/publications/the-aqua-book-guidance-on-producing-quality-analysis-for-government) -1. [UK Statistics Authority: Code of Practice for Statistics](https://code.statisticsauthority.gov.uk/the-code/) \ No newline at end of file +1. [UK Statistics Authority: Code of Practice for Statistics](https://code.statisticsauthority.gov.uk/the-code/) From 9052830d61ec2dde8322c638aa32a8a52a20ce0b Mon Sep 17 00:00:00 2001 From: Holly Goss Date: Wed, 16 Oct 2024 14:51:42 +0100 Subject: [PATCH 4/5] Added new charts and changed wording on shorthand --- .gitignore | 3 +- .../img/missing data/missing-data-ex5.svg | 70 ++ .../img/missing data/missing-data-ex6.svg | 73 +++ .../missing-data_bad-chart-example.png | Bin 13983 -> 0 bytes .../missing-data_good-chart-example.png | Bin 18902 -> 0 bytes docs/missing-data.md | 603 +++++++++++++----- 6 files changed, 576 insertions(+), 173 deletions(-) create mode 100644 docs/assets/img/missing data/missing-data-ex5.svg create mode 100644 docs/assets/img/missing data/missing-data-ex6.svg delete mode 100644 docs/assets/img/missing data/missing-data_bad-chart-example.png delete mode 100644 docs/assets/img/missing data/missing-data_good-chart-example.png diff --git a/.gitignore b/.gitignore index f15b7e7..235dcbc 100644 --- a/.gitignore +++ b/.gitignore @@ -8,4 +8,5 @@ # Local testing environment files Gemfile.lock -docs/_site/ \ No newline at end of file +docs/_site/ +.Rproj.user diff --git a/docs/assets/img/missing data/missing-data-ex5.svg b/docs/assets/img/missing data/missing-data-ex5.svg new file mode 100644 index 0000000..b5e67aa --- /dev/null +++ b/docs/assets/img/missing data/missing-data-ex5.svg @@ -0,0 +1,70 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +0 +1 +2 +3 +4 +5 + + + + + + + +2018 +2019 +2020 +2021 +2022 +2023 +Year +Value + + diff --git a/docs/assets/img/missing data/missing-data-ex6.svg b/docs/assets/img/missing data/missing-data-ex6.svg new file mode 100644 index 0000000..e08de5a --- /dev/null +++ b/docs/assets/img/missing data/missing-data-ex6.svg @@ -0,0 +1,73 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +No data for 2020 +(COVID-19 pandemic) + + +0 +1 +2 +3 +4 +5 + + + + + + + +2018 +2019 +2020 +2021 +2022 +2023 +Year +Value + + diff --git a/docs/assets/img/missing data/missing-data_bad-chart-example.png b/docs/assets/img/missing data/missing-data_bad-chart-example.png deleted file mode 100644 index d23a14e96e2c98df0b28ff9bdd2e0daa39684afe..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 13983 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 O2p7+(D&)zT-2Y#TnpI8xSK~GE5)HmhZ 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�uE;%EL$Ej>L6 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 F{{#2Hfl&Ye diff --git a/docs/missing-data.md b/docs/missing-data.md index eb97f73..e521a4f 100644 --- a/docs/missing-data.md +++ b/docs/missing-data.md @@ -1,185 +1,379 @@ --- title: "Handling missing data" layout: guidance-page +editor_options: + markdown: + wrap: 72 --- - > ## Main messages -> - Try to understand the causes of missing data and minimise the chance of it happening. -> - Assess input data for missing values to understand which variables and records are affected, how much is missing and whether there might be bias in the missingness. -> - Decide how to deal with missing data: update, discard or replace it. -> - Tell your users about the prevalence and treatment of missing data. +> +> - Try to understand the causes of missing data and minimise the +> chance of it happening. +> - Assess input data for missing values to understand which variables +> and records are affected, how much is missing and whether there +> might be bias in the missingness. +> - Decide how to deal with missing data: update, discard or replace +> it. +> - Tell your users about the prevalence and treatment of missing +> data. {% include sources-text.md %} ## Assessing missingness before analysis begins -Data is missing when no value is provided for a given variable. This is common for many datasets and missing values can reduce statistical power and introduce bias if not handled appropriately. +Data is missing when no value is provided for a given variable. This is +common for many datasets and missing values can reduce statistical power +and introduce bias if not handled appropriately. -You should try to understand the extent, causes and type of missingness as soon as you receive your input data. This knowledge will help inform how you handle the data, analyse it and communicate your results. The earlier an issue can be recognised, the quicker a plan can be developed for how to address it. +You should try to understand the extent, causes and type of missingness +as soon as you receive your input data. This knowledge will help inform +how you handle the data, analyse it and communicate your results. The +earlier an issue can be recognised, the quicker a plan can be developed +for how to address it. ### Check for presence and extent of missingness -You should inspect for missingness each time you receive a dataset, whether it's part of a routine or one-off data collection. -This could be as simple as counting or visualising the missing values in your dataset to understand their volume and location. Most software records missing data as a blank value or as ‘NA’ (not available), but check with your data providers in case they have used other special symbols. Pay particular attention to unexpected patterns, which may expose new underlying data quality issues. +You should inspect for missingness each time you receive a dataset, +whether it's part of a routine or one-off data collection. -Input validation tests (‘assertions’) are also encouraged early in your analytical pipelines so that you can 'sense check' your data. These tests should be automated when you need to re-run the same checks frequently, such as for routine data collections, for greater efficiency (according to principles of [Reproducible Analytical Pipelines (RAP)](rap)). +This could be as simple as counting or visualising the missing values in +your dataset to understand their volume and location. Most software +records missing data as a blank value or as ‘NA’ (not available), but +check with your data providers in case they have used other special +symbols. Pay particular attention to unexpected patterns, which may +expose new underlying data quality issues. -You should be aware of whose job it is to check for missing data. The responsible analyst has ownership of missing data and that the assurer must ensure that checks have taken place. You can refer to our [quality assurance guidance](quality-assurance) for further information. +Input validation tests (‘assertions’) are also encouraged early in your +analytical pipelines so that you can 'sense check' your data. These +tests should be automated when you need to re-run the same checks +frequently, such as for routine data collections, for greater efficiency +(according to principles of [Reproducible Analytical Pipelines +(RAP)](rap)). +You should be aware of whose job it is to check for missing data. The +responsible analyst has ownership of missing data and that the assurer +must ensure that checks have taken place. You can refer to our [quality +assurance guidance](quality-assurance) for further information. ### Understand causes of missingness -The presence of missing data may indicate problems with the way the data has been collected or processed. Understanding the causes can help you to fix the underlying problem and allow you to be more transparent with users of your data. -Some examples include: +The presence of missing data may indicate problems with the way the data +has been collected or processed. Understanding the causes can help you +to fix the underlying problem and allow you to be more transparent with +users of your data. -- measurement error, which could be caused by using defective tools for data collection; for example, a faulty machine may fail to take a reading from a patient’s sample -- handling errors, which can be caused by administrative lapses during data entry; for example, someone might fail to transcribe a handwritten value into a recording system -- data processing errors, which can be introduced when handling or analysing data; for example, naively coercing a text string to numeric type in R will result in a ‘NA’ value (so '4%' would become 'NA' rather than 4) -- survey-related errors, including non-response and sampling biases; these can occur when participants fail to respond to a question and when a survey sample is unrepresentative of the target population -- data providers could not or did not provide data ahead of deadlines +Some examples include: +- measurement error, which could be caused by using defective tools + for data collection; for example, a faulty machine may fail to take + a reading from a patient’s sample +- handling errors, which can be caused by administrative lapses during + data entry; for example, someone might fail to transcribe a + handwritten value into a recording system +- data processing errors, which can be introduced when handling or + analysing data; for example, naively coercing a text string to + numeric type in R will result in a ‘NA’ value (so '4%' would become + 'NA' rather than 4) +- survey-related errors, including non-response and sampling biases; + these can occur when participants fail to respond to a question and + when a survey sample is unrepresentative of the target population +- data providers could not or did not provide data ahead of deadlines ### Understand the type of missingness -It is important to understand how missingness may be distributed through your dataset and whether it can be explained. This impacts the strategies you might take to replace missing values or analyse your data. - -Typically, [three main types of missing data are recognised](https://stefvanbuuren.name/fimd/sec-MCAR.html). Data for a given variable can be: - -{% capture card_content_1 %} -When missingness is independent of any variable. An example of this would be if a batch of blood samples from a fully randomised set of patients is dropped and broken. This is true randomness. -{% endcapture %} - -{% capture card_content_2 %} -When there’s a pattern to the missingness that can be explained by another variable. For example, you might have missing blood-sample data that can be explained by men being less likely than women to submit a sample. Values are still missing at random within each group, but one group has more missing values than the other. A better term is perhaps ‘missing conditionally at random’. -{% endcapture %} - -{% capture card_content_3 %} -When there’s a pattern of missingness that’s unrelated to any variable we know about. This might occur if blood samples became contaminated and unusable due to the failure of a certain manufacturer’s vials, a variable we didn’t collect information about. -{% endcapture %} - - -{% include cards-container-start.html %} - {% include card.html content=card_content_1 title="Missing completely at random (MCAR)" %} - {% include card.html content=card_content_2 title="Missing at random (MAR)" %} - {% include card.html content=card_content_3 title="Missing not at random (MNAR)" %} -{% include cards-container-end.html %} - - -It can be difficult in practice to identify the type of missing data. In particular, the difference between MCAR and MNAR hinges on a relationship that may or may not exist with variables you haven’t collected. MAR may be a good default position if you’ve designed your collection to cover variables that explain the missingness, but they may not be obvious and it may not be practical to do this. +It is important to understand how missingness may be distributed through +your dataset and whether it can be explained. This impacts the +strategies you might take to replace missing values or analyse your +data. + +Typically, [three main types of missing data are +recognised](https://stefvanbuuren.name/fimd/sec-MCAR.html). Data for a +given variable can be: + +{% capture card_content_1 %} When missingness is independent of any +variable. An example of this would be if a batch of blood samples from a +fully randomised set of patients is dropped and broken. This is true +randomness. {% endcapture %} + +{% capture card_content_2 %} When there’s a pattern to the missingness +that can be explained by another variable. For example, you might have +missing blood-sample data that can be explained by men being less likely +than women to submit a sample. Values are still missing at random within +each group, but one group has more missing values than the other. A +better term is perhaps ‘missing conditionally at random’. {% endcapture +%} + +{% capture card_content_3 %} When there’s a pattern of missingness +that’s unrelated to any variable we know about. This might occur if +blood samples became contaminated and unusable due to the failure of a +certain manufacturer’s vials, a variable we didn’t collect information +about. {% endcapture %} + +{% include cards-container-start.html %} {% include card.html +content=card_content_1 title="Missing completely at random (MCAR)" %} {% +include card.html content=card_content_2 title="Missing at random (MAR)" +%} {% include card.html content=card_content_3 title="Missing not at +random (MNAR)" %} {% include cards-container-end.html %} + +It can be difficult in practice to identify the type of missing data. In +particular, the difference between MCAR and MNAR hinges on a +relationship that may or may not exist with variables you haven’t +collected. MAR may be a good default position if you’ve designed your +collection to cover variables that explain the missingness, but they may +not be obvious and it may not be practical to do this. ## Handle missing data -According to the [Code of Practice for Statistics](https://code.statisticsauthority.gov.uk/the-code/), producers of statistical publications are required to 'identify and address' any 'limitations in data sources'. As such, you must decide how to handle missing data in order to maintain reliability and transparency of your outputs. This is a good principle to follow even if you are not producing a statistical publication. -This section describes three broad approaches for dealing with missing data: +According to the [Code of Practice for +Statistics](https://code.statisticsauthority.gov.uk/the-code/), +producers of statistical publications are required to 'identify and +address' any 'limitations in data sources'. As such, you must decide how +to handle missing data in order to maintain reliability and transparency +of your outputs. This is a good principle to follow even if you are not +producing a statistical publication. -1. Update the missing data. -1. Discard the missing data. -1. Generate replacement values. +This section describes three broad approaches for dealing with missing +data: +1. Update the missing data. +2. Discard the missing data. +3. Generate replacement values. ### Update the missing data -In the first instance, you should try to improve completion rates. Failing this, you may also be able to recover missing data by returning to the source of collection, by using data collected from another source, or by deductive reasoning on the basis of other variables. + +In the first instance, you should try to improve completion rates. +Failing this, you may also be able to recover missing data by returning +to the source of collection, by using data collected from another +source, or by deductive reasoning on the basis of other variables. #### Return to the source -It may be possible to go back to your data suppliers and recover data that was lost through administrative error, for example, or to request a re-collection of data for the cases where it’s missing. This may be difficult in practice, however, because of the effort required. (The [Code of Practice for Statistics](https://code.statisticsauthority.gov.uk/the-code/) also states that you must ‘reduce the burden on those providing their information, and on those involved in collecting, recording and supplying data’.) + +It may be possible to go back to your data suppliers and recover data +that was lost through administrative error, for example, or to request a +re-collection of data for the cases where it’s missing. This may be +difficult in practice, however, because of the effort required. (The +[Code of Practice for +Statistics](https://code.statisticsauthority.gov.uk/the-code/) also +states that you must ‘reduce the burden on those providing their +information, and on those involved in collecting, recording and +supplying data’.) #### Infer from other variables -You may be able to use other variables to deduce the true value of a missing data point. For example, if a user writes ‘Kent’ in a ‘county’ field, but doesn’t complete the ‘region’ field, it can be assumed that the region is ‘South East England’. Arguably the data isn’t really ‘missing’ because it’s derived from other fields. As a result, you should consider whether it’s worth collecting this kind of derived information in the first place. -Regardless, you should consider carefully whether your inference is appropriate. For example, you are likely to make an error if you infer gender or ethnicity from a person’s name. +You may be able to use other variables to deduce the true value of a +missing data point. For example, if a user writes ‘Kent’ in a ‘county’ +field, but doesn’t complete the ‘region’ field, it can be assumed that +the region is ‘South East England’. Arguably the data isn’t really +‘missing’ because it’s derived from other fields. As a result, you +should consider whether it’s worth collecting this kind of derived +information in the first place. + +Regardless, you should consider carefully whether your inference is +appropriate. For example, you are likely to make an error if you infer +gender or ethnicity from a person’s name. #### Match to another dataset -You might be able to fill gaps in your collection by matching to another dataset on some unique identifier, like patient NHS numbers. The dataset being joined might not be complete either, but the combination of sources could help to reduce missingness. If the dataset being joined has complete information for the variable of interest, you should consider whether it's worth collecting that data or whether you should prefer to join it from secondary sources. -Beware: the matched data could have its own biases. [The Goldacre Review](https://www.gov.uk/government/publications/better-broader-safer-using-health-data-for-research-and-analysis) cites an Electronic Health Record (EHR) example for which completeness of ethnicity data is improved by matching Hospital Episode Statistics (HES), though this only improves coverage for the population subset that is most ill. +You might be able to fill gaps in your collection by matching to another +dataset on some unique identifier, like patient NHS numbers. The dataset +being joined might not be complete either, but the combination of +sources could help to reduce missingness. If the dataset being joined +has complete information for the variable of interest, you should +consider whether it's worth collecting that data or whether you should +prefer to join it from secondary sources. + +Beware: the matched data could have its own biases. [The Goldacre +Review](https://www.gov.uk/government/publications/better-broader-safer-using-health-data-for-research-and-analysis) +cites an Electronic Health Record (EHR) example for which completeness +of ethnicity data is improved by matching Hospital Episode Statistics +(HES), though this only improves coverage for the population subset that +is most ill. ### Discard the missing data -You could analyse your dataset by ignoring missingness in some way. This may only be useful when your dataset is mostly complete or if you have reason to believe that your missing data is MCAR. + +You could analyse your dataset by ignoring missingness in some way. This +may only be useful when your dataset is mostly complete or if you have +reason to believe that your missing data is MCAR. For example, you could use only the: -- complete cases, which are the records that have a response value in every variable in the dataset (‘listwise deletion’) -- available cases, which are the non-missing values that remain within a given variable (a process known as ‘pairwise deletion’) +- complete cases, which are the records that have a response value in + every variable in the dataset (‘listwise deletion’) +- available cases, which are the non-missing values that remain within + a given variable (a process known as ‘pairwise deletion’) -Both approaches are straightforward and require no additional calculation. Of these, complete-case analysis may be preferred where there is little data missing across the whole dataset, since the available-case approach could result in different samples being used for each variable in your analysis. Both methods ignore whether there’s any bias in the missingness and could result in a lot of useful data being thrown away, particularly if you use only the complete cases. +Both approaches are straightforward and require no additional +calculation. Of these, complete-case analysis may be preferred where +there is little data missing across the whole dataset, since the +available-case approach could result in different samples being used for +each variable in your analysis. Both methods ignore whether there’s any +bias in the missingness and could result in a lot of useful data being +thrown away, particularly if you use only the complete cases. ### Generate replacement data -There are several methods for generating replacements for missing values. The method used will depend on the type and cause of your missingness, as well as how much of it is missing. This section is intended as a non-exhaustive and non-technical introduction to some possible approaches. + +There are several methods for generating replacements for missing +values. The method used will depend on the type and cause of your +missingness, as well as how much of it is missing. This section is +intended as a non-exhaustive and non-technical introduction to some +possible approaches. #### Single imputation -[Single imputation methods](https://www.researchgate.net/profile/Geert-Van-Der-Heijden/publication/6814409_Review_A_gentle_introduction_to_imputation_of_missing_values/links/6048b70a299bf1e0786bfbfe/Review-A-gentle-introduction-to-imputation-of-missing-values.pdf) are simple approaches that use non-missing values to generate replacements for missing values. -Average imputation is when you generate a replacement value from a simple average of the non-missing values within a variable. This is typically the mean for continuous variables and the mode (most common) value for categorical variables. Note that mean imputation will maintain the overall mean of a variable, but will reduce its variance. +[Single imputation +methods](https://www.researchgate.net/profile/Geert-Van-Der-Heijden/publication/6814409_Review_A_gentle_introduction_to_imputation_of_missing_values/links/6048b70a299bf1e0786bfbfe/Review-A-gentle-introduction-to-imputation-of-missing-values.pdf) +are simple approaches that use non-missing values to generate +replacements for missing values. -Regression imputation is when you predict missing values from a model involving other variables in the dataset. For example, height and weight may be correlated, so regression imputation could help you to infer missing values. This is preferential to average imputation because it takes account of the relationships between variables, but it can be sensitive to outliers or misspecification of the model. +Average imputation is when you generate a replacement value from a +simple average of the non-missing values within a variable. This is +typically the mean for continuous variables and the mode (most common) +value for categorical variables. Note that mean imputation will maintain +the overall mean of a variable, but will reduce its variance. -#### Interpolation -If you have data collected over time, you can use prior information to generate a replacement value. The simplest approach would be to reuse the last known value, known as 'Last Observation Carried Forward' (LOCF). This within-record context helps reduce bias but ignores the potential and magnitude of change. +Regression imputation is when you predict missing values from a model +involving other variables in the dataset. For example, height and weight +may be correlated, so regression imputation could help you to infer +missing values. This is preferential to average imputation because it +takes account of the relationships between variables, but it can be +sensitive to outliers or misspecification of the model. -Interpolation is typically used to predict a value for an unsampled point, but we can use it to replace missing values as well. For example, you could fit a model to the data over time and predict the missing value. The quality of this method is dependent on selecting an appropriate model for the data. It could be a simple linear model if appropriate, for example, or could build in seasonality. +#### Interpolation -#### Multiple imputation -[Multiple imputation](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2714692/) acknowledges that there’s uncertainty in generating one replacement value, like in single imputation. To overcome this, you can generate more than one prediction. +If you have data collected over time, you can use prior information to +generate a replacement value. The simplest approach would be to reuse +the last known value, known as 'Last Observation Carried Forward' +(LOCF). This within-record context helps reduce bias but ignores the +potential and magnitude of change. -The general process for multiple imputation involves two steps: +Interpolation is typically used to predict a value for an unsampled +point, but we can use it to replace missing values as well. For example, +you could fit a model to the data over time and predict the missing +value. The quality of this method is dependent on selecting an +appropriate model for the data. It could be a simple linear model if +appropriate, for example, or could build in seasonality. -1. Create many different ‘complete’ copies of the dataset where a statistical model has been used to generate plausible imputations. -2. Fit your model to each dataset copy and pool the results. +#### Multiple imputation -One specific technique is called [Multiple Imputation by Chained Equations](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3074241/) (MICE). It follows these steps: +[Multiple +imputation](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2714692/) +acknowledges that there’s uncertainty in generating one replacement +value, like in single imputation. To overcome this, you can generate +more than one prediction. -1. Perform simple imputation (for example, mean imputation) for all variables. These will be treated as ‘placeholders’ for now. -2. For one variable, remove the placeholders and regress against the other variables. Use the predictions to replace the missing values. -3. Repeat the steps above for the remaining variables in the dataset to complete one ‘cycle’. -4. Perform multiple cycles to help converge the imputations. +The general process for multiple imputation involves two steps: -Incorporating variance into the replacement values can result in a better estimate of ‘true’ values and therefore a less-biased outcome compared to single imputation. The method is more complicated, however, given the need for selecting and specifying an appropriate imputation model. It may also be more difficult to communicate this method to end-users. +1. Create many different ‘complete’ copies of the dataset where a + statistical model has been used to generate plausible imputations. +2. Fit your model to each dataset copy and pool the results. + +One specific technique is called [Multiple Imputation by Chained +Equations](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3074241/) +(MICE). It follows these steps: + +1. Perform simple imputation (for example, mean imputation) for all + variables. These will be treated as ‘placeholders’ for now. +2. For one variable, remove the placeholders and regress against the + other variables. Use the predictions to replace the missing values. +3. Repeat the steps above for the remaining variables in the dataset to + complete one ‘cycle’. +4. Perform multiple cycles to help converge the imputations. + +Incorporating variance into the replacement values can result in a +better estimate of ‘true’ values and therefore a less-biased outcome +compared to single imputation. The method is more complicated, however, +given the need for selecting and specifying an appropriate imputation +model. It may also be more difficult to communicate this method to +end-users. ## Communicate about missing data -Transparency is required when reporting on the prevalence and handling of missingness, statistical methods for imputation, and the limitations of the approaches taken. However, the level of detail should be proportionate to the complexity of methods used. -When you publish your report you should describe the characteristics of missing data and how it was handled. There are usually three places where you can do this: +Transparency is required when reporting on the prevalence and handling +of missingness, statistical methods for imputation, and the limitations +of the approaches taken. However, the level of detail should be +proportionate to the complexity of methods used. -1. A detailed breakdown in a dedicated Quality and Methodology Information (QMI) document published alongside your release. -1. A brief explanation within the text of the published report. -1. In the documentation for data releases, such as the notes and placeholder symbols of a published spreadsheet. +When you publish your report you should describe the characteristics of +missing data and how it was handled. There are usually three places +where you can do this: +1. A detailed breakdown in a dedicated Quality and Methodology + Information (QMI) document published alongside your release. +2. A brief explanation within the text of the published report. +3. In the documentation for data releases, such as the notes and + placeholder symbols of a published spreadsheet. ### 1. In the Quality and Methodology Information (QMI) report -We recommend that you create a separate QMI document to provide extra detail that caters to the needs of different users and provides full transparency about how the outputs were produced. -Examples of specific information to include are: +We recommend that you create a separate QMI document to provide extra +detail that caters to the needs of different users and provides full +transparency about how the outputs were produced. -- the volume of missing data by variable -- biases in the presence of missing data, for example if prevalence was greater for records with certain characteristics -- possible reasons for missing data, especially if the rate is different compared to prior or similar publications -- any statistical methods used to take account of missingness, such as imputation or removal -- steps you will take to maximise completeness in future, if possible +Examples of specific information to include are: +- the volume of missing data by variable +- biases in the presence of missing data, for example if prevalence + was greater for records with certain characteristics +- possible reasons for missing data, especially if the rate is + different compared to prior or similar publications +- any statistical methods used to take account of missingness, such as + imputation or removal +- steps you will take to maximise completeness in future, if possible ### 2. In written reports #### The main body text -The main publication should include brief information about data, quality, and methods, but only to the extent necessary to understand the data. The report should refer users to the QMI document for greater depth on missing data, where appropriate. - -If the incomplete data is because of a data provider failing to submit, explain at the start of the affected section the figures impacted and outline plans for when and how updates will be made once the data does become available. - -The [Government Data Quality Framework](https://www.gov.uk/government/publications/the-government-data-quality-framework/the-government-data-quality-framework-guidance) asks producers to communicate the trade-offs between timeliness of data and its completeness. Missing data may be a consequence of needing to publish within a given time frame, which is perhaps more likely in an urgent setting like a national health threat. In these cases, it's important to highlight that missing data may become available in future and so a ‘provisional’ label could be applied to data or analysis to make this clear to users. Information about the impact of late-arriving data can also be expressed in a separate QMI report published alongside the main report. +The main publication should include brief information about data, +quality, and methods, but only to the extent necessary to understand the +data. The report should refer users to the QMI document for greater +depth on missing data, where appropriate. + +If the incomplete data is because of a data provider failing to submit, +explain at the start of the affected section the figures impacted and +outline plans for when and how updates will be made once the data does +become available. + +The [Government Data Quality +Framework](https://www.gov.uk/government/publications/the-government-data-quality-framework/the-government-data-quality-framework-guidance) +asks producers to communicate the trade-offs between timeliness of data +and its completeness. Missing data may be a consequence of needing to +publish within a given time frame, which is perhaps more likely in an +urgent setting like a national health threat. In these cases, it's +important to highlight that missing data may become available in future +and so a ‘provisional’ label could be applied to data or analysis to +make this clear to users. Information about the impact of late-arriving +data can also be expressed in a separate QMI report published alongside +the main report. #### Strategies for tables and charts -You should represent missing data in data summaries like tables and charts so that the user is aware that data is incomplete. This will also ensure that missingness is acknowledged if the table or chart are used elsewhere in isolation and out of context. -Specifically for tables, you must use placeholder symbols that highlight when a value is missing. [The Government Analysis Function guidance on symbols](https://analysisfunction.civilservice.gov.uk/policy-store/symbols-in-tables-definitions-and-help/) suggests using '[b]' for a break in time series, or '[u]' if the value is of low reliability, which could happen when summarising a variable that contains a lot of missing data. To give an example: if data wasn't collected in 2020 due to the coronavirus pandemic, a placeholder symbol '[b]' should be given in a table to highlight the break to users. +You should represent missing data in data summaries like tables and +charts so that the user is aware that data is incomplete. This will also +ensure that missingness is acknowledged if the table or chart are used +elsewhere in isolation and out of context. -A placeholder symbol allows you to provide information about why a data point is missing, which is not apparent if you leave the cell blank. A blank cell may also lead to accessibility issues for users of assistive technology. +Specifically for tables, you must use placeholder symbols that highlight +when a value is missing. [The Government Analysis Function guidance on +symbols](https://analysisfunction.civilservice.gov.uk/policy-store/symbols-in-tables-definitions-and-help/) +suggests using '[b]' for a break in time series, or '[u]' if the value +is of low reliability, which could happen when summarising a variable +that contains a lot of missing data. To give an example: if data wasn't +collected in 2020 due to the coronavirus pandemic, a placeholder symbol +'[b]' should be given in a table to highlight the break to users. -Where data is missing, you should include a note under each affected table or chart to explain how it has been impacted by the missing data and explain why. +A placeholder symbol allows you to provide information about why a data +point is missing, which is not apparent if you leave the cell blank. A +blank cell may also lead to accessibility issues for users of assistive +technology. +Where data is missing, you should include a note under each affected +table or chart to explain how it has been impacted by the missing data +and explain why. -{% capture card_content_4 %} -Example 1: table of fictional annual values, England, 2018 to 2023. +{% capture card_content_4 %} Example 1: table of fictional annual +values, England, 2018 to 2023. | Year | Value | |------|-------| @@ -189,10 +383,11 @@ Example 1: table of fictional annual values, England, 2018 to 2023. | 2021 | 4 | | 2022 | 3 | | 2023 | 5 | + {% endcapture %} -{% capture card_content_5 %} -Example 2: table of fictional annual values, England, 2018 to 2023. +{% capture card_content_5 %} Example 2: table of fictional annual +values, England, 2018 to 2023. | Year | Value | |------|-------| @@ -203,19 +398,26 @@ Example 2: table of fictional annual values, England, 2018 to 2023. | 2022 | 3 | | 2023 | 5 | -Note: The shorthand '[b]' is used to denote where there was a break in the time series due to the coronavirus (COVID-19) pandemic. -{% endcapture %} - -{% include cards-container-start.html %} - {% include card.html content=card_content_4 title="❌ To be avoided: leaving a blank space in a table where data is missing." %} - {% include card.html content=card_content_5 title="✔️ Best practice: use a placeholder symbol to indicate that data is missing and include a note beneath the table." %} -{% include cards-container-end.html %} +Note: The shorthand '[b]' is used to denote where there was a break in +the time series due to the coronavirus (COVID-19) pandemic. {% +endcapture %} +{% include cards-container-start.html %} {% include card.html +content=card_content_4 title="❌ To be avoided: leaving a blank space in +a table where data is missing." %} {% include card.html +content=card_content_5 title="✔️ Best practice: use a placeholder symbol +to indicate that data is missing and include a note beneath the table." +%} {% include cards-container-end.html %} -Where a value has been estimated or imputed, official guidance suggests adding '[e]' for estimated. As an example, let's say that we interpolated the value missing in 2020. When you present this data in a table, you should add the placeholder symbol '[e]' in a separate column, in this case for the year 2020, and include a short text note underneath the table explaining the shorthand. Avoid adding more than one value or piece of information to a single cell, as this can be difficult to interpret for users of assistive technology. +Where a value has been estimated or imputed, official guidance suggests +adding '[e]' for estimated. As an example, let's say that we +interpolated the value missing in 2020. When using a presentation table, +e.g. in a report, you can place shorthand in cells alongside a data +point. In this case for the year 2020, we have shown the shorthand '[e]' +and included a short note underneath the table explaining the shorthand. -{% capture card_content_6 %} -Example 3: table of fictional annual values, England, 2018 to 2023. +{% capture card_content_6 %} Example 3: table of fictional annual +values, England, 2018 to 2023. | Year | Value | |------|-------| @@ -225,58 +427,76 @@ Example 3: table of fictional annual values, England, 2018 to 2023. | 2021 | 4 | | 2022 | 3 | | 2023 | 5 | -{% endcapture %} -{% capture card_content_7 %} -Example 4: table of fictional annual values, England, 2018 to 2023. - -| Year | Value | Note | -|------|-------|------| -| 2018 | 2 | | -| 2019 | 3 | | -| 2020 | 4 | [e] | -| 2021 | 4 | | -| 2022 | 3 | | -| 2023 | 5 | | - -Note: The shorthand '[e]' is used to indicate that the value in 2020 has been estimated. {% endcapture %} -{% include cards-container-start.html %} - {% include card.html content=card_content_6 title="❌ To be avoided: leaving a blank space in a table where data is missing." %} - {% include card.html content=card_content_7 title="✔️ Best practice: use a placeholder symbol to indicate that data has been estimated and include a note beneath the table." %} -{% include cards-container-end.html %} - - -You should also highlight discontinuities in time series data when presenting charts, for example by leaving a gap between points in a line chart to show where data is missing between them. You could also use dashed lines or shade the chart background to highlight where data is missing, and add a short text note underneath to explain the reason. - - -{% capture card_content_8 %} -Example 5: line chart of fictional annual values, England, 2018 to 2023. - -A line chart which does not clearly show that there is a missing value - -This figure shows a line chart with a discontinuity. It joins two data points in 2019 and 2021, despite a missing data point in 2020. +{% capture card_content_7 %} Example 4: table of fictional annual +values, England, 2018 to 2023. + +| Year | Value | +|----------|-------| +| 2018 | 2 | +| 2019 | 3 | +| 2020 [e] | 4 | +| 2021 | 4 | +| 2022 | 3 | +| 2023 | 5 | + +Note: The shorthand '[e]' is used to indicate that the value in 2020 has +been estimated. {% endcapture %} + +If you were presenting this data in a spreadsheet, you should add the +placeholder symbol '[e]' in a separate note column. When working in +spreadsheets, always avoid adding more than one value or piece of +information to a single cell, as this can be difficult to interpret for +users of assistive technology. For example, if you want to sum a column +but one of the data points has a shorthand marker next to it, the data +point will be ignored. + +{% include cards-container-start.html %} {% include card.html +content=card_content_6 title="❌ To be avoided: leaving a blank space in +a table where data is missing." %} {% include card.html +content=card_content_7 title="✔️ Best practice: use a placeholder symbol +to indicate that data has been estimated and include a note beneath the +table." %} {% include cards-container-end.html %} + +You should also highlight discontinuities in time series data when +presenting charts, for example by leaving a gap between points in a line +chart to show where data is missing between them. You could also use +dashed lines or shade the chart background to highlight where data is +missing, and add a short text note underneath to explain the reason. + +{% capture card_content_8 %} Example 5: line chart of fictional annual +values, England, 2018 to 2023. + +A line chart which does not clearly show that there is a missing value + +This figure shows a line chart with a discontinuity. It joins two data +points in 2019 and 2021, despite a missing data point in 2020. {% endcapture %} -{% capture card_content_9 %} -Example 6: line chart of fictional annual values, England, 2018 to 2023. - -A line chart which clearly shows a missing value by leaving a gap in the line, marking out the gap with dashed lines and an annotation +{% capture card_content_9 %} Example 6: line chart of fictional annual +values, England, 2018 to 2023. -This figure shows a line chart with a discontinuity. It leaves a gap in the line and marks out the gap with two vertical dashed lines and annotation stating the data was not collected in 2020 due to the coronavirus (COVID-19) pandemic. -{% endcapture %} +A line chart which clearly shows a missing value by leaving a gap in the line, marking out the gap with dashed lines and an annotation -{% include cards-container-start.html %} - {% include card.html content=card_content_8 title="❌ To be avoided: ignoring missing data in a line chart by joining the next nearest available data points." %} - {% include card.html content=card_content_9 title="✔️ Best practice: leave a gap in a line chart where there is missing data and highlight it with dashed lines and a text explanation." %} -{% include cards-container-end.html %} +This figure shows a line chart with a discontinuity. It leaves a gap in +the line and marks out the gap with two vertical dashed lines and +annotation stating the data was not collected in 2020 due to the +coronavirus (COVID-19) pandemic. {% endcapture %} +{% include cards-container-start.html %} {% include card.html +content=card_content_8 title="❌ To be avoided: ignoring missing data in +a line chart by joining the next nearest available data points." %} {% +include card.html content=card_content_9 title="✔️ Best practice: leave +a gap in a line chart where there is missing data and highlight it with +dashed lines and a text explanation." %} {% include +cards-container-end.html %} {% capture expandable_content_1 %} -``` +``` # Create data frame: df <- data.frame(year = seq(2018, 2023, 1), value = c(2, 3, NA, 4, 3, 5)) @@ -307,39 +527,78 @@ df |> y = 2, size = 18 * 5/14) ``` -{% endcapture %} -{% include expandable-block-start.html %} - {% include expandable-section.html number="1" content=expandable_content_1 title="Example 6 R code" %} -{% include expandable-block-end.html %} +{% endcapture %} +{% include expandable-block-start.html %} {% include +expandable-section.html number="1" content=expandable_content_1 +title="Example 6 R code" %} {% include expandable-block-end.html %} -You can read more about best practice for data visualisation in our [data visualisation guidance pages](data-vis). +You can read more about best practice for data visualisation in our +[data visualisation guidance pages](data-vis). ### 3. In data files -It's possible that some users may use data releases without referring to the main report or QMI document. It's important that supporting data files have sufficient information to provide context for the presence and handling of missing data, where appropriate. + +It's possible that some users may use data releases without referring to +the main report or QMI document. It's important that supporting data +files have sufficient information to provide context for the presence +and handling of missing data, where appropriate. #### In spreadsheets -You should provide notes and a note sheet in your published spreadsheets, which allow for short written explanations about issues like missing data and how it was prepared or analysed. You should also use symbolic shorthand to explain why data is missing from certain cells. For example, '[b]' for a break in a time series, '[e]' for estimated data and '[z]' to indicate that a variable was ‘not applicable’ to a particular record. These symbols are preferable to using blank cells, NA or '..' from the perspective of clarity and accessibility. -You can read more in our [guidance on accessible reference tables in spreadsheets](spreadsheets). +You should provide notes and a note sheet in your published +spreadsheets, which allow for short written explanations about issues +like missing data and how it was prepared or analysed. You should also +use symbolic shorthand to explain why data is missing from certain +cells. For example, '[b]' for a break in a time series, '[e]' for +estimated data and '[z]' to indicate that a variable was ‘not +applicable’ to a particular record. These symbols are preferable to +using blank cells, NA or '..' from the perspective of clarity and +accessibility. + +You can read more in our [guidance on accessible reference tables in +spreadsheets](spreadsheets). #### In machine-readable data files -It can be difficult to provide contextual information for certain types of data files, like machine-readable comma-separated Values (CSV) files. In this case, you should provide to users a data dictionary to explain how you’ve represented missing data. Like spreadsheets, you should consider using symbolic placeholders where data is missing. -You might also consider using the comma-separated Values on the Web (CSVW) format, which allows you to supply metadata information alongside the data. With CSVW you can set ‘null’ and ‘default’ properties in the metadata that could be used to indicate missing values. You can also use the special ‘required’ property as a validation check if you were expecting a field to be complete. +It can be difficult to provide contextual information for certain types +of data files, like machine-readable comma-separated Values (CSV) files. +In this case, you should provide to users a data dictionary to explain +how you’ve represented missing data. Like spreadsheets, you should +consider using symbolic placeholders where data is missing. +You might also consider using the comma-separated Values on the Web +(CSVW) format, which allows you to supply metadata information alongside +the data. With CSVW you can set ‘null’ and ‘default’ properties in the +metadata that could be used to indicate missing values. You can also use +the special ‘required’ property as a validation check if you were +expecting a field to be complete. ## Sources -1. [Government Analysis Function: Communicating quality, uncertainty and change](https://analysisfunction.civilservice.gov.uk/policy-store/communicating-quality-uncertainty-and-change/) -1. [Government Analysis Function: Data visualisation: tables](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-tables/) -1. [Government Analysis Function: Using symbols and shorthand](https://analysisfunction.civilservice.gov.uk/policy-store/symbols-in-tables-definitions-and-help/) -1. [Government Analysis Function: Data visualisation: charts](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-charts/) -1. [Government Analysis Function: Making spreadsheets accessible: a checklist of the basics](https://analysisfunction.civilservice.gov.uk/policy-store/making-spreadsheets-accessible-a-brief-checklist-of-the-basics/) -1. [Government Data Quality Hub: The Government Data Quality Framework](https://www.gov.uk/government/publications/the-government-data-quality-framework/the-government-data-quality-framework) -1. [Government Data Quality Hub: The Government Data Quality Framework -guidance](https://www.gov.uk/government/publications/the-government-data-quality-framework/the-government-data-quality-framework-guidance) -1. [Office for National Statistics: The Duck Book - Quality assurance of code for analysis and research](https://best-practice-and-impact.github.io/qa-of-code-guidance/) -1. [The Aqua Book: guidance on producing quality analysis for government](https://www.gov.uk/government/publications/the-aqua-book-guidance-on-producing-quality-analysis-for-government) -1. [The Goldacre Review: Better, broader, safer: using health data for research and analysis](https://www.gov.uk/government/publications/better-broader-safer-using-health-data-for-research-and-analysis) -1. [UK Statistics Authority: Code of Practice for Statistics](https://code.statisticsauthority.gov.uk/the-code/) +1. [Government Analysis Function: Communicating quality, uncertainty + and + change](https://analysisfunction.civilservice.gov.uk/policy-store/communicating-quality-uncertainty-and-change/) +2. [Government Analysis Function: Data visualisation: + tables](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-tables/) +3. [Government Analysis Function: Using symbols and + shorthand](https://analysisfunction.civilservice.gov.uk/policy-store/symbols-in-tables-definitions-and-help/) +4. [Government Analysis Function: Data visualisation: + charts](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-charts/) +5. [Government Analysis Function: Making spreadsheets accessible: a + checklist of the + basics](https://analysisfunction.civilservice.gov.uk/policy-store/making-spreadsheets-accessible-a-brief-checklist-of-the-basics/) +6. [Government Data Quality Hub: The Government Data Quality + Framework](https://www.gov.uk/government/publications/the-government-data-quality-framework/the-government-data-quality-framework) +7. [Government Data Quality Hub: The Government Data Quality Framework + -guidance](https://www.gov.uk/government/publications/the-government-data-quality-framework/the-government-data-quality-framework-guidance) +8. [Office for National Statistics: The Duck Book - Quality assurance + of code for analysis and + research](https://best-practice-and-impact.github.io/qa-of-code-guidance/) +9. [The Aqua Book: guidance on producing quality analysis for + government](https://www.gov.uk/government/publications/the-aqua-book-guidance-on-producing-quality-analysis-for-government) +10. [The Goldacre Review: Better, broader, safer: using health data for + research and + analysis](https://www.gov.uk/government/publications/better-broader-safer-using-health-data-for-research-and-analysis) +11. [UK Statistics Authority: Code of Practice for + Statistics](https://code.statisticsauthority.gov.uk/the-code/) From 7912eb2745da8a909272d770705d908dacf6840f Mon Sep 17 00:00:00 2001 From: hollygoss Date: Wed, 16 Oct 2024 15:10:08 +0100 Subject: [PATCH 5/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6621b7f..0e4a3bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,13 +23,11 @@ Remember to run `git pull` regularly to keep up to date with the main branch. The 'main' branch is protected, meaning you will have to create a new branch to make any changes. -To do this, on your local machine, first update your 'main' branch using `git pull`. Then run `git checkout -b branch-name` to create and switch to a new branch. You can switch between branches (for example, to work on different fixes) by using `git checkout branch-name`. - -Branch names should be short but descriptive, with each word separated by a hyphen. Author initials should be added to the prefix. For example: `"bc-update-data-vis"`. +To do this, on your local machine, first update your 'main' branch using `git pull`. Then run `git checkout -b branch-name` to create and switch to a new branch. You can switch between branches (for example, to work on different fixes) by using `git checkout branch-name`. Branch names should be short but descriptive, with each word separated by a hyphen. Use `git add` and `git commit -m "a clear descriptive commit message"` as usual to stage and commit your changes. -Once you have finished making your changes, push your branch to GitHub (using `git push` - it may give you instructions for setting an upstream branch). Then log in to GitHub and raise a pull request to have your changes reviewed and merged into 'main'. +Once you have finished making your changes, push your branch to GitHub (using `git push` - it may give you instructions for setting an upstream branch like using git push --set upstream origib branch-name). Then you can click the link it gives you to open GitHub and raise a pull request to have your changes reviewed and merged into 'main'. ## Building websites with Jekyll and GitHub