Live Notebook

You can run this notebook in a live session Binder or view it on Github.

DataFrames: Reading in messy data

In the 01-data-access example we show how Dask Dataframes can read and store data in many of the same formats as Pandas dataframes. One key difference, when using Dask Dataframes is that instead of opening a single file with a function like pandas.read_csv, we typically open many files at once with dask.dataframe.read_csv. This enables us to treat a collection of files as a single dataset. Most of the time this works really well. But real data is messy and in this notebook we will explore a more advanced technique to bring messy datasets into a dask dataframe.

Start Dask Client for Dashboard

Starting the Dask Client is optional. It will provide a dashboard which is useful to gain insight on the computation.

The link to the dashboard will become visible when you create the client below. We recommend having it open on one side of your screen while using your notebook on the other side. This can take some effort to arrange your windows, but seeing them both at the same is very useful when learning.

from dask.distributed import Client
client = Client(n_workers=1, threads_per_worker=4, processes=True, memory_limit='2GB')



Connection method: Cluster object Cluster type: distributed.LocalCluster

Cluster Info

Create artificial dataset

First we create an artificial dataset and write it to many CSV files.

You don’t need to understand this section, we’re just creating a dataset for the rest of the notebook.

import dask
df = dask.datasets.timeseries()
Dask DataFrame Structure:
id name x y
2000-01-01 int64 object float64 float64
2000-01-02 ... ... ... ...
... ... ... ... ...
2000-01-30 ... ... ... ...
2000-01-31 ... ... ... ...
Dask Name: make-timeseries, 30 tasks
import os
import datetime

if not os.path.exists('data'):

