Merge branch 'feature/user-documentation' into develop

.gitignore

@@ -41,5 +41,5 @@ node_modules/
 # mypy
 .mypy_cache/
 
-# docs
+# documentation
 site/

CHANGELOG.md

@@ -40,7 +40,10 @@ Upgraded SASTADEV dependency
 - Split Angular frontend into core-, shared-, and feature- modules
 - Extended anonymization codes and moved to a centrally located JSON file
 
-## [0.6.2] - 2022-03-15
+### Added
+- First version of user documentation
+
+## [0.6.2] - 2022-02-15
 
 ### Changed
 - Various frontend refactors

docs/accounts.md

@@ -0,0 +1,17 @@
+# Gebruikersaccount
+
+## Registreren
+- Kies in de menubalk de optie `Sign up`
+- Vul het formulier in, zorg voor een geldig e-mailadres
+- Als de registratie succesvol verlopen is, ontvangt u een email met instructies om uw e-mailadres te bevestigen
+- Na bevestigen kunt u inloggen
+
+## Inloggen
+- Kies in de menubalk de optie `Login`
+- Vul uw gebruikersnaam en wachtwoord in en log in
+
+## Uitloggen
+- Kies rechts in de menubalk de knop met uw gebruikersnaam, en vervolgens `Logout`
+
+## Account verwijderen
+- Er is geen mogelijheid tot automatische verwijdering van uw account. Als u uw account en alle bijbehorende corpora en transcripten dient te wissen, neemt u [contact met ons op](mailto:dh.developers@uu.nl?subject=[SASTA]%20Account%20verwijderen).

docs/annotaties/saf.md

