[Experimental]

Constructs a numeric vector that can be formatted with predefined significant digits, or with a maximum or fixed number of digits after the decimal point. Scaling is supported, as well as forcing a decimal, scientific or engineering notation. If a label is given, it is shown in the header of a column.

The formatting is applied when the vector is printed or formatted, and also in a tibble column. The formatting annotation and the class survives most arithmetic transformations, the most notable exceptions are var() and sd().

num(
  x,
  ...,
  sigfig = NULL,
  digits = NULL,
  label = NULL,
  scale = NULL,
  notation = c("fit", "dec", "sci", "eng", "si"),
  fixed_exponent = NULL,
  extra_sigfig = NULL
)

Arguments

x

A numeric vector.

...

These dots are for future extensions and must be empty.

sigfig

Define the number of significant digits to show. Must be one or greater. The "pillar.sigfig" option is not consulted. Can't be combined with digits.

digits

Number of digits after the decimal points to show. Positive numbers specify the exact number of digits to show. Negative numbers specify (after negation) the maximum number of digits to show. With digits = 2, the numbers 1.2 and 1.234 are printed as 1.20 and 1.23, with digits = -2 as 1.2 and 1.23, respectively. Can't be combined with sigfig.

label

A label to show instead of the type description.

scale

Multiplier to apply to the data before showing. Useful for displaying e.g. percentages. Must be combined with label.

notation

One of "fit", "dec", "sci", "eng", or "si".

  • "fit": Use decimal notation if it fits and if it consumes 13 digits or less, otherwise use scientific notation. (The default for numeric pillars.)

  • "dec": Use decimal notation, regardless of width.

  • "sci": Use scientific notation.

  • "eng": Use engineering notation, i.e. scientific notation using exponents that are a multiple of three.

  • "si": Use SI notation, prefixes between 1e-24 and 1e24 are supported.

fixed_exponent

Use the same exponent for all numbers in scientific, engineering or SI notation. -Inf uses the smallest, +Inf the largest fixed_exponent present in the data. The default is to use varying exponents.

extra_sigfig

If TRUE, increase the number of significant digits if the data consists of numbers of the same magnitude with subtle differences.

See also

Other vector classes: char()

Examples

# Display as a vector
num(9:11 * 100 + 0.5)
#> <pillar_num[3]>
#> [1]  900. 1000. 1100.

# Significant figures
tibble(
  x3 = num(9:11 * 100 + 0.5, sigfig = 3),
  x4 = num(9:11 * 100 + 0.5, sigfig = 4),
  x5 = num(9:11 * 100 + 0.5, sigfig = 5),
)
#> # A tibble: 3 × 3
#>        x3      x4      x5
#>   <num:3> <num:4> <num:5>
#> 1    900.   900.5   900.5
#> 2   1000.  1000.   1000.5
#> 3   1100.  1100.   1100.5

# Maximum digits after the decimal points
tibble(
  x0 = num(9:11 * 100 + 0.5, digits =  0),
  x1 = num(9:11 * 100 + 0.5, digits = -1),
  x2 = num(9:11 * 100 + 0.5, digits = -2),
)
#> # A tibble: 3 × 3
#>         x0       x1       x2
#>   <num:.0> <num:.1> <num:.2>
#> 1     900.    900.5    900.5
#> 2    1000.   1000.5   1000.5
#> 3    1100.   1100.5   1100.5

# Use fixed digits and a currency label
tibble(
  usd = num(9:11 * 100 + 0.5, digits = 2, label = "USD"),
  gbp = num(9:11 * 100 + 0.5, digits = 2, label = "£"),
  chf = num(9:11 * 100 + 0.5, digits = 2, label = "SFr")
)
#> # A tibble: 3 × 3
#>       usd     gbp     chf
#>       USD       £     SFr
#> 1  900.50  900.50  900.50
#> 2 1000.50 1000.50 1000.50
#> 3 1100.50 1100.50 1100.50

# Scale
tibble(
  small  = num(9:11 / 1000 + 0.00005, label = "%", scale = 100),
  medium = num(9:11 /  100 + 0.0005 , label = "%", scale = 100),
  large  = num(9:11 /   10 + 0.005  , label = "%", scale = 100)
)
#> # A tibble: 3 × 3
#>   small medium large
#>       %      %     %
#> 1 0.905   9.05  90.5
#> 2 1.00   10.0  100. 
#> 3 1.10   11.0  110. 

