HullQSAR

Interaction and Occupancy Hybrid 4D-QSAR descriptors

An experimental research software that leverages convex hull–based hybrid methods to generate 4D-QSAR descriptors. Currently in development at the Universidade Federal de Minas Gerais (Federal University of Minas Gerais, Brazil - UFMG), it integrates interaction and occupancy descriptors to explore innovative approaches in computer-aided drug design. Use with the understanding that it’s a research prototype subject to ongoing refinement.

Introduction

In a study of QSAR, the main goal is to find quantitative relations between chemical structure, i.e., physicochemical, structural and conformational properties, and biological response through a mathematical model. These relationships help to understand and explain the mechanism of action of a drug without a molecular level and allow the planning and development of new compounds that exhibit desirable biological properties.

Calculated descriptors

HullQSAR envolves the molecule or its Conformational Ensemble Profile (CEP) in a convex hull, and then calculates the interaction and occupancy descriptors.

The interaction descriptors calculated are Coulomb and Lennard-Jones interaction energy between a charged probe atom (e.g. NH3+) and the atoms on the CEP. The energy of the atoms should be calculated by external software such as GROMACS.

The occupancy descriptors [Hopfinger, 1997] are calculated by slicing the convex hull into a configurable amount of layers and counting the presence or absence of each atom type in each cell.

Usage

Outwards

$ uv run hullqsar outwards --help

Usage: hullqsar outwards [OPTIONS]

  Generate traditional (outwards) HullQSAR descriptors.

Options:
  -f, --directory, --from DIRECTORY
                                  Directory containing GROMACS files
                                  (`*.{gro,itp,top}`).
  -p, --probe TEXT                Probe atom to be used.
  -d, --initial-distance FLOAT RANGE
                                  Initial distance from molecule hull (in Å).
                                  [x>0.0]
  -a, --angle INTEGER RANGE       Angular step (in degrees).  [1<=x<=359]
  -r, --radius FLOAT RANGE        Radius step (in Å).  [x>0.0]
  -l, --layers INTEGER RANGE      Number of layers.  [x>=1]
  -o, --output PATH               Output matrix file basename without
                                  extension.
  --save-plot PATH                Save the visualization as HTML to the
                                  provided path.
  -P, --plot                      Plot the generated hull.
  --help                          Show this message and exit.

Inwards

$ uv run hullqsar inwards --help

Usage: hullqsar inwards [OPTIONS]

  Generate experimental (inwards) HullQSAR descriptors.

Options:
  -f, --directory, --from DIRECTORY
                                  Directory containing GROMACS files
                                  (`*.{gro,itp,top}`).
  -p, --probe TEXT                Probe atom to be used. Should be one of:
                                  ArCH | ArNH | CH3 | CO | COO | Cl | H3O2 |
                                  NH2 | NH2_ARG | NH3 | Na | OH | SH | Zn2
  -m, --min-distance FLOAT RANGE  Minimal distance from centroid (in Å).
                                  [x>0.0]
  -a, --angle INTEGER RANGE       Angular step (in degrees).  [1<=x<=359]
  -r, --radius FLOAT RANGE        Radius step (in Å).  [x>0.0]
  -o, --output PATH               Output matrix file basename without
                                  extension.
  --save-plot PATH                Save the visualization as HTML to the
                                  provided path.
  -P, --plot                      Plot the generated hull.
  --help                          Show this message and exit.

Examples

$ uv run hullqsar inwards -P -f examples/data/small-cancer            # plot

$ uv run hullqsar inwards -o outputs/sc -f examples/data/small-cancer # save

$ uv run hullqsar inwards --save-plot outputs/sc.html -f examples/data/small-cancer # save plot

Development

You'll need uv installed. Then, clone the repository and install the dependencies:

$ git clone https://github.com/hellmrf/HullQSAR
$ cd HullQSAR
$ uv sync

Then, you can run the CLI interface with:

$ uv run hullqsar --help

Or run any file directly:

$ uv run tests/plot_hull.py

uv run will take care of resolving the dependencies and running the script in the appropriate environment. No need to activate a virtual environment or install dependencies manually.

Examples

Check examples/ (and tests/) folder for examples.

Project Structure

The project is organized as follows:

lqtagridhull/
├── defaultsFiles/         # Default configuration files
│   ├── AtomProva.atp     # Atom probe definitions
│   └── ffcargasnb.itp    # Force field parameters
│
├── descriptors/            # Core molecular descriptor calculations
│   ├── base.py            # Abstract base classes for descriptors
│   ├── convex_hull.py     # Hull-based molecular interaction calculations
│   └── grid.py           # Grid-based molecular interaction calculations
│
├── utils/                 # Utility functions and helpers
│   ├── coordinates.py     # Geometric calculations and coordinate transformations
│   ├── files.py          # File handling utilities
│   └── molecular_io.py    # Molecular structure file I/O operations
│
├── generate_points.py     # Functions to generate sampling points
├── lqtagrid.py           # Main CLI interface
└── probe.py              # Probe molecule definitions

Key Components

• descriptors/: Contains the core calculation engines

  • HullMolecularDescriptors: Computes molecular interactions using convex hull approach
  • GridMolecularDescriptors: Computes molecular interactions using traditional grid approach

• utils/: Helper functions and I/O operations

  • Coordinate transformations (spherical ↔ cartesian)
  • Molecular file parsing (.gro, .itp formats)
  • Hull intersection calculations

• defaultsFiles/: Configuration files defining:

  • Atom types and their properties
  • Force field parameters for interactions

• generate_points.py: Implements point generation algorithms:

  • Hull-based sampling point generation
  • Inward/outward sampling strategies

• lqtagrid.py: Command-line interface implementation

  • Argument parsing
  • Job execution workflow

• probe.py: Defines probe molecules used for interaction calculations