metacountregressor 0.1.48

A python package for count regression of rare events assisted by metaheuristics

The Below code demonstrates how to set up automatic optimization assisted by the harmony search algorithm. References to the Differential Evolution and Simulated Annealing has been mentioned (change accordingly)

Quick install: Requires Python 3.10

Install metacountregressor using pip as follows:

pip install metacountregressor


```python
import pandas as pd
import numpy as np
from metacountregressor.solution import ObjectiveFunction
from metacountregressor.metaheuristics import (harmony_search,
                                            differential_evolution,
                                            simulated_annealing)

Basic setup. Read in data, and select optimization algorithm. New solutiosn will be evaluated overtime. At the end of the runtime, the best solution will be reported

# Read data from CSV file
df = pd.read_csv(
"https://raw.githubusercontent.com/zahern/data/main/Ex-16-3.csv")
X = df
y = df['FREQ']  # Frequency of crashes
X['Offset'] = np.log(df['AADT']) # Explicitley define how to offset the data, no offset otherwise
# Drop Y, selected offset term and  ID as there are no panels
X = df.drop(columns=['FREQ', 'ID', 'AADT'])  

#some example argument, these are defualt so the following line is just for claritity
arguments = {'algorithm': 'hs', 'test_percentage': 0.15, 'test_complexity': 6, 'instance_number':1, '_mpai':1, 'val_percentage':0.15, 'obj_1': 'bic', '_obj_2': 'RMSE_TEST', "MAX_TIME": 6}
# Fit the model with metacountregressor
obj_fun = ObjectiveFunction(X, y, **arguments)
#replace with other metaheuristics if desired
results = harmony_search(obj_fun)

Arguments to feed into the Objective Function

Reduce the lisst down into single elements to control the optimization routine

arguments = {
    'algorithm': ['hs', 'sa', 'de'],  # Multiple choices for algorithm
    'test_percentage': 0.15, #data used to in sample predict the model, where 1 represents 100% of the data
    'val_percentage': 0.15, #data used to validate the model, where 1 represents 100% of the data
    'test_complexity': 6, 
    'instance_number': 1, #Used for giving a name to your outputs
    '_mpai': 1,
    'obj_1': ['bic', 'aic', 'hqic'],  # Multiple choices for obj_1
    '_obj_2': ['RMSE_TEST', 'MSE_TEST', 'MAE_TEST'], # Multiple choices for objecttive 2
    'MAX_TIME': 10 # Number of seconds for total estimation before 
}

Change the arguments.

Reduce down the list sizes where necsessary

#Solution Arguments
arguments = {
        'algorithm': 'hs',
        'test_percentage': 0.2,
        'test_complexity': 6, #or list based [0, 1, 2, 6]
        'instance_number': 'name',
        'is_multi': 1,
        'distribution': ['Normal', 'LnNormal', 'Triangular', 'Unifrom'],
        'Model': [0,1],  # or equivalently ['POS', 'NB']
        'transformations': ['no', 'sqrt', 'archsinh'],
        '_max_time': 10
    }
obj_fun = ObjectiveFunction(X, y, **arguments)
results = harmony_search(obj_fun)

Initial Solution Configurement

 #Model Decisions, Specify for Intial Optimization
manual_fit_spec = {
    'fixed_terms': ['SINGLE', 'LENGTH'],
    'rdm_terms': ['AADT:normal'],
    'rdm_cor_terms': ['GRADEBR:uniform', 'CURVES:triangular'],
    'grouped_terms': [],
    'hetro_in_means': ['ACCESS:normal', 'MINRAD:normal'],
    'transformations': ['no', 'no', 'log', 'no', 'no', 'no', 'no'],
    'dispersion': 1
}

#Search Arguments
arguments = {
    'algorithm': 'hs',
    'test_percentage': 0.2,
    'test_complexity': 6,
    'instance_number': 'name',
    'Manual_Fit': manual_fit_spec
}
obj_fun = ObjectiveFunction(X, y, **arguments)

simarly to return the results feed the objective function into a metaheuristic solution algorithm. An example of this is provided below:

results = harmony_search(obj_fun)

Notes

Capabilities of the software include:

• Handling of Panel Data
• Support for Data Transformations
• Implementation of Models with Correlated and Non-Correlated Random Parameters
• A variety of mixing distributions for parameter estimations, including normal, lognormal, truncated normal, Lindley, Gamma, triangular, and uniform distributions Capability to handle heterogeneity in the means of the random parameters
• Use of Halton draws for simulated maximum likelihood estimation
• Support for grouped random parameters with unbalanced groups
• Post-estimation tools for assessing goodness of fit, making predictions, and conducting out-of-sample validation
• Multiple parameter optimization routines, such as the BFGS method
• Comprehensive hypothesis testing using single objectives, such as in-sample BIC and log-likelihood
• Extensive hypothesis testing using multiple objectives, such as in-sample BIC and out-of-sample MAE (Mean Absolute Error), or in-sample AIC and out-of-sample MSPE (mean-square prediction errorr)
• Features that allow analysts to pre-specify variables, interactions, and mixing distributions, among others
• Meta-heuristic Guided Optimization, including techniques like Simulated Annealing, Harmony Search, and Differential Evolution
• Customization of Hyper-parameters to solve problems tailored to your dataset
• Out-of-the-box optimization capability using default metaheuristics

Arguments:

In reference to the arguments that can be fed into the solution alrogithm, a dictionary system is utilised with relecant names these include

The following list describes the arguments available in this function. By default, all of the capabilities described are enabled unless specified otherwise as an argument. For list arguments, include all desired elements in the list to ensure the corresponding options are considered. Example code will be provided later in this guide.

1. complexity_level: This argument accepts an integer between 0 to 5 or a list of such integers. Each integer represents a hierarchy level for estimable models associated with each explanatory variable. Here is a summary of the hierarchy:

   • 0: Null model
   • 1: Simple fixed effects model
   • 2: Random parameters model
   • 3: Random correlated parameters model
   • 4: Grouped random parameters model
   • 5: Heterogeneity in the means random parameter model

2. distributions: This argument accepts a list of strings where each string corresponds to a distribution. Valid options include:

   • "Normal"
   • "Lindley"
   • "Uniform"
   • "LogNormal"
   • "Triangular"
   • "Gamma"
   • "TruncatedNormal"
   • Any of the above, concatenated with ":" (e.g., "Normal:grouped"; requires a grouping term defined in the model)

3. Model: This argument specifies the model form. It can be a list of integers representing different models to test:

   • 0: Poisson
   • 1: Negative-Binomial
   • 2: Generalized-Poisson

4. transformations: This argument accepts a list of strings representing available transformations within the framework. Valid options include:

   • "no"
   • "square-root"
   • "logarithmic"
   • "archsinh"
   • "as factor"

5. is_multi: This argument accepts an integer indicating whether single or multiple objectives are to be tested (0 for single, 1 for multiple).

6. testing_split: This argument is used for multi-objective optimization. Define it as a decimal; for example, 0.2 represents 20% of the data for testing.

7. _max_time: This argument is used to add a termination time in the algorithm. It takes values as seconds. Note the time is only dependenant on the time after intial population of solutions are generated.

Contact

If you have any questions, ideas to improve MetaCountRegressor, or want to report a bug, just open a new issue in GitHub repository.

Citing MetaCountRegressor

Please cite MetaCountRegressor as follows:

Ahern, Z., Corry P., Paz A. (2023). MetaCountRegressor [Computer software]. https://pypi.org/project/metacounregressor/

Or using BibTex as follows:

@misc{Ahern2023,
   author = {Zeke Ahern and Paul Corry and Alexander Paz},
   journal = {PyPi},
   title = {metacountregressor · PyPI},
   url = {https://pypi.org/project/metacountregressor/0.1.47/},
   year = {2023},
}