---
title: Dataset
aliases:
  - ../dataset.html
---

The [Dataset](`mikeio.Dataset`) is the MIKE IO data structure 
for data from dfs files. 
The [](`mikeio.read`) methods returns a Dataset as a container of [DataArray](`mikeio.DataArray`) (Dfs items). Each DataArray has the properties, *item*, *time*, *geometry* and *values*. The time and geometry are common to all DataArrays in the Dataset. 

The Dataset has the following primary properties: 

* **items** - a list of [](`mikeio.ItemInfo`) items for each dataarray
* **time** - a [](`pandas.DatetimeIndex`) with the time instances of the data
* **geometry** - a Geometry object with the spatial description of the data


Use Dataset's string representation to get an overview of the Dataset


```{python}
import mikeio
ds = mikeio.read("../data/HD2D.dfsu")
ds
```

## {{< fa filter >}} Selecting items

Selecting a specific item "itemA" (at position 0) from a Dataset ds can be done with:

* `ds[["itemA"]]` - returns a new Dataset with "itemA"
* `ds["itemA"]` - returns "itemA" DataArray
* `ds[[0]]` - returns a new Dataset with "itemA" 
* `ds[0]` - returns "itemA" DataArray
* `ds.itemA` - returns "itemA" DataArray

We recommend the use *named* items for readability. 

```{python}
ds.Surface_elevation
```

Negative index e.g. ds[-1] can also be used to select from the end. 
Several items ("itemA" at 0 and "itemC" at 2) can be selected with the notation:

* `ds[["itemA", "itemC"]]`
* `ds[[0, 2]]`

Note that this behavior is similar to pandas and xarray.


## {{< fa calendar >}} Temporal selection

A time slice of a Dataset can be selected in several different ways. 

```{python}
ds.sel(time="1985-08-06 12:00")
```

```{python}
ds["1985-8-7":]
```

## {{< fa map >}} Spatial selection

The `sel` method finds a single element.

```{python}
ds.sel(x=607002, y=6906734)
```


## {{< fa chart-line >}} Plotting

In most cases, you will *not* plot the Dataset, but rather it's DataArrays. But there are two exceptions: 

* dfs0-Dataset : plot all items as timeseries with ds.plot()
* scatter : compare two items using ds.plot.scatter(x="itemA", y="itemB")

See details in the [Dataset Plotter API](`mikeio.dataset._data_plot._DatasetPlotter`).


## Add a new item

A common workflow is to create a new item based on existing items in a dataset.

This can be in done in several ways. Let's try one of the options.

```{python}
ds = mikeio.read("../data/NorthSea_HD_and_windspeed.dfsu")
ds
```

1. Create a copy of the DataArray

```{python}
ws2 = ds.Wind_speed.copy()
ws2.plot.hist();
```

2. Make the modifications, in this case we will clip the values to the interval 1-18 m/s.

```{python}
import numpy as np
ws2.values = np.clip(ws2.to_numpy(), 1,18)
ws2.plot.hist();
```

3. Assign it to a new name in the dataset

```{python}
ds["Wind_speed_clipped"] = ws2
ds
```

4. Reorder items if necessary (See [selecting items](#selecting-items) above)

```{python}
ds2 = ds[["Wind_speed_clipped", "Surface elevation", "Wind speed"]]
ds2
```

5. Write the new dataset to a new file

```{python}
ds2.to_dfs("modified.dfsu")
```


## Properties
The Dataset (and DataArray) has several properties:

* n_items - Number of items
* n_timesteps - Number of timesteps
* n_elements - Number of elements
* start_time - First time instance (as datetime)
* end_time - Last time instance (as datetime)
* is_equidistant - Is the time series equidistant in time
* timestep - Time step in seconds (if is_equidistant)
* shape - Shape of each item
* deletevalue - File delete value (NaN value)

## Methods

Dataset (and DataArray) has several useful methods for working with data, 
including different ways of *selecting* data:

* [`sel()`](`mikeio.Dataset.sel`) - Select subset along an axis
* [`isel()`](`mikeio.Dataset.isel`) - Select subset along an axis with an integer

*Aggregations* along an axis:

* [`mean()`](`mikeio.Dataset.mean`) - Mean value along an axis
* [`nanmean()`](`mikeio.Dataset.nanmean`) - Mean value along an axis (NaN removed)
* [`max()`](`mikeio.Dataset.max`) - Max value along an axis
* [`nanmax()`](`mikeio.Dataset.nanmax`) - Max value along an axis (NaN removed)
* [`min()`](`mikeio.Dataset.min`) - Min value along an axis
* [`nanmin()`](`mikeio.Dataset.nanmin`) - Min value along an axis (NaN removed)
* [`average()`](`mikeio.Dataset.average`) - Compute the weighted average along the specified axis.
* [`aggregate()`](`mikeio.Dataset.aggregate`) - Aggregate along an axis
* [`quantile()`](`mikeio.Dataset.quantile`) - Quantiles along an axis
* [`nanquantile()`](`mikeio.Dataset.nanquantile`) - Quantiles along an axis (NaN ignored)

### {{< fa calculator >}} Mathematical operations

* ds + value
* ds - value
* ds * value

and + and - between two Datasets (if number of items and shapes conform):

* ds1 + ds2
* ds1 - ds2

Other methods that also return a Dataset:

* [`interp_like`](`mikeio.Dataset.interp_like`) - Spatio (temporal) interpolation (see [Dfsu interpolation notebook](../examples/Dfsu-2D-interpolation.qmd))
* [`interp_time()`](`mikeio.Dataset.interp_time`) - Temporal interpolation (see [Time interpolation notebook](../examples/Time-interpolation.qmd))
* [`dropna()`](`mikeio.Dataset.dropna`) - Remove time steps where all items are NaN
* [`squeeze()`](`mikeio.Dataset.squeeze`) - Remove axes of length 1

### Conversion:

* [`to_dataframe()`](`mikeio.Dataset.to_dataframe`) - Convert Dataset to a [](`pandas.DataFrame`).
* [`to_xarray()`](`mikeio.Dataset.to_xarray`) - Convert Dataset to a [](`xarray.Dataset`) (great for Dfs2, Dfs3).
* [`to_dfs()`](`mikeio.Dataset.to_dfs`) - Write Dataset to a Dfs file



