{"id":19660627,"url":"https://github.com/seonghwanseo/molvoxel","last_synced_at":"2025-04-28T20:32:17.688Z","repository":{"id":211603522,"uuid":"588042886","full_name":"SeonghwanSeo/molvoxel","owner":"SeonghwanSeo","description":"Easy-to-Use Molecular Voxelization Tool","archived":false,"fork":false,"pushed_at":"2025-04-16T07:12:55.000Z","size":484,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-17T18:36:25.845Z","etag":null,"topics":["3d-image","bioinformatics","chemistry","molecule","protein-ligand-complex","protein-structure","python","representation","voxelization","voxelizer"],"latest_commit_sha":null,"homepage":"","language":"Python","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/SeonghwanSeo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-01-12T07:28:34.000Z","updated_at":"2024-11-10T10:53:58.000Z","dependencies_parsed_at":"2023-12-09T17:24:35.155Z","dependency_job_id":"d27c9e6e-df91-4937-88de-a78c0b6f8db4","html_url":"https://github.com/SeonghwanSeo/molvoxel","commit_stats":null,"previous_names":["seonghwanseo/molvoxel"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeonghwanSeo%2Fmolvoxel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeonghwanSeo%2Fmolvoxel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeonghwanSeo%2Fmolvoxel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeonghwanSeo%2Fmolvoxel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SeonghwanSeo","download_url":"https://codeload.github.com/SeonghwanSeo/molvoxel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251383924,"owners_count":21580970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["3d-image","bioinformatics","chemistry","molecule","protein-ligand-complex","protein-structure","python","representation","voxelization","voxelizer"],"created_at":"2024-11-11T16:04:41.559Z","updated_at":"2025-04-28T20:32:17.338Z","avatar_url":"https://github.com/SeonghwanSeo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![pypi](https://img.shields.io/pypi/v/molvoxel.svg?logo=pypi)](https://pypi.org/project/molvoxel/)\n![versions](https://img.shields.io/pypi/pyversions/molvoxel.svg?logo=python)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n\n# MolVoxel: Molecular Voxelization Tool\n\nMolVoxel is an Easy-to-Use **Molecular Voxelization Tool** implemented in Python.\n\nIt requires minimal dependencies, so it's very simple to install and use. If you want to use numba version, just install numba additionally.\n\nIf there's a feature you need, let me know! I'll do my best to add it.\n\n### Dependencies\n\n- Required\n  - Numpy, SciPy\n- Optional\n  - Numba\n  - PyTorch, **CUDA Available**\n  - RDKit, pymol-open-source\n\n### Citation\n\n```\n@article{seo2023pharmaconet,\n  title = {PharmacoNet: Accelerating Large-Scale Virtual Screening by Deep Pharmacophore Modeling},\n  author = {Seo, Seonghwan and Kim, Woo Youn},\n  journal = {arXiv preprint arXiv:2310.00681},\n  year = {2023},\n  url = {https://arxiv.org/abs/2310.00681},\n}\n```\n\n\n\n## Quick Start\n\n### Installation\n\n```shell\npip install molvoxel\npip install molvoxel[numba, torch, rdkit]\t# Optional Dependencies\n```\n\n### Configuring Voxelizer Object\n```python\nimport molvoxel\n# Default (Resolution: 0.5, dimension: 64, density_type: gaussian, sigma: 0.5, library='numpy')\nvoxelizer = molvoxel.create_voxelizer()\n# Set gaussian sigma = 1.0, spatial dimension = (48, 48, 48) with numba library\nvoxelizer = molvoxel.create_voxelizer(dimension=48, density_type='gaussian', sigma=1.0, library='numba')\n# Set binary density with torch library\nvoxelizer = molvoxel.create_voxelizer(density_type='binary', library='torch')\n# CUDA\nvoxelizer = molvoxel.create_voxelizer(library='torch', device='cuda')\n```\n\n### Voxelization\n#### Numpy, Numba\n\n```python\nfrom rdkit import Chem  # rdkit is not required packages\nimport numpy as np\n\ndef get_atom_features(atom):\n    symbol, aromatic = atom.GetSymbol(), atom.GetIsAromatic()\n    return [symbol == 'C', symbol == 'N', symbol == 'O', symbol == 'S', aromatic]\n\nmol = Chem.SDMolSupplier('./test/10gs/10gs_ligand.sdf')[0]\nchannels = {'C': 0, 'N': 1, 'O': 2, 'S': 3}\ncoords = mol.GetConformer().GetPositions()                                      # (V, 3)\ncenter = coords.mean(axis=0)                                                    # (3,)\natom_types = np.array([channels[atom.GetSymbol()] for atom in mol.GetAtoms()])  # (V,)\natom_features = np.array([get_atom_features(atom) for atom in mol.GetAtoms()])  # (V, 5)\natom_radius = 1.0                                                               # scalar\n\nimage = voxelizer.forward_single(coords, center, atom_radius)                   # (1, 64, 64, 64)\nimage = voxelizer.forward_types(coords, center, atom_types, atom_radius)        # (4, 64, 64, 64)\nimage = voxelizer.forward_features(coords, center, atom_features, atom_radius)  # (5, 64, 64, 64)\n```\n\n#### PyTorch - Cuda Available\n\n```python\n# PyTorch is required\nimport torch\n\ndevice = 'cuda' # or 'cpu'\ncoords = torch.FloatTensor(coords).to(device)               # (V, 3)\ncenter = torch.FloatTensor(center).to(device)               # (3,)\natom_types = torch.LongTensor(atom_types).to(device)        # (V,)\natom_features = torch.FloatTensor(atom_features).to(device) # (V, 5)\n\nimage = voxelizer.forward_single(coords, center, atom_radius)                   # (1, 64, 64, 64)\nimage = voxelizer.forward_types(coords, center, atom_types, atom_radius)        # (4, 32, 32, 32)\nimage = voxelizer.forward_features(coords, center, atom_features, atom_radius)  # (5, 32, 32, 32)\n```\n\n\n\n## Voxelization\n\n### Input\n\n- $X \\in \\mathbb{R}^{N\\times3}$ : Coordinates of $N$ atoms\n- $R \\in \\mathbb{R}^N$ : Radii of $N$ atoms\n- $F \\in \\mathbb{R}^{N\\times C}$ : Atomic Features of $N$ atoms - $C$ channels.\n\n### Kernel\n\n$d$: distance, $r$: atom radius\n\n#### Gaussian Kernel\n\n$\\sigma$: gaussian sigma (default=0.5)\n\n$$\nf(d, r, \\sigma) =\n\\begin{cases}\n\t\\exp\n\t\t\\left(\n\t\t\t-0.5(\\frac{d/r}{\\sigma})^2\n\t\t\\right)\t\u0026 \\text{if}~d \\leq r \\\\\n\t0\t\t\t\t\t\u0026 \\text{else}\n\\end{cases}\n$$\n\n#### Binary Kernel\n\n$$\nf(d, r) =\n\\begin{cases}\n\t1\t\u0026 \\text{if}~d \\leq r \\\\\n\t0\t\u0026 \\text{else}\n\\end{cases}\n$$\n\n### Output\n\n- $I \\in \\mathbb{R}^{D \\times H \\times W \\times C}$ : Output Image with $C$ channels.\n- $G \\in \\mathbb{R}^{D\\times H\\times W \\times 3}$ : 3D Grid of $I$.\n\n$$\nI_{d,h,w,:} = \\sum_{n}^{N} F_n \\times f(||X_n - G_{d,h,w}||,R_n,\\sigma)\n$$\n\n\n\n## RDKit Wrapper\n\n``` python\n# RDKit is required\nfrom molvoxel.rdkit import AtomTypeGetter, BondTypeGetter, MolPointCloudMaker, MolWrapper\natom_getter = AtomTypeGetter(['C', 'N', 'O', 'S'])\nbond_getter = BondTypeGetter.default()\t\t# (SINGLE, DOUBLE, TRIPLE, AROMATIC)\n\npointcloudmaker = MolPointCloudMaker(atom_getter, bond_getter, channel_type='types')\nwrapper = MolWrapper(pointcloudmaker, voxelizer, visualizer)\nimage = wrapper.run(rdmol, center, radii=1.0)\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseonghwanseo%2Fmolvoxel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseonghwanseo%2Fmolvoxel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseonghwanseo%2Fmolvoxel/lists"}