Added dapla-toolbelt-pseudo chapter

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"

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                | ✅  | ✅       | ✅         | ✅         |
+| data-admins (interaktivt) | ✅  | ✅       | ✅         | ✅         |
+| developers (interaktivt)  | ✅  | ✅       | ✅         | ✅         |
+
+: Test-miljø {#tbl-pseudo-first}
+
+| Aktør                      | Validator | Pseudonymize() | Depseudonymize() | Repseudonymize() |
+| -------------------------- | :-------: | :------------: | :--------------: | :--------------: |
+| Kildomaten                 | ✅  | ✅       | 🚫        | 🚫        |
+| data-admins (interaktivt)  | 🚫 | 🚫      | 🚫        | 🚫        |
+| developers (interaktivt)   | 🚫 | 🚫      | 🚫        | 🚫        |
+
+: 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. 
+