===============
Saint Lightning
===============

This repository contains an implementation of SAINT using Pytorch-Lightning_ as a framework
and Hydra_ for the configuration.
Find the paper on arxiv_

.. _arxiv: https://arxiv.org/abs/2106.01342
.. _Pytorch-Lightning: https://www.pytorchlightning.ai/
.. _Hydra: https://hydra.cc/

How to install
--------------

.. code-block:: bash

    pip install lit-saint


How to Use it
-------------

1. Create an yaml file that contains the configuration needed by the application or use default values

2. Create an instance of SaintConfig using Hydra

3. Create the Dataframe that will be used for the model. In order to split correctly the data, you need to add a new column where you assign the label "train" to the rows of the training set, "validation" for the ones of the validation set and "test" for the testing one

.. code-block:: python3

    data_module = SaintDatamodule(df=df, target="TARGET", split_column="SPLIT")

4. Create an instance of SaintDataModule and SAINT

.. code-block:: python3

    model = Saint(categories=data_module.categorical_dims, continuous=data_module.numerical_columns,
                  config=cfg, dim_target=data_module.dim_target)

5. Create the Trainers defined by Pytorch lightning to fit the model

.. code-block:: python3

    pretrainer = Trainer(max_epochs=1)
    trainer = Trainer(max_epochs=5)

6. Create the SaintTrainer that will be used in order to fit the model and make predictions

.. code-block:: python3

    saint_trainer = SaintTrainer(pretrainer=pretrainer, trainer=trainer)
    saint_trainer.fit(model=model, datamodule=data_module, enable_pretraining=True)

7. Then you can define the data for the prediction step

.. code-block:: python3

    prediction = saint_trainer.predict(model=model, datamodule=data_module, df=df_to_predict)
    df_test["prediction"] = np.argmax(prediction, axis=1)

How to Generate Yaml
--------------------
.. code-block:: python3

    from lit_saint import SaintConfig
    from omegaconf import OmegaConf


    conf = OmegaConf.create(SaintConfig)
    with open("<FILE_NAME>", "w+") as fp:
        OmegaConf.save(config=conf, f=fp.name)


In order to make type validation at runtime, you need to add at the beginning of your file the following lines:

.. code-block:: yaml

    defaults:
      - base_config


Credits
-------

We would like to thank the repo with the official implementation of SAINT:
https://github.com/somepago/saint