def name(i):
    """ Provide date for filename given index

    >>> name(0)
    >>> name(10)
    return str(, 1, 1) + i * datetime.timedelta(days=1))

df.to_csv('data/*.csv', name_function=name, index=False);

Read CSV files

We now have many CSV files in our data directory, one for each day in the month of January 2000. Each CSV file holds timeseries data for that day. We can read all of them as one logical dataframe using the dd.read_csv function with a glob string.

!ls data/*.csv | head
import dask.dataframe as dd

df = dd.read_csv('data/2000-*-*.csv')
Dask DataFrame Structure:
id name x y
int64 object float64 float64
... ... ... ...
... ... ... ... ...
... ... ... ...
... ... ... ...
Dask Name: read-csv, 30 tasks
id name x y
0 1035 Norbert -0.757208 0.410627
1 1088 Hannah 0.655573 -0.618467
2 979 Dan 0.112189 0.363218
3 983 Edith 0.547462 -0.595247
4 1039 Wendy 0.710590 0.695703

Let’s look at some statistics on the data

id x y
count 2.592000e+06 2.592000e+06 2.592000e+06
mean 9.999959e+02 -2.440908e-04 2.330697e-06
std 3.162768e+01 5.772636e-01 5.773129e-01
min 8.550000e+02 -9.999995e-01 -9.999996e-01
25% 9.790000e+02 -4.962286e-01 -4.949900e-01
50% 1.000000e+03 5.109524e-03 6.483245e-03
75% 1.021000e+03 5.067333e-01 5.048855e-01
max 1.160000e+03 9.999983e-01 9.999985e-01

Make some messy data

Now this works great, and in most cases dd.read_csv or dd.read_parquet etc are the preferred way to read in large collections of data files into a dask dataframe, but real world data is often very messy and some files may be broken or badly formatted. To simulate this we are going to create some fake messy data by tweaking our example csv files. For the file data/2000-01-05.csv we will replace with no data and for the file data/2000-01-07.csv we will remove the y column

# corrupt the data in data/2000-01-05.csv
with open('data/2000-01-05.csv', 'w') as f:
# remove y column from data/2000-01-07.csv
import pandas as pd
df = pd.read_csv('data/2000-01-07.csv')
del df['y']
df.to_csv('data/2000-01-07.csv', index=False)
!head data/2000-01-05.csv
!head data/2000-01-07.csv

Reading the messy data

Let’s try reading in the collection of files again

df = dd.read_csv('data/2000-*-*.csv')
id name x y
0 1035 Norbert -0.757208 0.410627
1 1088 Hannah 0.655573 -0.618467
2 979 Dan 0.112189 0.363218
3 983 Edith 0.547462 -0.595247
4 1039 Wendy 0.710590 0.695703

Ok this looks like it worked, let us calculate the dataset statistics again

ValueError                                Traceback (most recent call last)
Input In [14], in <cell line: 1>()
----> 1 df.describe().compute()

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/dask/, in DaskMethodsMixin.compute(self, **kwargs)
    268 def compute(self, **kwargs):
    269     """Compute this dask collection
    271     This turns a lazy Dask collection into its in-memory equivalent.
    290     dask.base.compute
    291     """
--> 292     (result,) = compute(self, traverse=False, **kwargs)
    293     return result

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/dask/, in compute(traverse, optimize_graph, scheduler, get, *args, **kwargs)
    572     keys.append(x.__dask_keys__())
    573     postcomputes.append(x.__dask_postcompute__())
--> 575 results = schedule(dsk, keys, **kwargs)
    576 return repack([f(r, *a) for r, (f, a) in zip(results, postcomputes)])

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/distributed/, in Client.get(self, dsk, keys, workers, allow_other_workers, resources, sync, asynchronous, direct, retries, priority, fifo_timeout, actors, **kwargs)
   3016         should_rejoin = False
   3017 try:
-> 3018     results = self.gather(packed, asynchronous=asynchronous, direct=direct)
   3019 finally:
   3020     for f in futures.values():

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/distributed/, in Client.gather(self, futures, errors, direct, asynchronous)
   2169 else:
   2170     local_worker = None
-> 2171 return self.sync(
   2172     self._gather,
   2173     futures,
   2174     errors=errors,
   2175     direct=direct,
   2176     local_worker=local_worker,
   2177     asynchronous=asynchronous,
   2178 )

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/distributed/, in SyncMethodMixin.sync(self, func, asynchronous, callback_timeout, *args, **kwargs)
    307     return future
    308 else:
--> 309     return sync(
    310         self.loop, func, *args, callback_timeout=callback_timeout, **kwargs
    311     )

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/distributed/, in sync(loop, func, callback_timeout, *args, **kwargs)
    374 if error:
    375     typ, exc, tb = error
--> 376     raise exc.with_traceback(tb)
    377 else:
    378     return result

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/distributed/, in sync.<locals>.f()
    347         future = asyncio.wait_for(future, callback_timeout)
    348     future = asyncio.ensure_future(future)
--> 349     result = yield future
    350 except Exception:
    351     error = sys.exc_info()

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/tornado/, in
    759 exc_info = None
    761 try:
--> 762     value = future.result()
    763 except Exception:
    764     exc_info = sys.exc_info()

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/distributed/, in Client._gather(self, futures, errors, direct, local_worker)
   2032         exc = CancelledError(key)
   2033     else:
-> 2034         raise exception.with_traceback(traceback)
   2035     raise exc
   2036 if errors == "skip":

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/dask/, in __call__()
    988 if not len(args) == len(self.inkeys):
    989     raise ValueError("Expected %d args, got %d" % (len(self.inkeys), len(args)))
--> 990 return core.get(self.dsk, self.outkey, dict(zip(self.inkeys, args)))

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/dask/, in get()
    147 for key in toposort(dsk):
    148     task = dsk[key]
--> 149     result = _execute_task(task, cache)
    150     cache[key] = result
    151 result = _execute_task(out, cache)

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/dask/, in _execute_task()
    115     func, args = arg[0], arg[1:]
    116     # Note: Don't assign the subtask results to a variable. numpy detects
    117     # temporaries by their reference count and can execute certain
    118     # operations in-place.
--> 119     return func(*(_execute_task(a, cache) for a in args))
    120 elif not ishashable(arg):
    121     return arg

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/dask/, in apply()
     37 def apply(func, args, kwargs=None):
     38     if kwargs:
---> 39         return func(*args, **kwargs)
     40     else:
     41         return func(*args)

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/dask/dataframe/, in apply_and_enforce()
   6353     return meta
   6354 if is_dataframe_like(df):
-> 6355     check_matching_columns(meta, df)
   6356     c = meta.columns
   6357 else:

File /usr/share/miniconda3/envs/dask-examples/lib/python3.9/site-packages/dask/dataframe/, in check_matching_columns()
    413 else:
    414     extra_info = "Order of columns does not match"
--> 415 raise ValueError(
    416     "The columns in the computed data do not match"
    417     " the columns in the provided metadata\n"
    418     f"{extra_info}"
    419 )

ValueError: The columns in the computed data do not match the columns in the provided metadata
  Extra:   []
  Missing: ['y']

So what happened?

When creating a dask dataframe from a collection of files, dd.read_csv samples the first few files in the dataset to determine the datatypes and columns available. Since it has not opened all the files it does not now if some of them are corrupt. Hence, df.head() works since it is only looking at the first file. df.describe.compute() fails because of the corrupt data in data/2000-01-05.csv

Building a delayed reader

To get around this problem we are going to use a more advanced technique to build our dask dataframe. This method can also be used any time some custom logic is required when reading each file. Essentially, we are going to build a function that uses pandas and some error checking and returns a pandas dataframe. If we find a bad data file we will either find a way to fix/clean the data or we will return and empty pandas dataframe with the same structure as the good data.

import numpy as np
import io

def read_data(filename):

    # for this to work we need to explicitly set the datatypes of our pandas dataframe
    dtypes = {'id': int, 'name': str, 'x': float, 'y': float}
        # try reading in the data with pandas
        df = pd.read_csv(filename, dtype=dtypes)
        # if this fails create an empty pandas dataframe with the same dtypes as the good data
        df = pd.read_csv(io.StringIO(''), names=dtypes.keys(), dtype=dtypes)

    # for the case with the missing column, add a column of data with NaN's
    if 'y' not in df.columns:
        df['y'] = np.NaN

    return df

Let’s test this function on a good file and the two bad files

# test function on a normal file
id name x y
0 1035 Norbert -0.757208 0.410627
1 1088 Hannah 0.655573 -0.618467
2 979 Dan 0.112189 0.363218
3 983 Edith 0.547462 -0.595247
4 1039 Wendy 0.710590 0.695703
# test function on the empty file
id name x y
# test function on the file missing the y column
id name x y
0 1024 Sarah 0.186412 NaN
1 1086 Michael -0.157312 NaN
2 1031 Kevin 0.776239 NaN
3 1058 Charlie -0.164126 NaN
4 929 Jerry 0.689860 NaN

Assembling the dask dataframe

First we take our read_data function and convert it to a dask delayed function

from dask import delayed
read_data = delayed(read_data)

Let us look at what the function does now

df = read_data('data/2000-01-01.csv')

It creates a delayed object, to actually run read the file we need to run .compute()

id name x y
0 1035 Norbert -0.757208 0.410627
1 1088 Hannah 0.655573 -0.618467
2 979 Dan 0.112189 0.363218
3 983 Edith 0.547462 -0.595247
4 1039 Wendy 0.710590 0.695703
... ... ... ... ...
86395 1021 Kevin 0.125742 -0.711153
86396 965 Zelda -0.624159 0.855033
86397 1042 Frank 0.738092 0.464486
86398 1067 Oliver -0.325376 0.768031
86399 1003 Charlie -0.755295 -0.279816

86400 rows × 4 columns

Now let’s build a list of all the available csv files

# loop over all the files
from glob import glob
files = glob('data/2000-*-*.csv')

Now we run the delayed read_data function on each file in the list

df = [read_data(file) for file in files]

Then we use dask.dataframe.from_delayed. This function creates a Dask DataFrame from a list of delayed objects as long as each delayed object returns a pandas dataframe. The structure of each individual dataframe returned must also be the same.

df = dd.from_delayed(df, meta={'id': int, 'name': str, 'x': float, 'y': float})
Dask DataFrame Structure:
id name x y
int64 object float64 float64
... ... ... ...
... ... ... ... ...
... ... ... ...
... ... ... ...
Dask Name: from-delayed, 60 tasks

Note: we provided the dtypes in the meta keyword to explicitly tell Dask Dataframe what kind of dataframe to expect. If we did not do this Dask would infer this from the first delayed object which could be slow if it was a large csv file

Now let’s see if this works

id name x y
0 968 Wendy 0.427086 -0.267555
1 1011 Zelda -0.944234 -0.925922
2 1009 Ray -0.499415 0.092161
3 998 Dan 0.243237 0.754739
4 982 Xavier 0.300957 0.548789
id x y
count 2.505600e+06 2.505600e+06 2.419200e+06
mean 1.000001e+03 -2.724378e-04 -3.678182e-06
std 3.162445e+01 5.772779e-01 5.772706e-01
min 8.550000e+02 -9.999995e-01 -9.999996e-01
25% 9.790000e+02 -4.962286e-01 -4.949900e-01
50% 1.000000e+03 5.109524e-03 6.483245e-03
75% 1.021000e+03 5.067333e-01 5.048855e-01
max 1.160000e+03 9.999983e-01 9.999985e-01


To recap, in this example, we looked at an approach to create a Dask Dataframe from a collection of many data files. Typically you would use built-in functions like dd.read_csv or dd.read_parquet to do this. Sometimes, this is not possible because of messy/corrupted files in your dataset or some custom processing that might need to be done.

In these cases, you can build a Dask DataFrame with the following steps.

  1. Create a regular python function that reads the data, performs any transformations, error checking etc and always returns a Pandas dataframe with the same structure

  2. Convert this read function to a delayed object using the dask.delayed function

  3. Call each file in your dataset with the delayed data reader and assemble the output as a list of delayed objects

  4. Used dd.from_delayed to covert the list of delayed objects to a Dask Dataframe

This same technique can be used in other situations as well. Another example might be data files that require using a specialized reader, or several transformations before they can be converted to a pandas dataframe.