JATS: Convert JATS XML articles to Markdown with peer review extraction
Project description
jats - JATS XML Parser
A Python CLI tool for converting JATS (Journal Article Tag Suite) XML files to Markdown format, with support for extracting peer review comments and author responses.
Overview
jats parses JATS XML files from scientific publishers (bioRxiv, eLife, etc.) and converts them to clean, readable Markdown. It's particularly useful for working with preprint manuscripts and their associated peer review materials.
Key Features
- Convert JATS XML articles to Markdown
- Extract peer review comments and author responses from multi-article XML files
- Support for bioRxiv manifest files (optional metadata)
- Organize reviews and responses by revision round
- Simple CLI interface with stdout or file output
Installation
Prerequisites
- Python >=3.10
Install with uv (recommended)
cd jats
uv pip install -e .
Install with pip
cd jats
pip install -e .
Usage
Basic Conversion
Convert a JATS XML file to Markdown:
# Output to stdout
jats convert article.xml
# Output to file
jats convert article.xml -o article.md
# With bioRxiv manifest file (optional)
jats convert article.xml -m manifest.xml -o article.md
Extract Peer Reviews
Extract peer review comments and author responses from JATS XML files that include sub-articles (common in eLife and some bioRxiv articles):
# Extract reviews and responses to separate files
jats convert article.xml -o article.md -r output_base
# Creates:
# - output_base_reviews.md (all review comments, organized by round)
# - output_base_responses.md (all author responses, organized by round)
The -r flag extracts sub-articles with the following JATS article types:
- Review comments: decision-letter, referee-report, editor-report, reviewer-report
- Author responses: author-comment, reply
Reviews and responses are automatically organized by revision round using JATS4R peer-review-revision-round metadata (defaults to round 1 if not specified).
Examples
Convert bioRxiv Preprint
jats convert 2023.01.01.12345.xml -o paper.md
Convert eLife Article with Peer Reviews
# Convert main article and extract reviews
jats convert elife-12345-v1.xml -o paper.md -r elife-12345-v1
# Output files:
# - paper.md (main article)
# - elife-12345-v1_reviews.md (peer review comments)
# - elife-12345-v1_responses.md (author responses)
bioRxiv with Manifest
# manifest.xml provides additional metadata
jats convert article.xml -m manifest.xml -o article.md
Input File Format
jats expects JATS XML files following the JATS (Journal Article Tag Suite) standard. This format is used by:
- bioRxiv and medRxiv preprint servers
- eLife journal
- PubMed Central (PMC)
- Many other scientific publishers
JATS XML Structure
A typical JATS XML file contains:
<front>: Article metadata (title, authors, abstract)<body>: Main article content organized in sections<back>: References, acknowledgments, etc.<sub-article>: Optional peer review materials (eLife, some bioRxiv)
Manifest Files (bioRxiv)
bioRxiv articles may include an optional manifest.xml file that provides:
- Collection/category information
- Version history
- Links to published versions
- Peer review URLs
Output Format
jats converts JATS XML to clean, readable Markdown with:
- Article title as H1 heading
- Authors with affiliations
- Abstract
- Body sections with appropriate heading levels
- Inline figures with captions
- References (when available)
Peer Review Output
When using -r, peer review materials are extracted to separate Markdown files:
Reviews file (*_reviews.md):
# Revision Round 1
## Reviewer 1
[Review content...]
---
## Reviewer 2
[Review content...]
Responses file (*_responses.md):
# Revision Round 1
## Author Response
[Response content...]
Development
Running Tests
# Install development dependencies
uv pip install -e ".[dev]"
# Run tests
pytest
Project Structure
jats/
├── jats/
│ ├── __init__.py
│ ├── main.py # CLI entry point
│ ├── parser.py # JATS XML parsing
│ ├── converter.py # Markdown conversion
│ └── models.py # Data models
├── tests/
│ ├── test_*.py # Test files
│ └── *.xml # Test fixtures
├── pyproject.toml # Package configuration
└── README.md
See DEVELOPMENT.md for detailed development documentation and code style guide.
Known Limitations and Future Work
Source Data Files
Currently, <supplementary-material> elements (such as source data files for figures) are excluded from the markdown output. These typically appear as:
<supplementary-material id="fig6sdata1">
<label>Figure 6—source data 1.</label>
<caption>
<title>PDF files containing original western blots...</title>
</caption>
<media mimetype="application" mime-subtype="zip" xlink:href="..."/>
</supplementary-material>
Future Enhancement: Add support for extracting and linking to source data files, including:
- Source data download links
- Separate source data manifest
- Integration with figure references
JATS Resources
- JATS Documentation
- JATS4R (JATS for Reuse) - Recommendations for peer review tagging
- bioRxiv JATS XML
- eLife JATS XML
License
MIT
Support
For issues or questions, please open an issue on GitHub.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file jats-0.2.2.tar.gz.
File metadata
- Download URL: jats-0.2.2.tar.gz
- Upload date:
- Size: 32.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.5.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b9938285861a47e46d2aa49fc5f1b838be5076109fba0565f386c9eb55c618aa
|
|
| MD5 |
c0a02f36d68c42cb8e84aef0d50b52bb
|
|
| BLAKE2b-256 |
b205d2386cd01e551d206742fe09da3ef63c54f254273ec7e9c091780b5e1080
|
File details
Details for the file jats-0.2.2-py3-none-any.whl.
File metadata
- Download URL: jats-0.2.2-py3-none-any.whl
- Upload date:
- Size: 30.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.5.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f38830bf480e56c0b2719638b240293d06cb23991747500267c7c7ee76161b28
|
|
| MD5 |
c39c802006c60b46c2f872d66dc8681f
|
|
| BLAKE2b-256 |
53fd7000562e10db9075b938b703f4a6e82166f3496cec8ccb7756e44a5d64ad
|
