.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "tutorial/using.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_tutorial_using.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_tutorial_using.py:


.. _using:

Downloading data
================

Ensaio provides functions for downloading datasets from the `fatiando/data
<https://github.com/fatiando/data>`__ collection to your computer. The
functions are available through different modules for each major release of
the data collection. For example, datasets from the version 1.X series are
available through :mod:`ensaio.v1`.

The recommended way to use Ensaio is to import a particular version module like
so:

.. GENERATED FROM PYTHON SOURCE LINES 22-27

.. code-block:: default

    # Load Pandas as well so we can read in some data
    import pandas as pd

    import ensaio.v1 as ensaio








.. GENERATED FROM PYTHON SOURCE LINES 28-30

To download a particular dataset, say our Southern Africa gravity data,
call the corresponding ``fetch_`` functions:

.. GENERATED FROM PYTHON SOURCE LINES 30-33

.. code-block:: default

    fname = ensaio.fetch_southern_africa_gravity()
    print(fname)





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    /home/runner/work/_temp/cache/ensaio/v1/southern-africa-gravity.csv.xz




.. GENERATED FROM PYTHON SOURCE LINES 34-58

.. tip::

    You can browse a list of all available datasets in :ref:`api` or
    :ref:`gallery_v1`.

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 <https://www.fatiando.org/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 <https://pandas.pydata.org/>`__:

.. GENERATED FROM PYTHON SOURCE LINES 58-61

.. code-block:: default

    data = pd.read_csv(fname)
    data






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>longitude</th>
          <th>latitude</th>
          <th>height_sea_level_m</th>
          <th>gravity_mgal</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>18.34444</td>
          <td>-34.12971</td>
          <td>32.2</td>
          <td>979656.12</td>
        </tr>
        <tr>
          <th>1</th>
          <td>18.36028</td>
          <td>-34.08833</td>
          <td>592.5</td>
          <td>979508.21</td>
        </tr>
        <tr>
          <th>2</th>
          <td>18.37418</td>
          <td>-34.19583</td>
          <td>18.4</td>
          <td>979666.46</td>
        </tr>
        <tr>
          <th>3</th>
          <td>18.40388</td>
          <td>-34.23972</td>
          <td>25.0</td>
          <td>979671.03</td>
        </tr>
        <tr>
          <th>4</th>
          <td>18.41112</td>
          <td>-34.16444</td>
          <td>228.7</td>
          <td>979616.11</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>14354</th>
          <td>21.22500</td>
          <td>-17.95833</td>
          <td>1053.1</td>
          <td>978182.09</td>
        </tr>
        <tr>
          <th>14355</th>
          <td>21.27500</td>
          <td>-17.98333</td>
          <td>1033.3</td>
          <td>978183.09</td>
        </tr>
        <tr>
          <th>14356</th>
          <td>21.70833</td>
          <td>-17.99166</td>
          <td>1041.8</td>
          <td>978182.69</td>
        </tr>
        <tr>
          <th>14357</th>
          <td>21.85000</td>
          <td>-17.95833</td>
          <td>1033.3</td>
          <td>978193.18</td>
        </tr>
        <tr>
          <th>14358</th>
          <td>21.98333</td>
          <td>-17.94166</td>
          <td>1022.6</td>
          <td>978211.38</td>
        </tr>
      </tbody>
    </table>
    <p>14359 rows × 4 columns</p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 62-72

.. admonition:: Using Ensaio in your project documentation?

    Make sure you take a look at :ref:`developers` for useful tips and
    tricks.

Where are the data?
-------------------

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

.. GENERATED FROM PYTHON SOURCE LINES 72-74

.. code-block:: default

    print(ensaio.locate())





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    /home/runner/work/_temp/cache/ensaio/v1




.. GENERATED FROM PYTHON SOURCE LINES 75-81

You can also set the location manually by creating a ``ENSAIO_V1_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.

Similar variables and functions are available for each data collection
version.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  0.025 seconds)


.. _sphx_glr_download_tutorial_using.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: sphx-glr-footer-example



  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: using.py <using.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: using.ipynb <using.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_