# Sample data

`nbdemo.data` holds sample datasets for Nominal’s open-source projects, grouped by domain: `aero`, `med` and `rf`.

Each dataset is a [`Dataset`](https://dev.nominal.io/demos/reference/data-api.md#nbdemo.data.Dataset "nbdemo.data.Dataset") with up to three ways to be accessed:

- as a file path, with [`path`](https://dev.nominal.io/demos/reference/data-api.md#nbdemo.data.Dataset.path "nbdemo.data.Dataset.path")
- as its format’s own Python object, with [`native`](https://dev.nominal.io/demos/reference/data-api.md#nbdemo.data.Dataset.native "nbdemo.data.Dataset.native")
- as a pandas [`DataFrame`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html#pandas.DataFrame "(in pandas v3.1)"), with [`df`](https://dev.nominal.io/demos/reference/data-api.md#nbdemo.data.Dataset.df "nbdemo.data.Dataset.df")

## Usage

Import a dataset from its domain: [`aero`](https://dev.nominal.io/demos/reference/data-api.md#module-nbdemo.data.aero "nbdemo.data.aero"), [`med`](https://dev.nominal.io/demos/reference/data-api.md#module-nbdemo.data.med "nbdemo.data.med") or
[`rf`](https://dev.nominal.io/demos/reference/data-api.md#module-nbdemo.data.rf "nbdemo.data.rf"). Importing reads only a small manifest; nothing is downloaded or parsed
until you use the dataset.

### As Path

```ipython3
from nbdemo.data.med import ecg_mitbih_119

ecg_mitbih_119.path  # a Path, to pass to your own loader
```

```myst-ansi
PosixPath('/home/runner/work/nbdemo/nbdemo/src/nbdemo/data/med/ecg_mitbih_119/119.hea')
```

The same dataset as the Python object that its format’s library returns, and as a DataFrame. A dataset
has each only where it makes sense; see [`forms`](https://dev.nominal.io/demos/reference/data-api.md#nbdemo.data.Dataset.forms "nbdemo.data.Dataset.forms").

### As Native

```ipython3
ecg_mitbih_119.native  # a wfdb.Record
```

```myst-ansi
<wfdb.io.record.Record at 0x7f846ee7c590>
```

### As Dataframe

```ipython3
ecg_mitbih_119.df.head()
```

|  | MLII | V1 | beat |
| --- | --- | --- | --- |
| time |  |  |  |
| 0.000000 | -0.995 | -0.47 | NaN |
| 0.002778 | -0.995 | -0.47 | NaN |
| 0.005556 | -0.995 | -0.47 | NaN |
| 0.008333 | -0.995 | -0.47 | NaN |
| 0.011111 | -0.995 | -0.47 | NaN |

To work with the domains as a group, import the package under a short name.
[`catalog()`](https://dev.nominal.io/demos/reference/data-api.md#nbdemo.data.catalog "nbdemo.data.catalog") lists the datasets, and [`get()`](https://dev.nominal.io/demos/reference/data-api.md#nbdemo.data.get "nbdemo.data.get") looks one up by id:

```ipython3
import nbdemo.data as nd

nd.catalog("rf")
```

```myst-ansi
[Dataset('rf/sigmf_synthetic', 8.00 MB, local, forms=('path', 'native'))]
```

[Install](https://dev.nominal.io/demos/reference/data-install.md) the package with the extras for the formats you read.
[Using the paths](https://dev.nominal.io/demos/reference/data-paths.md) covers testing a file loader, and
[Using the loaded data](https://dev.nominal.io/demos/reference/data-loaded.md) covers `native` and `df`, including
[`FormUnavailable`](https://dev.nominal.io/demos/reference/data-api.md#nbdemo.data.FormUnavailable "nbdemo.data.FormUnavailable"), which a dataset raises for a form it does not have.
The [catalog](https://dev.nominal.io/demos/reference/data-catalog.md) lists every dataset, and [Adding a dataset](https://dev.nominal.io/demos/reference/data-adding.md)
explains how to contribute one. The [API](https://dev.nominal.io/demos/reference/data-api.md) is the full reference.