@@ -0,0 +1,34 @@
+# SASTA Output formaat (SAF)
+
+## Het bestand
+Een bestand in het SASTA Output formaat representeert de uitingen en annotaties van één transcript. Het bestand wordt opgeleverd als een Excel spreadsheet (`.xlsx`).
+
+## Kolommen
+### ID
+In deze kolom staat het uitingsnummer van de uiting. Let op: dit zijn alleen de uitingen die geselecteerd zijn voor analyse. De `ID` kolom loopt dus altijd van `1` tot `<hoeveelheid gemarkeerde uitingen>`.
+### Level
+In deze kolom word de naam van de verschillende niveaus getoond, zie [levels](#levels).
+
+### Unaligned
+Deze kolom is bedoeld voor niet-gealigneerde annotaties. Een voorbeeld zijn annotaties die niet bij een specifiek woord of woordgroep horen, maar bij de gehele uiting.
+
+### Word1, Word2, ...WordN
+De `Word`-kolommen zijn bedoeld voor annotaties behorende bij een specifiek woord in de uiting. Wanneer annotaties behoren bij woordgroepen, worden deze genoteerd onder het eerste woord van de woordgroep. De kolommen lopen door tot het aantal woorden van de langste geanalyseerde uiting in het transcript.
+
+### Fases
+In deze kolom wordt automatisch een opsomming gemaakt van alle fases die horen bij de annotaties van de uiting, in Romeinse cijfers.
+
+### Commentaar
+In deze kolom kan commentaar worden opgenomen, behorende bij de gehele zin. Voor commentaar over een specifiek woord word het level `Commentaar` gebruikt.
+
+## Rijen
+Eén uiting bestaat uit meerdere rijen, elk beginnende met dezelfde [ID](#id). Voor een uiting zijn steeds de `Utt`-rij, `level`-rijen, en de `Commentaar`-rij opgenomen.
+
+### Utt
+Op deze rij staan de woorden van uiting. Als een woord in het invoerbestand bijvoorbeeld voorzien is van een CHAT-annotatie, wordt deze verwerkt en wordt het woord opgeschoond getoond.
+
+### Levels
+Annotaties kunnen op verschillende niveaus worden gemaakt.
+
+Voor elk niveau is er een aparte rij opgenomen. Voor TARSP-transcripten is er een uitzondering: het `Zc`-niveau komt eenmaal voor per zc-embedding.
+

docs/assets/example-files/sif.txt

@@ -0,0 +1,33 @@
+##META text samplenaam = ASTA-00
+##TARGET SPEAKERS = PMA
+
+INV:
+1 | PMA:
+INV:
+2 | PMA:
+INV:
+3 | PMA:
+INV:
+4 | PMA:
+INV:
+5 | PMA:
+INV:
+6 | PMA:
+INV:
+7 | PMA:
+INV:
+8 | PMA:
+INV:
+9 | PMA:
+INV:
+10 | PMA:
+INV:
+11 | PMA:
+INV:
+12 | PMA:
+INV:
+13 | PMA:
+INV:
+14 | PMA:
+INV:
+15 | PMA:

docs/corpora.md

@@ -0,0 +1,28 @@
+# Corpus-overzicht
+Als u in de menubalk voor `corpora` kiest, krijgt u een overzicht te zien van uw corpora. Dit is tevens de home pagina. U heeft alleen toegang tot corpora die u zelf heeft aangemaakt. Klik op de rij van het corpus dat u wil analyseren om naar de corpuspagina te navigeren.
+
+## Corpus pagina
+In het corpus overzicht vindt u informatie over het corpus en de transcripten die er deel van uitmaken.
+
+### De titelbalk
+Op deze balk vindt u de naam van het corpus, en de gekozen analysemethode.
+
+### Acties
+Er zijn een aantal acties die u kunt uitvoeren op een corpus:
+
+- `add transcript(s)`. Als u hiervoor kiest wordt u naar de `upload` pagina omgeleid, waar vast het juiste corpus geselecteerd is.
+- `download` genereert een ZIP bestand van het gehele corpus met daarin per transcript:
+	- Het CHAT bestand
+	- Het Alpino geparseerde XML bestand
+- `(re)process` brengt u naar de `process` pagina, waar u de status van de SASTA bewerkingen kunt bekijken, en deze zo nodig handmatig opstarten.
+
+### Transcripten
+In deze tabel vindt u informatie over de transcripten in het corpus, in de volgende kolommen:
+
+- `Transcript`: de naam van het transcript. Als u op deze kolom klikt navigeert u naar de pagina van het transcript
+- `Status`: de status van de SASTA bewerkingen. Als hier een andere waarde dan `parsed` voorkomt, zijn de bewerkingen nog bezig, of is er iets misgegaan. Kies dan voor `re(process)`
+- Utterances: het totaal aantal uitingen in het transcript
+- `Created on`: de datum waarop het transcript is toegevoegd
+- Actions: acties die u op een transcript kunt uitvoeren
+	- `delete transcript` (prullenbak-icoon): verwijdert het transcript
+

docs/index.md

@@ -0,0 +1,4 @@
+# SASTA Documentatie
+Kies in het menu aan de linkerzijde een onderwerp om de documentatie te bekijken, of gebruik de zoekfunctie om een onderwerp te vinden.
+
+Voor vragen en feedback neemt u contact op met: [Centre for Digital Humanities - Research Software Lab](mailto:dh.developers@uu.nl?subject=[SASTA]%20Feedback)

docs/input-formats/anonimisatie.md

@@ -0,0 +1,48 @@
+# Anonimisatie
+De transcripten kunnen gevoelige informatie over participanten bevatten. SASTA staat toe dat anonimisatiecodes gebruikt worden. In de bewerkingstappen die SASTA uitvoert worden deze omgezet in grammaticaal gelijke. De anonimisaties volgen een vast patroon:
+```
+<optioneel: prefix>CODE<optioneel: affix><optioneel: nummer 1-4>
+```
+Dezelfde combinatie van CODE + nummering zal steeds hetzelfde woord vervangen worden. Zo blijft een transcript ook voor de menselijke gebruiker duidelijk volgbaar. Voorbeelden:
+
+```
+Ik heet NAAM1. -> Ik heet Jan.
+Ik heet VOORNAAM1. -> Ik heet Jan.
+Ik heet NAAMKIND. -> Ik heet Maria.
+```
+Merk op dat NAAM1 en VOORNAAM1 dezelfde vervanging toegewezen krijgen. Dit komt omdat de combinatie code (NAAM) en nummering (1) gelijk is. SASTA houdt intern bij waar vervangingen uitgevoerd zijn. Deze zijn terug te vinden in de CHAT-bestanden op de %xano tier. Voorbeeld:
+```
+*PMA:	uh buiten Breda
+%xano:	10|PLAATS1|Breda
+```
+Op de tiende positie in de zin stond PLAATS1, en dit is vervangen door Breda.
+
+## Beschikbare anonimisatiecodes
+- categorie: plaats
+    - codes: `PLAATS`, `PLAATSNAAM`, `WOONPLAATS`
+    - vervangingen: `Utrecht`, `Breda`, `Leiden`, `Maastricht`, `Arnhem`
+    - voorbeeld: `Ik woon in PLAATS2` -> `Ik woon in Leiden`
+- categorie: achternaam
+    - codes: `ACHTERNAAM`
+    - vervangingen: `Jansen`, `Hendriks`, `Dekker`, `Dijkstra`, `Veenstra`
+    - voorbeeld: `Dat zei NAAM ACHTERNAAM` -> `Dat zei Maria Jansen`
+- categorie: naam
+    - codes: `NAAM`, `BROER`, `ZUS`, `KIND`, `VADER`, `MOEDER`
+    - vervangingen: `Maria`, `Jan`, `Anna`, `Esther`, `Pieter`, `Sam`
+    - voorbeeld: `Dat zei BROER1` -> `Dat zei Jan`
+- categorie: beroep
+    - codes: `BEROEP`
+    - vervangingen: `timmerman`, `chirurgh`, `leraar`, `ober`, `verslaggever`
+    - voorbeeld: `Ik ben BEROEP van beroep` -> `Ik ben timmerman van beroep`
+- categorie: land
+    - codes: `LAND`
+    - vervangingen: `Duitsland`, `Nederland`, `Japan`, `Kameroen`, `India`
+    - voorbeeld: `Ik woon in LAND2` -> `Ik woon in Japan`
+- categorie: opleiding
+    - codes: `STUDIE`, `OPLEIDING`
+    - vervangingen: `bedrijfskunde`, `informatica`, `filosofie`, `rechtsgeleerdheid`, `werktuigbouwkunde`
+    - voorbeeld: `Ik volg de studie STUDIE` -> `ik volg de studie bedrijfskunde`
+- categorie: instelling
+    - codes: `ZORGINSTELLING`, `INSTELLING`, `ZIEKENHUIS`
+    - vervangingen: `Diakonessenhuis`, `Rijnstate`, `Vogellanden`, `HagaZiekenhuis`, `Slingeland`
+    - voorbeeld: `Ik lag in het ZIEKENHUIS1` -> `Ik lag in het Rijstate`

docs/input-formats/sif.md

@@ -0,0 +1,72 @@
+# SASTA Input Format (SIF)
+
+## Het bestand
+Het transcript dient te worden aangeleverd als een Microsoft Word  `.docx`-bestand. Een `.txt`-bestand met `utf-8`-encoding wordt ook geaccepteerd. De naam van het bestand wordt gebruikt als titel van het transcript binnen SASTA. Zo zal het bestand `sample 12.docx` het transcript `sample_12` opleveren.
+
+## Sprekers
+Het transcript kan uitingen van meerdere sprekers bevatten. Ken elke spreker een unieke drieletterige code toe; bijvoorbeeld CHI (child), INV (interviewer) of PMA (patient met afasie).
+
+
+##  Metadata
+### Uitingen selecteren
+SASTA werkt optimaal wanneer het volledige transcript wordt aangeleverd. Dus ook uitingen van sprekers die niet geanalyseerd hoeven te worden, kunnen de resultaten verbeteren. Het is nodig om in dit volledige transcript de uitingen te markeren waarin je geinterresseerd bent. Je kunt dit mechanisme gebruiken om de analyse te baseren op een vast aantal uitingen, bijvoorbeeld 50.
+
+Er zijn twee manieren om een zin te markeren voor analyse:
+
+1. De spreker van de uiting
+2. De uiting nummeren, zie [uitingen](#uitingen)
+
+Om alle uitingen van spreker PMA te analyseren, voeg je de volgende regel in:
+
+```
+##TARGET SPEAKER PMA
+```
+
+Om alleen de genummerde uitingen te analyseren:
+
+```
+##TARGET UTTIDS
+```
+
+Wanneer uitingen van een spreker worden gemarkeerd, **én** er zijn gemarkeerde uitingen aanwezig, worden alleen de genummerde uitingen van de spreker geanalyseerd.
+
+### Samplenaam
+Het is mogelijk de titel van een transcript te overschrijven aan de hand van het metadata-veld `samplenaam`:
+```##META text samplenaam = ASTA-13```
+Als dit veld aanwezig is wordt de bestandsnaam genegeerd.
+
+### Overige metadata
+Alle metadata volgens het [PAQU-formaat](https://paqu.let.rug.nl:8068/info.html#credits) zijn geldige invoer. deze worden echter door niet door SASTA verwerkt.
+
+## Uitingen
+
+Elke uiting begint op een nieuwe regel. Ze kunnen doorlopen op de volgende regel, maar mogen niet onderbroken worden met een regeleinde. Uitingen hebben een vaste vorm:
+
+```
+SPK:<tab of spatie(s)>Inhoud van de uiting
+```
+
+Optioneel zijn ze ook genummerd:
+```
+<nummer> | SPK:<tab of spatie(s)>Inhoud van de uiting
+```
+
+```
+
+INV: Waar ben je vandaag geweest?
+1 | PMA: In de dierentuin.
+2 | INV: Oh wat leuk!
+```
+
+
+
+### Annoteren
+Uitingen kunnen geannoteerd worden volgens de [CHAT handleiding][chat-manual].
+
+[Voor lijsten met veel gebruikte annotaties, zie TODO: ASTA, STAP, TARSP-specifieke annotaties.]: #
+
+
+## Voorbeeldbestanden
+Zie [link](../input-formats/voorbeelden) voor downloadbare voorbeeldbestanden.
+
+[chat-manual]: https://talkbank.org/manuals/CHAT.pdf

docs/input-formats/voorbeelden.md

@@ -0,0 +1,6 @@
+# Voorbeeldbestanden
+
+## [SASTA Input Formaat](/input-formats/sif)
+- Microsoft Word (`.docx`): [download](../assets/example-files/sif.docx)
+- Platte tekst (`.txt`): [download](../assets/example-files/sif.txt)
+## CHAT Input

docs/methodes.md

@@ -0,0 +1,12 @@
+# Methode-overzicht
+In SASTA kan gewerkt worden met `ASTA`, `STAP`, en `TARSP`.
+Kies in de menubalk voor `Methods` om naar het overzicht van de methodes te navigeren.
+Door op de rij van een methode te klikken, worden de details van deze methode geopend.
+
+## Methode details
+Voor de geselecteerde methode wordt een tabel getoond met per query (taalmaat):
+
+- `code`: de interne code die SASTA hanteert..
+- `level`: Het niveau waarop de query opereert. Per methodecategorie verschillen de beschikbare niveaus.
+- `item`: De code die gegenereert wordt door SASTA, en door de gebruiker ook toegevoegd kan worden in het [SASTA Annotation Format](../annotaties/saf). De codes zijn hoofdletter-ongevoelig, dus `BVBep` en `bvbep` leveren dezelfde scores op.
+- `actions`: Klik op het vergrootglas om alle beschikbare details van een query te tonen.

docs/process.md

@@ -0,0 +1,14 @@
+# Voorbewerking van transcripten
+Om het transcript geschikt te maken voor analyse, voer SASTA een aantal bewerkingen uit. Het transcript wordt onder andere opgeschoond, en er wordt geparseerd met behulp van Alpino.
+
+## Starten
+- Na het uploaden komt u automatisch op de `process` pagina van het corpus terecht. U kunt deze ook bereiken door op de corpus-pagina `re(process)` te kiezen.
+- Kies `Process` om de bewerkingen te starten.
+
+## Het statusoverzicht
+Op de `Process` pagina van een corpus vindt u de realtime status van de SASTA bewerkingen. Een transcript is gereed voor analyse wanneer:
+
+- De kolom `status` de waarde `parsed` heeft
+- De kolommen `convert` en `parse` beide een groen vinkje hebben
+
+U hoeft niet te wachten tot alle transcripten volledig verwerkt zijn. Door op `to corpus` te klikken, kunt u vast aan de slag met de transcripten die gereed zijn.

docs/stylesheets/extra.css

@@ -0,0 +1,5 @@
+:root {
+    --md-primary-fg-color: #002984;
+    --md-primary-fg-color--light: #3f51b5;
+    --md-primary-fg-color--dark: #002984;
+}

docs/tools/format_anonymizations.py

@@ -0,0 +1,29 @@
+# flake8: noqa: E501
+import json
+import pathlib
+
+ANON_FP = pathlib.Path(__file__).parent.parent.parent.resolve() / 'backend' / 'anonymization.json'
+
+def format_anons(anons):
+    for spec in anons:
+        codes = ', '.join([f'`{code}`' for code in spec['codes']])
+        common = ', '.join([f'`{com}`' for com in spec['common']])
+        example = f'`{spec["example"][0]}` -> `{spec["example"][1]}`'
+
+        l1 = f'- categorie: {spec["label-nl"]}'
+        l2 = f'    - codes: {codes}'
+        l3 = f'    - vervangingen: {common}'
+        l4 = f'    - voorbeeld: {example}'
+
+        total = [l1, l2, l3, l4]
+        print(*total, sep='\n')
+
+
+def main():
+    with open(ANON_FP, 'r') as f:
+        content = json.load(f)
+        format_anons(content)
+
+
+if __name__ == '__main__':
+    main()

docs/transcript.md

@@ -0,0 +1,43 @@
+# Transcript pagina
+Op de transcriptpagina vindt u informatie over het gekozen transcript, en kunt u de analyse uitvoeren. De pagina is verdeeld in een aantal panelen.
+
+## Titelbalk
+In de titelbalk vindt u de titel van het transcript. Onder de titel vindt u relevante informatie over het transcript en de SASTA bewerkingen:
+
+- Status: de status van de SASTA bewerkingen
+- Analysing: hoeveel uitingen (van het totaal aantal uitingen) door SASTA genalyseerd worden [link naar selecting speakers]
+- Analysing speakers: de codes van de sprekers wiens uitingen worden geanalyseerd
+- Method: de methode waarmee het transcript geanalyseerd wordt
+- Created on: de datum waarop het transcript is toegevoegd
+
+## Scoring
+In dit paneel bevindt zich de hoofdfunctionaliteit van SASTA: het genereren van automatische analyses.
+Er is een drietal opties. De onderliggende analyse is steeds dezelfde, maar het uitvoerformaat verschilt:
+
+- Annotate (xlsx)
+	- Genereert een bestand in het Sasta Annotatie Formaat (SAF) [link]
+	- Dit bestandsformaat wordt ook gebruikt voor handmatige verbetering van de analyse
+- Annotate (CHAT)
+	- Genereert een CHAT bestand, met daaraan toegevoegd de annotaties voor elke genalyseerde uiting. Dit bestand kan bijvoorbeeld gebruikt worden in STAMPER.
+- Generate form
+	- Genereert het (gedeeltelijk) ingevulde formulier voor de gekozen methode. Dit uitvoerformaat bootst analyse middels handmatige analyse na.
+
+## Annotations
+- Download annotations: download een `xlsx` bestand met annotaties volgens de laatste analyse
+- Upload (corrected) annotations: hier kunt u een verbeterd annotatiebestand uploaden (zie [link])
+- Reset corrections: zet het bestand terug naar de eerste versie, zonder handmatige verbeteringen
+
+## Utterances
+U kunt het paneel met uitingen openklikken door op de balk te klikken. Per uiting in het transcript wordt weergeven:
+
+- Speaker: de code van de spreker
+- Sentence: de (opgeschoonde) uiting
+- For analysis: een vinkje wanneer SASTA de uiting analyseert, een streepje wanneer dit niet het geval is
+- Parse tree: een visuele representatie van de geparseerde uiting. Hier kunt u bekijken hoe Alpino de uiting heeft geparseerd
+
+## Files
+In dit paneel heeft u toegang tot enkele van de bestanden die SASTA gebruikt voor een transcript:
+
+- CHAT: het door SASTA bewerkte inputbestand, in CHAT formaat
+- Alpino parse: het Alpino geparseerde bestand, in LASSY XML formaat
+- corrected Alpino parse: het door SASTA verbeterde geparseerde bestand, in LASSY XML formaat