From 013b34c2556786606ba80d1f87ff18d54cefb554 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Bruer-Skarsb=C3=B8?= <obr@ssb.no>
Date: Wed, 20 Mar 2024 16:01:23 +0100
Subject: [PATCH] Added dapla-toolbelt-pseudo chapter

---
 dapla-manual/_quarto.yml                    |   2 +-
 dapla-manual/images/mask.png                | Bin 0 -> 3032 bytes
 dapla-manual/statistikkere/dapla-pseudo.qmd | 187 ++++++++++++++++++++
 3 files changed, 188 insertions(+), 1 deletion(-)
 create mode 100644 dapla-manual/images/mask.png
 create mode 100644 dapla-manual/statistikkere/dapla-pseudo.qmd

diff --git a/dapla-manual/_quarto.yml b/dapla-manual/_quarto.yml
index 424a98fc..655be5ba 100644
--- a/dapla-manual/_quarto.yml
+++ b/dapla-manual/_quarto.yml
@@ -118,7 +118,7 @@ website:
           contents:
             - statistikkere/gcc.qmd
             - statistikkere/kildomaten.qmd
-            #- statistikkere/pseudonymisering.qmd
+            - statistikkere/dapla-pseudo.qmd
             - statistikkere/transfer-service.ipynb
             - statistikkere/statistikkbanken.qmd
         - section: "Appendix"
diff --git a/dapla-manual/images/mask.png b/dapla-manual/images/mask.png
new file mode 100644
index 0000000000000000000000000000000000000000..7a7ee5f66aea6297e4998b2efeb1310b64730343
GIT binary patch
literal 3032
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
aVE7+YsT|JnXS5Cg0000<MNUMnLSTZkd8B6m

literal 0
HcmV?d00001

