volgrids 0.1.0__tar.gz

volgrids-0.1.0/LICENSE.md

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2026 Diego Barquero Morera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

volgrids-0.1.0/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: volgrids
+Version: 0.1.0
+Summary: Framework for volumetric calculations, with emphasis in biological molecular systems.
+Home-page: https://github.com/diegobarmor/volgrids
+Author: DiegoBarMor
+Author-email: diegobarmor42@gmail.com
+License: MIT
+Keywords: grid mif smif volumetric molecular structural biology interaction field
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+# Volumetric Grids (VolGrids)
+This is a framework for volumetric calculations, with emphasis in biological molecular systems. Three tools are also provided: **SMIF Calculator** (`./smiffer.py`), **Volumetric Energy INSpector (VEINS)** (`./veins.py`) and **Volgrid Tools** (`./vgtools.py`). You can read more in their respective sections.
+
+## QuickStart
+```
+pip install -r environment/requirements.txt
+python3 smiffer.py --help
+```
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- -------------------------------- SETUP -------------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# Setup
+## Requirements
+This framework only has 2 Python dependencies:
+- **MDAnalysis** for parsing structure and trajectories data. Installing this should also install **NumPy**, also needed by volgrids.
+- **h5py** for parsing CMAP files.
+
+
+<!-- ----------------------------------------------------------------------- -->
+### Option 1: Setting up a Conda environment
+#### Automatic
+```
+conda env create -f environment/conda.yml
+conda activate volgrids
+```
+
+#### Manual
+```
+conda create --name volgrids -y
+conda activate volgrids
+conda install python -y
+conda install -c conda-forge mdanalysis -y
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+### Option 2: Simple setup with PIP
+#### Automatic
+```
+pip install -r environment/requirements.txt
+```
+
+#### Manual
+```
+pip install mdanalysis h5py
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+### APBS (optional)
+```
+sudo apt-get install apbs
+sudo apt install pdb2pqr
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+## Usage
+### Without installing VolGrids
+You can use the tools provided by VolGrids without installing it, by calling any of the scripts in the root directory of this repository (it doesn't have to be the current directory, you can call them from anywhere). Leave `[options...]` empty to read more about the available options.
+
+- **SMIF Calculator:**
+```
+python3 smiffer.py [options...]
+```
+
+- **Volumetric Energy INSpector (VEINS):**
+```
+python3 veins.py [options...]
+```
+
+- **Volgrid Tools:**
+```
+python3 vgtools.py [options...]
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+### Using VolGrids as a package
+You can install VolGrids as a package and import it from your own scripts. For installing with pip:
+```
+# your current directory should be the root folder of this repository
+pip install .
+rm -rf build volgrids.egg-info # optional cleanup
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+### Running the tests
+Follow the instructions at the [test data repo](https://github.com/DiegoBarMor/volgrids-testdata).
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- ------------------------------- SMIFFER ------------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# Statistical Molecular Interaction Fields (SMIF) Calculator
+This is a custom implementation of the [Statistical Molecular Interaction Fields (SMIF)](https://www.biorxiv.org/content/10.1101/2025.04.16.649117v1) method.
+
+## Usage
+Run `python3 smiffer.py [mode] [path_structure] [options...]` and provide the parameters of the calculation via arguments:
+  - replace `[mode]` with `prot`, `rna` or `ligand` according to the structure of interest.
+  - replace `[path_structure]` with the path to the structure file (e.g. PDB). Mandatory positional argument.
+  - Optionally, replace `[options...]` with any combination of the following:
+    - `-o [folder_out]` where `[folder_out]` is the folder where the output SMIFs should be stored. if not provided, the parent folder of the input file will be used.
+    - `-t [path_traj]`  where `[path_traj]` is the path to a trajectory file (e.g. XTC) supported by MDAnalysis. This activates "traj" mode, where SMIFs are calculated for all the frames of the trajectory and saved in a CMAP-series file.
+    - `-a [path_apbs]` where `[path_apbs]` is the path to the output of APBS. An *OpenDX* file is expected. This grid will be interpolated into the shape of the other grids.
+    - `-s [x] [y] [z] [r]` where `[x]`, `[y]`, `[z]` and `[r]` are the float values for the X,Y,Z coordinates and the radius of a sphere in space, respectively. This activates "pocket sphere" mode, where the SMIFs will only be calculated inside the sphere provided.
+    - `-b [path_table]` where `[path_table]` is the path to a *.chem* table file to use for ligand mode, or to override the default macromolecules' tables. This flag is mandatory for "ligand" mode.
+    - `-c [path_config]` where `[path_config]` is the path to a configuration file with global settings, to override the default settings (e.g. `config_volgrids.ini`).
+
+
+<!-- ----------------------------------------------------------------------- -->
+## Commands examples
+- Sample commands to obtain the electrostatic grids from [pdb2pqr](https://pdb2pqr.readthedocs.io/en/latest/) and [APBS](https://apbs.readthedocs.io/en/latest/)
+```
+pdb2pqr --ff=AMBER testdata/smiffer/pdb-nosolv/1iqj.pdb testdata/smiffer/pqr/1iqj.pqr --apbs-input testdata/smiffer/1iqj.in
+apbs testdata/smiffer/1iqj.in
+```
+
+- Calculate SMIFs for a protein system (`prot`) considering only the space inside a pocket sphere (`-s`).
+```
+python3 smiffer.py prot testdata/smiffer/pdb-nosolv/1iqj.pdb -s 4.682 21.475 7.161 14.675
+```
+
+- Calculate SMIFs for a whole RNA system (`rna`) considering APBS data (`-a`).
+```
+python3 smiffer.py rna testdata/smiffer/pdb-nosolv/5bjo.pdb -a testdata/smiffer/apbs/5bjo.pqr.dx
+```
+
+- Calculate SMIFs for an RNA system (`rna`) along a trajectory (`-t`). Note that for "pocket sphere" mode, the same coordinates/radius are used for the whole trajectory.
+```
+python3 smiffer.py rna testdata/smiffer/traj/7vki.pdb -t testdata/smiffer/traj/7vki.xtc
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+## Visualization
+### Color standard
+| Potential       | Color      | RGB 0-1    | RGB 0-255  | HEX    |
+|-----------------|------------|------------|------------|--------|
+| APBS -          | Red        | 1,0,0      | 255,0,0    | FF0000 |
+| APBS +          | Blue       | 0,0,1      | 0,0,255    | 0000FF |
+| HB Acceptors    | Violet     | 0.7,0,1    | 179,0,255  | B300FF |
+| HB Donors       | Orange     | 1,0.5,0    | 255,128,0  | FF8000 |
+| Hydrophilic (-) | Light Blue | 0.3,0.85,1 | 77,217,255 | 4DD9FF |
+| Hydrophobic (+) | Yellow     | 1,1,0      | 255,255,0  | FFFF00 |
+| Stacking        | Green      | 0,1,0      | 0,255,0    | 00FF00 |
+
+
+### MRC/CCP4 data in Chimera
+Use this command when visualizing MRC/CCP4 data with negative values in Chimera (replace `1` with the actual number of the model).
+```
+volume #1 capFaces false
+```
+
+
+### CMAP trajectories in Chimera
+Follow these instructions to visualize the atomic and SMIF trajectories simultaneously in Chimera. ChimeraX is recommended.
+1) Open the PDB and load the atom trajectory into it (in ChimeraX, simply drag the files into the window).
+2) Open the CMAP file in a similar way.
+3) Start the playback by using this Chimera command. The numbers specified would change if dealing with multiple structures/cmaps. Examples:
+```
+coordset #1; vseries play #2
+coordset #1 pauseFrames 5; vseries play #2 pauseFrames 5
+coordset #1 pauseFrames 5; vseries play #2 pauseFrames 5; vseries play #3 pauseFrames 5
+```
+4) Use this Chimera command to stop the playback. The ids used must match the previous command.
+```
+coordset stop #1; vseries stop #2
+```
+
+
+#### Smooth Trajectories
+1) Load the PDB and the trajectory files into it Chimera (in ChimeraX, simply drag the files into the window).
+2) Load the CMAP file in a similar way.
+3) (Optional) Load the `smooth_md.py` script (again, can be done by dragging it into ChimeraX).
+4) Start the playback by using this Chimera command. The numbers specified would change if dealing with multiple structures/cmaps. Examples:
+```
+coordset #1 pauseFrames 10; vop morph #2 playStep 0.0005 frames 2000 modelId 3
+coordset #1 pauseFrames 20; vop morph #2 playStep 0.00025 frames 4000 modelId 3
+coordset #1 pauseFrames 20; vop morph #2 playStep 0.00025 frames 4000 modelId 4; vop morph #3 playStep 0.00025 frames 4000 modelId 5
+```
+4) Use this Chimera command to stop the playback. The ids used must match the previous command.
+```
+coordset stop #1; vseries stop #2
+```
+Note that this time, the morph can be paused manually with the slider button (is there a command equivalent?)
+
+#### Other useful Chimera commands
+```
+volume level 0.5
+volume transparency 0.5
+volume showOutlineBox true
+```
+
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- -------------------------------- VEINS -------------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# Volumetric Energy INSpector (VEINS)
+This tool allows to visualize interaction energies in space by portraying them as a volumetric grid. Apart from the usual structure/trajectory files (PDB, XTC...), a CSV with energy values and the indices of the atoms/residues involved must be given. Interactions between 2, 3 and 4 particles are supported and represented accordingly
+
+## Usage
+Run `python3 veins.py [mode] [path_structure] [path_csv] [options...]` and provide the parameters of the calculation via arguments:
+  - replace `[mode]` with `energies`.
+  - replace `[path_structure]` with the path to the structure file (e.g. PDB). Mandatory positional argument.
+  - replace `[path_csv]` with the path to the energies CSV file. Mandatory positional argument. It must contain the following rows:
+    - **kind**: Name of the interaction kind. All rows with the same *kind* will be used to calculate a single grid with its name.
+    - **npoints**: Number of particles involved in the interaction.
+    - **idxs**: Group of 0-based indices joined by `-`. These are the indices of the particles involved in the interaction. This group must contain *npoints* indices.
+    - **idxs_are_residues**: Whether the indices correspond to the molecule's residues (`true`) or atoms (`false`).
+    - **energy**: Value of the interaction's energy.
+  - Optionally, replace `[options...]` with any combination of the following:
+    - `-o [folder_out]` where `[folder_out]` is the folder where the output SMIFs should be stored. if not provided, the parent folder of the input file will be used.
+    `-c [cutoff]` where `[cutoff]` is a float number. Energies below this cutoff will be ignored. Default value: 1e-3.
+
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- ---------------------------- VOLGRID TOOLS ---------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# Volgrid Tools
+Collection of utilities for manipulating DX, MRC, CCP4 and CMAP grids.
+
+## Usage
+Run `python3 vgtools.py [mode] [options...]` and provide the parameters of the calculation via arguments.
+  - Replace `[mode]` with one of the following available modes:
+    - `convert`: Convert grid files between formats.
+    - `pack`: Pack multiple grid files into a single CMAP series-file.
+    - `unpack`: Unpack a CMAP series-file into multiple grid files.
+    - `fix_cmap`: Ensure that all grids in a CMAP series-file have the same resolution, interpolating them if necessary.
+    - `compare`: Compare two grid files by printing the number of differing points and their accumulated difference.
+  - `[options...]` will depend on the mode, check the respective help string for more information (run `python3 vgtools.py [mode] -h`).
+
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- --------------------------------- TODO -------------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# TODO
+* improve help strings
+* add annotations, docstrings and overall cleaning
+* try out cavities-finder ideas
+
+## VGrids
+* implement: raise an error if a format file is opened with the wrong function
+* add tests for parameters being directly passed to the App classes (instead of parsing the CLI arguments)
+* standard ini files use ; instead of # for comments
+
+## SMIFFER
+* maybe: replace the RNDS trimming with a faster method
+* change the ligand example to one that uses both NAMES_HBACCEPTORS, NAMES_HBDONORS and NAMES_HBD_FIXED
+* document the .chem tables
+* check if there's a bug in the peptide bond N of the test toy system peptide_no_h
+* add safeguard when there's no atoms for the specified molecule type
+
+## VEINS
+* finish/rework "energies" mode implementation
+* implement "forces" mode
+* move Grid's static fields into config_volgrids.ini
+* add tests
+
+## VGTools
+* check what happens if performing "fix_cmap" operation when cmap input and output are the same file
+* implement the fixing operation directy on "packing", to ensure that packed frames have the same resolution (add flag to override this behavior)
+* mode to describe grids
+* mode to perform operations on grids: abs, sum, diff, mask...
+* when editing a CMAP file (be it converting it or performing an operation on it), one should be able to specify the key of the relevant grid (instead of GridIO.read_auto arbitrarily deciding to take the first key it finds in the CMAP header)
+* bypass the "large grid" warning when processing an existing large grid with VGTools.
+* add tests for the "average" operation.
+
+
+<!-- ----------------------------------------------------------------------- -->

