.. _quickstart:

===================
Quickstart
===================

Get started with the twinLab Python Interface. 

---------------
Requirements
---------------

A Python version between 3.8 and 3.12 is required to run twinLab.

To check your Python version, you can either use your shell directly or use a Python script. 

.. tab-set:: 

   .. tab-item:: Shell

      Type the following into your shell: 

      .. code-block:: shell 

         python --version

   .. tab-item:: Python script

      Execute the following in a Python script or notebook: 

      .. code-block:: shell 

         import sys 
         sys.version_info

.. note::
   We recommend managing your Python packages with Python virtual environments. See more `here. <https://docs.python.org/3/tutorial/venv.html>`__

--------------
Installation
--------------

1. **Open a terminal**

2. **Create a directory**

Create a folder/directory where you want to install twinLab. Then, set that folder/directory as your current one.

.. code-block:: shell

    mkdir my_project 
    cd my_project

3. **Install twinLab** 

In your newly created directory, install twinLab from `PyPI <https://pypi.org/project/twinlab/>`__.

.. code-block:: shell

    pip install twinlab

After installation, you'll need to add your user details, including your API key, in order to access twinLab capabilities. 

.. admonition:: Need an API key?
   :class: note

   To access an API key, and for more information on licensing, `get in touch <https://www.digilab.co.uk/contact>`_ and let our solution engineers set you up with a free trial.

-----------------------
Configure your API key
-----------------------

There are two options for configuring your user details: creating a `.env` file, which contains your details, or providing them manually within Python scripts or notebooks.

If ever you forget or misplace your API key, you can find your user details through the `Portal <https://portal.twinlab.ai/>`__. 

.. tab-set:: 

   .. tab-item:: .env file

      Once this `.env` file has been set, this will enable your username and API key to be read from any script run in the subsequent directory tree. Note that your username is usually an email address.

      .. tab-set::

         .. tab-item:: Windows

            .. tab-set::

               .. tab-item:: Powershell

                  .. code-block:: powershell

                     echo "TWINLAB_USER=<your_username>" >> .env
                     echo "TWINLAB_API_KEY=<your_api_key>" >> .env

               .. tab-item:: Command Line

                  .. code-block:: console

                     echo TWINLAB_USER=<your_username> >> .env
                     echo TWINLAB_API_KEY=<your_api_key> >> .env

         .. tab-item:: Linux

            .. code-block:: bash

               echo "TWINLAB_USER=<your_username>" >> .env
               echo "TWINLAB_API_KEY=<your_api_key>" >> .env

         .. tab-item:: MacOS

            .. code-block:: bash

               echo "TWINLAB_USER=<your_username>" >> .env
               echo "TWINLAB_API_KEY=<your_api_key>" >> .env

      
      You can check that the `.env` file has been created successfully using the following:

      .. code-block:: shell

         ls -a .env

      You should see the `.env` file listed.

      If twinLab is unable to locate your `.env` file, you may receive the following error:

      .. code-block:: shell

         {message: 'Unable to find user with API key: `None`'}

      Or

      .. code-block:: shell

         Error: permission denied

      This could be for a few reasons:
      
      - The `.env` file does not exist (see the steps above).

      - The `.env` file does not have the correct information (see the steps above).

      - The `.env` file does not exist in the current working directory or above. 

      - Your Windows user account doesn't have read permissions on the `.env` file and the directory where the Python code is being executed.

      - Your Windows user account doesn't have execute permissions on the directory where the Python code is being executed. 

      - The `.env` file doesn't exist on the same drive as the directory where the Python code is being executed.

   .. tab-item:: Script

      Setting your user details within a script will mean that you don't have to store them on your computer's operating system.

      .. code-block:: python

         import twinlab as tl

         tl.set_user("<your_username>")
         tl.set_api_key("<your_api_key>")

      Executing this code should return something like this:

      .. code-block:: shell

          ====== TwinLab Client Initialisation ======
          Version     : 2.10.0
          User        : user@digilab.co.uk
          Server      : https://twinlab.digilab.co.uk/v3
          Environment : <my_project_directory>/.env
      
      .. warning::
         While we offer the flexibility to utilize the `set_user()` and `set_api_key()` functionality, this should be used with care, so as to not to publicly expose your API key when sharing files.
         Ensure you replace *<your_username>* and *<your_api_key>* with the API key you received in the `Portal <https://portal.twinlab.ai/>`__. Be aware of any blank spaces in the words between the quotation marks, as this can cause errors when using twinLab.

--------------
Run an example
--------------

.. tab-set:: 

   .. tab-item:: Quickstart script

      Use the following example script to get you started: 

      .. code-block:: shell

         # Import pandas as well
         import pandas as pd
         
         # Create a dataset and upload to twinLab cloud
         df = pd.DataFrame({"X": [1, 2, 3, 4], "y": [1, 4, 9, 16]})
         dataset = tl.Dataset("test-data")
         dataset.upload(df)
         
         # Train a machine-learning emulator for the data
         emulator = tl.Emulator("test-emulator")
         emulator.train(dataset=dataset, inputs=["X"], outputs=["y"])
         
         # Evaluate the emulator on some unseen data
         sample_points = pd.DataFrame({"X": [1.5, 2.5, 3.5]})
         df_mean, df_std = emulator.predict(df=sample_points)
         
         # Explore the results
         print(df_mean)
         print(df_std)

   .. tab-item:: Tutorials and demos

      Use longer-form examples to test out twinLab with our :ref:`examples`.