.. _getting_started:

===============
Getting Started
===============

Installation
~~~~~~~~~~~~

.. grid:: 1 1 2 2
   :gutter: 4

   .. grid-item-card:: Pip install
      :class-card: install-card
      :columns: 12 12 12 12
      :padding: 3

      twinLab can be installed via pip from `PyPI <https://pypi.org/project/twinlab/>`__.

      ++++

      .. code-block:: bash

         pip install twinlab

.. note::
   See our :ref:`installation guide <installation>` for more detailed installation instructions.

Import 
~~~~~~

To start using twinLab, enter the following line of Python.

.. code-block:: shell

    import twinlab as tl

.. tip::

   If you're using `Google Colab <https://colab.research.google.com/>`__, you don't have to install twinLab on your machine. You can just install and import at the top of the .ipynb file:

   .. code-block:: shell

      !pip install twinlab
      import twinlab as tl

Configure API Key
~~~~~~~~~~~~~~~~~

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

   If you still need an API key `get in touch <https://www.digilab.co.uk/contact>`_ and let our solution engineers set you up with a free trial.

There are two options for configuring your API key. One involves setting a .env file on your computer which contains your API key:

.. tab-set:: 

   .. tab-item:: .env file

      Once this .env file has been set, this will enable your API key to be read from any script run in the subsequent directory tree.

      .. tab-set::

         .. tab-item:: Windows

            .. tab-set::

               .. tab-item:: Powershell

                  .. code-block:: powershell

                     echo "TWINLAB_API_KEY=<your_api_key>" > .env

               .. tab-item:: Command Line

                  .. code-block:: console

                     echo TWINLAB_API_KEY=<your_api_key> > .env

         .. tab-item:: Linux

            .. code-block:: bash

               echo "TWINLAB_API_KEY=<your_api_key>" > .env

         .. tab-item:: MacOS

            .. code-block:: bash

               echo "TWINLAB_API_KEY=<your_api_key>" > .env

   .. tab-item:: set_api_key()

      Setting this function will enable you not to have to store your API key on your computer's operating system.

      .. code-block:: python

         import twinlab as tl

         API_KEY = '<your_api_key>'

         tl.set_api_key(API_KEY)

      .. warning::
         While we offer the flexibility to utilize the `set_api_key()` functionality, this should be used with care not to publicly expose your API key when sharing files.


It should return something like this:

.. code-block:: shell

          ====== TwinLab Client Initialisation ======
          Version     : 2.0.0
          Server      : https://twinlab.digilab.co.uk
          Environment : <my_project_directory>/.env

Run an example
~~~~~~~~~~~~~~

You're all set! Here's an 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)


Having Problems?
~~~~~~~~~~~~~~~~

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

Anything else?
~~~~~~~~~~~~~~

If you have any questions or concerns you can email us at twinlab@digilab.co.uk or find out more on our `website <https://www.digilab.co.uk/twinlab>`__.