Repository files navigation

Number Words will build numeric expressions for natural numbers, percentages and fractions. For example:

• 0.231 will be converted toless than a quarter,
• 102 toover one hundred.

Supports multiple languages.

The implementation is based on ideas expressed inGenerating Numerical Approximations.

Numerical approximations are all over texts based on data:

- Water temperature is below 10C (input data would be 9.53C)- A third of students failed the exam (34.3%)- Q2 sales were over 1M$ (1,002,184 $)

Numeric data providing information about some metrics of interest is often a number with the precision we do not need. If we see 9.382%, the information we need is likely -almost 10% - instead of the precise number. Furthermore, different approximation strategies are often used in the report involving the same metrics. At the beginning of the report we might sayalmost 10% or "below 10%" while later in the text, we might choose a more precise expression -around 9.4%.

Number Words will help you build such numerical approximations. Making them available for the text generation systems.

Number Words uses the following abstractions:

• Actual Value is a number which needs to be approximated - an input to the approximation function. In the examples above it is the temperature -9.53C, or the percentage34.3%.
• Scale of approximation. It is a snapping grid across the range of numbers along which the approximation is done. The scale to use is determined by the domain. For example:
  • 1/4 scale, will form approximation steps starting at0 then1/4,1/2,3/4 ending with1;
  • 1/10 scale will express percentages with one precision point;
  • scales which are multiples of10 are useful for natural number approximation. The10 will round to tens:1007 ->1010, the100 to hundreds:1003 ->1000, and so on.

The result ofactual value approximation to a given scale provides:

• Given Value a discrete value along the scaled number range to whichactual value is the closest.
• Hedge a common use word describing the relation betweenactual andgiven values.Actual Value of9.5 isbelow thegiven value of10.Actual Value of101 isover thegiven value of100.
• Text a textual spell out of thegiven value. A2666 isTwo thousand six hundred sixty six.
• Favorite Number expresses some common language names for certain numbers. A0.25 is a favorite number in that that it has the name -a quarter.

A full approximation result returns three such approximation data structures for agiven value which is:

• less than theactual value on the scaled number range.
• more than theactual value on the scaled number range.
• around theactual value on the scaled number range. For this 'less' or 'more' value closer to theactual value is chosen.

Lastly the number formatting can be specified:

• words - spell out the number in words (110 -> hundred and ten).
• bites - spell out the number using bite size style shortening (1022 -> 1k).
• numbers - report number as is.

Numeric approximation has two functionality points which are language dependent

• Hedges which will differ from language to language. SeeConfiguration section to see how this can be controlled.
• Text number to text translation for agiven value. For this translation Number Words relies onICU4J.

Currently supported languages:

• French
• German
• English
• Lithuanian
• Portuguese
• Russian

Number Words exposes approximation functionality throughnumeric-expression function which takes on the following parameters:

• actual-value - the number to approximate
• scale - at which the approximation is to be performed.
• language - use two letter language code (like :pt), default is :en
• relation - what kind of relation to between actual and given value to use (valid values specified in:numberwords.domain/relation)
• formatting - which number formatting should be used (valid values specified in:numberwords.domain/formatting)

Number Words is available as a Maven artifact fromClojars.

Leiningen

[ai.tokenmill.numberwords/numberwords "1.1.0"]

deps.edn

ai.tokenmill.numberwords/numberwords {:mvn/version "1.1.0"}

Usage example:

(require '[numberwords.core :as nw])(numeric-expression 144 10 :en :numberwords.domain/around :numberwords.domain/words)=>"around one hundred forty"(numeric-expression 144 10 :de :numberwords.domain/less :numberwords.domain/numbers)=>"weniger als 150";; with defaults(numeric-expression 144 10)=>"around 140"

Get ajar by building it with

clojure -A:uberjar

Or as aMaven dependency

<repository>    <id>clojars.org</id>    <url>http://clojars.org/repo</url></repository><dependency>    <groupId>ai.tokenmill.numberwords</groupId>    <artifactId>numberwords</artifactId>    <version>1.1.0</version></dependency>

Usage example:

import ai.tokenmill.numberwords.NumberWords;NumberWords nw = new NumberWords();nw.numericExpression(1.22, 0.1, "en", "more", "numbers");

Hedges, favorite numbers can be modified and new languages added via changes to a configuration file -resources/numwords.edn

{;;Configuration is structured by the language  :en {      ;;Hedges section specifies which words are associated with given actual to given value relations      :hedges {:equal  #{"exactly"}               :around #{"around" "approximately" "about"}               :more   #{"more than" "over"}               :less   #{"less than" "under" "nearly"}}            ;;Favourite numbers map a special number with its textual expressions      :favorite-numbers {1/4  #{"a quarter" "a fourth"}                         1/2  #{"a half"}}}}

Copyright © 2020TokenMill UAB.

Distributed under the The Apache License, Version 2.0.

Photo byAmanda Jones onUnsplash