README changed

README.md

@@ -1,12 +1,129 @@
 ---
-title: Tox21 Grover Classifier
-emoji: 👀
-colorFrom: gray
-colorTo: gray
+title: Tox21 GROVER Classifier
+emoji: 🤖
+colorFrom: green
+colorTo: blue
 sdk: docker
 pinned: false
 license: cc-by-nc-4.0
-short_description: Grover Classifier for Tox21
+short_description: GROVER Classifier for Tox21
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Tox21 Graph Isomorphism Network (GIN) Classifier
+
+This repository hosts a Hugging Face Space that provides an examplary API for submitting models to the [Tox21 Leaderboard](https://huggingface.co/spaces/ml-jku/tox21_leaderboard).
+
+Here the base version of [GROVER](https://arxiv.org/pdf/2007.02835) is finetuned on the Tox21 dataset, using the [code](https://github.com/tencent-ailab/grover) provided and the finetuning hyperparameters specified in the paper. The final model is provided for 
+inference. Model input is a SMILES string of the small molecule, and the output are 12 numeric values for 
+each of the toxic effects of the Tox21 dataset. 
+
+
+**Important:** For leaderboard submission, your Space needs to include training code. The file `train.py` should train the model using the config specified inside the `config/` folder and save the final model parameters into a file inside the `checkpoints/` folder. The model should be trained using the [Tox21_dataset](https://huggingface.co/datasets/ml-jku/tox21) provided on Hugging Face. The datasets can be loaded like this:
+```python
+from datasets import load_dataset
+ds = load_dataset("ml-jku/tox21", token=token)
+train_df = ds["train"].to_pandas()
+val_df = ds["validation"].to_pandas()
+```
+ Additionally, the Space needs to implement inference in the `predict()` function inside `predict.py`. The `predict()` function must keep the provided skeleton: it should take a list of SMILES strings as input and return a nested prediction dictionary as output, with SMILES as keys and dictionaries containing targetname-prediction pairs as values. Therefore, any preprocessing of SMILES strings must be executed on-the-fly during inference.
+
+# Repository Structure
+- `predict.py` - Defines the `predict()` function required by the leaderboard (entry point for inference).
+- `app.py` - FastAPI application wrapper (can be used as-is).
+- `main.py` - provided grover code.
+- `evaluate.py` - predict outputs of a given model on a dataset and compute AUC.
+- `generate_features.py` - generate features used as model input, given a csv containing smiles.
+- `hp_search.py` - finetune and evaluate 300 configs that are randomly drawn from a parameter grid specified in the paper.
+- `prepare_data.py` - clean smiles in a given csv and save a mask to consider uncleanable smiles during evaluation.
+- `train.py` - finetunes and saves a model using the config in the `config/` folder.
+
+- `config/` - the config file used by `train.py`. 
+- `checkpoint/` - the saved model that is used in `predict.py` is here.
+- `grover/` - [GROVER](https://github.com/tencent-ailab/grover) repository with slight changes in file structure and import paths.
+- `predictions/` - [GROVER](https://github.com/tencent-ailab/grover) saves prediction results in a csv. These are saved here.
+- `pretrained/` - pretrained GROVER models provided.
+- `tox21/` - all masks, generated features and clean data csv files are saved here.
+
+- `src/` - Core model & preprocessing logic:
+    - `preprocess.py` - SMILES preprocessing pipeline and dataset creation
+    - `commands.py` - GROVER commands
+    - `eval.py` - compute evaluation metric
+    - `hp_search.py` - generate configs for hyperparameter search
+
+# Quickstart with Spaces
+
+You can easily adapt this project in your own Hugging Face account:
+
+- Open this Space on Hugging Face.
+
+- Click "Duplicate this Space" (top-right corner).
+
+- Create a `.env` according to `.example.env`.
+
+- Modify `src/` for your preprocessing pipeline and model class
+
+- Modify `predict()` inside `predict.py` to perform model inference while keeping the function skeleton unchanged to remain compatible with the leaderboard.
+
+- Modify `train.py` according to your model and preprocessing pipeline.
+
+- Modify the file inside `config/` to contain all hyperparameters that are set in `train.py`.
+That’s it, your model will be available as an API endpoint for the Tox21 Leaderboard.
+
+# Installation
+To run the GROVER classifier, clone the repository and install dependencies:
+
+```bash
+git clone https://huggingface.co/spaces/ml-jku/tox21_grover_classifier
+cd tox21_grover_classifier
+conda env create -f environment.yaml
+```
+
+# Training
+
+
+To train the GROVER model from scratch, download the [Tox21](https://huggingface.co/datasets/ml-jku/tox21/tree/main) csv files and put them into the tox21 folder.
+
+Then run:
+
+```bash
+python prepare_data.py
+python generate_features.py
+python train.py
+```
+
+These commands will:
+1. Load and preprocess the Tox21 training dataset
+2. Generate and save features used as GROVER inputs
+2. Finetune the GROVER base model
+3. Store the resulting model in the `finetune/` directory.
+
+# Inference
+
+For inference, you only need `predict.py`.
+
+Example usage inside Python:
+
+```python
+from predict import predict
+
+smiles_list = ["CCO", "c1ccccc1", "CC(=O)O"]
+results = predict(smiles_list)
+
+print(results)
+```
+
+The output will be a nested dictionary in the format:
+
+```python
+{
+    "CCO": {"target1": 0, "target2": 1, ..., "target12": 0},
+    "c1ccccc1": {"target1": 1, "target2": 0, ..., "target12": 1},
+    "CC(=O)O": {"target1": 0, "target2": 0, ..., "target12": 0}
+}
+```
+
+# Notes
+
+- Adapting `predict.py`, `train.py`, `config/`, and `checkpoints/` is required for leaderboard submission.
+
+- Preprocessing (here inside `src/preprocess.py`) must be done inside `predict.py` not just `train.py`.