A Python library providing template blueprint schema, data entry workflows, Excel and NeXus conversions, ontology annotation, and REST API access for the eNanoMapper/AMBIT ecosystem — supporting experimental safety data for chemicals, nanomaterials, polymers, microplastics, and UVCB substances.
pynanomapper builds on the pyambit data model and is a required dependency of templates-api, the backend powering Template Designer.
The core of the library. Implements the Template Designer blueprint schema and all data conversion pipelines:
-
blueprint.py— Parses JSON blueprint definitions and generates styled, semantically annotated Excel templates from blueprint JSON. Extracts and structures method metadata (protocol, provenance, endpoints, units, sample preparation), generates nmparser configuration, and handles Template Designer blueprint embedding. -
template_designer.py— SurveyJS definition for Template Designer blueprint creation. -
template_parser.py/tdparser.py— Excel template parsing: reads filled-in Template Designer Excel files, extracts the hidden JSON blueprint from theTemplateDesignersheet, and converts data entries into structured eNanoMapper records. -
excel_to_nexus.py— Excel → NeXus conversion: converts Template Designer Excel files to NeXus (.nxs) format via pyambit. Parses the embedded blueprint, converts to pyambitSubstances/ProtocolApplication, and writes NeXus output using pyambit's nexus_writer. Supports flat and hierarchical NeXus organisation. -
data_entry_survey.py— Survey/data entry support for template-based data collection workflows. -
template_config.py— Configuration for template rendering and validation.
Dictionary-based annotation of experimental endpoints and parameters against ontology terms (ENM ontology, BioPortal). Maps free-text parameter names to controlled vocabulary URIs, supporting semantic enrichment of experimental records.
-
client_ambit.py— Client for the original AMBIT REST API (api.ideaconsult.net/portal): structured access to substances, studies, endpoints, and experimental results using the full eNanoMapper data model. Based on the OpenTox API architecture published in 2011. -
client_solr.py— Client for the Solr search layer that indexes the federated eNanoMapper instances: full-text and faceted search across the consolidated dataset. Complements the AMBIT API for discovery and filtering across large collections of substances and studies.
The modules above are top-level modules under src/pynanomapper/.
The clients/ package contains additional service integrations:
-
h5service.py/h5converter.py— HDF5/NeXus service integration: read and write NeXus files via HSDS (HDF5 Dynamic Data Service). -
service_charisma.py— Integration with the CHARISMA/ramanchada spectral data service (spectra.adma.ai). -
service_import.py— Data import utilities for batch loading into eNanoMapper. -
authservice.py— Authentication handling for eNanoMapper API access. -
datamodel_simple.py— Simplified data model representations for lightweight use cases.
Some service integrations require optional packages or external deployments that are not needed by the core template and conversion workflows.
Unit handling and conversion for experimental measurements.
NeXus image data support for experimental data containing imaging outputs.
pip install pynanomapperSee the notebooks-ambit repository for worked examples covering substance search, study retrieval, template generation, Excel parsing, and NeXus conversion.
API documentation: api.ideaconsult.net/portal
The eNanoMapper deployment at enanomapper.adma.ai hosts experimental safety data compiled across 15+ years and 30+ EU Horizon projects, spanning nanosafety, advanced materials, microplastics, and regulatory toxicology. The dataset exceeds the scope described in Jeliazkova et al., Nature Nanotechnology 2021.
Template Designer provides a web interface for collaborative template blueprint creation, powered by this library via templates-api.
pynanomapper is a dependency of:
- templates-api — Template Designer backend; uses pynanomapper for blueprint schema, Excel generation, NeXus conversion, and API access
Related libraries:
- pyambit — eNanoMapper/AMBIT data model and NeXus writer; used by pynanomapper as the underlying data representation layer
- AOPMapper — mechanistic interpretation via Adverse Outcome Pathways, live at aop.adma.ai
- QUBounds — conformal prediction for safety assessment models
The eNanoMapper/AMBIT platform was published as a distributed REST API in 2011 (doi:10.1186/1758-2946-3-18), originally designed for REACH substance data including multicomponent UVCB substances from ECHA IUCLID dossiers. The data model was subsequently extended to nanomaterials and advanced materials. pynanomapper implements the template and conversion workflows that make this ecosystem accessible for structured experimental data entry and export.
Developed across EU Horizon 2020 and Horizon Europe projects including RiskGONE, Sbd4Nano, CHARISMA, HARMLESS, POLYRISK.
If you use pynanomapper in your research, please cite the relevant work from the eNanoMapper ecosystem:
- eNanoMapper data model and dataset: Jeliazkova N. et al. (2021). The eNanoMapper database for nanomaterial safety information. Nature Nanotechnology. doi:10.1038/s41565-021-00911-6
- AMBIT REST API: Jeliazkova N. & Jeliazkov V. (2011). AMBIT RESTful web services: an implementation of the OpenTox application programming interface. Journal of Cheminformatics, 3, 18. doi:10.1186/1758-2946-3-18
- Template Wizard methodology: Nymark P. et al. (2024). Nature Protocols. doi:10.1038/s41596-024-00993-1
- HTS FAIRification case study using this library: doi:10.1186/s13321-025-01001-8
MIT