Liking cljdoc? Tell your friends :D

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

`0.231`

will be converted to`less than a quarter`

,`102`

to`over one hundred`

.

Supports multiple languages.

The implementation is based on ideas expressed in Generating 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 say *almost 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 percentage`34.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 at`0`

then`1/4`

,`1/2`

,`3/4`

ending with`1`

;`1/10`

scale will express percentages with one precision point;- scales which are multiples of
`10`

are useful for natural number approximation. The`10`

will round to tens:`1007`

->`1010`

, the`100`

to hundreds:`1003`

->`1000`

, and so on.

The result of *actual value* approximation to a given scale provides:

*Given Value*a discrete value along the scaled number range to which*actual value*is the closest.*Hedge*a common use word describing the relation between*actual*and*given*values.*Actual Value*of`9.5`

is**below**the*given value*of`10`

.*Actual Value*of`101`

is**over**the*given value*of`100`

.*Text*a textual spell out of the*given value*. A`2666`

is`Two thousand six hundred sixty six`

.*Favorite Number*expresses some common language names for certain numbers. A`0.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 a *given value* which is:

**less**than the*actual value*on the scaled number range.**more**than the*actual value*on the scaled number range.**around**the*actual value*on the scaled number range. For this 'less' or 'more' value closer to the*actual 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. See Configuration section to see how this can be controlled.*Text*number to text translation for a*given value*. For this translation Number Words relies on ICU4J.

Currently supported languages:

- French
- German
- English
- Lithuanian
- Portuguese
- Russian

Number Words exposes approximation functionality through `numeric-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 from Clojars.

*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 a *jar* by building it with

```
clojure -A:uberjar
```

Or as a *Maven* 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 © 2020 TokenMill UAB.

Distributed under the The Apache License, Version 2.0.

Photo by Amanda Jones on Unsplash

**Can you improve this documentation?** These fine people already did:

Žygimantas Medelis, 0xflotus & Luke HarriesEdit on GitHub

**cljdoc** is a website building & hosting documentation for Clojure/Script libraries