diff --git a/dapla-manual/statistikkere/dapla-pseudo.qmd b/dapla-manual/statistikkere/dapla-pseudo.qmd
new file mode 100644
index 00000000..a6be552b
--- /dev/null
+++ b/dapla-manual/statistikkere/dapla-pseudo.qmd
@@ -0,0 +1,187 @@
+# dapla-toolbelt-pseudo
+
+![](../images/mask.png){style="max-width: 80%; float: right;" fig-alt="Dapla logo"}
+
+[dapla-toolbelt-pseudo](https://pypi.org/project/dapla-toolbelt-pseudo/) er en python-pakke som har som sitt hovedformål å gi Dapla-brukere muligheten til å pseudonymisere, de-pseudonymisere og re-pseudonymisere data. Det skal sikre at brukerne av Dapla har verktøyene de trenger for å jobbe med *direkte identifiserende opplysninger* i henhold til lovverk og SSBs tolkninger av disse. 
+
+Siden tilgang til direkte identifiserende opplysninger er underlagt strenge regler, så krever bruken av *dapla-pseudo-toolbelt* at man forholder seg til vedtatte standarder som [datatilstander](./datatilstander.html) og systemer som [Kildomaten](./kildomaten.html). I tillegg er det en streng tilgangsstyring til hvor man kan kalle funksjonaliteten fra. Tjenestene er satt opp på en slik måte at Dapla-team skal være selvbetjent i bruken av funksjonaliteten, samtidig som regler, prosesser og standarder etterleves på enklest mulig måte.
+
+::: {.callout-important}
+# Standardisert klassifisering av datatilstander
+
+I SSB er det bestemt at all data skal klassifiseres på en standardisert måte basert på [datatilstander](./datatilstander.html) for å avgjøre om de er sensitive, skjermet eller åpen. Den eneste datatilstanden som klassifiseres som sensitiv er [kildedata](./datatilstander.html#kildedata). Det er derfor bestemt at pseudonymisering er en av prosesseringene som skal skje mellom datatilstandene kildedata og inndata.  
+:::
+
+## Forberedelser
+
+Før man tar i bruk funksjonaliteten er det viktig at man kjenner godt til [tilgangstyring i Dapla-team](./tilgangsstyring.html) og [Kildomaten](./kildomaten.html), og har diskutert med seksjonen hvordan man skal behandle direkte identifiserende opplysninger i de aktuelle dataene. 
+
+For at et Dapla-team skal kunne bruke dapla-toolbelt-pseudo må [Kildomaten](./kildomaten.html) være skrudd på for miljøet^[Et Dapla-team har både et test- og et prod-miljø. Kildomaten må være skrudd på i det miljøet du ønkser å benytte dapla-toolbelt-pseudo fra.] man ønsker å jobbe fra. Som standard får alle statistikkteam skrudd på Kildomaten i prod-miljøet og ikke i test-miljøet. Ønsker du å aktivere Kildomaten i test-miljøet kan dette gjøres selvbetjent som en [feature](./features.html).
+
+## Tilgangsstyring
+
+Tilgang til å funksjonalitet i dapla-toolbelt-pseudo kan regnes som sensitivt i seg selv, og derfor er det en streng tilgangsstyring for bruk av tjenesten. I prod-miljøet kan man kun ta i bruk funksjonaliteten ved å prosessere dataene i Kildomaten, og det er bare tilgangsgruppen [data-admins](./hva-er-dapla-team.html#data-admins) som har tilgang til å godkjenne slike automatiske prosesseringer. I test-miljøet derimot kan alle på teamet benytte seg av all funksjonalitet, siden det aldri skal forekomme ekte data her. 
+
+
+::: {#tbl-pseudo-panel layout-nrwos=2}
+| Aktør                     | Validator | Pseudonymize() | Depseudonymize() | Repseudonymize() |
+| ------------------------- | :-------: | :------------: | :--------------: | :--------------: |
+| Kildomaten                | &#x2705;  | &#x2705;       | &#x2705;         | &#x2705;         |
+| data-admins (interaktivt) | &#x2705;  | &#x2705;       | &#x2705;         | &#x2705;         |
+| developers (interaktivt)  | &#x2705;  | &#x2705;       | &#x2705;         | &#x2705;         |
+
+: Test-miljø {#tbl-pseudo-first}
+
+| Aktør                      | Validator | Pseudonymize() | Depseudonymize() | Repseudonymize() |
+| -------------------------- | :-------: | :------------: | :--------------: | :--------------: |
+| Kildomaten                 | &#x2705;  | &#x2705;       | &#128683;        | &#128683;        |
+| data-admins (interaktivt)  | &#128683; | &#128683;      | &#128683;        | &#128683;        |
+| developers (interaktivt)   | &#128683; | &#128683;      | &#128683;        | &#128683;        |
+
+: Prod-miljø {#tbl-pseudo-second}
+
+Tilgangsstyring til dapla-pseudo-toolbelt
+:::
+
+I @tbl-pseudo-panel ser vi fra @tbl-pseudo-first at test-miljøet har full tilgang til funksjonaliteten i dapla-toolbelt-pseudo. Både fra Kildomaten og når man sitter og jobber interaktivt i Jupyterlab. @tbl-pseudo-second viser at det kun er tilgang til *pseudonymize()* og *validator()* fra Kildomaten i prod-miljøet, og man kan aldri interaktivt kalle på funksjoner som potensielt avslører et pseudonym. Av den grunn er det alltid anbefalt å teste ut koden sin i test-miljøet før den produksjonssettes i i prod-miljøet med Kildomaten.
+
+## Funksjonalitet
+
+I denne delen viser vi hvilken funksjonalitet som tilbys gjennom dapla-toolbelt-pseudo. Eksempelkoden under viser hvordan man ville kjørt det fra en notebook i Jupyterlab og ikke hvordan koden må skrives når det skal kjøres i [Kildomaten](./kildomaten.html)^[I Kildomaten må koden blant annet pakke inn i `main()`-funksjon.].
+
+### Installering
+
+[dapla-toolbelt-pseudo](https://pypi.org/project/dapla-toolbelt-pseudo/) er ferdig installert i Kildomaten. Men ønsker du å bruke det i test-miljøet til teamet så kan du installere det i et `ssb-project` fra [PyPI](https://pypi.org/) med denne kommandoen: 
+
+```{.bash filename="Terminal"}
+poetry add dapla-toolbelt-pseudo
+```
+
+### Pseudonymisering
+
+Pseudonymisering tilbys via `Pseudonymize`-metoden i **dapla-toolbelt-pseudo**. Den følger et *builder-pattern* der man spesifiserer hva og i hvilken rekkefølge operasjonene skal gjøres. Anta at det finnes i en dataframe i minnet som heter `df` hvor kolonnen `fnr` skal pseudonymiseres. Da vil koden se slik ut:
+
+```{.python filename="Notebook"}
+from dapla_pseudo import Pseudonymize
+
+result_df = (
+    Pseudonymize.from_polars(df) 
+    .on_fields("fnr")
+    .with_default_encryption()                     
+    .run()                                
+    .to_polars()                                   
+)
+```
+I koden over så angir `from_polars(df)` at kolonnen vi ønsker å pseudonymisere ligger i en [Polars](https://docs.pola.rs/) dataframe i minnet og heter `df`. Deretter spesifiserer vi at kolonnen `fnr` er den som skal behandles med funksjonen `on_fields("fnr")`. Videre angir `with_default_encryption()` at `fnr` skal pseudonymiseres med dapla-toolbelt-speudo sin standard-algoritme^[Standardalgoritmen i *dapla-toolbelt-pseudo* er den deterministiske krypteringsalgoritmen *Deterministic Authenticated Encryption with Associated Data*, eller DAEAD-algoritmen.]. Til slutt ber vi om at det ovennevnte blir kjørt med funksjonen `run()`, og at dataene skal returneres som en Polars dataframe med funksjonen `to_polars()`. 
+
+Se flere [eksempler i dokumentasjonen](https://statisticsnorway.github.io/dapla-toolbelt-pseudo/index.html#pseudonymize).
+
+### De-pseudonymisering
+
+Pseudonymisering tilbys via `Depseudonymize`-metoden i **dapla-toolbelt-pseudo**. Den følger et *builder-pattern* der man spesifiserer hva og i hvilken rekkefølge operasjonene skal gjøres. Anta at det finnes i en Polars dataframe i minnet som heter `df` hvor kolonnen `fnr` skal de-pseudonymiseres. Da vil koden se slik ut:
+
+```{.python filename="Notebook"}
+result_df = (
+    Depseudonymize.from_polars(df)            
+    .on_fields("fnr")                          
+    .with_default_encryption()                     
+    .run()                                         
+    .to_polars()                                   
+)
+```
+Oppbygningen av koden med `Depseudonymize()` er helt lik som for `Pseudonomize()`. Les beskrivelsen der for å se hva de ulike funksjonskallene gjør. Se flere [eksempler i dokumentasjonen](https://github.com/statisticsnorway/dapla-toolbelt-pseudo#depseudonymize).
+
+Foreløpig er det kun tilgang til å pseudonymisere i test-miljøet med test-data. Ta kontakt med Dapla-teamene dersom det dukker opp behov for å kunne de-pseudonymisere i prod-miljøet. 
+
+
+
+
+### Re-pseudonymisering
+
+Under utvikling. 
+
+### Stabil ID
+
+I statistikkproduksjon og forskning er det viktig å kunne følge de samme personene over tid. Derfor har fødselsnummer ofte blitt oversatt til en mer stabilt identifikator, ofte kalt SNR eller stabil ID^[SNR-katalogen eies og tilbys av Team Register på Dapla.]. Funksjonene `with_stable_id()` og `validator()` bruker stabilID-katalogen til å henholdsvis bytte ut fødselsnummer med stabil ID, og for å validere om fødselsnummer er gyldige(se under).
+
+Du kan selv spesifisere hvilken versjon av SNR-katalogen du ønsker å bruke. Det gjør du ved å oppgi en gyldighetsdato og så finner dapla-toolbelt-pseudo hvilken versjon av katalogen som ligger nærmest i tid. 
+
+### Validere fødselsnummer
+
+`Validator`-metoden kan benyttes til å sjekke om fødselsnummer finnes i SNR-katalogen (se over). Her kan man også spesifisere hvilken versjon av SNR-katalogen man ønsker å bruke. Standard, hvis ingenting velges, er at siste tilgjengelige versjon velges. Under er et eksempel på hvordan man validerer fødselsnummer for en gitt gyldighetsdato:
+
+```{.python filename="Notebook"}
+from dapla_pseudo import Validator
+from dapla_pseudo.utils import convert_to_date
+
+result = (
+    Validator.from_polars(df)
+    .on_field("fnr")
+    .validate_map_to_stable_id(
+        sid_snapshot_date=convert_to_date("2023-08-29")
+    )
+)
+# Vis hvilken versjon av SNR-katalogen som er benyttet
+result.metadata
+# Vis fødselsnummer som ikke fikk treff i SNR-katalogen som en Polars dataframe
+result.to_polars()
+```
+
+### Dataformater
+
+**dapla-toolbelt-pseudo** støtter følgende dataformater:
+
+- csv (filformat)
+- json (filformat)
+- Polars dataframe (minnet)
+- Pandas dataframe (minnet)
+
+Over har vi vist hvordan vi leser data fra minnet, men det støttes også å lese direkte fra filformatene csv og json. Under er et eksempel med en csv-fil:
+
+```{.python filename="Notebook"}
+from dapla_pseudo import Pseudonymize
+from dapla import AuthClient
+
+
+file_path="data/personer.csv"
+
+options = {
+    "dtypes": {"fnr": pl.Utf8, "fornavn": pl.Utf8, "etternavn": pl.Utf8, "kjonn": pl.Categorical, "fodselsdato": pl.Utf8}
+}
+
+result_df = (
+    Pseudonymize.from_file(file_path)
+    .on_fields("fnr")
+    .with_default_encryption()
+    .run()
+    .to_polars(**options)
+)
+```
+
+Se flere [eksempler i dokumentasjonen](https://github.com/statisticsnorway/dapla-toolbelt-pseudo#read-from-file-systems).
+
+
+### Algoritmer
+
+**dapla-toolbelt-pseudo** støtter mange forskjellige krypteringsalgoritmer. Les mer i [dokumentasjonen](https://github.com/statisticsnorway/dapla-toolbelt-pseudo#pseudonymize-using-custom-keyskeysets).
+
+### Metadata
+
+Kommer snart. 
+
+## Brukerveiledning
+
+På grunn av den strenge tilgangsstyringen til dapla-pseudo-toolbelt og kildedata er det anbefalt å utvikle kode for overgangen fra kildedata til inndata i test-miljøet til teamet.
+
+### Interaktiv utvikling
+
+Kommer snart.
+
+### Kildomaten i test
+
+Kommer snart.
+
+### Kildomaten i prod
+
+Kommer snart. 
+