coarsify


Namecoarsify JSON
Version 1.0.3 PyPI version JSON
download
home_pagehttps://github.com/jackericson98/coarsify
SummaryA Python tool for coarse-graining molecular structures
upload_time2025-07-23 21:14:02
maintainerNone
docs_urlNone
authorJohn Ericson
requires_python>=3.7
licenseMIT
keywords molecular dynamics coarse-graining protein structure chemistry physics
VCS
bugtrack_url
requirements numpy pandas matplotlib
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Coarsify

A Python tool for coarse-graining molecular structures from various file formats (.pdb, .gro, .mol, .cif, .xyz) into simplified representations using different coarse-graining schemes. Designed for researchers working with molecular dynamics simulations who need to approximate molecules as fewer spheres or perform structural analysis.

## Features

- **Multiple Input Formats**: Supports PDB, GRO, MOL, CIF, and XYZ file formats
- **Various Coarse-Graining Schemes**:
  - **Average Distance**: Balls located at center of mass of residues with radius based on average distance of constituent atoms
  - **Encapsulate Residues**: Balls that minimally encapsulate atoms in a residue
  - **Side Chain/Backbone Split**: Separate beads for backbone and sidechain atoms
  - **Martini**: Pre-processed PDB files using CG-MARTINI force field mapping
- **Mass-Weighted Options**: Choose between mass-weighted or geometric center calculations
- **Thermal Cushion**: Add additional radius to account for thermal motion
- **Hydrogen Handling**: Option to include or exclude hydrogen atoms
- **PyMOL Integration**: Automatic generation of PyMOL scripts for visualization
- **Multiple Output Formats**: PDB files with coarse-grained structures and text files with coordinates and radii

## Installation

### From PyPI (Recommended)

```bash
pip install coarsify
```

### From Source

1. Clone the repository:
   ```bash
   git clone https://github.com/your-username/coarsify.git
   cd coarsify
   ```

2. Install in development mode:
   ```bash
   pip install -e .
   ```

### Prerequisites
- Python 3.7 or higher
- Required Python packages (automatically installed):
  - numpy >= 1.24.0
  - pandas >= 2.0.0

## Usage

### Graphical User Interface (Recommended)

The GUI provides an intuitive interface for all coarse-graining operations:

```bash
coarsify-gui
```

Or if installed from source:
```bash
python -m coarsify.src.gui.gui
```

**GUI Features:**
- File selection dialog for input structures
- Dropdown menus for all parameters
- Real-time parameter validation
- Help system with detailed explanations
- Output folder selection

### Command Line Interface

For batch processing or scripting:

```bash
coarsify
```

Or if installed from source:
```bash
python -m coarsify
```

**CLI Options:**
- Interactive prompts for all parameters
- File dialog for input selection
- Multiple output location options

## Coarse-Graining Schemes

### 1. Average Distance
- **Description**: Creates balls at the center of mass of residues
- **Radius**: Average distance of constituent atoms from the center
- **Options**: Mass-weighted or geometric center calculation
- **Best for**: General structural analysis and visualization

### 2. Encapsulate Residues
- **Description**: Creates minimal spheres that contain all atoms in a residue
- **Radius**: Minimum radius to encapsulate all residue atoms
- **Best for**: Preserving molecular volume and shape

### 3. Side Chain/Backbone Split
- **Description**: Separates backbone and sidechain atoms into different beads
- **Variants**: 
  - Average Distance with split
  - Encapsulate with split
- **Best for**: Detailed analysis of protein structure and dynamics

### 4. Martini
- **Description**: Applies CG-MARTINI force field mapping
- **Best for**: Molecular dynamics simulations with MARTINI force field

## Parameters

- **Thermal Cushion**: Additional radius (in Angstroms) added to account for thermal motion
- **Mass Weighted**: Use mass-weighted averaging for bead positions (vs. geometric center)
- **Include Hydrogens**: Include hydrogen atoms in coarse-graining calculations
- **Split Residue**: Separate backbone and sidechain into different beads

## Output Files