# Notation
tibble(
  sci = num(10^(-13:6), notation = "sci"),
  eng = num(10^(-13:6), notation = "eng"),
  si  = num(10^(-13:6), notation = "si"),
  dec = num(10^(-13:6), notation = "dec")
)
#> # A tibble: 20 × 4
#>      sci     eng    si                   dec
#>    <sci>   <eng>  <si>                 <dec>
#>  1 1e-13 100e-15  100f       0.0000000000001
#>  2 1e-12   1e-12    1p       0.000000000001 
#>  3 1e-11  10e-12   10p       0.00000000001  
#>  4 1e-10 100e-12  100p       0.0000000001   
#>  5 1e- 9   1e- 9    1n       0.000000001    
#>  6 1e- 8  10e- 9   10n       0.00000001     
#>  7 1e- 7 100e- 9  100n       0.0000001      
#>  8 1e- 6   1e- 6    1µ       0.000001       
#>  9 1e- 5  10e- 6   10µ       0.00001        
#> 10 1e- 4 100e- 6  100µ       0.0001         
#> 11 1e- 3   1e- 3    1m       0.001          
#> 12 1e- 2  10e- 3   10m       0.01           
#> 13 1e- 1 100e- 3  100m       0.1            
#> 14 1e+ 0   1e+ 0    1        1              
#> 15 1e+ 1  10e+ 0   10       10              
#> 16 1e+ 2 100e+ 0  100      100              
#> 17 1e+ 3   1e+ 3    1k    1000              
#> 18 1e+ 4  10e+ 3   10k   10000              
#> 19 1e+ 5 100e+ 3  100k  100000              
#> 20 1e+ 6   1e+ 6    1M 1000000              

# Fixed exponent
tibble(
  scimin = num(10^(-7:6) * 123, notation = "sci", fixed_exponent = -Inf),
  engmin = num(10^(-7:6) * 123, notation = "eng", fixed_exponent = -Inf),
  simin  = num(10^(-7:6) * 123, notation = "si",  fixed_exponent = -Inf)
)
#> # A tibble: 14 × 3
#>                  scimin               engmin              simin
#>                   <sci>                <eng>               <si>
#>  1              1.23e-5              12.3e-6              12.3µ
#>  2             12.3 e-5             123  e-6             123  µ
#>  3            123   e-5            1230  e-6            1230  µ
#>  4           1230   e-5           12300  e-6           12300  µ
#>  5          12300   e-5          123000  e-6          123000  µ
#>  6         123000   e-5         1230000  e-6         1230000  µ
#>  7        1230000   e-5        12300000  e-6        12300000  µ
#>  8       12300000   e-5       123000000  e-6       123000000  µ
#>  9      123000000   e-5      1230000000  e-6      1230000000  µ
#> 10     1230000000   e-5     12300000000  e-6     12300000000  µ
#> 11    12300000000   e-5    123000000000  e-6    123000000000  µ
#> 12   123000000000   e-5   1230000000000  e-6   1230000000000  µ
#> 13  1230000000000   e-5  12300000000000  e-6  12300000000000  µ
#> 14 12300000000000   e-5 123000000000000  e-6 123000000000000  µ

tibble(
  scismall = num(10^(-7:6) * 123, notation = "sci", fixed_exponent = -3),
  scilarge = num(10^(-7:6) * 123, notation = "sci", fixed_exponent = 3),
  scimax   = num(10^(-7:6) * 123, notation = "sci", fixed_exponent = Inf)
)
#> # A tibble: 14 × 3
#>                scismall            scilarge              scimax
#>                   <sci>               <sci>               <sci>
#>  1            0.0123e-3      0.0000000123e3 0.000000000000123e8
#>  2            0.123 e-3      0.000000123 e3 0.00000000000123 e8
#>  3            1.23  e-3      0.00000123  e3 0.0000000000123  e8
#>  4           12.3   e-3      0.0000123   e3 0.000000000123   e8
#>  5          123     e-3      0.000123    e3 0.00000000123    e8
#>  6         1230     e-3      0.00123     e3 0.0000000123     e8
#>  7        12300     e-3      0.0123      e3 0.000000123      e8
#>  8       123000     e-3      0.123       e3 0.00000123       e8
#>  9      1230000     e-3      1.23        e3 0.0000123        e8
#> 10     12300000     e-3     12.3         e3 0.000123         e8
#> 11    123000000     e-3    123           e3 0.00123          e8
#> 12   1230000000     e-3   1230           e3 0.0123           e8
#> 13  12300000000     e-3  12300           e3 0.123            e8
#> 14 123000000000     e-3 123000           e3 1.23             e8

#' Extra significant digits
tibble(
  default = num(100 + 1:3 * 0.001),
  extra1 = num(100 + 1:3 * 0.001, extra_sigfig = TRUE),
  extra2 = num(100 + 1:3 * 0.0001, extra_sigfig = TRUE),
  extra3 = num(10000 + 1:3 * 0.00001, extra_sigfig = TRUE)
)
#> # A tibble: 3 × 4
#>   default  extra1   extra2      extra3
#>     <num>   <num>    <num>       <num>
#> 1    100. 100.001 100.0001 10000.00001
#> 2    100. 100.002 100.0002 10000.00002
#> 3    100. 100.003 100.0003 10000.00003