Downloading data

Downloading data#

Ensaio provides functions for downloading datasets from the Fatiando a Terra Datasets collection to your computer. These functions don’t attempt to do any loading of the data into memory and only return the path of the downloaded file on your computer.

To take care of the actual loading of the data, we’ll import Pandas as well since the data we’ll use is in CSV format.

import pandas as pd

import ensaio

To download a particular dataset, say version 1 of our Southern Africa gravity data, call the corresponding fetch_* functions:

fname = ensaio.fetch_southern_africa_gravity(version=1)
print(fname)
/home/runner/work/_temp/cache/ensaio/v1/southern-africa-gravity.csv.xz

Tip

The version of the data should always be explicitly included so that you code continues to work in the same way even if a newer version of the data is released.

If the data are not yet available on your computer, Ensaio will automatically download it and return the path to the downloaded file. In the file had already been downloaded, Ensaio won’t repeat the download and will only return the path to the existing file.

This means that placing the code above in a Python script or Jupyter notebook will mean that whoever runs it is guaranteed to get the data on their computer. Running the code multiple times or using the same data in multiple places will only trigger a single download, saving bandwidth and storage space.

Note

Ensaio uses Pooch under the hood to make all of this work.

Once we have the path to the data file, we can load it like we would any other data file. In this case, our data is in a CSV file so the natural choice is to use Pandas:

data = pd.read_csv(fname)
data
longitude latitude height_sea_level_m gravity_mgal
0 18.34444 -34.12971 32.2 979656.12
1 18.36028 -34.08833 592.5 979508.21
2 18.37418 -34.19583 18.4 979666.46
3 18.40388 -34.23972 25.0 979671.03
4 18.41112 -34.16444 228.7 979616.11
... ... ... ... ...
14354 21.22500 -17.95833 1053.1 978182.09
14355 21.27500 -17.98333 1033.3 978183.09
14356 21.70833 -17.99166 1041.8 978182.69
14357 21.85000 -17.95833 1033.3 978193.18
14358 21.98333 -17.94166 1022.6 978211.38

14359 rows × 4 columns

See also

You can browse a list of all available datasets in List of functions and classes (API) or Available datasets.

Where are the data?#

The location of the cache folder varies by operating system. Use the ensaio.locate function to get its location on your computer.

print(ensaio.locate())
/home/runner/work/_temp/cache/ensaio

You can also set the location manually by creating a ENSAIO_DATA_DIR environment variable with the desired path. Ensaio will search for this variable and if found will use its value instead of the default cache folder.