cts.frequency

cts.frequency(
   value as Item
) as Number

Summary

Returns an integer representing the number of times in which a particular value occurs in a value lexicon lookup.

Usage Notes

You must have a suitable index configured to use the lexicon APIs. For example you must configure a range index to use value lexicon lookup functions such as cts.elementValues, cts.elementValueMatch, cts.elementAttributeValues, or cts.elementAttributeValueMatch.

If the value specified is not from a value lexicon lookup, this function returns a frequency of 0.

When using the fragment-frequency lexicon option, this function returns the number of fragments in which the lexicon value occurs. When using the item-frequency lexicon option, this function returns the total number of times in which the lexicon value occurs in each item.

The frequency returned this function is fragment-based by default (using the default fragment-frequency option in the lexicon API). If there are multiple occurrences of the value in any given fragment, the frequency is still one per fragment when using fragment-frequency. For example, if this function returns a value of 13, then the input value occurs in 13 fragments.

To get the total frequency rather than the fragment-based frequency, pass the item-frequency option to the lexicon lookup function that generates the input values for this function. See the second example, below.

Example

// Example using fragment frequency (default). An element range index
// on SPEAKER must exist. 
let results = new Array();
const speakers = cts.elementValues(xs.QName("SPEAKER"),"", null,
  cts.documentQuery("/shakespeare/plays/hamlet.xml"));
for (const speaker of speakers) {
  results.push({name: speaker, numSpeeches: cts.frequency(speaker)})
};
results;

// Returns the names of the speakers in Hamlet with the number of times 
// they speak. If the play is fragmented at the SCENE level, then
// it returns the number of scenes in which each speaker speaks. 
// For example:
//
// [{"name":"All", "numSpeeches":4}, 
//  {"name":"BERNARDO", "numSpeeches":2},
//  ...]

Example

// Example using item frequency. An element range index on SPEAKER must exist. 
let results = new Array();
const speakers = cts.elementValues(xs.QName("SPEAKER"),"",
  ['item-frequency'],
  cts.documentQuery("/shakespeare/plays/hamlet.xml"));
for (const speaker of speakers) {
  results.push({name: speaker, numSpeeches: cts.frequency(speaker)})
};
results;

// Returns the names of the speakers in Hamlet with the number of times 
// they speak. Returns the total times they speak, regardless of
// fragmentation. For example:
// For example:
//
// [{"name":"All", "numSpeeches":4}, 
//  {"name":"BERNARDO", "numSpeeches":23},
//  ...]