Skip to content

Add notebooks/wang_mle_tutorial.ipynb walking through pooled + hierarchical estimation #35

Description

@YichengYang-Ethan

Problem

The Wang Transform MLE estimator (oracle3.pricing.wang_mle.WangMLE) is the academic centerpiece of Oracle3 (v1.1.0+, DOI 10.5281/zenodo.20062549). The docstrings are thorough, but there is no end-to-end notebook that a new user can step through to see what the estimator actually does, what the output means, and how it connects to trading decisions.

We need a notebooks/ folder with one polished tutorial.

Acceptance criteria

  1. Create notebooks/wang_mle_tutorial.ipynb with the following sections:
    1. Synthetic data generation: simulate 5,000 contracts under the model p_mkt = Phi(Phi^{-1}(p*) + lambda) with a known true lambda (e.g. 0.18).
    2. Pooled MLE: fit WangMLE().fit(prices, outcomes), recover lambda_hat, and verify it's within ~2 SE of the true value.
    3. Hierarchical MLE: simulate covariates (volume, duration, extremity) with a known beta vector, run build_design_matrix + fit, print summary_table().
    4. Likelihood-ratio test: compare nested models with WangMLE().lr_test(...).
    5. Greeks visualization: plot kelly_fraction and delta_lambda vs. p_market for a fitted lambda using oracle3.pricing.greeks.
  2. Add a one-line entry to README.md under "Examples" linking to the notebook.
  3. Notebook should run end-to-end with no errors using only numpy, scipy, matplotlib (already deps), and the package itself. Cell outputs committed.

Hints

  • API: oracle3.pricing.wang_mle.WangMLE, MLEResult.
  • Empirical priors at the top of wang_mle.py (LAMBDA_POLYMARKET = 0.166 etc.) are useful as anchors when discussing the lambda magnitude.
  • Greeks helpers in oracle3.pricing.greeks: kelly_fraction, delta_lambda, compute_greeks_table.
  • For sample data generation, scipy.stats.norm.ppf / cdf mirror the model's probit form.

Estimated time

3-4 hours.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is neededpricingPricing engine / Wang Transform / MLEtutorialTutorial / notebook content

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions