Merge pull request #2009 from CentreForDigitalHumanities/feature/collocations-frontend

lukavdplas · web-flow · commit 4eda5a8e90be · 2026-03-03T17:29:05.000+01:00
Collocations frontend
diff --git a/frontend/src/app/models/ngram.spec.ts b/frontend/src/app/models/ngram.spec.ts
@@ -6,14 +6,15 @@ describe('NgramParameters', ()=> {
     let store: RouterStoreService = new SimpleStore() as any;
     let ngramParameters: NgramParameters;
     const testState = {
+        mode: 'ngrams',
         size: 3,
         positions: 'first',
         freqCompensation: true,
         analysis: 'clean',
         maxDocuments: 100,
         numberOfNgrams: 20,
     } as NgramSettings;
-    const testParams = {ngramSettings: 's:3,p:first,c:true,a:clean,m:100,n:20'}
+    const testParams = {ngramSettings: 'o:n,s:3,p:first,c:true,a:clean,m:100,n:20'}
 
     beforeEach(() => {
         ngramParameters = new NgramParameters(store);
@@ -31,6 +32,7 @@ describe('NgramParameters', ()=> {
 
     it('should return default values if no relevant route parameter is present', () => {
         const defaultSettings = {
+            mode: 'ngrams',
             size: 2,
             positions: 'any',
             freqCompensation: false,
@@ -40,6 +42,11 @@ describe('NgramParameters', ()=> {
         } as NgramSettings;
         const state = ngramParameters.storeToState({irrelevant: 'parameter'})
         expect(state).toEqual(defaultSettings);
-    })
+    });
+
+    it('should parse partial parameters', () => {
+        const partialParams = {ngramSettings: 's:3,p:first,c:true,a:clean,m:100,n:20'};
+        expect(ngramParameters.storeToState(partialParams)).toEqual(testState);
 
+    });
 });
diff --git a/frontend/src/app/models/ngram.ts b/frontend/src/app/models/ngram.ts
@@ -4,9 +4,12 @@ import * as _ from 'lodash';
 import { StoreSync } from '../store/store-sync';
 import { Store } from '../store/types';
 
+export type NgramMode = 'ngrams' | 'collocates';
+
 export interface NgramSettings {
+    mode: NgramMode,
     size: number;
-    positions: string;
+    positions?: string;
     freqCompensation: boolean;
     analysis: string;
     maxDocuments: number;
@@ -23,38 +26,41 @@ export class NgramParameters extends StoreSync<NgramSettings> {
     }
 
     stringifyNgramSettings(state: NgramSettings): string {
-        return [`s:${state.size}`,`p:${state.positions}`,`c:${state.freqCompensation}`,
-            `a:${state.analysis}`,`m:${state.maxDocuments}`,`n:${state.numberOfNgrams}`].join(',')
+        return [
+            `o:${state.mode == 'collocates' ? 'c' : 'n'}`,
+            `s:${state.size}`,
+            `p:${state.positions}`,
+            `c:${state.freqCompensation}`,
+            `a:${state.analysis}`,
+            `m:${state.maxDocuments}`,
+            `n:${state.numberOfNgrams}`
+        ].join(',')
     }
 
     stateToStore(state: NgramSettings): Params {
         return { ngramSettings: this.stringifyNgramSettings(state)}
     }
 
     storeToState(params: Params): NgramSettings {
-        if (_.has(params, 'ngramSettings')) {
-            const stringComponents = params['ngramSettings'].split(',');
-            return {
-                size: parseInt(this.findSetting('s', stringComponents), 10),
-                positions: this.findSetting('p', stringComponents),
-                freqCompensation: this.findSetting('c', stringComponents) === 'true',
-                analysis: this.findSetting('a', stringComponents),
-                maxDocuments: parseInt(this.findSetting('m', stringComponents), 10),
-                numberOfNgrams: parseInt(this.findSetting('n', stringComponents), 10),
-            }
-        }
+        const parsed = this.parseParamString(_.get(params, 'ngramSettings', ''));
         return {
-            size: 2,
-            positions: 'any',
-            freqCompensation: false,
-            analysis: 'none',
-            maxDocuments: 50,
-            numberOfNgrams: 10,
-        } as NgramSettings;
+            mode: _.get(parsed, 'o') === 'c' ? 'collocates' : 'ngrams',
+            size: this.parseInt(_.get(parsed, 's'), 2),
+            positions: _.get(parsed, 'p', 'any'),
+            freqCompensation: _.get(parsed, 'c') === 'true',
+            analysis: _.get(parsed, 'a', 'none'),
+            maxDocuments: this.parseInt(_.get(parsed, 'm'), 50),
+            numberOfNgrams: this.parseInt(_.get(parsed, 'n'), 10),
+        }
+    }
+
+    private parseParamString(value: string): Record<string, string> {
+        const pairs = value.split(',').map(part => part.split(':', 2))
+        return _.fromPairs(pairs);
     }
 
-    findSetting(abbreviation: string, stringComponents: string[]): string | undefined{
-        const setting = stringComponents.find(s => s[0] === abbreviation);
-        return setting.split(':')[1];
+    private parseInt(value: string | undefined, defaultValue: number): number {
+        const parsed = parseInt(value, 10);
+        return _.isNaN(parsed) ? defaultValue : parsed;
     }
 }
diff --git a/frontend/src/app/models/visualization.ts b/frontend/src/app/models/visualization.ts
@@ -78,14 +78,14 @@ export type WordcloudParameters = {
 export type NGramRequestParameters = {
     corpus_name: string;
     field: string;
+    mode: 'ngrams' | 'collocates',
     ngram_size?: number;
     term_position?: string;
     freq_compensation?: boolean;
     subfield?: string;
     max_size_per_interval?: number;
     number_of_ngrams?: number;
     date_field: string;
-    mode?: 'ngrams' | 'collocates',
 } & APIQuery;
 
 
diff --git a/frontend/src/app/services/visualization.service.ts b/frontend/src/app/services/visualization.service.ts
@@ -104,6 +104,7 @@ export class VisualizationService {
             ...query,
             corpus_name: corpus.name,
             field,
+            mode: params.mode,
             ngram_size: params.size,
             term_position: params.positions,
             freq_compensation: params.freqCompensation,
diff --git a/frontend/src/app/visualization/ngram/ngram.component.html b/frontend/src/app/visualization/ngram/ngram.component.html
@@ -3,17 +3,17 @@
     <div class="columns is-multiline">
         <div class="column is-one-third">
             <div class="field">
-                <label class="label" iaBalloon="search for bigrams (2 words) or trigrams (3 words)"
+                <label class="label" iaBalloon="view ngrams (phrases) or collocates (loose words)"
                     iaBalloonPosition="up-left" iaBalloonLength="fit"
-                    id="label-size">
-                    Length of n-gram
+                    id="label-mode">
+                    Mode
                 </label>
                 <div class="control">
-                    <ia-dropdown [value]="currentSizeOption" labelledBy="label-size"
-                        (onChange)="onParameterChange('size', $event.value)">
-                        <span iaDropdownLabel>{{currentSizeOption?.label}}</span>
+                    <ia-dropdown [value]="currentModeOption" labelledBy="label-mode"
+                        (onChange)="onParameterChange('mode', $event.value)">
+                        <span iaDropdownLabel>{{currentModeOption?.label}}</span>
                         <div iaDropdownMenu>
-                            <a *ngFor="let option of sizeOptions"
+                            <a *ngFor="let option of modeOptions"
                                 iaDropdownItem [value]="option">
                                 {{option.label}}
                             </a>
@@ -24,17 +24,21 @@
         </div>
         <div class="column is-one-third">
             <div class="field">
-                <label class="label" iaBalloon="only search n-grams with the search term in the specified position"
-                iaBalloonPosition="up-left" iaBalloonLength="fit"
-                id="label-positions">
-                    Position of search term
+                <label class="label" iaBalloon="search for bigrams (2 words) or trigrams (3 words)"
+                    iaBalloonPosition="up-left" iaBalloonLength="fit"
+                    id="label-size">
+                    @if (currentSettings.mode === 'ngrams') {
+                        Length of n-gram
+                    } @else {
+                        Maximum distance
+                    }
                 </label>
                 <div class="control">
-                    <ia-dropdown [value]="currentPositionsOption" labelledBy="label-positions"
-                        (onChange)="onParameterChange('positions', $event.value)">
-                        <span iaDropdownLabel>{{currentPositionsOption?.label}}</span>
+                    <ia-dropdown [value]="currentSizeOption" labelledBy="label-size"
+                        (onChange)="onParameterChange('size', $event.value)">
+                        <span iaDropdownLabel>{{currentSizeOption?.label}}</span>
                         <div iaDropdownMenu>
-                            <a *ngFor="let option of positionsOptions"
+                            <a *ngFor="let option of sizeOptions"
                                 iaDropdownItem [value]="option">
                                 {{option.label}}
                             </a>
@@ -43,6 +47,29 @@
                 </div>
             </div>
         </div>
+        @if (currentSettings.mode === 'ngrams') {
+            <div class="column is-one-third">
+                <div class="field">
+                    <label class="label" iaBalloon="only search n-grams with the search term in the specified position"
+                    iaBalloonPosition="up-left" iaBalloonLength="fit"
+                    id="label-positions">
+                        Position of search term
+                    </label>
+                    <div class="control">
+                        <ia-dropdown [value]="currentPositionsOption" labelledBy="label-positions"
+                            (onChange)="onParameterChange('positions', $event.value)">
+                            <span iaDropdownLabel>{{currentPositionsOption?.label}}</span>
+                            <div iaDropdownMenu>
+                                <a *ngFor="let option of positionsOptions"
+                                    iaDropdownItem [value]="option">
+                                    {{option.label}}
+                                </a>
+                            </div>
+                        </ia-dropdown>
+                    </div>
+                </div>
+            </div>
+        }
         <div class="column is-one-third">
             <div class="field">
                 <label class="label" iaBalloon="divide by the average frequency of the words in the n-gram; favours words that are otherwise rare"
diff --git a/frontend/src/app/visualization/ngram/ngram.component.spec.ts b/frontend/src/app/visualization/ngram/ngram.component.spec.ts
@@ -17,15 +17,17 @@ describe('NgramComponent', () => {
     let fixture: ComponentFixture<NgramComponent>;
     let apiService: ApiServiceMock;
     let visualizationService: VisualizationService;
-    let cacheKey = 's:2,p:any,c:false,a:none,m:50,n:10';
-    let defaultSettings = {
+    let cacheKey = 'o:n,s:2,p:any,c:false,a:none,m:50,n:10';
+    let defaultSettings: NgramSettings = {
+        mode: 'ngrams',
         size: 2,
         positions: 'any',
         freqCompensation: false,
         analysis: 'none',
         maxDocuments: 50,
         numberOfNgrams: 10,
-    } as NgramSettings;
+    };
+    let element: HTMLElement;
 
     beforeEach(waitForAsync(() => {
         commonTestBed().testingModule.compileComponents();
@@ -56,6 +58,7 @@ describe('NgramComponent', () => {
         component.asTable = false;
         component.palette = ['yellow', 'blue'];
         fixture.detectChanges();
+        element = fixture.nativeElement;
     });
 
     it('should create', () => {
@@ -66,11 +69,31 @@ describe('NgramComponent', () => {
         expect(component.ngramParameters.state$.value).toEqual(defaultSettings);
     });
 
+    it('should switch labels in size selection', () => {
+        const label = element.querySelector('#label-size');
+        const dropdownLabel = (label.nextSibling as HTMLElement).querySelector('[iaDropdownLabel]')
+        expect(label.textContent.trim()).toBe('Length of n-gram');
+        expect(dropdownLabel.textContent.trim()).toBe('bigrams');
+
+        component.onParameterChange('mode', 'collocates');
+        fixture.detectChanges();
+        expect(label.textContent.trim()).toBe('Maximum distance');
+        expect(dropdownLabel.textContent.trim()).toBe('1');
+
+        component.onParameterChange('size', 3);
+        fixture.detectChanges();
+        expect(dropdownLabel.textContent.trim()).toBe('2');
+
+        component.onParameterChange('mode', 'ngrams');
+        fixture.detectChanges();
+        expect(dropdownLabel.textContent.trim()).toBe('trigrams');
+    });
+
     it('should not abort tasks when `onParameterChange` is triggered during initialization', () => {
         spyOn(component.stopPolling$, 'next');
         component.onParameterChange('size', 2);
         expect(component.stopPolling$.next).not.toHaveBeenCalled();
-    })
+    });
 
     it('should stop polling and abort running tasks when changing settings', () => {
         const dropdown = fixture.debugElement.query(By.css('ia-dropdown'));
@@ -102,6 +125,6 @@ describe('NgramComponent', () => {
         component.resultsCache = { [cacheKey]: fakeNgramResult };
         component.confirmChanges();
         expect(visualizationService.getNgramTasks).not.toHaveBeenCalled();
-    })
+    });
 
 });
diff --git a/frontend/src/app/visualization/ngram/ngram.component.ts b/frontend/src/app/visualization/ngram/ngram.component.ts
@@ -20,6 +20,10 @@ import {
 import { RouterStoreService } from '@app/store/router-store.service';
 import { NgramParameters, NgramSettings } from '@models/ngram';
 
+const makeNumberOptions = (values: number[]) => values.map((n) => ({
+    label: `${n}`,
+    value: n,
+}));
 
 @Component({
     selector: 'ia-ngram',
@@ -62,11 +66,26 @@ export class NgramComponent implements OnChanges {
     currentResults: NgramResults;
 
     // options
-    sizeOptions = [
+    modeOptions = [
+        { label: 'ngrams', value: 'ngrams' },
+        { label: 'collocates', value: 'collocates' },
+    ];
+    /** Size options for ngrams mode */
+    ngramsSizeOptions = [
         { label: 'bigrams', value: 2 },
         { label: 'trigrams', value: 3 },
         { label: 'fourgrams', value: 4 },
     ];
+    /** Size options for collocates mode.
+     * Note: for compatability with ngrams mode, values also count the search term itself,
+     * so a value of 2 (analogous to a bigram) means a maximum distance of 1.
+     */
+    collocationsSizeOptions = [
+        { label: '1', value: 2 },
+        { label: '2', value: 3 },
+        { label: '3', value: 4 },
+        { label: '5', value: 6 },
+    ];
     positionsOptions = ['any', 'first', 'second'].map((n) => ({
         label: `${n}`,
         value: n,
@@ -76,14 +95,8 @@ export class NgramComponent implements OnChanges {
         { label: 'Yes', value: true },
     ];
     analysisOptions: { label: string; value: string }[];
-    maxDocumentsOptions = [50, 100, 200, 500].map((n) => ({
-        label: `${n}`,
-        value: n,
-    }));
-    numberOfNgramsOptions = [10, 20, 50, 100].map((n) => ({
-        label: `${n}`,
-        value: n,
-    }));
+    maxDocumentsOptions = makeNumberOptions([50, 100, 200, 500]);
+    numberOfNgramsOptions = makeNumberOptions([10, 20, 50, 100]);
 
     tasksToCancel: string[];
 
@@ -110,10 +123,21 @@ export class NgramComponent implements OnChanges {
         this.currentSettings = _.clone(this.ngramParameters.state$.value);
     }
 
+    get sizeOptions() {
+        return this.currentSettings.mode == 'ngrams' ? this.ngramsSizeOptions :
+            this.collocationsSizeOptions;
+    }
+
+    get currentModeOption() {
+        return this.modeOptions.find(
+            (item) => item.value === this.currentSettings.mode
+        );
+    }
+
     get currentSizeOption() {
         return this.sizeOptions.find(
             (item) => item.value === this.currentSettings.size
-        );
+        ) || this.sizeOptions[0];
     }
 
     get currentPositionsOption() {
