{"id":37610912,"url":"https://github.com/brsynth/molecule-signature-paper","last_synced_at":"2026-01-16T10:20:45.034Z","repository":{"id":274981088,"uuid":"671458895","full_name":"brsynth/molecule-signature-paper","owner":"brsynth","description":"Code supporting the paper 'Getting Molecules from their Fingerprints: Generative Models vs. Deterministic Enumeration'","archived":false,"fork":false,"pushed_at":"2025-11-24T17:25:34.000Z","size":770,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-14T12:59:57.599Z","etag":null,"topics":["chemistry","chemoinformatics","deterministic-enumeration","fingerprint","generative-model","molecular-generation","signature"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brsynth.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.rst","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-27T11:13:14.000Z","updated_at":"2025-06-18T10:07:00.000Z","dependencies_parsed_at":"2025-09-04T23:26:36.593Z","dependency_job_id":"72006256-ae90-4f43-bb08-7da26e5ede64","html_url":"https://github.com/brsynth/molecule-signature-paper","commit_stats":null,"previous_names":["brsynth/molecule-signature-paper"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/brsynth/molecule-signature-paper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brsynth%2Fmolecule-signature-paper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brsynth%2Fmolecule-signature-paper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brsynth%2Fmolecule-signature-paper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brsynth%2Fmolecule-signature-paper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brsynth","download_url":"https://codeload.github.com/brsynth/molecule-signature-paper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brsynth%2Fmolecule-signature-paper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chemistry","chemoinformatics","deterministic-enumeration","fingerprint","generative-model","molecular-generation","signature"],"created_at":"2026-01-16T10:20:44.407Z","updated_at":"2026-01-16T10:20:45.024Z","avatar_url":"https://github.com/brsynth.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Supporting content for the Molecule Signature paper\n\n[![Github Version](https://img.shields.io/github/v/release/brsynth/molecule-signature-paper?display_name=tag\u0026sort=semver\u0026logo=github)](version)\n[![Github Licence](https://img.shields.io/github/license/brsynth/molecule-signature-paper?logo=github)](LICENSE.md)\n\nThis repository contains code to support the Molecule Signature publication. See citation for details.\n\n## Table of Contents\n- [1. Repository structure](#1-repository-structure)\n  - [1.1. Datasets](#11-datasets)\n  - [1.2. Supporting Notebooks](#12-supporting-notebooks)\n  - [1.3. Source code](#13-source-code)\n- [2. Installation](#2-installation)\n- [3. Usage](#3-usage)\n  - [3.1. Preparing datasets](#31-preparing-datasets)\n  - [3.2 Deterministic enumeration](#32-deterministic-enumeration)\n  - [3.3. Train generative models](#33-train-generative-models)\n  - [3.4. Predict molecules with generative models](#34-predict-molecules-with-generative-models)\n- [4. Reproduce results (notebooks)](#4-reproduce-results-notebooks)\n  - [Deterministic enumeration](#deterministic-enumeration)\n  - [Generative models](#generative-models)\n  - [Analyses](#analyses)\n- [5. Citation](#5-citation)\n\n## 1. Repository structure\n\n```text\n.\n├── data       \u003c placeholder for data files \u003e\n│   └── ..\n├── notebooks  \u003c supporting jupyter notebooks \u003e\n│   └── ..\n└── src        \u003c source code for data preparation and modeling \u003e\n    └── paper\n        ├── dataset\n        └── learning\n\n```\n\n### 1.1. Datasets\n\nThe `data` directory is the place where put required data files to be used by the code. `emolecules` and `metanetx` subdirectories are created at execution time. See [data organization README](data/README.md) for details.\n\n### 1.2. Supporting Notebooks\n\nThe `notebooks` directory contains Jupyter notebooks that support figures and tables from the paper. The `handy.py` file contains utility functions that are used in some of the notebooks.\n\n### 1.3. Source code\n\nThe `src` directory contains the source code for the paper. The code is organized in two main directories: `dataset` for preparing datasets and `learning` for training and using the generative model. See [Usage](#3-usage) for details on how to run the code.\n\n## 2. Installation\n\nThe following steps will set up a `signature-paper` conda environment.\n\n0. **Install Conda:**\n\n    The conda package manager is required. If you do not have it installed, you\n    can download it from [here](https://docs.conda.io/en/latest/miniconda.html).\n    Follow the instructions on the page to install Conda. For example, on\n    Windows, you would download the installer and run it. On macOS and Linux,\n    you might use a command like:\n\n    ```bash\n    bash ~/Downloads/Miniconda3-latest-Linux-x86_64.sh\n    ```\n\n    Follow the prompts on the installer to complete the installation.\n\n1. **Install dependencies:**\n\n    ```bash\n    conda env create -f recipes/environment.yaml\n    conda activate signature-paper\n    pip install --no-deps -e .\n    ```\n\n2. **Download data:**\n\n    Precomputed alphabets, trained generative models and most important datasets are available as a Zenodo archive: \u003chttps://zenodo.org/records/14760992\u003e. Extract the files and place them in the `data` directory.\n\n3. **Optionnaly (for dev): set the signature package from source**\n\n    Installing the signature code from source is optional may be useful for development\n    purposes. This will allow you to make changes to the signature code and see the\n    effects in the paper code without having to reinstall the package.\n\n    ```bash\n    conda activate signature-paper\n    \n    # Remove the packaged version\n    conda remove molecule-signature\n    \n    # Set up the source version\n    git clone git@github.com:brsynth/molecule-signature.git lib/molecule-signature\n    pushd lib/molecule-signature\n    pip install --no-deps -e .\n    popd\n    ```\n\n## 3. Usage\n\n### 3.1. Preparing datasets\n\nThe `src/paper/dataset` module contains code to prepare datasets for training and evaluation. The `prepare` command will create the datasets in the `data` directory.\n\n- **Getting help**\n\n    ```bash\n    python -u src/paper/dataset/prepare.py --help\n    python -u src/paper/dataset/tokens.py --help\n    ```\n\n- **eMolecules dataset**\n\n    Prepare the emolecules dataset. **Cautions:** the emolecules dataset is large and may take a long time to download and process (as well as a substantial disk space and RAM consumption).\n\n    ```bash\n    # Datasets\n    python src/paper/dataset/prepare.py all --db emolecules --workers 10  --show_progress --split_method train_valid_split\n\n    # Tokenizers\n    python src/paper/dataset/tokens.py --db emolecules --token_min_presence 0.0001\n    ```\n\n- **MetaNetX dataset**\n\n    ```bash\n    # Datasets\n    python src/paper/dataset/prepare.py all --db metanetx --workers 10 --show_progress\n\n    # Tokenizers\n    python src/paper/dataset/tokens.py --db metanetx --token_min_presence 0.0001\n    ```\n\n### 3.2 Deterministic enumeration\n\nUsers will find explanations and examples on how to use the deterministic enumeration code in the notebooks folder, in particular:\n\n- [1.enumeration_create_alphabets.ipynb](notebooks/1.enumeration_create_alphabets.ipynb): Create alphabets for deterministic enumeration.\n- [2.enumeration_results.ipynb](notebooks/2.enumeration_results.ipynb): Get deterministic enumeration results.\n- [3.analysis_alphabets.ipynb](notebooks/3.analysis_alphabets.ipynb): Analyze alphabets.\n\n### 3.3. Train generative models\n\n**Cautions**: settings may need to be adjusted depending on the available resources (e.g., GPU memory, disk space, etc.) and the HPC environment.\n\n- **Getting help**\n\n    ```bash\n    python -u src/paper/learning/train.py --help\n    ```\n\n- **Pre-train model (from eMolecules datasets)**\n\n    ```bash\n    python src/paper/learning/train.py \\\n        --db emolecules \\\n        --source ECFP \\\n        --target SMILES \\\n        --dataloader_num_workers 3 \\\n        --enable_mixed_precision True \\\n        --ddp_num_nodes 1 \\\n        --split_method train_valid_split \\\n        --train_fold_index 0 \\\n        --data_max_rows -1 \\\n        --out_dir ${WORK}/hpc \\\n        --out_sub_dir NULL \\\n        --model_dim 512 \\\n        --model_num_encoder_layers 3 \\\n        --model_num_decoder_layers 3 \\\n        --scheduler_method plateau \\\n        --scheduler_lr 0.0001 \\\n        --scheduler_plateau_patience 1 \\\n        --scheduler_plateau_factor 0.1 \\\n        --early_stopping_patience 5 \\\n        --early_stopping_min_delta 0.0001 \\\n        --train_max_epochs 200 \\\n        --train_batch_size 128 \\\n        --train_accumulate_grad_batches 1 \\\n        --train_val_check_interval 1 \\\n        --train_seed 42 \\\n        --finetune false \\\n        --finetune_lr 0.0001 \\\n        --finetune_freeze_encoder false \\\n        --finetune_checkpoint None\n    ```\n\n- **Fine-tune model (from MetaNetX datasets, fold 0)**\n\n    ```bash\n    python src/paper/learning/train.py \\\n        --db metanetx \\\n        --source ECFP \\\n        --target SMILES \\\n        --dataloader_num_workers 3 \\\n        --enable_mixed_precision True \\\n        --ddp_num_nodes 1 \\\n        --split_method kfold \\\n        --train_fold_index 0 \\\n        --data_max_rows -1 \\\n        --out_dir ${WORK}/hpc/llogs \\\n        --out_sub_dir FOLD_0 \\\n        --model_dim 512 \\\n        --model_num_encoder_layers 3 \\\n        --model_num_decoder_layers 3 \\\n        --scheduler_method plateau \\\n        --scheduler_lr 0.0001 \\\n        --scheduler_plateau_patience 2 \\\n        --scheduler_plateau_factor 0.1 \\\n        --early_stopping_patience 6 \\\n        --early_stopping_min_delta 0.0001 \\\n        --train_max_epochs 200 \\\n        --train_batch_size 128 \\\n        --train_accumulate_grad_batches 1 \\\n        --train_val_check_interval 1 \\\n        --train_seed 42 \\\n        --finetune true \\\n        --finetune_lr 0.0001 \\\n        --finetune_freeze_encoder true \\\n        --finetune_checkpoint \u003cpath_to_pretrain_model_checkpoint\u003e\n    ```\n\n### 3.4. Predict molecules with generative models\n\nThe `src/paper/learning/predict.py` script can be used to generate molecules from the trained models. The script requires a trained model checkpoint and a tokenizer, which can be downloaded from the Zenodo archive(see [Installation](#2-installation)).\n\n- **Generate molecules from the fine-tuned model**\n\n    ```bash\n    python src/paper/learning/predict.py \\\n        --model_path \"data/models/finetuned.ckpt\" \\\n        --model_source_tokenizer \"data/tokens/ECFP.model\" \\\n        --model_target_tokenizer \"data/tokens/SMILES.model\" \\\n        --pred_mode \"beam\"\n    ```\n\n- **Getting help**\n\n    ```bash\n    python -u src/paper/learning/predict.py --help\n    ```\n\n## 4. Reproduce results (notebooks)\n\n### Deterministic enumeration\n\n- The alphabets used the deterministic enumeration are created using the [1.enumeration_create_alphabets.ipynb](notebooks/1.enumeration_create_alphabets.ipynb) notebook.\n\n- The deterministic enumerations on the test datasets are performed using the [2.enumeration_results.ipynb](notebooks/2.enumeration_results.ipynb) notebook.\n\n### Generative models\n\n- Accuracies from the generative model (**Tables 1** and **2**) are computed using the [4.generation_recovery.ipynb](notebooks/4.generation_recovery.ipynb) notebook. This notebook also provides examples of how to use the `predict.py` script to generate molecules and evaluate their accuracy.\n\n- Accuracies from the cross comparisons between generative models(present and molforge models) and test datasets are computed using the [5.generative_molforge.ipynb](notebooks/5.generative_molforge.ipynb) notebook.\n\n### Analyses\n\n- The analysis of the alphabets in terms of size and diversity (**Figures 2**, **S1** and **S3**) are computed using the [3.analysis_alphabets.ipynb](notebooks/3.analysis_alphabets.ipynb) notebook.\n\n- The analysis about the atomic signature repetitions of datasets and the Venn diagram of alphabets (**Figure S3**) are computed using the [6.statistics_databases.ipynb](notebooks/6.statistics_databases.ipynb) notebook.\n\n- The analysis and comparison of the enumerated and generated molecules (**Tables 1**, **2** and **Figure S5**) are computed using the [7.enumeration_generation_analysis.ipynb](notebooks/7.enumeration_generation_analysis.ipynb) notebook.\n\n- The correlations between molecular descriptors and computation times (**Table S1**) are computed using the [8.correlation_complexity_computation_time.ipynb](notebooks/8.correlation_complexity_computation_time.ipynb) notebook.\n\n- The analysis of the enumeration results on the DrugBank molecules (**Figures 3**, **S6**, **S7**, **Table S2**) are computed using the [9.enumeration_drugbank_analysis.ipynb](notebooks/9.enumeration_drugbank_analysis.ipynb) notebook.\n\n## 5. Citation\n\nMeyer, P., Duigou, T., Gricourt, G., \u0026 Faulon, J.-L. Reverse Engineering Molecules from Fingerprints through Deterministic Enumeration and Generative Models. In preparation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrsynth%2Fmolecule-signature-paper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrsynth%2Fmolecule-signature-paper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrsynth%2Fmolecule-signature-paper/lists"}