chore: JOSS paper by williambdean · Pull Request #2163 · pymc-labs/pymc-marketing

williambdean · 2026-01-04T20:16:43Z

Description

Add a JOSS paper. View the latest here: https://github.com/pymc-labs/pymc-marketing/blob/joss-paper/paper/paper.pdf

Next steps:

Get everyones JOSS ids
review here ...
review by the JOSS team
🎉

Related Issue

Closes Publish paper about this package in JOSS #30
Related to #

Checklist

Checked that the pre-commit linting/style checks pass. Feel free to comment pre-commit.ci autofix to auto-fix.
Included tests that prove the fix is effective or that the new feature works
Added necessary documentation (docstrings and/or example notebooks) using numpydoc format.
If you are a pro: each commit corresponds to a relevant logical change

📚 Documentation preview 📚: https://pymc-marketing--2163.org.readthedocs.build/en/2163/

cursor · 2026-01-04T20:16:48Z

PR Summary

Low Risk
Documentation-only change adding manuscript sources; no runtime code paths or data handling are affected.

Overview
Adds a JOSS submission under paper/, including a new paper.md manuscript (metadata, summary, feature overview, funding/AI disclosure, etc.) and a paper.bib bibliography with the referenced citations.

No library code, APIs, or runtime behavior changes are included—this PR is purely publication/documentation content.

^{Written by Cursor Bugbot for commit daec1e5. This will update automatically on new commits. Configure here.}

Copilot

Pull request overview

This PR adds a JOSS (Journal of Open Source Software) paper for PyMC-Marketing, which is a preparatory step before formal submission to JOSS for peer review and publication.

Introduces a comprehensive academic paper describing PyMC-Marketing's features and capabilities
Includes bibliography with citations to relevant academic and technical sources
Provides example code demonstrating the library's key functionality

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
paper/paper.md	JOSS paper manuscript containing summary, statement of need, installation instructions, key features, example usage, and community guidelines
paper/paper.bib	Bibliography file with BibTeX entries for all cited references in the paper

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

paper/paper.md

Copilot · 2026-01-04T20:32:33Z

paper/paper.bib

