# Summary Statistics

[`summarize()`](../reference/summarize.md) computes the basic summary statistics of a set of numbers:


``` python
from tinytab import summarize

result = summarize([3.5, 2.25, 4.0, 1.75])
result
```


    SummaryResult(n=4, mean=2.875, sd=1.051, min=1.75, max=4)


# The result object

[summarize()](../reference/summarize.md#tinytab.summarize) returns a [`SummaryResult`](../reference/SummaryResult.md), with one attribute per statistic:


``` python
result.mean, result.sd
```


    (2.875, 1.050793351076541)


| Attribute    | Meaning                                             |
|--------------|-----------------------------------------------------|
| `n`          | the number of values summarized                     |
| `mean`       | the arithmetic mean                                 |
| `sd`         | the sample standard deviation (dividing by `n - 1`) |
| `min`, `max` | the smallest and largest values                     |

The printed form rounds to four significant figures, to keep it readable. The attributes hold the full values.

A result can't be changed after it's created. Assigning to an attribute is an error:


``` python
result.mean = 0
```


    ---------------------------------------------------------------------------
    FrozenInstanceError                       Traceback (most recent call last)
    Cell In[3], line 1
    ----> 1 result.mean = 0

    File <string>:19, in __create_fn__.<locals>.__setattr__(self, name, value)
         17 'Could not get source, probably due dynamically evaluated source code.'

    FrozenInstanceError: cannot assign to field 'mean'


# Missing values

Missing values, written as `None` or NaN, are left out of the calculation. Since dropping data silently could hide a problem, [summarize()](../reference/summarize.md#tinytab.summarize) issues a warning saying how many were dropped:


``` python
import math

summarize([3.5, None, 4.0, math.nan])
```


    /var/folders/s8/bj_jsx3d7jqd2btw7bwm6yx80000gp/T/ipykernel_51131/577297194.py:3: UserWarning: Dropped 2 missing value(s).
      summarize([3.5, None, 4.0, math.nan])


    SummaryResult(n=2, mean=3.75, sd=0.3536, min=3.5, max=4)


If there are no values left to summarize, [summarize()](../reference/summarize.md#tinytab.summarize) raises an error:


``` python
summarize([None, None])
```


    /var/folders/s8/bj_jsx3d7jqd2btw7bwm6yx80000gp/T/ipykernel_51131/1716788409.py:1: UserWarning: Dropped 2 missing value(s).
      summarize([None, None])


    ---------------------------------------------------------------------------
    ValueError                                Traceback (most recent call last)
    Cell In[5], line 1
    ----> 1 summarize([None, None])

    File ~/py_projects/example-python-package/tinytab/_stats.py:93, in summarize(values)
         90     warnings.warn(f"Dropped {n_dropped} missing value(s).", UserWarning, stacklevel=2)
         92 if not clean:
    ---> 93     raise ValueError("Cannot summarize `values`: there are no non-missing values.")
         95 n = len(clean)
         96 mean = sum(clean) / n

    ValueError: Cannot summarize `values`: there are no non-missing values.


# A single value

With only one value, there's no spread to measure, so the standard deviation is 0:


``` python
summarize([23])
```


    SummaryResult(n=1, mean=23, sd=0, min=23, max=23)