volgrids-0.1.0/README.md

@@ -0,0 +1,276 @@
+# Volumetric Grids (VolGrids)
+This is a framework for volumetric calculations, with emphasis in biological molecular systems. Three tools are also provided: **SMIF Calculator** (`./smiffer.py`), **Volumetric Energy INSpector (VEINS)** (`./veins.py`) and **Volgrid Tools** (`./vgtools.py`). You can read more in their respective sections.
+
+## QuickStart
+```
+pip install -r environment/requirements.txt
+python3 smiffer.py --help
+```
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- -------------------------------- SETUP -------------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# Setup
+## Requirements
+This framework only has 2 Python dependencies:
+- **MDAnalysis** for parsing structure and trajectories data. Installing this should also install **NumPy**, also needed by volgrids.
+- **h5py** for parsing CMAP files.
+
+
+<!-- ----------------------------------------------------------------------- -->
+### Option 1: Setting up a Conda environment
+#### Automatic
+```
+conda env create -f environment/conda.yml
+conda activate volgrids
+```
+
+#### Manual
+```
+conda create --name volgrids -y
+conda activate volgrids
+conda install python -y
+conda install -c conda-forge mdanalysis -y
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+### Option 2: Simple setup with PIP
+#### Automatic
+```
+pip install -r environment/requirements.txt
+```
+
+#### Manual
+```
+pip install mdanalysis h5py
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+### APBS (optional)
+```
+sudo apt-get install apbs
+sudo apt install pdb2pqr
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+## Usage
+### Without installing VolGrids
+You can use the tools provided by VolGrids without installing it, by calling any of the scripts in the root directory of this repository (it doesn't have to be the current directory, you can call them from anywhere). Leave `[options...]` empty to read more about the available options.
+
+- **SMIF Calculator:**
+```
+python3 smiffer.py [options...]
+```
+
+- **Volumetric Energy INSpector (VEINS):**
+```
+python3 veins.py [options...]
+```
+
+- **Volgrid Tools:**
+```
+python3 vgtools.py [options...]
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+### Using VolGrids as a package
+You can install VolGrids as a package and import it from your own scripts. For installing with pip:
+```
+# your current directory should be the root folder of this repository
+pip install .
+rm -rf build volgrids.egg-info # optional cleanup
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+### Running the tests
+Follow the instructions at the [test data repo](https://github.com/DiegoBarMor/volgrids-testdata).
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- ------------------------------- SMIFFER ------------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# Statistical Molecular Interaction Fields (SMIF) Calculator
+This is a custom implementation of the [Statistical Molecular Interaction Fields (SMIF)](https://www.biorxiv.org/content/10.1101/2025.04.16.649117v1) method.
+
+## Usage
+Run `python3 smiffer.py [mode] [path_structure] [options...]` and provide the parameters of the calculation via arguments:
+  - replace `[mode]` with `prot`, `rna` or `ligand` according to the structure of interest.
+  - replace `[path_structure]` with the path to the structure file (e.g. PDB). Mandatory positional argument.
+  - Optionally, replace `[options...]` with any combination of the following:
+    - `-o [folder_out]` where `[folder_out]` is the folder where the output SMIFs should be stored. if not provided, the parent folder of the input file will be used.
+    - `-t [path_traj]`  where `[path_traj]` is the path to a trajectory file (e.g. XTC) supported by MDAnalysis. This activates "traj" mode, where SMIFs are calculated for all the frames of the trajectory and saved in a CMAP-series file.
+    - `-a [path_apbs]` where `[path_apbs]` is the path to the output of APBS. An *OpenDX* file is expected. This grid will be interpolated into the shape of the other grids.
+    - `-s [x] [y] [z] [r]` where `[x]`, `[y]`, `[z]` and `[r]` are the float values for the X,Y,Z coordinates and the radius of a sphere in space, respectively. This activates "pocket sphere" mode, where the SMIFs will only be calculated inside the sphere provided.
+    - `-b [path_table]` where `[path_table]` is the path to a *.chem* table file to use for ligand mode, or to override the default macromolecules' tables. This flag is mandatory for "ligand" mode.
+    - `-c [path_config]` where `[path_config]` is the path to a configuration file with global settings, to override the default settings (e.g. `config_volgrids.ini`).
+
+
+<!-- ----------------------------------------------------------------------- -->
+## Commands examples
+- Sample commands to obtain the electrostatic grids from [pdb2pqr](https://pdb2pqr.readthedocs.io/en/latest/) and [APBS](https://apbs.readthedocs.io/en/latest/)
+```
+pdb2pqr --ff=AMBER testdata/smiffer/pdb-nosolv/1iqj.pdb testdata/smiffer/pqr/1iqj.pqr --apbs-input testdata/smiffer/1iqj.in
+apbs testdata/smiffer/1iqj.in
+```
+
+- Calculate SMIFs for a protein system (`prot`) considering only the space inside a pocket sphere (`-s`).
+```
+python3 smiffer.py prot testdata/smiffer/pdb-nosolv/1iqj.pdb -s 4.682 21.475 7.161 14.675
+```
+
+- Calculate SMIFs for a whole RNA system (`rna`) considering APBS data (`-a`).
+```
+python3 smiffer.py rna testdata/smiffer/pdb-nosolv/5bjo.pdb -a testdata/smiffer/apbs/5bjo.pqr.dx
+```
+
+- Calculate SMIFs for an RNA system (`rna`) along a trajectory (`-t`). Note that for "pocket sphere" mode, the same coordinates/radius are used for the whole trajectory.
+```
+python3 smiffer.py rna testdata/smiffer/traj/7vki.pdb -t testdata/smiffer/traj/7vki.xtc
+```
+
+
+<!-- ----------------------------------------------------------------------- -->
+## Visualization
+### Color standard
+| Potential       | Color      | RGB 0-1    | RGB 0-255  | HEX    |
+|-----------------|------------|------------|------------|--------|
+| APBS -          | Red        | 1,0,0      | 255,0,0    | FF0000 |
+| APBS +          | Blue       | 0,0,1      | 0,0,255    | 0000FF |
+| HB Acceptors    | Violet     | 0.7,0,1    | 179,0,255  | B300FF |
+| HB Donors       | Orange     | 1,0.5,0    | 255,128,0  | FF8000 |
+| Hydrophilic (-) | Light Blue | 0.3,0.85,1 | 77,217,255 | 4DD9FF |
+| Hydrophobic (+) | Yellow     | 1,1,0      | 255,255,0  | FFFF00 |
+| Stacking        | Green      | 0,1,0      | 0,255,0    | 00FF00 |
+
+
+### MRC/CCP4 data in Chimera
+Use this command when visualizing MRC/CCP4 data with negative values in Chimera (replace `1` with the actual number of the model).
+```
+volume #1 capFaces false
+```
+
+
+### CMAP trajectories in Chimera
+Follow these instructions to visualize the atomic and SMIF trajectories simultaneously in Chimera. ChimeraX is recommended.
+1) Open the PDB and load the atom trajectory into it (in ChimeraX, simply drag the files into the window).
+2) Open the CMAP file in a similar way.
+3) Start the playback by using this Chimera command. The numbers specified would change if dealing with multiple structures/cmaps. Examples:
+```
+coordset #1; vseries play #2
+coordset #1 pauseFrames 5; vseries play #2 pauseFrames 5
+coordset #1 pauseFrames 5; vseries play #2 pauseFrames 5; vseries play #3 pauseFrames 5
+```
+4) Use this Chimera command to stop the playback. The ids used must match the previous command.
+```
+coordset stop #1; vseries stop #2
+```
+
+
+#### Smooth Trajectories
+1) Load the PDB and the trajectory files into it Chimera (in ChimeraX, simply drag the files into the window).
+2) Load the CMAP file in a similar way.
+3) (Optional) Load the `smooth_md.py` script (again, can be done by dragging it into ChimeraX).
+4) Start the playback by using this Chimera command. The numbers specified would change if dealing with multiple structures/cmaps. Examples:
+```
+coordset #1 pauseFrames 10; vop morph #2 playStep 0.0005 frames 2000 modelId 3
+coordset #1 pauseFrames 20; vop morph #2 playStep 0.00025 frames 4000 modelId 3
+coordset #1 pauseFrames 20; vop morph #2 playStep 0.00025 frames 4000 modelId 4; vop morph #3 playStep 0.00025 frames 4000 modelId 5
+```
+4) Use this Chimera command to stop the playback. The ids used must match the previous command.
+```
+coordset stop #1; vseries stop #2
+```
+Note that this time, the morph can be paused manually with the slider button (is there a command equivalent?)
+
+#### Other useful Chimera commands
+```
+volume level 0.5
+volume transparency 0.5
+volume showOutlineBox true
+```
+
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- -------------------------------- VEINS -------------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# Volumetric Energy INSpector (VEINS)
+This tool allows to visualize interaction energies in space by portraying them as a volumetric grid. Apart from the usual structure/trajectory files (PDB, XTC...), a CSV with energy values and the indices of the atoms/residues involved must be given. Interactions between 2, 3 and 4 particles are supported and represented accordingly
+
+## Usage
+Run `python3 veins.py [mode] [path_structure] [path_csv] [options...]` and provide the parameters of the calculation via arguments:
+  - replace `[mode]` with `energies`.
+  - replace `[path_structure]` with the path to the structure file (e.g. PDB). Mandatory positional argument.
+  - replace `[path_csv]` with the path to the energies CSV file. Mandatory positional argument. It must contain the following rows:
+    - **kind**: Name of the interaction kind. All rows with the same *kind* will be used to calculate a single grid with its name.
+    - **npoints**: Number of particles involved in the interaction.
+    - **idxs**: Group of 0-based indices joined by `-`. These are the indices of the particles involved in the interaction. This group must contain *npoints* indices.
+    - **idxs_are_residues**: Whether the indices correspond to the molecule's residues (`true`) or atoms (`false`).
+    - **energy**: Value of the interaction's energy.
+  - Optionally, replace `[options...]` with any combination of the following:
+    - `-o [folder_out]` where `[folder_out]` is the folder where the output SMIFs should be stored. if not provided, the parent folder of the input file will be used.
+    `-c [cutoff]` where `[cutoff]` is a float number. Energies below this cutoff will be ignored. Default value: 1e-3.
+
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- ---------------------------- VOLGRID TOOLS ---------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# Volgrid Tools
+Collection of utilities for manipulating DX, MRC, CCP4 and CMAP grids.
+
+## Usage
+Run `python3 vgtools.py [mode] [options...]` and provide the parameters of the calculation via arguments.
+  - Replace `[mode]` with one of the following available modes:
+    - `convert`: Convert grid files between formats.
+    - `pack`: Pack multiple grid files into a single CMAP series-file.
+    - `unpack`: Unpack a CMAP series-file into multiple grid files.
+    - `fix_cmap`: Ensure that all grids in a CMAP series-file have the same resolution, interpolating them if necessary.
+    - `compare`: Compare two grid files by printing the number of differing points and their accumulated difference.
+  - `[options...]` will depend on the mode, check the respective help string for more information (run `python3 vgtools.py [mode] -h`).
+
+
+
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- --------------------------------- TODO -------------------------------- -->
+<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+# TODO
+* improve help strings
+* add annotations, docstrings and overall cleaning
+* try out cavities-finder ideas
+
+## VGrids
+* implement: raise an error if a format file is opened with the wrong function
+* add tests for parameters being directly passed to the App classes (instead of parsing the CLI arguments)
+* standard ini files use ; instead of # for comments
+
+## SMIFFER
+* maybe: replace the RNDS trimming with a faster method
+* change the ligand example to one that uses both NAMES_HBACCEPTORS, NAMES_HBDONORS and NAMES_HBD_FIXED
+* document the .chem tables
+* check if there's a bug in the peptide bond N of the test toy system peptide_no_h
+* add safeguard when there's no atoms for the specified molecule type
+
+## VEINS
+* finish/rework "energies" mode implementation
+* implement "forces" mode
+* move Grid's static fields into config_volgrids.ini
+* add tests
+
+## VGTools
+* check what happens if performing "fix_cmap" operation when cmap input and output are the same file
+* implement the fixing operation directy on "packing", to ensure that packed frames have the same resolution (add flag to override this behavior)
+* mode to describe grids
+* mode to perform operations on grids: abs, sum, diff, mask...
+* when editing a CMAP file (be it converting it or performing an operation on it), one should be able to specify the key of the relevant grid (instead of GridIO.read_auto arbitrarily deciding to take the first key it finds in the CMAP header)
+* bypass the "large grid" warning when processing an existing large grid with VGTools.
+* add tests for the "average" operation.
+
+
+<!-- ----------------------------------------------------------------------- -->

volgrids-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"

volgrids-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

volgrids-0.1.0/setup.py

@@ -0,0 +1,23 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="volgrids",
+    version="0.1.0",
+    description="Framework for volumetric calculations, with emphasis in biological molecular systems.",
+    keywords="grid mif smif volumetric molecular structural biology interaction field",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="DiegoBarMor",
+    author_email="diegobarmor42@gmail.com",
+    url="https://github.com/diegobarmor/volgrids",
+    license="MIT",
+    packages=find_packages(),
+    package_data={"volgrids": ["_tables/*"]},
+    install_requires=[],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.10",
+)