symbolfit 0.0.1__tar.gz

symbolfit-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ho Fung Tsoi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

symbolfit-0.0.1/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.1
+Name: symbolfit
+Version: 0.0.1
+Summary: Automatic parametric modeling with symbolic regression
+Home-page: https://github.com/hftsoi/symbolfit
+Author: Ho Fung Tsoi
+Author-email: ho.fung.tsoi@cern.ch
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pysr==0.16.9
+Requires-Dist: lmfit==1.2.2
+Requires-Dist: pandas==2.2.3
+Requires-Dist: matplotlib==3.8.2
+Requires-Dist: seaborn==0.13.2
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hftsoi/symbolfit/main/docs/logo.png" width="300"/>
+</p>
+
+[![Documentation Status](https://readthedocs.org/projects/symbolfit/badge/?version=latest)](https://symbolfit.readthedocs.io)
+
+An API to automate parametric modeling with symbolic regression, originally developed for data analysis in the experimental high-energy physics community, but also applicable beyond.
+
+Symbolfit takes binned data with measurement/systematic uncertainties as input, utilizes [PySR](https://github.com/MilesCranmer/PySR) to perform a machine-search for batches of functional forms that model the data, parameterizes these functions, and utilizes [LMFIT](https://github.com/lmfit/lmfit-py) to re-optimize the functions and provide uncertainty estimation, all in one go.
+It is designed to maximize automatation with minimal human input. Each run produces a batch of functions with uncertainty estimation, which are evaluated, saved, and plotted automatically into readable output files, ready for downstream tasks.
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Documentation](#documentation)
+- [Citation](#citation)
+
+## Installation
+**Prerequisite**
+
+Install Julia (backend for PySR)
+```
+curl -fsSL https://install.julialang.org | sh
+```
+then check if installed properly
+```
+julia --version
+```
+
+**Installation via PyPI**
+
+With Python>=3.9
+```
+pip install symbolfit
+```
+Upon first installation, run
+```
+python3 -m pysr install
+```
+
+## Getting Started
+To run an example fit (or ```python fit_example.py```):
+```
+from symbolfit.symbolfit import *
+
+dataset = importlib.import_module('examples.datasets.toy_dataset_1.dataset')
+pysr_config = importlib.import_module('examples.pysr_configs.pysr_config_1')
+
+model = SymbolFit(
+    	x = dataset.x,
+    	y = dataset.y,
+    	y_up = dataset.y_up,
+    	y_down = dataset.y_down,
+    	pysr_config = pysr_config,
+    	max_complexity = 60,
+    	input_rescale = True,
+    	scale_y_by = 'mean',
+    	max_stderr = 40,
+    	fit_y_unc = True,
+    	random_seed = None,
+    	loss_weights = None
+)
+
+model.fit()
+```
+After the fit, save results to csv:
+```
+model.save_to_csv(output_dir = 'output_dir/')
+```
+and plot results to pdf:
+```
+model.plot_to_pdf(
+    	output_dir = 'output_dir/',
+    	bin_widths_1d = dataset.bin_widths_1d,
+    	#bin_edges_2d = dataset.bin_edges_2d,
+    	plot_logy = False,
+    	plot_logx = False
+)
+```
+Candidate functions with full substitutions can be printed in prompt:
+```
+model.print_candidate(candidate_number = 10)
+```
+
+Each run will produce a batch of candidate functions and will automatically save all results to five output files:
+1) ```candidates.csv```: saves all candidate functions and evaluations in a csv table.
+2) ```candidates_reduced.csv```: saves a reduced version for essential information without intermediate results.
+3) ```candidates.pdf```: plots all candidate functions with associated uncertainties one by one for fit quality evaluation.
+4) ```candidates_gof.pdf```: plots the goodness-of-fit scores.
+5) ```candidates_correlation.pdf```: plots the correlation matrices for the parameters of each candidate function.
+
+## Documentation
+The documentation can be found [here](https://symbolfit.readthedocs.io) for more info and demonstrations.
+
+## Citation
+If you find this useful in your research, please consider citing Symbolfit:
+```
+Coming soon!
+```
+and PySR:
+```
+@misc{cranmerInterpretableMachineLearning2023,
+    title = {Interpretable {Machine} {Learning} for {Science} with {PySR} and {SymbolicRegression}.jl},
+    url = {http://arxiv.org/abs/2305.01582},
+    doi = {10.48550/arXiv.2305.01582},
+    urldate = {2023-07-17},
+    publisher = {arXiv},
+    author = {Cranmer, Miles},
+    month = may,
+    year = {2023},
+    note = {arXiv:2305.01582 [astro-ph, physics:physics]},
+    keywords = {Astrophysics - Instrumentation and Methods for Astrophysics, Computer Science - Machine Learning, Computer Science - Neural and Evolutionary Computing, Computer Science - Symbolic Computation, Physics - Data Analysis, Statistics and Probability},
+}
+```
+

symbolfit-0.0.1/README.md

@@ -0,0 +1,114 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hftsoi/symbolfit/main/docs/logo.png" width="300"/>
+</p>
+
+[![Documentation Status](https://readthedocs.org/projects/symbolfit/badge/?version=latest)](https://symbolfit.readthedocs.io)
+
+An API to automate parametric modeling with symbolic regression, originally developed for data analysis in the experimental high-energy physics community, but also applicable beyond.
+
+Symbolfit takes binned data with measurement/systematic uncertainties as input, utilizes [PySR](https://github.com/MilesCranmer/PySR) to perform a machine-search for batches of functional forms that model the data, parameterizes these functions, and utilizes [LMFIT](https://github.com/lmfit/lmfit-py) to re-optimize the functions and provide uncertainty estimation, all in one go.
+It is designed to maximize automatation with minimal human input. Each run produces a batch of functions with uncertainty estimation, which are evaluated, saved, and plotted automatically into readable output files, ready for downstream tasks.
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Documentation](#documentation)
+- [Citation](#citation)
+
+## Installation
+**Prerequisite**
+
+Install Julia (backend for PySR)
+```
+curl -fsSL https://install.julialang.org | sh
+```
+then check if installed properly
+```
+julia --version
+```
+
+**Installation via PyPI**
+
+With Python>=3.9
+```
+pip install symbolfit
+```
+Upon first installation, run
+```
+python3 -m pysr install
+```
+
+## Getting Started
+To run an example fit (or ```python fit_example.py```):
+```
+from symbolfit.symbolfit import *
+
+dataset = importlib.import_module('examples.datasets.toy_dataset_1.dataset')
+pysr_config = importlib.import_module('examples.pysr_configs.pysr_config_1')
+
+model = SymbolFit(
+    	x = dataset.x,
+    	y = dataset.y,
+    	y_up = dataset.y_up,
+    	y_down = dataset.y_down,
+    	pysr_config = pysr_config,
+    	max_complexity = 60,
+    	input_rescale = True,
+    	scale_y_by = 'mean',
+    	max_stderr = 40,
+    	fit_y_unc = True,
+    	random_seed = None,
+    	loss_weights = None
+)
+
+model.fit()
+```
+After the fit, save results to csv:
+```
+model.save_to_csv(output_dir = 'output_dir/')
+```
+and plot results to pdf:
+```
+model.plot_to_pdf(
+    	output_dir = 'output_dir/',
+    	bin_widths_1d = dataset.bin_widths_1d,
+    	#bin_edges_2d = dataset.bin_edges_2d,
+    	plot_logy = False,
+    	plot_logx = False
+)
+```
+Candidate functions with full substitutions can be printed in prompt:
+```
+model.print_candidate(candidate_number = 10)
+```
+
+Each run will produce a batch of candidate functions and will automatically save all results to five output files:
+1) ```candidates.csv```: saves all candidate functions and evaluations in a csv table.
+2) ```candidates_reduced.csv```: saves a reduced version for essential information without intermediate results.
+3) ```candidates.pdf```: plots all candidate functions with associated uncertainties one by one for fit quality evaluation.
+4) ```candidates_gof.pdf```: plots the goodness-of-fit scores.
+5) ```candidates_correlation.pdf```: plots the correlation matrices for the parameters of each candidate function.
+
+## Documentation
+The documentation can be found [here](https://symbolfit.readthedocs.io) for more info and demonstrations.
+
+## Citation
+If you find this useful in your research, please consider citing Symbolfit:
+```
+Coming soon!
+```
+and PySR:
+```
+@misc{cranmerInterpretableMachineLearning2023,
+    title = {Interpretable {Machine} {Learning} for {Science} with {PySR} and {SymbolicRegression}.jl},
+    url = {http://arxiv.org/abs/2305.01582},
+    doi = {10.48550/arXiv.2305.01582},
+    urldate = {2023-07-17},
+    publisher = {arXiv},
+    author = {Cranmer, Miles},
+    month = may,
+    year = {2023},
+    note = {arXiv:2305.01582 [astro-ph, physics:physics]},
+    keywords = {Astrophysics - Instrumentation and Methods for Astrophysics, Computer Science - Machine Learning, Computer Science - Neural and Evolutionary Computing, Computer Science - Symbolic Computation, Physics - Data Analysis, Statistics and Probability},
+}
+```
+

symbolfit-0.0.1/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

symbolfit-0.0.1/setup.cfg

@@ -0,0 +1,30 @@
+[metadata]
+name = symbolfit
+version = 0.0.1
+description = Automatic parametric modeling with symbolic regression
+author = Ho Fung Tsoi
+author_email = ho.fung.tsoi@cern.ch
+license = MIT
+license_files = LICENSE
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/hftsoi/symbolfit
+classifiers = 
+	Programming Language :: Python :: 3
+	License :: OSI Approved :: MIT License
+
+[options]
+packages = find:
+python_requires = >=3.9
+install_requires = 
+	pysr==0.16.9
+	lmfit==1.2.2
+	pandas==2.2.3
+	matplotlib==3.8.2
+	seaborn==0.13.2
+include_package_data = True
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

symbolfit-0.0.1/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+if __name__ == "__main__":
+    setup()

symbolfit-0.0.1/symbolfit/evaluate.py

@@ -0,0 +1,228 @@
+import numpy as np
+from .utils import *
+import scipy
+
+
+# compute the refitted function, with all parameters at their best fit values, or have one of them shifted +/-1sigma
+def func_evaluate(
+    func_candidate,
+    x,
+    dim,
+    param_shifted = None,
+    sigma_pm = None,
+    evaluate_pysr = False
+):
+    '''
+    Compute the function values corresponding to the input array x.
+    
+    Arguments
+    ---------
+    func_candidate (pd.dataframe):
+        A particular function candidate (single row of the func_candidates dataframe).
+        
+    x0 (np.ndarray):
+        Numpy array of the independent variable.
+        
+    param_shifted (str):
+        Set to 'a3' to evaluate the function values shifting the 'a3' while keeping the rest parameters unshifted.
+        If None, evaluate the function values with all parameters at their best-fit values.
+        
+    sigma_pm (str):
+        Set to '+' ('-1') for +1 (-1) sigma of param_shifted.
+        If None, evaluate the function values with all parameters at their best-fit values.
+        
+    evaluate_pysr (bool):
+        True: evaluate with the original function from PySR.
+        False: evaluate with the refitted function from LMFIT.
+    
+    
+    Returns
+    -------
+    y_pred (np.ndarray):
+        The predicted dependent variable y for the function candidate.
+    '''
+    
+    if param_shifted is None:
+        # Substitute with the parameters from LMFIT (second fit) or from PySR (first fit).
+        if evaluate_pysr == False:
+            func = re.sub(r'\b(a\d+)\b',
+                        r"func_candidate['Parameters: (best-fit, +1, -1)']['\1'][0]",
+                        func_candidate['Parameterized equation, unscaled'])
+                        
+        else:
+            func = re.sub(r'\b(a\d+)\b',
+                        r"func_candidate['Parameterization']['\1']",
+                        func_candidate['Parameterized equation, unscaled'])
+                        
+    else:
+        # First substitute with all best-fit parameters.
+        func = re.sub(r'\b(a\d+)\b',
+                      r"func_candidate['Parameters: (best-fit, +1, -1)']['\1'][0]",
+                      func_candidate['Parameterized equation, unscaled'])
+                      
+        # Then replace the param_shifted with its +/-1 sigma value.
+        if sigma_pm == '+':
+            func = re.sub(r"func_candidate\['Parameters: \(best-fit, \+1, -1\)'\]\['" + re.escape(param_shifted) + r"'\]\[0\]",
+                          r"(func_candidate['Parameters: (best-fit, +1, -1)']['" + param_shifted + r"'][0] + func_candidate['Parameters: (best-fit, +1, -1)']['" + param_shifted + r"'][1])",
+                          func)
+                          
+        elif sigma_pm == '-':
+            func = re.sub(r"func_candidate\['Parameters: \(best-fit, \+1, -1\)'\]\['" + re.escape(param_shifted) + r"'\]\[0\]",
+                          r"(func_candidate['Parameters: (best-fit, +1, -1)']['" + param_shifted + r"'][0] + func_candidate['Parameters: (best-fit, +1, -1)']['" + param_shifted + r"'][2])",
+                          func)
+    
+    if dim > 1:
+        for i in range(dim):
+            globals()[f'x{i}'] = np.reshape(x[:, i], (-1, 1))
+            
+    else:
+        x0 = x
+        
+    if re.findall(r'x\d+', func_candidate['Parameterized equation, unscaled']):
+        return eval(func)
+        
+    else:
+        # For function not depending on x.
+        return np.full((x.shape[0], 1), eval(func))
+        
+        
+def add_gof(
+    func_candidates,
+    x,
+    y,
+    y_up,
+    y_down,
+    dim
+):
+    '''
+    Compute goodness-of-fit metrics for all function candidates at once.
+    
+    Arguments
+    ---------
+    func_candidates (pd.dataframe):
+        The full dataframe containing all function candidates.
+        
+    x (np.ndarray):
+        Numpy array of the independent variable.
+        
+    y (np.ndarray):
+        Numpy array of the dependent variable (input at central).
+        
+    y_up (np.ndarray):
+        Numpy array of the dependent variable (input at +1 sigma).
+
+    y_down (np.ndarray):
+        Numpy array of the dependent variable (input at -1 sigma).
+        
+    dim (np.int):
+        Dimension of the input data.
+    
+    
+    Returns
+    -------
+    func_candidates (pd.dataframe):
+        Add new columns to the dataframe:
+            RMSE (before refit): root-mean-square-error of the PySR function before refit with LMFIT,
+            RMSE: after refit with LMFIT,
+            R2: coefficient of determination,
+            NDF: number of degrees of freedom,
+            Chi2 (before refit): Chi2 of the PySR function before refit with LMFIT,
+            Chi2: after refit with LMFIT,
+            Chi2/NDF (before refit): similar as above,
+            Chi2/NDF: similar as above.
+    '''
+    # Functions after ROF.
+    rmse_values = []
+    r2_values = []
+    chi2_values = []
+    ndf_values = []
+    chi2_ndf_values = []
+    p_values = []
+    
+    # Functions before ROF.
+    chi2_values_pysr = []
+    chi2_ndf_values_pysr = []
+    p_values_pysr = []
+    rmse_values_pysr = []
+
+    for i in range(len(func_candidates)):
+        func_candidate = func_candidates.iloc[i]
+        
+        # Function evaluated with re-fitted parameters from LMFIT.
+        y_pred = func_evaluate(func_candidate, x, dim)
+        
+        # Function evaluated with original parameters from PySR.
+        y_pred_pysr = func_evaluate(func_candidate, x, dim, evaluate_pysr = True)
+        
+        rmse = np.sqrt(np.sum((y - y_pred)**2) / y.size)
+        r2 = 1 - np.sum((y - y_pred)**2) / np.sum((y - np.mean(y))**2)
+            
+        rmse_values.append(round_a_number(rmse, 4))
+        r2_values.append(round_a_number(r2, 4))
+        
+        # The uncertainties of input y are required to compute Chi2.
+        if y_up is not None and y_down is not None:
+            residual = y_pred - y
+            residual_pysr = y_pred_pysr - y
+            
+            # For each bin, take up/down uncertainty if the residual error is +/-ve.
+            # If either uncertainty input is 0, take the other one.
+            y_unc = np.where(residual > 0,
+                             np.where(y_up != 0, y_up, y_down),
+                             np.where(y_down != 0, y_down, y_up))
+                             
+            y_unc_pysr = np.where(residual_pysr > 0,
+                                  np.where(y_up != 0, y_up, y_down),
+                                  np.where(y_down != 0, y_down, y_up))
+                                  
+            chi2 = np.sum(residual**2 / y_unc**2)
+            chi2_pysr = np.sum(residual_pysr**2 / y_unc_pysr**2)
+            
+            # NDF = number of independent data point - number of varying parameters in the function.
+            num_free_param = 0
+            if len(func_candidate['Parameters: (best-fit, +1, -1)']) > 0:
+                for j in range(len(func_candidate['Parameters: (best-fit, +1, -1)'])):
+                    if func_candidate['Parameters: (best-fit, +1, -1)'][f'a{j+1}'][1] > 0:
+                        num_free_param += 1
+                        
+            if y.size - num_free_param > 0:
+                ndf = y.size - num_free_param
+                
+            else:
+                ndf = -1
+                
+            p_value = scipy.stats.chi2.sf(chi2, ndf)
+            p_value_pysr = scipy.stats.chi2.sf(chi2_pysr, ndf)
+                
+            ndf_values.append(ndf)
+            chi2_values.append(round_a_number(chi2, 4))
+            chi2_ndf_values.append(round_a_number(chi2/ndf, 4))
+            chi2_values_pysr.append(round_a_number(chi2_pysr, 4))
+            chi2_ndf_values_pysr.append(round_a_number(chi2_pysr/ndf, 4))
+            p_values.append(round_a_number(p_value, 4))
+            p_values_pysr.append(round_a_number(p_value_pysr, 4))
+            
+        else:
+            rmse_pysr = np.sqrt(np.sum((y - y_pred_pysr)**2) / y.size)
+            rmse_values_pysr.append(round_a_number(rmse_pysr, 4))
+        
+    func_candidates['RMSE'] = rmse_values
+    func_candidates['R2'] = r2_values
+    
+    if y_up is not None and y_down is not None:
+        func_candidates['NDF'] = ndf_values
+        
+        func_candidates['Chi2 (before ROF)'] = chi2_values_pysr
+        func_candidates['Chi2'] = chi2_values
+        
+        func_candidates['Chi2/NDF (before ROF)'] = chi2_ndf_values_pysr
+        func_candidates['Chi2/NDF'] = chi2_ndf_values
+        
+        func_candidates['p-value (before ROF)'] = p_values_pysr
+        func_candidates['p-value'] = p_values
+        
+    else:
+        func_candidates['RMSE (before ROF)'] = rmse_values_pysr
+    
+    return func_candidates
+    

symbolfit-0.0.1/symbolfit/math_defs.py

@@ -0,0 +1,20 @@
+import numpy as np
+from numpy import sin, cos, tan, exp, sinh, cosh, tanh, log10, log, where
+from numpy import arcsin, arccos, arctan, arcsinh, arccosh, arctanh
+
+
+def square(x):
+    return x*x
+    
+def cond(x, y):
+    return where(x > 0., y, 0.)
+    
+def piecewise(y, x):
+    return where(x > 0., y, 0.)
+    
+def gauss(x):
+    return exp(-x*x)
+    
+def sigmoid(x):
+    return 1./(1.+exp(-x))
+