nl.inl.blacklab.search

Class TermFrequencyList

java.lang.Object

nl.inl.blacklab.search.results.Results<TermFrequency>

nl.inl.blacklab.search.TermFrequencyList

All Implemented Interfaces:

Iterable<TermFrequency>, SearchResult

public class TermFrequencyList
extends Results<TermFrequency>

A collection of tokens and their (absolute) frequencies. This class calculates the total frequency of the entries added, but you can also set the total frequency explicitly (after all entries have been added) if you want to calculate relative frequencies based on a different total.

Field Summary

Fields inherited from class nl.inl.blacklab.search.results.Results

hitsObjId, NO_LIMIT, results, threadPauser

Constructor Summary

Constructors

Constructor and Description
TermFrequencyList(QueryInfo queryInfo, Map<String,Integer> wordFreq, boolean sort)

Method Summary

Modifier and Type	Method and Description
static TermFrequencyList	collocations(Hits hits, Annotation annotation, ContextSize contextSize, MatchSensitivity sensitivity, boolean sort) Count occurrences of context words around hit.
boolean	doneProcessingAndCounting() Check if we're done retrieving/counting hits.
protected void	ensureResultsRead(int number) Ensure that we have read at least as many results as specified in the parameter.
TermFrequencyList	filter(ResultProperty<TermFrequency> property, PropertyValue value) Select only the hits where the specified property has the specified value.
long	frequency(String token) Get the frequency of a specific token
TermFrequency	get(int index) Return the specified hit.
ResultGroups<TermFrequency>	group(ResultProperty<TermFrequency> criteria, int maxResultsToStorePerGroup) Group these hits by a criterium (or several criteria).
Iterator<TermFrequency>	iterator() Return an iterator over these hits.
int	numberOfResultObjects() How many result objects does this search store? Used for estimating the cache size.
TermFrequencyList	sample(SampleParameters sampleParameters) Take a sample of results.
int	size() This is an alias of resultsProcessedTotal().
<P extends ResultProperty<TermFrequency>> TermFrequencyList	sort(P sortProp) Return a new Results object with these results sorted by the given property.
TermFrequencyList	subList(int fromIndex, int toIndex)
long	totalFrequency()
TermFrequencyList	window(int first, int windowSize) Get a window into this list of results.

Methods inherited from class nl.inl.blacklab.search.results.Results

doFilter, doSample, doSort, doWindow, ensureAllResultsRead, field, index, isSample, isWindow, parallelStream, queryInfo, resultsCountedSoFar, resultsCountedTotal, resultsList, resultsObjId, resultsProcessedAtLeast, resultsProcessedSoFar, resultsProcessedTotal, resultsStats, resultsSubList, sampleParameters, stream, threadPauser, toString, windowStats

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

TermFrequencyList

public TermFrequencyList(QueryInfo queryInfo,
                         Map<String,Integer> wordFreq,
                         boolean sort)

Method Detail

collocations

public static TermFrequencyList collocations(Hits hits,
                                             Annotation annotation,
                                             ContextSize contextSize,
                                             MatchSensitivity sensitivity,
                                             boolean sort)

Count occurrences of context words around hit.

Parameters:

hits - hits to get collocations for

annotation - annotation to use for the collocations, or null if default

contextSize - how many words around hits to use

sensitivity - what sensitivity to use

sort - whether or not to sort the list by descending frequency

Returns:

the frequency of each occurring token

size

public int size()

Description copied from class: Results

This is an alias of resultsProcessedTotal().

Overrides:

size in class Results<TermFrequency>

Returns:

number of hits processed total

iterator

public Iterator<TermFrequency> iterator()

Description copied from class: Results

Return an iterator over these hits.

Specified by:

iterator in interface Iterable<TermFrequency>

Overrides:

iterator in class Results<TermFrequency>

Returns:

the iterator

get

public TermFrequency get(int index)

Description copied from class: Results

Return the specified hit.

Overrides:

get in class Results<TermFrequency>

Parameters:

index - index of the desired hit

Returns:

the hit, or null if it's beyond the last hit

frequency

public long frequency(String token)

Get the frequency of a specific token

Parameters:

token - the token to get the frequency for

Returns:

the frequency

totalFrequency

public long totalFrequency()

subList

public TermFrequencyList subList(int fromIndex,
                                 int toIndex)

ensureResultsRead

protected void ensureResultsRead(int number)

Description copied from class: Results

Ensure that we have read at least as many results as specified in the parameter.

Specified by:

ensureResultsRead in class Results<TermFrequency>

Parameters:

number - the minimum number of results that will have been read when this method returns (unless there are fewer hits than this); if negative, reads all hits

group

public ResultGroups<TermFrequency> group(ResultProperty<TermFrequency> criteria,
                                         int maxResultsToStorePerGroup)

Description copied from class: Results

Group these hits by a criterium (or several criteria).

Specified by:

group in class Results<TermFrequency>

Parameters:

criteria - the hit property to group on

maxResultsToStorePerGroup - maximum number of results to store per group, or -1 for all

Returns:

a HitGroups object representing the grouped hits

filter

public TermFrequencyList filter(ResultProperty<TermFrequency> property,
                                PropertyValue value)

Description copied from class: Results

Select only the hits where the specified property has the specified value.

Specified by:

filter in class Results<TermFrequency>

Parameters:

property - property to select on, e.g. "word left of hit"

value - value to select on, e.g. 'the'

Returns:

filtered hits

sort

public <P extends ResultProperty<TermFrequency>> TermFrequencyList sort(P sortProp)

Description copied from class: Results

Return a new Results object with these results sorted by the given property. This keeps the existing sort (or lack of one) intact and allows you to cache different sorts of the same resultset. The result objects are reused between the two Results instances, so not too much additional memory is used.

Specified by:

sort in class Results<TermFrequency>

Parameters:

sortProp - the property to sort on

Returns:

a new Results object with the same results, sorted in the specified way

window

public TermFrequencyList window(int first,
                                int windowSize)

Description copied from class: Results

Get a window into this list of results. Use this if you're displaying part of the resultset, like in a paging interface. It makes sure BlackLab only works with the results you want to display and doesn't do any unnecessary processing on the other hits. The resulting instance will has "window stats" to assist with paging, like figuring out if there hits before or after the window.

Specified by:

window in class Results<TermFrequency>

Parameters:

first - first result in the window (0-based)

windowSize - desired size of the window (if there's enough results)

Returns:

the window

sample

public TermFrequencyList sample(SampleParameters sampleParameters)

Description copied from class: Results

Take a sample of results.

Specified by:

sample in class Results<TermFrequency>

Parameters:

sampleParameters - sample parameters

Returns:

the sample

doneProcessingAndCounting

public boolean doneProcessingAndCounting()

Description copied from class: Results

Check if we're done retrieving/counting hits. If you're retrieving hits in a background thread, call this method from another thread to check if all hits have been processed.

Specified by:

doneProcessingAndCounting in class Results<TermFrequency>

Returns:

true iff all hits have been retrieved/counted.

numberOfResultObjects

public int numberOfResultObjects()

Description copied from interface: SearchResult

How many result objects does this search store? Used for estimating the cache size. Hits make up most of the storage of results objects, and they should take 24 bytes of memory, so we can use this number to make a reasonable approximation of memory usage. Note that this number can be misleading, because Hit objects are shared between results objects. But it's the best we have at the moment.

Returns:

how many hits are stored in this result object