+}
+
+@article{bass1969new,
+  title={A new product growth for model consumer durables},


The title in the bibliography entry should be "A new product growth model for consumer durables" not "A new product growth for model consumer durables". The words "for" and "model" are swapped.

Suggested change

title={A new product growth for model consumer durables},

title={A new product growth model for consumer durables},

Copilot · 2026-01-04T20:32:34Z

paper/paper.bib

+}
+
+@article{arviz2019,
+  title={ArviZ a unified library for exploratory analysis of Bayesian models in Python},


The ArviZ citation is missing a colon in the title. It should be "ArviZ: a unified library for exploratory analysis of Bayesian models in Python" (with a colon after "ArviZ").

Suggested change

title={ArviZ a unified library for exploratory analysis of Bayesian models in Python},

title={ArviZ: a unified library for exploratory analysis of Bayesian models in Python},

Copilot · 2026-01-04T20:32:34Z

paper/paper.md

+# Optimize budget allocation
+result = mmm.optimize_budget(
+    budget=1000,
+    time_periods=52,


The parameter name in the optimize_budget method call is incorrect. It should be num_periods not time_periods. The correct method signature uses num_periods as the parameter name.

Suggested change

time_periods=52,

num_periods=52,

ColtAllen

In addition to the author section, should we also add usage examples for the other modules in the library?

paper/paper.md

williambdean · 2026-01-05T07:55:21Z

In addition to the author section, should we also add usage examples for the other modules in the library?

I'm actually leaning toward removing all examples. The guidelines I've seen appear to be
1K word count which we are already over.

juanitorduz

This looks great! I left a first round of comments (shall we also push the pdf to the branch?)

paper/paper.md

juanitorduz · 2026-01-05T08:12:35Z

paper/paper.md

+
+Marketing organizations struggle with attribution across multiple touchpoints and delayed conversion effects. Existing solutions suffer from: (1) black-box proprietary models with limited customization; (2) oversimplified approaches failing to capture marketing dynamics; and (3) lack of uncertainty quantification for high-stakes decisions.
+
+PyMC-Marketing addresses these gaps by operationalizing advanced Bayesian methods—hierarchical modeling, experimental calibration, and uncertainty quantification—within a user-friendly, scikit-learn compatible API. Unlike point-estimate approaches in Robyn or commercial tools, all outputs include credible intervals enabling decision-makers to assess risk explicitly.


I think we also bridge the gap between research and applications. Examples:

time varying coefficients with moders GP approacimations in a way that works for marketing applications

mmm experimental calibration with additional likelihood <- THIS IS NEW in the literature

paper/paper.md

juanitorduz · 2026-01-05T08:19:17Z

paper/paper.md

+
+# Dependencies
+
+Core dependencies include PyMC (≥5.0), NumPy, Pandas, ArviZ [@arviz2019], and scikit-learn. Optional dependencies enable GPU acceleration (JAX), advanced samplers (NumPyro, Nutpie), and production deployment (MLflow [@zaharia2018mlflow], Docker).


Add references for NumPyro and Nutpie

@article{bingham2019pyro, author = {Eli Bingham and Jonathan P. Chen and Martin Jankowiak and Fritz Obermeyer and Neeraj Pradhan and Theofanis Karaletsos and Rohit Singh and Paul A. Szerlip and Paul Horsfall and Noah D. Goodman}, title = {Pyro: Deep Universal Probabilistic Programming}, journal = {J. Mach. Learn. Res.}, volume = {20}, pages = {28:1--28:6}, year = {2019}, url = {http://jmlr.org/papers/v20/18-403.html} }

paper/paper.md

juanitorduz

missing ohter author ;)

williambdean · 2026-01-05T08:52:07Z

I've pushed up a version of the PDF. Please use:

docker run --rm \
    --volume $PWD/paper:/data \
    --user $(id -u):$(id -g) \
    --env JOURNAL=joss \
    openjournals/inara

to generate the draft. View it here: https://github.com/pymc-labs/pymc-marketing/blob/joss-paper/paper/paper.pdf

OriolAbril

not sure what is the timeline but it would also be nice to update the citation to the new arviz paper if possible, but also not a reason to delay the paper. It is key for #2098 but not used anywhere on main yet

OriolAbril · 2026-01-05T14:06:35Z

paper/paper.bib

+@article{salvatier2016probabilistic,
+  title={Probabilistic programming in Python using PyMC3},
+  author={Salvatier, John and Wiecki, Thomas V and Fonnesbeck, Christopher},
+  journal={PeerJ Computer Science},
+  volume={2},
+  pages={e55},
+  year={2016},
+  publisher={PeerJ Inc.},
+  doi={10.7717/peerj-cs.55}
+}


this should use the new PyMC paper. The pymc readme has the bibtex citation ready to copy-paste: https://github.com/pymc-devs/pymc?tab=readme-ov-file#citing-pymc

paper/paper.md

twiecki · 2026-01-05T19:35:18Z

paper/paper.md

+
+# Summary
+
+PyMC-Marketing is a comprehensive Python library implementing Bayesian marketing analytics, built on PyMC [@salvatier2016probabilistic]. Commercial marketing analytics tools typically provide limited transparency into their models, while open-source alternatives like Meta's Robyn and Google's Meridian focus primarily on media mix modeling [@facebook2022robyn; @google2023meridian]. PyMC-Marketing provides a unified framework spanning multiple marketing domains, including: Media Mix Modeling, Customer Lifetime Value analysis, Bass Diffusion Models, and Customer Choice Models. All outputs include full posterior distributions rather than point estimates, enabling explicit risk assessment in business decisions.


should also cite the pymc 2025 paper.
and I wonder if there's something we should say/include of the benchmarks so that we can say how it compares performance-wise?

That performance comparison was just a blog post, right? Should I link to that?

Co-authored-by: Thomas Wiecki <thomas.wiecki@gmail.com>

paper/paper.md

ricardoV94 · 2026-01-06T21:28:55Z

Any non-labs contributors that have done large enough contributions to deserve being authors?

juanitorduz · 2026-01-06T21:32:24Z

Any non-labs contributors that have done large enough contributions to deserve being authors?

This reminds me that we should add @lucianopaz 🙈

ricardoV94 · 2026-01-06T22:10:41Z

May want to decide on a cutoff from https://github.com/pymc-labs/pymc-marketing/graphs/contributors (not that people not there shouldn't be included, but people there with meaningful contributions should?).

Seeing @larryshamalama for instance who was involved in early work on the CLV module

ColtAllen · 2026-01-06T22:23:18Z

Any non-labs contributors that have done large enough contributions to deserve being authors?

@PabloRoque added ADVI support, the MG/BND model, and covariate support for beta distributions. His research on the latter also uncovered a bug in how the BYTDPlus R library handles covariates.

Co-authored-by: Ricardo Vieira <28983449+ricardoV94@users.noreply.github.com>

… joss-paper

NathanielF · 2026-01-07T16:17:15Z

paper/paper.md

+    orcid: "0009-0000-6015-101X"
+    affiliation: 1
+  - name: Nathaniel Forde
+    orcid: PENDING-NEED-ORCID


Adding my orcid id: 0009-0005-7585-0987

@williambdean

lucianopaz

Thanks @juanitorduz for suggesting to add me as coauthor. I added my info.

paper/paper.md

OriolAbril · 2026-01-08T13:37:56Z

Do you have a rough ETA?

Ideally at some point next week, at most the other one.

juanitorduz · 2026-01-08T14:08:18Z

Do you have a rough ETA?

Ideally at some point next week, at most the other one.

Sure! We can wait, of course! 💪

PabloRoque · 2026-01-13T11:47:20Z

Any non-labs contributors that have done large enough contributions to deserve being authors?

@PabloRoque added ADVI support, the MG/BND model, and covariate support for beta distributions. His research on the latter also uncovered a bug in how the BYTDPlus R library handles covariates.

Hey, just seeing this after the long Xmas break.
I would be glad to be acknowledged as contributor. Should I add my ORCID?

Co-authored-by: Luciano Paz <luciano.paz.neuro@gmail.com>

juanitorduz · 2026-01-13T11:48:39Z

yes @PabloRoque ! That would be great!

PabloRoque

Added my ORCID

paper/paper.md

juanitorduz

adding @NathanielF

paper/paper.md

juanitorduz · 2026-01-14T12:50:23Z

paper/paper.md

+    orcid: 0009-0006-8055-6560
+    affiliation: 1
+  - name: Carlos Trujillo
+    orcid: PENDING-NEED-ORCID


@cetagostini do you have one?

@cetagostini friendly reminder :)

juanitorduz

I think we are just missing Carlos Id and then update the ArviZ reference right? @williambdean

williambdean · 2026-01-14T13:27:28Z

I think we are just missing Carlos Id and then update the ArviZ reference right? @williambdean

Yup. Then I will begin the submittal process. That seems to be long

OriolAbril · 2026-01-19T10:48:51Z

The ArviZ paper is already in pre-review: openjournals/joss-reviews#9786

juanitorduz

@williambdean did we update the arviz reference? anything else missing :) ?

juanitorduz · 2026-02-04T16:53:55Z

paper/paper.md

+    orcid: 0009-0006-8055-6560
+    affiliation: 1
+  - name: Carlos Trujillo
+    orcid: PENDING-NEED-ORCID


@cetagostini friendly reminder :)

