Subsections of Reference

CLI Reference

marketbayesmeta installs three console scripts.

Check a tracker

marketbayesmeta-check-tracker path/to/tracker.csv
marketbayesmeta-check-tracker path/to/tracker.csv --audit --include-partial

The audit mode reports model-readiness and tracker-quality checks for supported evidence/scale pairs present in the tracker.

Check a config

marketbayesmeta-check-config examples/config.yaml

This validates the YAML schema and confirms that the configured tracker path exists.

Run an analysis

marketbayesmeta-run examples/config.yaml

This runs the full config-driven workflow and writes configured outputs. It returns a non-zero exit code for package-level analysis failures, including blocked readiness, tracker validation errors, pooling errors, or blocking diagnostic failures.

Repository runner

python runme.py
python runme.py examples/config.yaml

Without an argument, runme.py looks for config.yaml in the repository root.

Configuration Reference

Use YAML config files for repeatable analysis runs.

Core fields

Field Required Default Notes
project.name No marketbayesmeta_analysis Human-readable project name.
project.analyst No null Analyst or owner.
project.notes No "" Short project note.
data.tracker Yes None CSV tracker path, resolved relative to the config file.
data.include_partial No false Include analysis_ready=partial rows.
analysis.evidence_type Yes None Currently pooled by default: geo_test, bls.
analysis.metric Yes None Exact metric name to pool.
analysis.scale Yes None log_relative or percentage_point.
analysis.max_abs_percent_uplift No 90 Hard limit for % geo uplift to log-relative conversion.
model.draws No 2000 Posterior draws per chain.
model.tune No 1000 Tuning draws per chain.
model.chains No 4 Number of chains.
model.target_accept No 0.9 Passed to PyMC sampling.
model.random_seed No null Sampling seed.
model.progressbar No false Keep false for scripted runs.
priors.mu_sd No scale-aware Prior SD for pooled mean mu.
priors.tau_scale No scale-aware HalfNormal scale for heterogeneity tau.
diagnostics.allow_directional No false Allow directional readiness runs only for exploratory work.
diagnostics.allow_not_recommended No false Override only for explicit exploratory work.
diagnostics.fail_on_diagnostic_failure No true Make failed sampler diagnostics blocking.
outputs.directory No output/analysis Output folder, resolved relative to config file.

Uncertainty fields

Rows with intervals must state ci_type. They must also state ci_level unless uncertainty.default_ci_level is explicitly set in config.

uncertainty:
  default_ci_level: null
  scenario_standard_errors:
    log_relative:
      low: 0.03
      medium: 0.08
      high: 0.15
    percentage_point:
      low: 1.0
      medium: 3.0
      high: 5.0

P-values are converted only when p_value_sidedness=two_sided.

Sensitivity fields

sensitivity:
  uncertainty: false
  prior: false

Custom prior sensitivity specs can be provided as sensitivity.prior_specs; when omitted the package uses scale-aware defaults.

Outputs Reference

Config runs write a small artefact set intended for review and downstream reporting.

File Purpose
config.resolved.yaml Config with defaults made explicit.
model_input.csv Effects and standard errors used for modelling.
effect_preparation.csv Row-level source values, uncertainty provenance, transformations, exclusions, and warnings.
readiness.csv Model-readiness status and messages.
tracker_issues.csv Tracker quality warnings/errors.
effect_summary.csv Pooled mean posterior summary.
future_true_effect_summary.csv Latent true effect for a comparable future study.
analysis_report.md Analyst-facing summary of reportability, diagnostics, readiness, and headline effects.
diagnostics.csv Sampler diagnostic checks.
prior_diagnostics.csv Approximate prior-information warning for mu plus tau prior-predictive checks.
ppc.csv In-sample study-level posterior predictive checks.
run_status.json Machine-readable run outcome, including reportable.
outputs_manifest.json Machine-readable artefact list.

Optional files:

File Written when
uncertainty_sensitivity.csv sensitivity.uncertainty: true
prior_sensitivity.csv sensitivity.prior: true

Prefer adding columns over renaming or removing columns. If a public artefact changes, update fixture tests and docs in the same change.

API Reference

The package exports the main workflow helpers from marketbayesmeta.

Tracker and readiness

  • load_tracker_csv
  • assess_model_readiness
  • tracker_quality_issues
  • readiness_frame
  • tracker_issue_frame

Model input and fitting

  • make_meta_analysis_input
  • make_effect_preparation_rows
  • fit_random_effects

Reporting and diagnostics

  • summarise_effect
  • summarise_diagnostics
  • check_diagnostics
  • make_posterior_predictive_check_rows
  • posterior_predictive_check_frame

Priors and sensitivity

  • default_priors_for_scale
  • assess_prior_influence
  • fit_prior_sensitivity
  • make_prior_sensitivity_report_frame
  • make_sensitivity_inputs
  • make_sensitivity_report_frame

Config runner

  • load_config
  • run_analysis
  • run_config

Minimal Python example

from marketbayesmeta import EffectScale, EvidenceType
from marketbayesmeta import fit_random_effects, load_tracker_csv, make_meta_analysis_input
from marketbayesmeta.reporting import summarise_effect

dataset = load_tracker_csv("examples/example_tracker.csv")
model_input = make_meta_analysis_input(
    dataset,
    evidence_type=EvidenceType.GEO_TEST,
    scale=EffectScale.LOG_RELATIVE,
    metric="Sales uplift",
    include_partial=True,
)

result = fit_random_effects(model_input, random_seed=20260521)
print(summarise_effect(result.idata, scale=model_input.scale))