Everyday helpers for reproducible research, collected from a PhD project and generalised for any project:
| Module | What it does | Command |
|---|---|---|
bib |
Verified BibTeX from DOIs (Crossref), title search, an author's works (OpenAlex), hand-off to Zotero | rh bib, rh find-doi, rh author-works, rh zotero-push |
open_access |
Download open-access PDFs for DOIs and check that each file is the right paper | rh oa |
latex2docx |
LaTeX to Word through pandoc, laid out like the PDF (numbering, cross-references, title page, page numbering, tables, contents), or on a publisher's Word template (IEEE) | rh latex2docx |
templates |
A local library of paper templates and citation styles from their official sources (IEEE, IGARSS, Elsevier, CSL), and new papers started from them | rh template |
safeio |
keep(): never overwrite an output; earlier versions are archived |
– |
records |
Data register (sizes, checksums, sources) and a reference of scripts from their docstrings | rh register, rh scripts |
tables |
Results as LaTeX booktabs tables, written from data | – |
spatial_cv |
Spatial block folds, repeated block cross-validation, area of applicability of a model | – |
jobqueue |
Run long jobs one after another, after a condition, with a log (overnight runs) | rh queue |
litreview |
Scopus and Web of Science ingest and de-duplication, rule-based screening, reviewer agreement, PRISMA counts, bibliometrics | – |
research_helpers.carousel turns a slide PDF into square PNG images and a PowerPoint deck with speaker notes, for social media and teaching.
from research_helpers.carousel import pdf_to_images, images_to_pptx
images = pdf_to_images("slides.pdf", "images", pixels=1440)
images_to_pptx(images, "slides.pptx", notes=["Read this aloud."] * len(images))Python 3.9 or later.
# latest version from GitHub
pip install "research-helpers[all] @ git+https://github.com/GeospatialGeeks/research-helpers"
# or a local copy, editable
git clone https://github.com/GeospatialGeeks/research-helpers
cd research-helpers
pip install -e ".[all]"The core (bib, open_access, latex2docx, safeio, records, jobqueue, tables) needs only the standard library.
The extras add what the other modules need: [data] pandas and NumPy; [spatial] NumPy and SciPy; [review] pandas and NumPy;
[all] everything; [dev] pytest.
External tools, where used:
latex2docxneeds pandoc 2.11 or later. If it isn't on your PATH, setRH_PANDOC=/path/to/pandoc.open_accesschecks PDFs withpdftotext(Poppler), or withpypdfif that is installed.- The Zotero hand-off needs a running Zotero desktop app; set
ZOTERO_DATA_DIRif your data folder isn't~/Zotero.
Check the installation with rh --help and python -m pytest -q (offline tests).
# references: verify, write BibTeX, and add them to a Zotero collection
rh bib refs.bib roberts2017=10.1111/ecog.02881 meyer2021=10.1111/2041-210X.13650 --zotero "My project"
rh bib refs.bib meyer2021=10.1111/2041-210X.13650 --expect 'meyer2021=area of applicability' # rejects a DOI that resolves to another paper
rh find-doi "Spatial validation reveals poor predictive performance"
rh author-works "Jane Researcher" --institution "University" --since 2018 --csv works.csv
# open-access full texts
rh oa dois.txt pdfs/
# Word version of a LaTeX manuscript or thesis (A4, binding margin 40 mm, Arial 12 pt, 1.5 spacing)
rh latex2docx thesis/main.tex Thesis.docx --csl harvard.csl --margins 40,25,25,25
# paper templates: fetch the library once, then start papers from it; Word version of an IEEE paper on IEEE's template
rh template fetch
rh template list
rh template new ieee-conference papers/my-conference-paper
rh latex2docx papers/my-conference-paper/main.tex paper.docx --csl ieee.csl --profile ieee
# records of a project
rh register data/ --out records/data_register.csv
rh scripts code/ --out records/pipeline_reference.md
# an overnight queue that starts when another run has finished
rh queue jobs.txt --log night.log --after-file first.log --after-text "queue finished" --keep-awakefrom research_helpers.safeio import keep
from research_helpers.spatial_cv import block_folds, AreaOfApplicability
from research_helpers.litreview import ingest, screen, bibliometrics
df.to_csv(keep("results/metrics.csv"), index=False) # the previous file goes to results/_archive/<time>/
folds = block_folds(x, y, block_size=2000, k=5, seed=0) # spatial cross-validation
rec, dups = ingest.load(scopus=["scopus.csv"], wos=["savedrecs.txt"])
rec = screen.apply(rec, {"pop": r"building|dwelling", "out": r"energy"}, rule=screen.all_of(["pop", "out"]))Each module has a guide in docs/ with its options, how it works, and the methods it follows (with references):
bib, open_access, latex2docx, safeio,
records, tables, spatial_cv, jobqueue,
litreview, templates. The full reference for each function is its docstring (help(research_helpers.bib)).
- Verify, don't trust. DOIs are resolved and titles checked; downloaded PDFs are matched to the paper; data folders are hashed.
- Never overwrite. Outputs are archived before being replaced; raw data are never written by code.
- Document where the code is. Every module and script explains what it reads, does and writes in its docstring, and the records are built from those docstrings.
- Only open services, no personal data sent. Crossref, doi.org, OpenAlex and Semantic Scholar are used without accounts; publisher APIs only with your own key.
If these helpers are useful in published work, please cite the repository:
Ahmad Ammar (2026) research-helpers: everyday helpers for reproducible research. GitHub. https://github.com/GeospatialGeeks/research-helpers
Copyright © Ahmad Ammar. Developed during a PhD at Ulster University, supported by a Vice-Chancellor's Research Scholarship (VCRS). Released under the MIT licence.
MIT (see LICENSE). The methods implemented are credited in each guide; please cite the original papers when you use them.
research_helpers.stack builds a project from LaTeX to PDF and to a website with one command. It adds a thin layer over latexmk, Pandoc, PDF.js and Zensical, and it does not change your source files. A document.toml beside the source names the title, authors, chapters and layouts.
python -m research_helpers.stack layouts # list what can be built
python -m research_helpers.stack pdf examples/demo # one PDF per layout
python -m research_helpers.stack web examples/demo # chapters, one long page, PDF reader
python -m research_helpers.stack check examples/demo # file names and missing files
python -m research_helpers.stack snapshot examples/demo # dated pictures of every output
Moving a paper to IEEE format means asking for the layout: stack pdf . ieee. A required template, such as a thesis class, stays as it is and is built with the own layout. Spacing and colours are set once in stack/tokens.toml, which both the PDF style and the web style read, so a change there reaches every project at the next build.
| IEEE | Two-column Elsevier | Manual | Web page |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
These pictures come from examples/demo, whose text is a placeholder.



