it.unimi.dsi.mg4j.search.score
Class AbstractAggregator

java.lang.Object
  it.unimi.dsi.fastutil.ints.AbstractIntIterator
      it.unimi.dsi.mg4j.search.score.AbstractAggregator

All Implemented Interfaces:

IntIterator, FlyweightPrototype<Scorer>, Scorer, Iterator<Integer>

Direct Known Subclasses:

LinearAggregator

public abstract class AbstractAggregator
extends AbstractIntIterator
implements Scorer

A Scorer that aggregates a number of underlying delegating scorers, providing equalisation if required.

An aggregator combines the results of several scorers following some policy (see, e.g., LinearAggregator). In doing so, often the aggregator needs to explore the first scores returned by each scorer, and tune some internal parameters. This procedure, equalisation, is supported by this class: if equalize(int) is provided with a positive number of samples, they will be fetched from the underlying document iterator, scored, and passed to the implementing subclass so that equalisation information can be properly set up.

Additionally, this class ensures that if several scorers need access to intervals, the document iterator to be scored is decorated with a CachingDocumentIterator, so that several scorer can access intervals.

Since this class uses the same document iterator for all aggregated scorers, they must be necessarily delegating scorers.

Implementing subclasses must provide the following methods:

• setupEqualizationFactors(), which is called in case equalisation is required and must examine actualSamples elements from sampleScore (each element is a tuple of scores, one for each scorer) and use that information to set the equalisation factors (if samples is zero, default values must be applied);
• score(double[]), which must compute the equalised aggregated score using the given array of scores (each to be thought as a score coming from the respective scorer).

Additionally, implementing subclasses must remember to call equalize(int) when generating a flyweight copy, so that the state of the aggregator is reproduced correctly.

Field Summary

protected int	actualSamples The actual number of samples obtained (might be less than samples if we exhausted the document iterator).
protected int	currSample The next sample to be returned, if smaller than actualSamples.
protected double[]	currScore The current score.
protected DocumentIterator	documentIterator The current document iterator.
protected int	n The number of underlying scorers.
protected boolean	needsCaching Whether we need caching the intervals.
protected int[]	sampleDocument Cached sample of document pointers.
protected int	samples The number of samples for equalisation (0 means no equalisation).
protected double[][]	sampleScore Cached sample of document scores.
protected Scorer[]	scorer The underlying scorers.

Constructor Summary

AbstractAggregator(Scorer[] scorer)
Creates an aggregator.

Method Summary

void	equalize(int samples) Set the number of samples for equalisation.
Reference2DoubleMap<Index>	getWeights() Delegates to the underlying scorers.
boolean	hasNext()
int	nextDocument() Returns the next document provided by this scorer, or -1 if no more documents are available.
int	nextInt() Returns the next document.
double	score() Returns a score for the current document of the last document iterator given to Scorer.wrap(DocumentIterator).
protected abstract double	score(double[] score) Computes an aggregated score using the given array of basic scores.
double	score(Index index) Returns a score for the current document of the last document iterator given to Scorer.wrap(DocumentIterator), but considering only a given index (optional operation).
protected abstract void	setupEqualizationFactors() Sets up the equalisation factors.
boolean	setWeights(Reference2DoubleMap<Index> index2weight) Delegates to the underlying scorers.
boolean	usesIntervals() Delegates to the underlying scorers.
void	wrap(DocumentIterator documentIterator) Delegates to the underlying scorers, possibly wrapping the argument in a CachingDocumentIterator; then, if samples is nonzero computes that many document scores and invokes setupEqualizationFactors().

Methods inherited from class it.unimi.dsi.fastutil.ints.AbstractIntIterator

next, remove, skip

Methods inherited from class java.lang.Object

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

Methods inherited from interface it.unimi.dsi.mg4j.search.score.Scorer

copy

Methods inherited from interface it.unimi.dsi.fastutil.ints.IntIterator

skip

Methods inherited from interface java.util.Iterator

