Python package for the SYNERGY+ and SYNERGY datasets
Python package for the SYNERGY and SYNERGY+ datasets — collections of systematically labelled records for systematic review research.
Installation
Requires Python 3.10 or later.
pip install synergy-dataset
Quick Start
synergy get
This downloads and exports the SYNERGY+ dataset as CSV files.
For the full set of CLI options and Python API, see the technical reference below. For an introduction to the SYNERGY project and example notebooks (including a Python getting-started notebook), see the main repository: asreview/synergy-dataset. Jupyter notebooks can be found in its examples folder.
Prefer working with the dataset in Python? Jump to the Python API.
Dataset variants
| Variable | Value | Dataset |
|---|---|---|
SYNERGY_SET |
synergy_plus (default) |
SYNERGY+ |
SYNERGY_SET |
synergy |
Original SYNERGY |
Set SYNERGY_SET=synergy in your environment to use the original SYNERGY dataset.
Command-line interface
synergy list — list all datasets
synergy list
| Flag | Default | Description |
|---|---|---|
--tablefmt FORMAT |
simple |
Table format (any tabulate format) |
--n-topics N |
3 |
Number of topics to show per dataset (-1 for all) |
synergy show DATASET — show dataset details
synergy show Appenzeller-Herzog_2019
synergy get — export datasets to CSV
Exports one CSV per dataset to the output folder, plus a review_metadata.csv that combines key fields from each dataset's OpenAlex work object the studies' eligiblity criteria.
synergy get
For SYNERGY+, only open-access works with a valid abstract (≥ 20 words or ≥ 100 characters) are exported. Datasets with fewer than 5 included records are skipped.
| Flag | Default | Description |
|---|---|---|
-o, --output PATH |
synergy_dataset |
Output folder |
-v, --vars VARS |
title + abstract | Comma-separated list of extra fields, or extended for all OpenAlex fields |
-d, --dataset NAME [NAME ...] |
all datasets | One or more dataset names to export |
-l, --ignore-legal |
prompt | Skip the abstract plaintext legal prompt |
Examples
Export all datasets with default fields:
synergy get -o ./output
Export with extended OpenAlex fields:
synergy get -v extended
Export a single dataset with specific fields:
synergy get -d Appenzeller-Herzog_2019 -v cited_by_count,publication_year
Skip the abstract plaintext legal prompt (e.g. for non-interactive/CI use):
synergy get --ignore-legal
Available --vars fields (on top of the always-included openalex_id, doi, lens_id, title, abstract, label_included):
publication_year publication_date type language
language_fasttext cited_by_count referenced_works_count fwci
is_retracted is_paratext is_oa oa_status
journal_name author_names authorships primary_topic_name
primary_topic_field primary_topic_domain topics keywords
mesh sustainable_development_goals indexed_in
referenced_works related_works counts_by_year
Output files
Each run of synergy get produces:
{dataset_name}.csv— one file per dataset, with one row per work (filtered by the active settings).review_metadata.csv— one row per dataset (≥ 5 inclusions), combining:key— dataset identifier (e.g.Abgaz_2023)split—trainortest(SYNERGY+ only)data_doi— DOI of the dataset depositn_records— number of works in the exportn_records_included— number of included workseligibility_criteria— the screening criteria text frommetadata.json(overwritten by reviews.csv'sEligibility Criteria, if available)- All fields selected via
--varsapplied to the review publication itself (the OpenAlex work for the systematic review paper) - If
reviews.csv(review-level metadata: screening process, search sizes, review type, etc.) is available at the top level of the dataset repository, all of its columns are merged in, converted to snake_case (e.g.Paper link→paper_link,Ti-ab screeners→ti_ab_screeners,Paper inclusion %→paper_inclusion_pct). Ifreviews.csvcan't be found or downloaded,synergy getprints a warning and continues without these extra columns.
synergy attribute — attribution for datasets
synergy attribute
synergy attribute --format markdown
Python API
Iterating over datasets
from synergy_dataset import iter_datasets
for dataset in iter_datasets():
print(dataset.name)
Filter by train/test split (SYNERGY+ only):
for dataset in iter_datasets(split="train"):
...
for dataset in iter_datasets(split="test"):
...
Working with a single dataset
from synergy_dataset import Dataset
d = Dataset("Appenzeller-Herzog_2019")
Export to pandas DataFrame
This functionality requires pandas to be installed. Install with pandas with pip install pandas.
df = d.to_frame() # title + abstract
df = d.to_frame(vars="extended") # all OpenAlex fields
df = d.to_frame(vars=["cited_by_count"]) # specific fields
For SYNERGY+, only open-access works with a valid abstract (≥ 20 words or ≥ 100 characters) are included.
Export to dict
records = d.to_dict() # openalex_id → record dict
records = d.to_dict(vars="extended")
Iterate over works
for work, label in d.iter():
print(work["title"], label)
Dataset metadata and labels
print(d.metadata) # dict with dataset/publication/collection info
print(d.labels) # openalex_id → {doi, pmid, lens_id, label_included, ...}
print(d.cite) # citation string for this dataset
print(d.summary()) # quick statistics
Environment variables
| Variable | Default | Description |
|---|---|---|
SYNERGY_SET |
synergy_plus |
Dataset variant: synergy_plus or synergy |
SYNERGY_VERSION |
3.0 |
Dataset version to download |
SYNERGY_PATH |
(auto) | Custom path to dataset; development for local dev |
License
Contact
See https://github.com/asreview/synergy-dataset for contact details.
Metadata
Release files for synergy-dataset 2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| synergy_dataset-2.2.tar.gz | 80.6 kB | With provenance | Details for synergy_dataset-2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| synergy_dataset-2.2-py3-none-any.whl | Python 3 | none | any | Details for synergy_dataset-2.2-py3-none-any.whl |
Total release size: 102.9 kB
Release files / synergy_dataset-2.2.tar.gz
| Download URL | synergy_dataset-2.2.tar.gz |
|---|---|
| Size | 80.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6eda383bd6497a23769e9d7f3fc949efcf4a07c9f506c5488739a13dcc07a7a8
|
|
BLAKE2b-256 checksum How to use checksums |
6cc7edad9112d0d3df4ab70c92b0c64ee0ea0bbbfe0720badb12a425159da7c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logRelease files / synergy_dataset-2.2-py3-none-any.whl
| Download URL | synergy_dataset-2.2-py3-none-any.whl |
|---|---|
| Size | 22.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fabe7b9dd3c93bb49fee0f80495513762fb184659a1858d3cf646559e26bd576
|
|
BLAKE2b-256 checksum How to use checksums |
941ace647985fe46c1be2ee759d38b3b202aa18c604ce442de899d83da57f39c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logSecurity for synergy-dataset 2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for synergy_dataset-2.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.