For each coarse-graining operation, the following files are generated:

1. **`[name]_[scheme].pdb`**: Coarse-grained structure in PDB format
2. **`[name]_base.pdb`**: Copy of the original input structure
3. **`set_atom_colors.pml`**: PyMOL script for sphere visualization
4. **`[name]_[scheme].txt`**: Text file with coordinates and radii of coarse-grained beads

## PyMOL Visualization

The tool automatically generates PyMOL scripts for easy visualization:

1. Load the coarse-grained PDB file in PyMOL
2. Run the generated `set_atom_colors.pml` script
3. The script will:
   - Set appropriate sphere radii for each bead
   - Apply color schemes based on residue types
   - Configure visualization settings

## Example Workflow

1. **Load Structure**: Select your PDB file through the GUI
2. **Choose Scheme**: Select "Average Distance" for general analysis
3. **Set Parameters**: 
   - Thermal cushion: 1.0 Å
   - Mass weighted: Yes
   - Include hydrogens: No
4. **Run Coarse-Graining**: Execute the process
5. **Visualize**: Open the output PDB in PyMOL and run the generated script

## Integration with Vorpy

This tool was originally developed to work in conjunction with [Vorpy](https://github.com/your-username/vorpy) for Voronoi diagram analysis of molecular structures. The coarse-grained representations can be used as input for Voronoi tessellation analysis.

## Contributing

This tool is actively developed for molecular dynamics research. Contributions are welcome, particularly for:
- Additional coarse-graining schemes
- Support for new file formats
- Performance optimizations
- Documentation improvements

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

## Citation

If you use this tool in your research, please cite:

```bibtex
@software{coarsify2024,
  author = {John Ericson},
  title = {Coarsify: A Python package for coarse graining molecular structures},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/jackericson98/coarsify}
}
```

## Contact

For questions, bug reports, or feature requests, please [create an issue](https://github.com/your-username/coarsify/issues) or contact [your-email@domain.com].

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/jackericson98/coarsify",
    "name": "coarsify",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "John Ericson <jackericson98@gmail.com>",
    "keywords": "molecular dynamics, coarse-graining, protein structure, chemistry, physics",
    "author": "John Ericson",
    "author_email": "John Ericson <jackericson98@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/08/ce/65d141ec959f3eea96e7a970561d16049f8bdd9d9bef383600e5b476aeed/coarsify-1.0.3.tar.gz",
    "platform": null,
    "description": "# Coarsify\r\n\r\nA Python tool for coarse-graining molecular structures from various file formats (.pdb, .gro, .mol, .cif, .xyz) into simplified representations using different coarse-graining schemes. Designed for researchers working with molecular dynamics simulations who need to approximate molecules as fewer spheres or perform structural analysis.\r\n\r\n## Features\r\n\r\n- **Multiple Input Formats**: Supports PDB, GRO, MOL, CIF, and XYZ file formats\r\n- **Various Coarse-Graining Schemes**:\r\n  - **Average Distance**: Balls located at center of mass of residues with radius based on average distance of constituent atoms\r\n  - **Encapsulate Residues**: Balls that minimally encapsulate atoms in a residue\r\n  - **Side Chain/Backbone Split**: Separate beads for backbone and sidechain atoms\r\n  - **Martini**: Pre-processed PDB files using CG-MARTINI force field mapping\r\n- **Mass-Weighted Options**: Choose between mass-weighted or geometric center calculations\r\n- **Thermal Cushion**: Add additional radius to account for thermal motion\r\n- **Hydrogen Handling**: Option to include or exclude hydrogen atoms\r\n- **PyMOL Integration**: Automatic generation of PyMOL scripts for visualization\r\n- **Multiple Output Formats**: PDB files with coarse-grained structures and text files with coordinates and radii\r\n\r\n## Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install coarsify\r\n```\r\n\r\n### From Source\r\n\r\n1. Clone the repository:\r\n   ```bash\r\n   git clone https://github.com/your-username/coarsify.git\r\n   cd coarsify\r\n   ```\r\n\r\n2. Install in development mode:\r\n   ```bash\r\n   pip install -e .\r\n   ```\r\n\r\n### Prerequisites\r\n- Python 3.7 or higher\r\n- Required Python packages (automatically installed):\r\n  - numpy >= 1.24.0\r\n  - pandas >= 2.0.0\r\n\r\n## Usage\r\n\r\n### Graphical User Interface (Recommended)\r\n\r\nThe GUI provides an intuitive interface for all coarse-graining operations:\r\n\r\n```bash\r\ncoarsify-gui\r\n```\r\n\r\nOr if installed from source:\r\n```bash\r\npython -m coarsify.src.gui.gui\r\n```\r\n\r\n**GUI Features:**\r\n- File selection dialog for input structures\r\n- Dropdown menus for all parameters\r\n- Real-time parameter validation\r\n- Help system with detailed explanations\r\n- Output folder selection\r\n\r\n### Command Line Interface\r\n\r\nFor batch processing or scripting:\r\n\r\n```bash\r\ncoarsify\r\n```\r\n\r\nOr if installed from source:\r\n```bash\r\npython -m coarsify\r\n```\r\n\r\n**CLI Options:**\r\n- Interactive prompts for all parameters\r\n- File dialog for input selection\r\n- Multiple output location options\r\n\r\n## Coarse-Graining Schemes\r\n\r\n### 1. Average Distance\r\n- **Description**: Creates balls at the center of mass of residues\r\n- **Radius**: Average distance of constituent atoms from the center\r\n- **Options**: Mass-weighted or geometric center calculation\r\n- **Best for**: General structural analysis and visualization\r\n\r\n### 2. Encapsulate Residues\r\n- **Description**: Creates minimal spheres that contain all atoms in a residue\r\n- **Radius**: Minimum radius to encapsulate all residue atoms\r\n- **Best for**: Preserving molecular volume and shape\r\n\r\n### 3. Side Chain/Backbone Split\r\n- **Description**: Separates backbone and sidechain atoms into different beads\r\n- **Variants**: \r\n  - Average Distance with split\r\n  - Encapsulate with split\r\n- **Best for**: Detailed analysis of protein structure and dynamics\r\n\r\n### 4. Martini\r\n- **Description**: Applies CG-MARTINI force field mapping\r\n- **Best for**: Molecular dynamics simulations with MARTINI force field\r\n\r\n## Parameters\r\n\r\n- **Thermal Cushion**: Additional radius (in Angstroms) added to account for thermal motion\r\n- **Mass Weighted**: Use mass-weighted averaging for bead positions (vs. geometric center)\r\n- **Include Hydrogens**: Include hydrogen atoms in coarse-graining calculations\r\n- **Split Residue**: Separate backbone and sidechain into different beads\r\n\r\n## Output Files\r\n\r\nFor each coarse-graining operation, the following files are generated:\r\n\r\n1. **`[name]_[scheme].pdb`**: Coarse-grained structure in PDB format\r\n2. **`[name]_base.pdb`**: Copy of the original input structure\r\n3. **`set_atom_colors.pml`**: PyMOL script for sphere visualization\r\n4. **`[name]_[scheme].txt`**: Text file with coordinates and radii of coarse-grained beads\r\n\r\n## PyMOL Visualization\r\n\r\nThe tool automatically generates PyMOL scripts for easy visualization:\r\n\r\n1. Load the coarse-grained PDB file in PyMOL\r\n2. Run the generated `set_atom_colors.pml` script\r\n3. The script will:\r\n   - Set appropriate sphere radii for each bead\r\n   - Apply color schemes based on residue types\r\n   - Configure visualization settings\r\n\r\n## Example Workflow\r\n\r\n1. **Load Structure**: Select your PDB file through the GUI\r\n2. **Choose Scheme**: Select \"Average Distance\" for general analysis\r\n3. **Set Parameters**: \r\n   - Thermal cushion: 1.0 \u00c5\r\n   - Mass weighted: Yes\r\n   - Include hydrogens: No\r\n4. **Run Coarse-Graining**: Execute the process\r\n5. **Visualize**: Open the output PDB in PyMOL and run the generated script\r\n\r\n## Integration with Vorpy\r\n\r\nThis tool was originally developed to work in conjunction with [Vorpy](https://github.com/your-username/vorpy) for Voronoi diagram analysis of molecular structures. The coarse-grained representations can be used as input for Voronoi tessellation analysis.\r\n\r\n## Contributing\r\n\r\nThis tool is actively developed for molecular dynamics research. Contributions are welcome, particularly for:\r\n- Additional coarse-graining schemes\r\n- Support for new file formats\r\n- Performance optimizations\r\n- Documentation improvements\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details\r\n\r\n## Citation\r\n\r\nIf you use this tool in your research, please cite:\r\n\r\n```bibtex\r\n@software{coarsify2024,\r\n  author = {John Ericson},\r\n  title = {Coarsify: A Python package for coarse graining molecular structures},\r\n  year = {2024},\r\n  publisher = {GitHub},\r\n  url = {https://github.com/jackericson98/coarsify}\r\n}\r\n```\r\n\r\n## Contact\r\n\r\nFor questions, bug reports, or feature requests, please [create an issue](https://github.com/your-username/coarsify/issues) or contact [your-email@domain.com].\r\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A Python tool for coarse-graining molecular structures",
    "version": "1.0.3",
    "project_urls": {
        "Bug Tracker": "https://github.com/jackericson98/coarsify/issues",
        "Documentation": "https://github.com/jackericson98/coarsify#readme",
        "Homepage": "https://github.com/jackericson98/coarsify",
        "Repository": "https://github.com/jackericson98/coarsify"
    },
    "split_keywords": [
        "molecular dynamics",
        " coarse-graining",
        " protein structure",
        " chemistry",
        " physics"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "06dc47de252bf0b018b62b30e8c7cb4eb550a87b4b4c94de1fbb54767adfc180",
                "md5": "6427f6106b994065b4c183bd811d00dc",
                "sha256": "8ddeb6309c8981a183e5b6d1ae47ce817433ddc959beed12db70d74aa7839365"
            },
            "downloads": -1,
            "filename": "coarsify-1.0.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "6427f6106b994065b4c183bd811d00dc",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 19826833,
            "upload_time": "2025-07-23T21:13:59",
            "upload_time_iso_8601": "2025-07-23T21:13:59.023315Z",
            "url": "https://files.pythonhosted.org/packages/06/dc/47de252bf0b018b62b30e8c7cb4eb550a87b4b4c94de1fbb54767adfc180/coarsify-1.0.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "08ce65d141ec959f3eea96e7a970561d16049f8bdd9d9bef383600e5b476aeed",
                "md5": "69e49450cc5e1f32d2ffe1c8ea393d47",
                "sha256": "a14ac83974e30880e1a026276b790911bec3a476741715370d3eb528bfa6957d"
            },
            "downloads": -1,
            "filename": "coarsify-1.0.3.tar.gz",
            "has_sig": false,
            "md5_digest": "69e49450cc5e1f32d2ffe1c8ea393d47",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 17366651,
            "upload_time": "2025-07-23T21:14:02",
            "upload_time_iso_8601": "2025-07-23T21:14:02.479956Z",
            "url": "https://files.pythonhosted.org/packages/08/ce/65d141ec959f3eea96e7a970561d16049f8bdd9d9bef383600e5b476aeed/coarsify-1.0.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-23 21:14:02",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "jackericson98",
    "github_project": "coarsify",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "requirements": [
        {
            "name": "numpy",
            "specs": [
                [
                    "~=",
                    "1.24.4"
                ]
            ]
        },
        {
            "name": "pandas",
            "specs": [
                [
                    "~=",
                    "2.0.3"
                ]
            ]
        },
        {
            "name": "matplotlib",
            "specs": [
                [
                    "~=",
                    "3.7.5"
                ]
            ]
        }
    ],
    "lcname": "coarsify"
}
        
Elapsed time: 1.17983s