Usage
=====

Running **doi2dataset** is done from the command line. Below is an example of how to use the tool.

Basic Example
-------------
To process one or more DOIs, run:

.. code-block:: bash

   python doi2dataset.py 10.1234/doi1 10.5678/doi2

Command Line Options
--------------------
The tool offers several command line options:

- ``-f, --file``: Specify a file containing DOIs (one per line).
- ``-o, --output-dir``: Directory where metadata files will be saved.
- ``-d, --depositor``: Name of the depositor.
- ``-s, --subject``: Default subject for the metadata.
- ``-m, --contact-mail``: Contact email address.
- ``-u, --upload``: Flag to upload metadata to a Dataverse server.

Configuration via config.yaml
-------------------------------
Some options are also set via the **config.yaml** file. This file includes settings such as:

- Dataverse connection details (URL, API token, authentication credentials).
- Mapping of project phases.
- PI (principal investigator) information.
- Default grant configurations.

Make sure that your **config.yaml** is properly configured before running the tool. For example, your **config.yaml** might include:

.. code-block:: yaml

   dataverse:
     url: "https://your.dataverse.server"
     api_token: "your_api_token"
     auth_user: "your_username"
     auth_password: "your_password"
     dataverse: "your_dataverse_name"

   phase:
     Phase1:
       start: 2010
       end: 2015
     Phase2:
       start: 2016
       end: 2020

   pis:
     - given_name: "John"
       family_name: "Doe"
       email: "john.doe@example.com"
       orcid: "0000-0001-2345-6789"
       affiliation: "Example University"
       project:
         - "Project A"
         - "Project B"

   default_grants:
     - funder: "Funder Name"
       id: "GrantID12345"

Usage Example with Configuration
----------------------------------
If you have configured your **config.yaml** and want to process DOIs from a file while uploading the metadata, you could run:

.. code-block:: bash

   python doi2dataset.py -f dois.txt -o output/ -d "John Doe" -s "Medicine, Health and Life Sciences" -m "john.doe@example.com" -u

This command will use the options provided on the command line as well as the settings from **config.yaml**.

For more details on usage and configuration, please refer to the rest of the documentation.