Guidance on preparing data for training from structures

[kirillshmilovich-insitro]

Is there any info/tutorials/examples on how I can generate data files from my own structures/docked poses as input compatible for training gnina models. I know libmolgrid is used for handling the data to enable things random rotations for data augmentation, but I can't seem to find anything on how I can go about featurizing my own structures into the file scheme read by libmolgrid, (i.e., using the ExampleProvider). (edited)

[RMeli]

Unfortunately this is still very much WIP and there are no proper tutorials or instructions besides what you can find at gnina-torch.rtfd.io.

However, you can find some examples on how to use gninatorch.training and gninatorch.inference under the examples folder.

As you say, gninatorch uses libmolgrid for grid-based featurisation of the molecular complexes, and you can find some more information in the libmolgrid documentation and in the libmolgrid tutorials. Essentially, what the ExampleProvider.pupulate expects is a file containing the labels, a path to the protein file, and a path to a ligand file:

0 protein1.pdb ligand1.sdf
1 protein1.pdb ligand2.sdf
0 protein1.pdb ligand3.sdf
...

This file is also the required argument of gninatorch.training and gninatorch.inference.

For molecular files, you can use whatever is supported by Open Babel, not just .pdb and .sdf files. libmolgrid takes care of I/O and you can then use libmolgrid.gridmaker to perform the featurisation. This is how gninatorch uses libmolgrid within dataloaders.GriddedExamplesLoader:

gnina-torch/gninatorch/dataloaders.py

Line 112 in 34650b8

batch = self.example_provider.next_batch(self.batch_size)

gnina-torch/gninatorch/dataloaders.py

Lines 124 to 140 in 34650b8

	batch_size = len(batch)
	# Compute grids from examples
	grids = torch.zeros((batch_size, *self.dims), device=self.device)
	self.grid_maker.forward(
	batch,
	grids,
	random_translation=self.random_rotation,
	random_rotation=self.random_rotation,
	)
	if not self.grids_only:
	# Ligand pose labels
	# Convert labels to integers; libmolgrid only supports float labels
	labels = torch.zeros((batch_size,), device=self.device)
	batch.extract_label(self.label_pos, labels)
	labels = labels.long() # Convert labels to integer

If your data set is large, you might want to use GNINA's gninatyper CLI utility to transform the molecular files into .types files which are binary files containing only atom types and coordinates (i.e. the information libmolgrid needs for the featurisation). This will reduce I/O.

In gninatorch.gnina you can find a small example of how to set things up using gninatorch's utilities, in case you want to use it within your own pipeline:

gnina-torch/gninatorch/gnina.py

Lines 321 to 338 in 34650b8

	model, ensemble = setup_gnina_model(args.cnn, args.dimension, args.resolution)
	model.eval() # Ensure models are in evaluation mode!
	device = utils.set_device(args.gpu)
	model.to(device)
	example_provider = setup.setup_example_provider(args.input, args, training=False)
	grid_maker = setup.setup_grid_maker(args)
	# TODO: Allow average over different rotations
	loader = dataloaders.GriddedExamplesLoader(
	example_provider=example_provider,
	grid_maker=grid_maker,
	random_translation=0.0, # No random translations for inference
	random_rotation=False, # No random rotations for inference
	device=device,
	grids_only=True,
	)

[kirillshmilovich-insitro]

Hey could you also clarify if libmolgrid generates voxel representations centered on the ligand? Or is there no centering performed?

[RMeli]

Yes, it does (but it depends on which molgrid.GridMaker method you use).

gnina/libmolgrid#50

[kirillshmilovich-insitro]

Makes sense, but can you clarify the default behavior of the grid maker setup by setup.setup_grid_maker in gnina in this context? Do the voxelizations provided by dataloaders.GriddedExamplesLoader apply this centering by default?

[RMeli]

The voxelisations provided by dataloaders.GriddedExamplesLoader are indeed centered on the ligand (which should be the last coordinate set for each example in the .types file), before the optional random translations and rotations applied to the system.

gninatorch.setup.setup_grid_maker() is a very thin layer and it just returns a molgrid.GridMaker:

gnina-torch/gninatorch/setup.py

Lines 92 to 94 in 34650b8

	grid_maker = molgrid.GridMaker(resolution=args.resolution, dimension=args.dimension)
	return grid_maker

In dataloaders.GriddedExamplesLoader the GridMaker.forward() function is called as follows:

gnina-torch/gninatorch/dataloaders.py

Lines 126 to 133 in 34650b8

	# Compute grids from examples
	grids = torch.zeros((batch_size, *self.dims), device=self.device)
	self.grid_maker.forward(
	batch,
	grids,
	random_translation=self.random_rotation,
	random_rotation=self.random_rotation,
	)

Since batch is obtained with molgrid.ExampleProvider.next_batch(), this corresponds to the following signatures in libmolgrid documentation:

forward((GridMaker)arg1, (ExampleVec)examplevec, (Grid5f)grid [, (float)random_translation=0.0 [, (bool)random_rotation=False]]) -> None :

forward( (GridMaker)arg1, (ExampleVec)examples, (Grid5fCUDA)grid [, (float)random_translation=0.0 [, (bool)random_rotation=False]]) -> None :

[RMeli]

As you can see above, there was a small bug in the random_translation argument. This has been fixed in pre-release 0.0.2 (see #48).