drbenvincent · 2026-02-06T08:22:39Z

Based on this discussion from @ErikRingen, it made me realise I should update my affiliation to my company rather than Labs. Got to be careful on the tax side of things. Could be relevant for others with companies too?

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

paper/paper.md

initial paper

c9e4f03

github-actions bot added the docs Improvements or additions to documentation label Jan 4, 2026

williambdean requested a review from Copilot January 4, 2026 20:29

Copilot started reviewing on behalf of williambdean January 4, 2026 20:30 View session

williambdean requested review from ColtAllen, cetagostini, drbenvincent, juanitorduz and ricardoV94 January 4, 2026 20:30

Copilot AI reviewed Jan 4, 2026

View reviewed changes

ColtAllen requested changes Jan 5, 2026

View reviewed changes

paper/paper.md Show resolved Hide resolved

williambdean added 2 commits January 5, 2026 02:57

placeholder for colt

4488536

remove the examples

fbe38ac

juanitorduz requested changes Jan 5, 2026

View reviewed changes

juanitorduz reviewed Jan 5, 2026

View reviewed changes

paper/paper.md Show resolved Hide resolved

juanitorduz reviewed Jan 5, 2026

View reviewed changes

williambdean added 3 commits January 5, 2026 03:49

update bib

4651550

feedback from Juan

f7a56a5

add pdf render

c634f77

williambdean added 2 commits January 5, 2026 04:16

push up edits

ab92faf

update paper

460fc9a

OriolAbril reviewed Jan 5, 2026

View reviewed changes

twiecki reviewed Jan 5, 2026

View reviewed changes

paper/paper.md Outdated Show resolved Hide resolved

twiecki reviewed Jan 5, 2026

View reviewed changes

paper/paper.md Outdated Show resolved Hide resolved

twiecki reviewed Jan 5, 2026

View reviewed changes

add Thomas ORDID

