protein-mosaic-q

protein-mosaic-q is a Python library for computing structural parameters (Q and Q_alt) that quantify the spatial clustering of amino acids in protein three-dimensional structures.

The library operates directly on PDB and mmCIF structure files and is built on top of Biopython.

---

Overview

Given a protein structure file (PDB or mmCIF), the library computes:

• Q — quantifies the degree of spatial clustering among amino acids of the same chemical type (acidic, basic, polar, hydrophobic)
• Q_alt — an extension of Q that also includes amino acids classified as “special”

In essence, higher values indicate stronger clustering of residues with similar physicochemical properties, whereas lower values correspond to a more homogeneous spatial distribution.

---

Scientific context

These parameters are motivated by the observation that amino acids in protein structures tend to organize into clusters according to their chemical families, forming a mosaic-like spatial arrangement.

This organization can be:

• quantified mathematically through parameters such as Q and Q_alt
• visually inspected in protein structural representations

Empirical analyses have shown that:

• the value of Q is strongly dependent on the number of residues (n)
• an analogous relationship exists for Q_alt

This suggests the existence of a highly conserved structural property across a wide range of proteins.

---

Proteins Mosaic Q Project

This library is associated with the Proteins Mosaic Q Project, a citizen-science initiative aimed at gathering evidence for this structural clustering pattern.

The project combines:

• computational analysis (such as the calculations implemented in this library)
• visual validation by independent observers that contribute to a collaborative repository of protein images.

---

Project links

• EU-Citizen.Science
  https://citizenscience.eu/project/686

• SciStarter
  https://scistarter.org/proteins-mosaic-q-project

• Observatorio de Ciencia Ciudadana https://ciencia-ciudadana.es/project/392

---

Installation

pip install protein-mosaic-q

---

Usage

from mosaicq import calculate_q, calculate_q_alt

q = calculate_q("protein.pdb")
q_alt = calculate_q_alt("protein.cif")

print(q, q_alt)

---

Command-line interface

mosaicq protein.pdb
mosaicq protein.cif --metric Q_alt

---

Interpretation of results

• Higher values indicate stronger clustering of amino acids of the same chemical type
• Lower values indicate a more uniform spatial distribution

These parameters provide a quantitative framework for analyzing protein structural organization.

---

Contributing

Contributions are welcome. Potential areas include:

• performance improvements
• additional structural descriptors
• expanded compatibility with other structural formats or tools

---

License

MIT License