Merge branch 'release/0.9.3'

.gitignore

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

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes (beginning at version 0.2.0) to this project will be documen
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.3] - 2024-06-04
+### Changed
+-   Upgraded SASTADEV to 0.2.2
+
 ## [0.9.2] - 2024-05-28
 ### Added
 -   Added a home page
@@ -40,7 +44,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

CITATION.cff

@@ -41,5 +41,5 @@ abstract: >-
   transcripts, to aid clinical linguists and research into
   language development and language disorders.
 license: BSD-3-Clause
-version: 0.9.2
+version: 0.9.3
 date-released: '2024-01-31'

backend/requirements.txt

@@ -215,7 +215,7 @@ requests==2.28.1
     #   spacy
 requests-oauthlib==1.3.1
     # via django-allauth
-sastadev==0.2.1
+sastadev==0.2.2
     # via
     #   -r requirements.in
     #   auchann

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,33 @@
+# 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
+### Uiting
+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).
+
+### Hele uiting
+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.
+
+### Opmerkingen
+In deze kolom kunnen opmerkingen worden opgenomen, behorende bij de gehele zin. Deze worden niet door SASTA verwerkt. Voor commentaar over een specifiek woord word het level `Opmerkingen` gebruikt.
+
+## Rijen
+Eén uiting bestaat uit meerdere rijen, elk beginnende met hetzelfde uitingsnummer. Voor een uiting zijn steeds de `Uiting`-rij, `level`-rijen, en de `Opmerkingen`-rij opgenomen.
+
+### Uiting
+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.
+

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](./voorbeelden.md) 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.md)
+- 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.md). 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: #3f51b5;
+    --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()