8230ca5

Co-authored-by: Thomas Wiecki <thomas.wiecki@gmail.com>

drbenvincent requested changes Jan 6, 2026

View reviewed changes

paper/paper.md Outdated Show resolved Hide resolved

williambdean and others added 3 commits January 7, 2026 03:19

add ricardo

024f1a4

Co-authored-by: Ricardo Vieira <28983449+ricardoV94@users.noreply.github.com>

updates with feedback

1bf00bd

Merge branch 'joss-paper' of github.com:pymc-labs/pymc-marketing into…

8b180f5

… joss-paper

NathanielF reviewed Jan 7, 2026

View reviewed changes

lucianopaz reviewed Jan 7, 2026

View reviewed changes

paper/paper.md Show resolved Hide resolved

Update paper/paper.md

c8be0d7

Co-authored-by: Luciano Paz <luciano.paz.neuro@gmail.com>

Merge branch 'main' into joss-paper

2a90621

PabloRoque approved these changes Jan 13, 2026

View reviewed changes

paper/paper.md Show resolved Hide resolved

Update paper/paper.md

e2f7cfc

juanitorduz reviewed Jan 14, 2026

View reviewed changes

paper/paper.md Outdated Show resolved Hide resolved

Update paper/paper.md

a23afd7

juanitorduz reviewed Jan 14, 2026

View reviewed changes

juanitorduz reviewed Feb 4, 2026

View reviewed changes

update my affiliation to my company

da027e9

drbenvincent and others added 2 commits February 6, 2026 08:49

InferenceWorks -> InferenceWorks Ltd

fb0717f

Add Luciano company affiliation

81c2d4a

cursor bot reviewed Feb 6, 2026

View reviewed changes

paper/paper.md Outdated Show resolved Hide resolved

Carlos orcid

daec1e5

	title={A new product growth for model consumer durables},
	title={A new product growth model for consumer durables},

	title={ArviZ a unified library for exploratory analysis of Bayesian models in Python},
	title={ArviZ: a unified library for exploratory analysis of Bayesian models in Python},


		Marketing organizations struggle with attribution across multiple touchpoints and delayed conversion effects. Existing solutions suffer from: (1) black-box proprietary models with limited customization; (2) oversimplified approaches failing to capture marketing dynamics; and (3) lack of uncertainty quantification for high-stakes decisions.

		PyMC-Marketing addresses these gaps by operationalizing advanced Bayesian methods—hierarchical modeling, experimental calibration, and uncertainty quantification—within a user-friendly, scikit-learn compatible API. Unlike point-estimate approaches in Robyn or commercial tools, all outputs include credible intervals enabling decision-makers to assess risk explicitly.


		# Dependencies

		Core dependencies include PyMC (≥5.0), NumPy, Pandas, ArviZ [@arviz2019], and scikit-learn. Optional dependencies enable GPU acceleration (JAX), advanced samplers (NumPyro, Nutpie), and production deployment (MLflow [@zaharia2018mlflow], Docker).


		# Summary

		PyMC-Marketing is a comprehensive Python library implementing Bayesian marketing analytics, built on PyMC [@salvatier2016probabilistic]. Commercial marketing analytics tools typically provide limited transparency into their models, while open-source alternatives like Meta's Robyn and Google's Meridian focus primarily on media mix modeling [@facebook2022robyn; @google2023meridian]. PyMC-Marketing provides a unified framework spanning multiple marketing domains, including: Media Mix Modeling, Customer Lifetime Value analysis, Bass Diffusion Models, and Customer Choice Models. All outputs include full posterior distributions rather than point estimates, enabling explicit risk assessment in business decisions.

Conversation

williambdean commented Jan 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Checklist

Uh oh!

cursor bot commented Jan 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

ColtAllen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

williambdean commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

juanitorduz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

juanitorduz left a comment

Choose a reason for hiding this comment

Uh oh!

williambdean commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

OriolAbril left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ricardoV94 commented Jan 6, 2026

Uh oh!

juanitorduz commented Jan 6, 2026

Uh oh!

ricardoV94 commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ColtAllen commented Jan 6, 2026

Uh oh!

williambdean commented Jan 4, 2026 •

edited

Loading

cursor bot commented Jan 4, 2026 •

edited

Loading

williambdean commented Jan 5, 2026 •

edited

Loading

williambdean commented Jan 5, 2026 •

edited

Loading

ricardoV94 commented Jan 6, 2026 •

edited

Loading

juanitorduz left a comment •

edited

Loading