Merge branch 'atrisovic-add-img'

src/pyDataverse/docs/source/user/basic-usage.rst

@@ -72,10 +72,21 @@ can then be used (e. g. :meth:`json() <requests.Response.json>`).
 Create Dataverse Collection
 -----------------------------
 
-The top-level data-type in the Dataverse software is called a Dataverse collection, so we will
-start with that.
+The top-level data-type in the Dataverse software is called a Dataverse collection, so we will start with that. 
+Take a look at the figure below to better understand the relationship between a Dataverse collection, a dataset, and a datafile. 
 
-First, instantiate a :class:`Dataverse <pyDataverse.models.Dataverse>`
+.. figure:: ../_images/collection_dataset.png
+   :align: center
+   :alt: collection dataset datafile
+
+A dataverse collection (also known as a :class:`Dataverse <pyDataverse.models.Dataverse>`) acts as a container for your :class:`Datasets<pyDataverse.models.Dataverse>`.
+It can also store other collections (:class:`Dataverses <pyDataverse.models.Dataverse>`).
+You could create your own Dataverse collections, but it is not a requirement. 
+A Dataset is a container for :class:`Datafiles<pyDataverse.models.Datafile>`, such as data, documentation, code, metadata, etc. 
+You need to create a Dataset to deposit your files. All Datasets are uniquely identified with a DOI at Dataverse. 
+For more detailed explanations, check out `the Dataverse User Guide <https://guides.dataverse.org/en/latest/user/dataset-management.html>`_.
+
+Going back to the example, first, instantiate a :class:`Dataverse <pyDataverse.models.Dataverse>`
 object and import the metadata from the Dataverse Software's own JSON format with
 :meth:`from_json() <pyDataverse.models.Dataverse.from_json>`:
 
@@ -287,6 +298,51 @@ always leads to a major version change:
     Dataset doi:10.5072/FK2/EO7BNB published
 
 
+.. _user_basic-usage_download-data:
+
+Download and save a dataset to disk
+----------------------------------------
+
+You may want to download and explore an existing dataset from Dataverse. The following code snippet will show how to retrieve and save a dataset to your machine.
+
+Note that if the dataset is public, you don't need to have an API_TOKEN. Furthermore, you don't even need to have a Dataverse account to use this functionality. The code would therefore look as follows:
+
+::
+
+    >>> from pyDataverse.api import NativeApi, DataAccessApi
+    >>> from pyDataverse.models import Dataverse
+
+    >>> base_url = 'https://dataverse.harvard.edu/'
+
+    >>> api = NativeApi(base_url)
+    >>> data_api = DataAccessApi(base_url)
+
+However, you need to know the DOI of the dataset that you want to download. In this example, we use ``doi:10.7910/DVN/KBHLOD``, which is hosted on Harvard's Dataverse instance that we specified as ``base_url``. The code looks as follows:
+
+::
+
+    >>> DOI = "doi:10.7910/DVN/KBHLOD"
+    >>> dataset = api.get_dataset(DOI)
+
+As previously mentioned, every dataset comprises of datafiles, therefore, we need to get the list of datafiles by ID and save them on disk. That is done in the following code snippet:
+
+::
+
+    >>> files_list = dataset.json()['data']['latestVersion']['files']
+
+    >>> for file in files_list:
+    >>>     filename = file["dataFile"]["filename"]
+    >>>     file_id = file["dataFile"]["id"]
+    >>>     print("File name {}, id {}".format(filename, file_id))
+
+    >>>     response = data_api.get_datafile(file_id)
+    >>>     with open(filename, "wb") as f:
+    >>>         f.write(response.content)
+    File name cat.jpg, id 2456195
+
+Please note that in this example, the dataset will be saved in the execution directory. You could change that by adding a desired path in the ``open()`` function above.
+
+
 .. _user_basic-usage_get-data-tree:
 
 Retrieve all created data as a Dataverse tree