hftsoi / symbolfit

Docs | Paper | Slides | Colab | pip | conda | |:-:|:-:|:-:|:-:|:-:|:-:| | | | | | | What is SymbolFit? **SymbolFit automatically finds closed-form functions that fit your data with uncertainty estimation, no manual guessing required.** SymbolFit was originally developed for experimental high-energy physics (HEP) analyses, but it works on any 1D, 2D, or higher-dimensional dataset where you need an interpretable parametric model with uncertainty estimates. You provide data points and SymbolFit returns a batch of candidate functions ranked by goodness-of-fit, each with optimized parameters and uncertainty estimates. All results are saved to CSV tables and PDF plots, ready for downstream use such as hypothesis testing in HEP. Under the hood, it chains three steps into a single pipeline: • **Function search**: PySR (symbolic regression) explores combinations of mathematical operators to discover functional forms that fit the data, without requiring a predefined template. • **Re-optimization**: LMFIT re-optimizes the numerical parameters in each candidate function and provides uncertainty estimates via covariance matrices. • **Evaluation**: every candidate is automatically scored (chi2/NDF, p-value, RMSE, R2), plotted with individual uncertainty variations and total uncertainty coverage, and saved to output files. • Installation • Quick Start • Fit Your Own Data • Documentation • Citation Installation **Installation via PyPI** (recommended), with Python>=3.10: Installation via conda Julia (the backend for PySR) is installed automatically the first time you import PySR (one-time setup): Quick Start A minimal fit to verify the installation works: Full example with more options For a more realistic fit, clone the repo to get the example datasets and configs: Then run the example (or simply do ): When it finishes, six output files are produced: | File | What it contains | |------|-----------------| | | All candidate functions with parameters, uncertainties, covariance matrices, and goodness-of-fit scores | | | Compact version with only final functions, parameters, and key metrics | | | Each candidate plotted against data, with per-parameter uncertainty variations and residual panels | | | Total uncertainty bands from Monte Carlo parameter sampling (1D only) | | | Summary of goodness-of-fit metrics (chi2/NDF, p-value, RMSE, R2) across all candidates | | | Parameter correlation matrices for each candidate | You can browse the output files from this example fit here. > **Tip:** The function space is vast. Each run with explores different regions and returns a different batch of candidates. If the first run doesn't produce a satisfactory fit, simply rerun with the same config. After several runs, if results are still unsatisfactory, try adjusting the PySR config (e.g., different operators or higher ) and the various fit options. Fit Your Own Data To fit your own data, replace the , , , with your own Python lists or NumPy arrays, as shown in the minimal example above. For details on input data format (1D histograms, 2D histograms, etc.), see the input format guide. **No input uncertainties?** Simply omit and (they default to 1), and set for an unweighted least-squares fit. **Custom PySR config:** The default PySR config includes simple operators ( , , , ). For your data, you may want to customize this and put some equation constraints. See the PySR config examples in the docs. Documentation Full documentation with tutorials, demo fits, and API reference is available here. Citation If you find this useful in your research, please consider citing both SymbolFit and PySR: