# Usage Guide¶

This page contains the most common use cases for the `sigfig` module.

First make sure that `sigfig` is installed.

## Quickstart¶

Using the `sigfig` module’s `round()` function is very simple.

Begin by importing the module and adding its features to the built-in round function:

```>>> from sigfig import round
```

let’s round a number to 4 significant figures

```>>> round(123.456, 4)
123.5
```

but let’s get in the habit of storing our numbers as `str`ings to circumvent `float`’s inherent lack of precision. `round()` will always return in the rounded number in the same type it was given unless told otherwise:

```>>> round('123.456', 4)
'123.5'
>>> from decimal import Decimal
>>> round(Decimal(123456E-3), 3)
Decimal('123')
>>> round('123.456', 5, type=float)
123.46
```

We can round numbers by number of decimals, by significant figures/digits, or by the number’s uncertainty:

```>>> round('3.14159', sigfigs=2)
'3.1'
>>> round('3.14159', decimals=2)
'3.14'
>>> round('3.14159', uncertainty=2)
'3 ± 2'
```

which the function will choose based on the type/context of the 2nd argument:

```>>> round('3.14159', 2)
'3.1'
>>> round('3.14159', '0.0007524')
'3.1416 ± 0.0008'
```

When rounding by uncertainties we can isolate the rounded number and/or uncertainty by setting the `sep`aration keyword argument to `list` or `tuple` :

```>>> round('123456E-5', '123E-6', sep=tuple)
'1.2346'
>>> round(123456E-5, 123E-6, sep=list, type=Decimal)
[Decimal('1.2346'), Decimal('0.0001')]
```

### Formatting¶

We can use `round()` to output numbers in a myriad of different formats:

```>>> round('86375.25799', decimals=2, notation='sci') # scientific notation
'8.637526E4'
>>> round('86375.25799', sigfigs=3, notation='eng') # engineering notation
'86.4E3'
>>> round('86375.25799', '0.023759', format='PDG') # Particle Data Group preferred formatting
'86375.258 ± 0.024'
>>> round('863192837.1176159248', '.00002742764', format='Drake') # Drake Group preferred formatting
'863 192 837.117 616(27)'
```

or we can create our own custom format either from scratch

```>>> round('17265098762.12345678', .000000289, spacing=5, spacer=',', decimal='_', separation=' +/- ')
'1,72650,98762_12345,68 +/- 0_00000,03'
```

or by modifying an existing format:

```>>> round('86375.25799', '0.023759', format='PDG', sep='brackets')
'86375.258(24)'
>>> round('863192837.1176159248', '.00002742764', format='Drake', cutoff=22)
'863 192 837.117 62(3)'
```

See the API Documentation for a more detailed explanation of all above-used features.