Scientific Writing

Overview

Scientific writing is the act of turning experiments and analyses into a manuscript that is rigorous, reproducible, and publishable. This skill covers the end-to-end pipeline that an agent can drive:

1. Structure the manuscript as IMRaD (Introduction, Methods, Results, and Discussion) plus Abstract, References, and Supplementary.
2. Generate LaTeX programmatically with pylatex (useful when the manuscript is generated by an analysis pipeline).
3. Write reproducible documents in Quarto (.qmd) that interleave narrative, code, figures, and cross-references, then render to PDF, Word, and HTML with one command.
4. Sync with Overleaf via Git so co-authors can edit online while the pipeline re-generates sections from data.
5. Draft the abstract to a target journal's word count and structure (e.g., 250 words, unstructured for Nature, structured for BMJ).
6. Write a plain-language summary for public engagement and for journals that require it (e.g., PLOS, eLife).
7. Prepare supplementary materials (extended methods, datasets, figures, tables) and link them to the main text.
8. Submit a preprint to arXiv (physics/CS/math), bioRxiv/medRxiv (biology/medicine), or the Open Science Framework (any discipline).
9. Assign authorship using the CRediT taxonomy and write the conflicts/data-availability statements.

When to use this skill

• You are drafting a new manuscript and need a structure scaffold.
• You want the manuscript to be reproducible end-to-end: from data cleaning to figures to the final PDF, in one Quarto project.
• You need to generate LaTeX programmatically (e.g., auto-build a methods section from a structured protocol).
• You are preparing a preprint submission (arXiv, bioRxiv, OSF).
• You need a plain-language summary alongside a technical abstract.
• You need to write author contributions with the CRediT taxonomy.
• You want to version-control the manuscript on Overleaf via Git.

Do NOT use this skill for grant applications (use grant-writing) or for slides and posters (use scientific-presentations).

Prerequisites

