| Name | biology-files JSON |
| Version |
0.2.14
JSON |
| download |
| home_page | None |
| Summary | Save and load common biology file formats |
| upload_time | 2025-09-13 17:35:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
mol2
sdf
mmcif
amber
biology
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Bio Files: Read and write common biology file formats
[](https://crates.io/crates/bio_files)
[](https://docs.rs/bio_files)
[](https://pypi.org/project/biology-files)
This Rust and Python library contains functionality to load and save data in common biology file formats. It operates
on data structures that are specific to each file format; you will need to convert to and from the structures
used by your application. The API docs, and examples below are sufficient to get started.
Note: Install the pip version with `pip install biology-files` due to a name conflict.
### Supported formats:
- mmCIF (Protein atom, residue, chain, and related data like secondary structure)
- Mol2 (Small molecules, e.g. ligands)
- SDF (Small molecules, e.g. ligands)
- PDBQT (Small molecules, e.g. ligands. Includes docking-specific fields.)
- Map (Electron density, e.g. from crystallography, Cryo EM)
- AB1 (Sequence tracing)
- DAT (Amber force field data for small molecules)
- FRCMOD (Amber force field patch data for small molecules)
- Amber .lib files, e.g. with charge data for amino acids and proteins.
### Planned:
- MTZ (Exists in Daedalus; needs to be decoupled)
- DNA (Exists in PlasCAD; needs to be decoupled)
- CIF structure formats (2fo-fc etc) (Exists in Daedalus; needs to be decoupled)
For Genbank, we recommend [gb-io](https://docs.rs/gb-io/latest/gb_io/). We do not plan to support this format, due to this high quality library.
Each module represents a file format, and most have dedicated structs dedicated to operating on that format.
It operates using structs with public fields, which you can explore
using the [API docs](https://docs.rs/bio_files), or your IDE. These structs generally include these three methods: `new()`,
`save()` and `load()`. `new()` accepts `&str` for text files, and a `R: Read + Seek` for binary. `save()` and
`load()` accept `&Path`.
The Force Field formats use `load_dat`, `save_frcmod` instead, as they use the same structs for both formats.
## Serial numbers
Serial numbers for atoms, residues, secondary structure, and chains are generally pulled directly from atom data files
(mmCIF, Mol2 etc). These lists reference atoms, or residues, stored as `Vec<u32>`, with the `u32` being the serial number.
In your application, you may wish to adapt these generic types to custom ones that use index lookups
instead of serial numbers. We use SNs here because they're more robust, and match the input files directly;
add optimizations downstream, like converting to indices, and/or applying back-references. (e.g. the index of the residue
an atom's in, in your derived Atom struct).
## Example use
Small molecule save and load, Python.
```python
from biology_files import Sdf
sdf_data = Sdf.load("./molecules/DB03496.sdf")
sdf_data.atoms[0]
#AtomGeneric { serial_number: 1, posit: Vec3 { x: 2.3974, y: 1.1259, z: 2.5289 }, element: Chlorine,
type_in_res: None, force_field_type: None, occupancy: None, partial_charge: None, hetero: true }
>>> sdf_data.atoms[0].posit
# [2.3974, 1.1259, 2.5289]
sdf_data.save("test.sdf")
mol2_data = sdf_data.to_mol2()
mol2_data.save("test.mol2")
```
Small molecule save and load, Rust.
```rust
use bio_files::{Sdf, Mol2};}
// ...
let sdf_data = Sdf::load("./molecules/DB03496.sdf");
sdf_data.atoms[0]; // (as above)
sdf_data.atoms[0].posit; // (as above, but lin_alg::Vec3))
sdf_data.save("test.sdf");
let mol2_data: Mol2 = sdf_data.into();
mol2_data.save("test.mol2");
// Loading Force field parameters:
let p = Path::new("gaff2.dat")
let params = ForceFieldParams::load_dat(p)?;
```
You can use similar syntax for mmCIF protein files.
## Amber force fields
Reference the [Amber 2025 Reference Manual, section 15](https://ambermd.org/doc12/Amber25.pdf)
for details on how we parse its files, and how to use the results. In some cases, we change the format from
the raw Amber data. For example, we store angles as radians (vice degrees), and σ vice R_min for Van der Waals
parameters. Structs and fields are documented with reference manual references.
The Amber forcefield parameter format has fields which each contain a `Vec` of a certain type of data. (Bond stretching parameters,
angle between 3 atoms, torsion/dihedral angles etc.) You may wish to parse these into a format that has faster lookups
for your application.
Note that the above examples expect that your application has a struct representing the molecule that has
`From<Mol2>`, and `to_mol2(&self)` (etc) methods. The details of these depend on the application. For example:
```rust
impl From<Sdf> for Molecule {
fn from(m: Sdf) -> Self {
// We've implemented `From<AtomGeneric>` and `From<ResidueGeneric>` for our application's `Atom` and
// `Residue`
let atoms = m.atoms.iter().map(|a| a.into()).collect();
let residues = m.residues.iter().map(|r| r.into()).collect();
Self::new(m.ident, atoms, m.chains.clone(), residues, None, None);
}
}
```
A practical example of parsing a molecule from a `mmCIF` as parsed from `bio_files` into an application-specific format:
```rust
fn load() {
let cif_data = mmcif::load("./1htm.cif");
let mol: Molecule = cif_data.try_into().unwrap();
}
impl TryFrom<MmCif> for Molecule {
type Error = io::Error;
fn try_from(m: MmCif) -> Result<Self, Self::Error> {
let mut atoms: Vec<_> = m.atoms.iter().map(|a| a.into()).collect();
let mut residues = Vec::with_capacity(m.residues.len());
for res in &m.residues {
residues.push(Residue::from_generic(res, &atoms)?);
}
let mut chains = Vec::with_capacity(m.chains.len());
for c in &m.chains {
chains.push(Chain::from_generic(c, &atoms, &residues)?);
}
// Now that chains and residues are loaded, update atoms with their back-ref index.
for atom in &mut atoms {
for (i, res) in residues.iter().enumerate() {
if res.atom_sns.contains(&atom.serial_number) {
atom.residue = Some(i);
break;
}
}
for (i, chain) in chains.iter().enumerate() {
if chain.atom_sns.contains(&atom.serial_number) {
atom.chain = Some(i);
break;
}
}
}
let mut result = Self::new(m.ident.clone(), atoms, chains, residues, None, None);
result.experimental_method = m.experimental_method.clone();
result.secondary_structure = m.secondary_structure.clone();
result.bonds_hydrogen = Vec::new();
result.adjacency_list = result.build_adjacency_list();
Ok(result)
}
}
```
Note: The Python version is currently missing support for some formats, and not all fields are exposed.
### References
- [Amber 2025 Reference Manual, section 15](https://ambermd.org/doc12/Amber25.pdf)
Raw data
{
"_id": null,
"home_page": null,
"name": "biology-files",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mol2, sdf, mmcif, amber, biology",
"author": null,
"author_email": "David O'Connor <the_alchemist@fastmail.com>",
"download_url": "https://files.pythonhosted.org/packages/67/96/5e518ea9c753b8d78a4e3d2dc36c0b5743642cfb6fa8d65fc3d0d8068e36/biology_files-0.2.14.tar.gz",
"platform": null,
"description": "# Bio Files: Read and write common biology file formats\n\n[](https://crates.io/crates/bio_files)\n[](https://docs.rs/bio_files)\n[](https://pypi.org/project/biology-files)\n\n\nThis Rust and Python library contains functionality to load and save data in common biology file formats. It operates\non data structures that are specific to each file format; you will need to convert to and from the structures\nused by your application. The API docs, and examples below are sufficient to get started.\n\nNote: Install the pip version with `pip install biology-files` due to a name conflict.\n\n### Supported formats:\n- mmCIF (Protein atom, residue, chain, and related data like secondary structure)\n- Mol2 (Small molecules, e.g. ligands)\n- SDF (Small molecules, e.g. ligands)\n- PDBQT (Small molecules, e.g. ligands. Includes docking-specific fields.)\n- Map (Electron density, e.g. from crystallography, Cryo EM)\n- AB1 (Sequence tracing)\n- DAT (Amber force field data for small molecules)\n- FRCMOD (Amber force field patch data for small molecules)\n- Amber .lib files, e.g. with charge data for amino acids and proteins.\n\n### Planned:\n- MTZ (Exists in Daedalus; needs to be decoupled)\n- DNA (Exists in PlasCAD; needs to be decoupled)\n- CIF structure formats (2fo-fc etc) (Exists in Daedalus; needs to be decoupled)\n\n\nFor Genbank, we recommend [gb-io](https://docs.rs/gb-io/latest/gb_io/). We do not plan to support this format, due to this high quality library.\n\nEach module represents a file format, and most have dedicated structs dedicated to operating on that format.\n\nIt operates using structs with public fields, which you can explore\nusing the [API docs](https://docs.rs/bio_files), or your IDE. These structs generally include these three methods: `new()`,\n`save()` and `load()`. `new()` accepts `&str` for text files, and a `R: Read + Seek` for binary. `save()` and\n`load()` accept `&Path`.\nThe Force Field formats use `load_dat`, `save_frcmod` instead, as they use the same structs for both formats.\n\n## Serial numbers\nSerial numbers for atoms, residues, secondary structure, and chains are generally pulled directly from atom data files\n(mmCIF, Mol2 etc). These lists reference atoms, or residues, stored as `Vec<u32>`, with the `u32` being the serial number.\nIn your application, you may wish to adapt these generic types to custom ones that use index lookups\ninstead of serial numbers. We use SNs here because they're more robust, and match the input files directly;\nadd optimizations downstream, like converting to indices, and/or applying back-references. (e.g. the index of the residue\nan atom's in, in your derived Atom struct).\n\n\n## Example use\n\n\nSmall molecule save and load, Python.\n```python\nfrom biology_files import Sdf\n\nsdf_data = Sdf.load(\"./molecules/DB03496.sdf\")\n\nsdf_data.atoms[0]\n#AtomGeneric { serial_number: 1, posit: Vec3 { x: 2.3974, y: 1.1259, z: 2.5289 }, element: Chlorine, \ntype_in_res: None, force_field_type: None, occupancy: None, partial_charge: None, hetero: true }\n\n>>> sdf_data.atoms[0].posit\n# [2.3974, 1.1259, 2.5289]\n\nsdf_data.save(\"test.sdf\")\n\nmol2_data = sdf_data.to_mol2()\nmol2_data.save(\"test.mol2\")\n```\n\nSmall molecule save and load, Rust.\n```rust\nuse bio_files::{Sdf, Mol2};}\n\n// ...\nlet sdf_data = Sdf::load(\"./molecules/DB03496.sdf\");\n\nsdf_data.atoms[0]; // (as above)\nsdf_data.atoms[0].posit; // (as above, but lin_alg::Vec3))\n\nsdf_data.save(\"test.sdf\");\n\nlet mol2_data: Mol2 = sdf_data.into();\nmol2_data.save(\"test.mol2\");\n\n\n// Loading Force field parameters:\nlet p = Path::new(\"gaff2.dat\")\nlet params = ForceFieldParams::load_dat(p)?;\n```\n\nYou can use similar syntax for mmCIF protein files.\n\n## Amber force fields\n\nReference the [Amber 2025 Reference Manual, section 15](https://ambermd.org/doc12/Amber25.pdf)\nfor details on how we parse its files, and how to use the results. In some cases, we change the format from\nthe raw Amber data. For example, we store angles as radians (vice degrees), and \u03c3 vice R_min for Van der Waals\nparameters. Structs and fields are documented with reference manual references.\n\nThe Amber forcefield parameter format has fields which each contain a `Vec` of a certain type of data. (Bond stretching parameters,\nangle between 3 atoms, torsion/dihedral angles etc.) You may wish to parse these into a format that has faster lookups\nfor your application.\n\n\nNote that the above examples expect that your application has a struct representing the molecule that has\n`From<Mol2>`, and `to_mol2(&self)` (etc) methods. The details of these depend on the application. For example:\n\n\n```rust\nimpl From<Sdf> for Molecule {\n fn from(m: Sdf) -> Self {\n // We've implemented `From<AtomGeneric>` and `From<ResidueGeneric>` for our application's `Atom` and\n // `Residue`\n let atoms = m.atoms.iter().map(|a| a.into()).collect();\n let residues = m.residues.iter().map(|r| r.into()).collect();\n\n Self::new(m.ident, atoms, m.chains.clone(), residues, None, None);\n }\n}\n```\n\nA practical example of parsing a molecule from a `mmCIF` as parsed from `bio_files` into an application-specific format:\n```rust\nfn load() {\n let cif_data = mmcif::load(\"./1htm.cif\");\n let mol: Molecule = cif_data.try_into().unwrap();\n}\n\nimpl TryFrom<MmCif> for Molecule {\n type Error = io::Error;\n\n fn try_from(m: MmCif) -> Result<Self, Self::Error> {\n let mut atoms: Vec<_> = m.atoms.iter().map(|a| a.into()).collect();\n\n let mut residues = Vec::with_capacity(m.residues.len());\n for res in &m.residues {\n residues.push(Residue::from_generic(res, &atoms)?);\n }\n\n let mut chains = Vec::with_capacity(m.chains.len());\n for c in &m.chains {\n chains.push(Chain::from_generic(c, &atoms, &residues)?);\n }\n\n // Now that chains and residues are loaded, update atoms with their back-ref index.\n for atom in &mut atoms {\n for (i, res) in residues.iter().enumerate() {\n if res.atom_sns.contains(&atom.serial_number) {\n atom.residue = Some(i);\n break;\n }\n }\n\n for (i, chain) in chains.iter().enumerate() {\n if chain.atom_sns.contains(&atom.serial_number) {\n atom.chain = Some(i);\n break;\n }\n }\n }\n\n let mut result = Self::new(m.ident.clone(), atoms, chains, residues, None, None);\n\n result.experimental_method = m.experimental_method.clone();\n result.secondary_structure = m.secondary_structure.clone();\n\n result.bonds_hydrogen = Vec::new();\n result.adjacency_list = result.build_adjacency_list();\n\n Ok(result)\n }\n}\n```\n\nNote: The Python version is currently missing support for some formats, and not all fields are exposed.\n\n\n### References\n- [Amber 2025 Reference Manual, section 15](https://ambermd.org/doc12/Amber25.pdf)\n",
"bugtrack_url": null,
"license": null,
"summary": "Save and load common biology file formats",
"version": "0.2.14",
"project_urls": {
"documentation": "https://docs.rs/bio_files",
"homepage": "https://github.com/David-OConnor/bio_files",
"repository": "https://github.com/David-OConnor/bio_files"
},
"split_keywords": [
"mol2",
" sdf",
" mmcif",
" amber",
" biology"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c528a3df01bdf75aaca237db8c125cf2802f92dbd7cff463dd07530673eff84b",
"md5": "4ecb7520d04482ab70ea9ec721f2eef9",
"sha256": "48ab96612459564aef84a96ef0bb966b936960ce72f65adf6f74a2a0ef198bfa"
},
"downloads": -1,
"filename": "biology_files-0.2.14-cp310-abi3-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "4ecb7520d04482ab70ea9ec721f2eef9",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 1067295,
"upload_time": "2025-09-13T17:35:30",
"upload_time_iso_8601": "2025-09-13T17:35:30.931326Z",
"url": "https://files.pythonhosted.org/packages/c5/28/a3df01bdf75aaca237db8c125cf2802f92dbd7cff463dd07530673eff84b/biology_files-0.2.14-cp310-abi3-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "50cfb8cd4caa6954ab1352c36fb0fa69ef11ae348f106011d94a62a836502b8b",
"md5": "c999af200b69355fccc5bd19279c732f",
"sha256": "4b0ce528e53ed69693dfce316a505522b9c4d945ab1bb248b175c370d584c701"
},
"downloads": -1,
"filename": "biology_files-0.2.14-cp310-abi3-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "c999af200b69355fccc5bd19279c732f",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 1005761,
"upload_time": "2025-09-13T17:35:33",
"upload_time_iso_8601": "2025-09-13T17:35:33.037189Z",
"url": "https://files.pythonhosted.org/packages/50/cf/b8cd4caa6954ab1352c36fb0fa69ef11ae348f106011d94a62a836502b8b/biology_files-0.2.14-cp310-abi3-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0d8c8e2ac3a4e7985401b152c59994babfb4b8b1d27741f49608bba1be96f131",
"md5": "0f2b4c28f72092efc9c94f312392cb13",
"sha256": "6f75473d478196ad98021173010167d885c24f5eb2cf734d45b0fc19063e598e"
},
"downloads": -1,
"filename": "biology_files-0.2.14-cp310-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl",
"has_sig": false,
"md5_digest": "0f2b4c28f72092efc9c94f312392cb13",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 2093435,
"upload_time": "2025-09-13T17:35:37",
"upload_time_iso_8601": "2025-09-13T17:35:37.400385Z",
"url": "https://files.pythonhosted.org/packages/0d/8c/8e2ac3a4e7985401b152c59994babfb4b8b1d27741f49608bba1be96f131/biology_files-0.2.14-cp310-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "28f015defdb4559e0bd081a994ce90377f8c79c7181c05c2105f95259d59c762",
"md5": "05bd48bb2ab80413a5af6f14836fd2c5",
"sha256": "8ab17c90b972a1c9592a38a9aa0b17d2c6fb80e2f25670d305b2483711e35852"
},
"downloads": -1,
"filename": "biology_files-0.2.14-cp310-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl",
"has_sig": false,
"md5_digest": "05bd48bb2ab80413a5af6f14836fd2c5",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 1236274,
"upload_time": "2025-09-13T17:35:39",
"upload_time_iso_8601": "2025-09-13T17:35:39.355483Z",
"url": "https://files.pythonhosted.org/packages/28/f0/15defdb4559e0bd081a994ce90377f8c79c7181c05c2105f95259d59c762/biology_files-0.2.14-cp310-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f88a11ea80b81b178a1ba30f4a457fe92c6c477008e279b60747e0bca34cfd3e",
"md5": "6dc69d7b5b37e89b9edde82fc5c1f066",
"sha256": "70adda1cdf29aebbda90075fb8e36260a04f1a8a9a637bd13bfe009986784a91"
},
"downloads": -1,
"filename": "biology_files-0.2.14-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "6dc69d7b5b37e89b9edde82fc5c1f066",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 1190649,
"upload_time": "2025-09-13T17:35:41",
"upload_time_iso_8601": "2025-09-13T17:35:41.303931Z",
"url": "https://files.pythonhosted.org/packages/f8/8a/11ea80b81b178a1ba30f4a457fe92c6c477008e279b60747e0bca34cfd3e/biology_files-0.2.14-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a41c010598549e8c5d69310a704956b1d485241fd44f9ac1ee2666143207d412",
"md5": "977ead6efd0c653f77197cefd0dc9af4",
"sha256": "df94838790b9077c03f4fa759ec1e633b01a55e7fe3165f5fc89958cd575bc74"
},
"downloads": -1,
"filename": "biology_files-0.2.14-cp310-abi3-musllinux_1_2_x86_64.whl",
"has_sig": false,
"md5_digest": "977ead6efd0c653f77197cefd0dc9af4",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 1361248,
"upload_time": "2025-09-13T17:35:43",
"upload_time_iso_8601": "2025-09-13T17:35:43.259457Z",
"url": "https://files.pythonhosted.org/packages/a4/1c/010598549e8c5d69310a704956b1d485241fd44f9ac1ee2666143207d412/biology_files-0.2.14-cp310-abi3-musllinux_1_2_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4dbcfa5ae8efdd4f96feae6052bb2b4961178870de5430adc9f0af1997cece1e",
"md5": "ab192c3e59979a345799759598b4c156",
"sha256": "17366c9daea111513b6193abea42951d77a69bc37d80426aa342ef1f7bc26fc5"
},
"downloads": -1,
"filename": "biology_files-0.2.14-cp310-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "ab192c3e59979a345799759598b4c156",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 1107566,
"upload_time": "2025-09-13T17:35:45",
"upload_time_iso_8601": "2025-09-13T17:35:45.268930Z",
"url": "https://files.pythonhosted.org/packages/4d/bc/fa5ae8efdd4f96feae6052bb2b4961178870de5430adc9f0af1997cece1e/biology_files-0.2.14-cp310-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "67965e518ea9c753b8d78a4e3d2dc36c0b5743642cfb6fa8d65fc3d0d8068e36",
"md5": "dcc9ef1d8fe299d937e1f1f1466980fd",
"sha256": "920d57ca4c9f06de6eae3af7d2daa9f9b2712fcf0865edf547a0ef341500b466"
},
"downloads": -1,
"filename": "biology_files-0.2.14.tar.gz",
"has_sig": false,
"md5_digest": "dcc9ef1d8fe299d937e1f1f1466980fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 71683,
"upload_time": "2025-09-13T17:35:46",
"upload_time_iso_8601": "2025-09-13T17:35:46.743758Z",
"url": "https://files.pythonhosted.org/packages/67/96/5e518ea9c753b8d78a4e3d2dc36c0b5743642cfb6fa8d65fc3d0d8068e36/biology_files-0.2.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 17:35:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "David-OConnor",
"github_project": "bio_files",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "biology-files"
}