next, remove

Field Detail

documentIterator

protected DocumentIterator documentIterator

The current document iterator.

n

protected final int n

The number of underlying scorers.

scorer

protected final Scorer[] scorer

The underlying scorers.

currScore

protected final double[] currScore

The current score.

needsCaching

protected final boolean needsCaching

Whether we need caching the intervals.

sampleDocument

protected int[] sampleDocument

Cached sample of document pointers.

sampleScore

protected double[][] sampleScore

Cached sample of document scores.

samples

protected int samples

The number of samples for equalisation (0 means no equalisation).

currSample

protected int currSample

The next sample to be returned, if smaller than actualSamples.

actualSamples

protected int actualSamples

The actual number of samples obtained (might be less than samples if we exhausted the document iterator).

Constructor Detail

AbstractAggregator

public AbstractAggregator(Scorer[] scorer)

Creates an aggregator.

Parameters:

scorer - the scorers.

Method Detail

score

public double score(Index index)

Description copied from interface: Scorer

Returns a score for the current document of the last document iterator given to Scorer.wrap(DocumentIterator), but considering only a given index (optional operation).

Specified by:

score in interface Scorer

Parameters:

index - the only index to be considered.

Returns:

the score.

score

public double score()
             throws IOException

Description copied from interface: Scorer

Returns a score for the current document of the last document iterator given to Scorer.wrap(DocumentIterator).

Specified by:

score in interface Scorer

Returns:

the score.

Throws:

IOException

equalize

public void equalize(int samples)

Set the number of samples for equalisation.

Parameters:

samples - the number of samples to be used to equalise scores; a value of zero disables equalisation.

See Also:

AbstractAggregator

setWeights

public boolean setWeights(Reference2DoubleMap<Index> index2weight)

Delegates to the underlying scorers.

Specified by:

setWeights in interface Scorer

Parameters:

index2weight - a map from indices to weights.

Returns:

true if at least one underlying scorer supports weights.

getWeights

public Reference2DoubleMap<Index> getWeights()

Delegates to the underlying scorers.

Specified by:

getWeights in interface Scorer

Returns:

true if at least one underlying scorer supports weights.

usesIntervals

public boolean usesIntervals()

Delegates to the underlying scorers.

Specified by:

usesIntervals in interface Scorer

Returns:

true if at least one underlying scorer uses intervals.

wrap

public void wrap(DocumentIterator documentIterator)
          throws IOException

Delegates to the underlying scorers, possibly wrapping the argument in a CachingDocumentIterator; then, if samples is nonzero computes that many document scores and invokes setupEqualizationFactors().

Specified by:

wrap in interface Scorer

Parameters:

documentIterator - the document iterator that will be used in subsequent calls to Scorer.score() and Scorer.score(Index).

Throws:

IOException

score

protected abstract double score(double[] score)

Computes an aggregated score using the given array of basic scores. The array is parallel to scorer.

Parameters:

score - an array of scores.

Returns:

the aggregated scorer.

setupEqualizationFactors

protected abstract void setupEqualizationFactors()

Sets up the equalisation factors.

Implementations should look into sampleScore and set up the equalisation logic. Note that this method is responsible for setting up appropriate equalisation factors even if no equalisation is required (e.g., setting all factors to 1 ).

nextDocument

public int nextDocument()
                 throws IOException

Description copied from interface: Scorer

Returns the next document provided by this scorer, or -1 if no more documents are available.

Specified by:

nextDocument in interface Scorer

Returns:

the next document, or -1 if no more documents are available.

Throws:

IOException

hasNext

public boolean hasNext()

Specified by:

hasNext in interface Iterator<Integer>

nextInt

public int nextInt()

Description copied from interface: Scorer

Returns the next document.

Specified by:

nextInt in interface IntIterator

Specified by:

nextInt in interface Scorer

Overrides:

nextInt in class AbstractIntIterator

See Also:

Scorer.nextDocument()