• Python 3.10 or newer.
• A TeX distribution: TeX Live (sudo apt install texlive-full) or MiKTeX (Windows/macOS); tlmgr to manage packages.
• Pandoc 3+ (https://pandoc.org/installing.html).
• Quarto CLI 1.5+ (https://quarto.org/docs/download/).
• Python libraries:

  pip install pylatex requests pyyaml

• Accounts / tokens:
  • Overleaf account with Git access enabled on the project ( paid plan or institutional).
  • OSF personal access token (https://osf.io/settings/tokens).
  • arXiv API token is not required for submission; use the web UI.
  • bioRxiv/medRxiv submission is via the web portal.

Core workflows

1. Generate a LaTeX manuscript programmatically with pylatex

from pylatex import Document, Section, Subsection, Math, Tabular
from pylatex.utils import bold
doc = Document("manuscript", documentclass="article",
              document_options=["11pt", "a4paper"])
with doc.create(Section("Introduction")):
    doc.append("We study the dynamics of ...")
with doc.create(Section("Methods")):
    with doc.create(Subsection("Statistics")):
        doc.append("Effect sizes are reported as ")
        doc.append(Math(data="g = \\frac{\\mu_1 - \\mu_2}{s_p}"))
with doc.create(Section("Results")):
    with doc.create(Tabular("lcc")) as t:
        t.add_row(["Model", "g", "95% CI"])
        t.add_row([bold("M1"), "0.42", "0.18, 0.66"])
doc.generate_pdf("manuscript", clean_tex=False)

2. Reproducible Quarto manuscript skeleton

---
title: "Effect of X on Y in disease model"
author: "Lovelace A., Curie M., Turing A."
date: today
format:
  pdf: { documentclass: article, fontsize: 11pt }
  docx: default
  html: default
bibliography: refs.bib
csl: nature.csl
crossref:
  fig-prefix: Fig.
  tbl-prefix: Table
number-sections: true
---

# Abstract
{{< include abstract.qmd >}}

# Introduction
@smith2024 reported ...

# Methods
## Data
We used the ... (@data2025).

## Statistical analysis
```{python}
import pandas as pd
df = pd.read_csv("data/clean.csv")
print(f"n = {len(df)}")

Results

#| label: fig-main
#| fig-cap: "Main effect of X on Y."
import matplotlib.pyplot as plt
plt.savefig("figures/main.png")

Discussion

Our findings converge with ...

### 3. Sync with Overleaf via Git

```bash
# Overleaf project -> Menu -> Git -> copy URL
git clone https://git.overleaf.com/<id> manuscript
cd manuscript
# pipeline regenerates sections/figures
git add -A && git commit -m "regenerate results from run 2025-04-01"
git push origin master

4. Draft a structured abstract to a word limit

def abstract(words, limits=(250,)):
    n = len(words.split())
    assert n <= limits[0], f"Abstract is {n} words (max {limits[0]})"
    return n
a = ("Background. ... "
     "Methods. ... "
     "Results. ... "
     "Conclusions. ... ")
print("Abstract word count:", abstract(a, (250,)))

5. Submit a preprint to OSF via API

import os, requests, json
hdr = {"Authorization": f"Bearer {os.environ['OSF_TOKEN']}"}
node = requests.post("https://api.osf.io/v2/nodes/",
    headers=hdr, json={"data": {"type":"nodes",
        "attributes": {"title":"Effect of X on Y",
                       "category":"project",
                       "description":"Preprint companion"}}}
    ).json()
nid = node["data"]["id"]
print(f"Project created: https://osf.io/{nid}")

Best practices

• Pick the journal before you write. Target journal determines abstract structure, word limits, figure sizes, reference style, and data-availability requirements.
• Write the methods first, then results, then discussion, then introduction, then abstract — this is the order in which the work is known and avoids the introduction promising things the results do not deliver.
• Use a single source of truth for figures: code that regenerates every figure from raw data, no manual editing in PowerPoint.
• Render all numbers from code, never retype them in prose: store results in results.json and inject via Quarto variables or LaTeX \input{}.
• Write the abstract as one sentence per claim, verifiable against the Results section.
• Plain-language summary should be 100-200 words, no jargon, written for an audience of secondary-school students; have a non-specialist read it before submission.
• For supplementary, store one file per figure/table named supp_fig_01.pdf, supp_table_01.csv — order matches the in-text "Supplementary" reference.
• CRediT taxonomy: assign every author 1+ roles from the 14 official ones (Conceptualization, Methodology, Software, Validation, Formal analysis, Investigation, Resources, Data curation, Writing — original draft, Writing — review & editing, Visualization, Supervision, Project administration, Funding acquisition).
• Pre-register analyses where possible (OSF, AsPredicted); cite the pre-registration in the methods and report deviations.
• Run a word/character counter before submission; many journals desk-reject for being 1 word over the abstract limit.

Common pitfalls

• Methods section written in the past passive without naming the software version (numpy 1.26, scanpy 1.10) and random seed; reviewers cannot reproduce.
• Figures edited in image software so the SVG/PDF in the repo no longer matches the PNG in the manuscript.
• Abstract that introduces claims not backed by Results, or vice versa.
• In-text citations not regenerated after BibTeX updates — use the latest .bbl/refs.bib and recompile, do not hand-edit.
• LaTeX cross-references \ref{} left broken because the document was only compiled once; run pdflatex twice (or latexmk).
• Word limit exceeded because the abstract was drafted at the end without the count.
• Supplementary materials not uploaded because the journal's portal rejected the file format; check .pdf/.csv/.mp4 requirements.
• Author list missing a contributor or including a "gift" author; CRediT and the ICMJE definition of authorship are the rules.
• Preprint and journal versions diverging because the preprint was never updated to v2 after revision — submit the v2 and link the DOI.

Worked example

A reproducible Quarto manuscript from data to PDF, with a structured abstract, a generated figure, and CRediT statement.

# build_results.py — runs the analysis and writes results.json
import json, pandas as pd
df = pd.read_csv("data/clean.csv")
g = (df[df.arm=="t"].y.mean() - df[df.arm=="c"].y.mean()) / df.y.std(ddof=1)
n = len(df)
json.dump({"g": float(g), "n": int(n)},
          open("results.json", "w"), indent=2)

---
title: "Effect of X on Y in disease model"
author: "Lovelace A., Curie M., Turing A."
date: today
format: { pdf: { documentclass: article } }
bibliography: refs.bib
csl: nature.csl
---

# Abstract
Background. ... Methods. ... Results (n = {{n}}, g = {{g}}). ...
Conclusions. ...

```{python}
#| results: asis
import json
r = json.load(open("results.json"))
print(f"<!-- n={r['n']}, g={r['g']:.2f} -->")

Methods

We analyzed data/clean.csv with pandas 2.2.

Results

#| label: fig-main
#| fig-cap: "Distribution of Y by arm."
import matplotlib.pyplot as plt, pandas as pd
df = pd.read_csv("data/clean.csv")
df.boxplot(column="y", by="arm"); plt.suptitle("")
plt.savefig("figures/main.png", dpi=300)

The pooled effect size was g = {{g}} (n = {{n}}).

Author contributions (CRediT)

A.L.: Conceptualization, Methodology, Writing — original draft. M.C.: Investigation, Writing — review & editing. A.T.: Software, Formal analysis, Visualization.

Render with `quarto render manuscript.qmd --to pdf` and upload to OSF
and bioRxiv. Tag the repository `v1.0-preprint`.

## Tools & libraries

| Tool | Purpose | Install |
|---|---|---|
| pylatex | Generate LaTeX documents from Python | `pip install pylatex` |
| Quarto | Reproducible manuscripts (qmd) to PDF/Word/HTML | https://quarto.org |
| Pandoc | Universal document converter | https://pandoc.org |
| latexmk | Automated LaTeX build loop | `apt install latexmk` |
| Overleaf (Git) | Online co-authoring via Git | paid Overleaf plan |
| OSF API | Preprint and project submission | `pip install requests` |
| arXiv | Physics/CS/math preprints | https://arxiv.org |
| bioRxiv / medRxiv | Biology/medicine preprints | https://www.biorxiv.org |
| CSL styles | Citation rendering for 10k+ journals | https://www.zotero.org/styles |
| CRediT taxonomy | Contributor Roles | https://credit.niso.org |
| languageTool | Grammar/style checks before submission | `pip install language_tool_python` |
| aspell / hunspell | Spell-check .tex/.md before submission | `apt install aspell hunspell` |

## References

- ICMJE recommendations (authorship, conflicts, manuscript prep):
  https://www.icmje.org/recommendations/
- CRediT contributor roles taxonomy: https://credit.niso.org/
- Quarto documentation: https://quarto.org/docs/
- pylatex documentation: https://jeltef.github.io/PyLaTeX/
- Overleaf documentation: https://www.overleaf.com/learn
- arXiv submission help: https://arxiv.org/help/submit
- bioRxiv submission guide: https://www.biorxiv.org/about-biorxiv
- OSF API documentation: https://developers.osf.io/

## Ethics & safety

- **Authorship honesty.** All listed authors must meet the ICMJE
  definition (substantial contributions, drafting/approving, accountable)
  plus CRediT roles. No ghost, gift, or honorary authors.
- **Plagiarism.** Self-plagiarism still counts; do not paste methods
  text from your prior papers without attribution. Use Turnitin or
  iThenticate before submission.
- **Citation integrity.** Cite primary sources, not secondary; verify
  every DOI; never cite a paper you have not read.
- **Data availability.** State where the data and code live (Zenodo,
  OSF, GitHub, figshare); use FAIR principles (findable, accessible,
  interoperable, reusable).
- **Conflicts of interest.** Disclose financial and non-financial COIs
  for every author in the manuscript.
- **Preprint policy.** Disclose the preprint DOI in the journal
  submission letter; most journals allow prior preprints.
- **Human/animal ethics.** State the IRB/IACUC approval number and
  informed-consent procedures; never publish identifying data.
- **Image integrity.** No cropping, contrast manipulation, or
  splicing that misleads; show original gels/images as supplementary.
- **AI use disclosure.** If generative AI was used for drafting, editing,
  or analysis, disclose per journal policy; AI cannot be an author.