Roger

Used by SupervisedTermExtractor with method="roger".

RogerTermExtractor(population_size=20, offspring_size=100, generations=100, runs=21, n=2, random_state=None, max_negatives=10000, patience=None, n_jobs=None, stopwords='english', words_layer=None, terms_layer=GOLD_LAYER)

Supervised term ranking with n'Roger (Azé et al., 2005).

Each multi-word candidate w1 ... wk is described by the association measures in MEASURES between its first words w1 ... wk-1 and its last word wk, computed over all the k-word sequences in the corpus. Single words have no parts to associate, so they are not ranked.

A (μ+λ) evolution strategy learns a ranking function that maximises the area under the ROC curve (the Wilcoxon rank statistic) of the labelled candidates. Ranking functions are non-linear: a candidate with (normalised) measures x is scored sum(w[i] * abs(x[i] - c[i])), with weights w and centre c. The final score of a candidate is the median of its scores under the ranking functions learned by runs independent runs.

Reference

Azé, J., Roche, M., Kodratoff, Y. and Sebag, M. (2005). Preference learning in terminology extraction: a ROC-based approach. In Proceedings of Applied Stochastic Models and Data Analysis, pp. 209–219. https://arxiv.org/abs/cs/0512050

Initialize the Roger extractor.

The defaults for population_size, offspring_size and runs are those of Azé et al. (2005).

Parameters:

Name	Type	Description	Default
population_size	int	Number of parents (μ) kept in each generation.	20
offspring_size	int	Number of offspring (λ) created in each generation.	100
generations	int	Number of generations in each run.	100
runs	int	Number of independent runs whose ranking functions are combined.	21
n	int	Maximum n-gram size, at least 2.	2
random_state	Optional[int]	Seed for the evolutionary search, for reproducible scores.	None
max_negatives	Optional[int]	Train on at most this many of the candidates labelled 0, chosen at random for each run, and on all those labelled 1. The area under the ROC curve does not depend on the share of each label, so this speeds up training on large corpora with little effect on the ranking functions: on the English benchmark, 10,000 negatives train about 30 times faster than all of them, with similar results. None trains on every labelled candidate.	10000
patience	Optional[int]	Stop a run early when its best ranking function has not improved for this many generations, or None to run every generation.	None
n_jobs	Optional[int]	Number of runs trained in parallel, as in joblib: -1 for one per CPU, or None for one at a time.	None
stopwords	Union[str, Iterable[str], None]	Drop extracted terms that start or end with a stopword: a name in STOPWORD_LISTS, a list of words, or None.	'english'
words_layer	Optional[str]	For Teanga input, the span layer holding the words, or None for words or, failing that, tokens.	None
terms_layer	str	For Teanga input without labels, the span layer of gold terms to train on.	GOLD_LAYER

Raises:

Type	Description
ValueError	If n is less than 2.

crossover_rate = 0.6 class-attribute instance-attribute

Probability that an offspring is created by uniform crossover of two parents.

extract_features(docs)

Compute the association measures of every candidate of 2 to n words.

Parameters:

Name	Type	Description	Default
docs	list[list[str]]	The words of each document.	required

Returns:

Type	Description
ndarray	The feature matrix (one row per candidate, one column per measure) and the
list[str]	candidates, in order of first occurrence.

rank_scores(w, c, X) staticmethod

Score the candidates X with each ranking function (w[j], c[j]).

Returns:

Type	Description
ndarray	np.ndarray: One row of candidate scores per ranking function.

auc(scores, y) staticmethod

Area under the ROC curve of each row of scores.

This is the Wilcoxon rank statistic: the probability that a positive example is scored higher than a negative one, counting ties as one half.

optimize_rank_function(X, y, rng)

Run the (μ+λ) evolution strategy once.

Each individual is a ranking function (w, c) with a self-adaptive mutation step size for each of its genes. Offspring are created by uniform crossover of two random parents (with probability crossover_rate) or by copying one, and are then mutated. The best population_size of the parents and offspring become the next parents.

Returns:

Type	Description
tuple[ndarray, ndarray]	The weights and centre of the best ranking function, with sum(abs(w)) == 1.

train(docs, labels)

Learn runs ranking functions from the labelled candidates in docs.

As in Azé et al. (2005), only the labelled candidates are training examples. If none of them is labelled 0, as with a list of gold terms, every unlabelled candidate is a negative example instead. The measures are normalised to the range of all the candidates in docs.

Raises:

Type	Description
ValueError	If no candidate in docs is labelled 1, or every one is.

predict(docs)

Score the candidates in docs with the median of the learned functions.

train_model(corpus, labels)

Learn the ranking functions from a list of strings.

predict_terms_strings(corpus)

Score the candidates in a list of strings.

predict_terms_teanga(corpus)

Score the candidates in a Teanga corpus.

fit_strings(corpus, labels)

Learn the ranking functions from a list of strings.

fit_teanga(corpus, labels=None)

Learn the ranking functions from a Teanga corpus, with the gold terms of terms_layer as the terms if labels is None.

gold_terms(corpus)

The gold terms of terms_layer, each as the lower-cased words within its span, as candidates are written.

predict_strings(corpus)

Rank the candidates of a list of strings with the learned functions.

predict_teanga(corpus)

Rank the candidates of a Teanga corpus, with their offsets.

extract_terms_teanga(corpus, labels)

Learn from a Teanga corpus with Roger and rank its candidates.

extract_terms_strings(corpus, labels)

Learn from a list of strings with Roger and rank its candidates.