Skip to content

Commit a8e26eb

Browse files
committed
Update README
1 parent d33b294 commit a8e26eb

File tree

1 file changed

+200
-57
lines changed

1 file changed

+200
-57
lines changed

README.md

Lines changed: 200 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
---
77

88

9-
[![GitHub release](https://img.shields.io/badge/release-1.0.0-yellow.svg)](https://github.com/thieu1995/evorbf/releases)
9+
[![GitHub release](https://img.shields.io/badge/release-2.0.0-yellow.svg)](https://github.com/thieu1995/evorbf/releases)
1010
[![Wheel](https://img.shields.io/pypi/wheel/gensim.svg)](https://pypi.python.org/pypi/evorbf)
1111
[![PyPI version](https://badge.fury.io/py/evorbf.svg)](https://badge.fury.io/py/evorbf)
1212
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/evorbf.svg)
@@ -27,20 +27,51 @@
2727
We explain several keys components and provide several types of RBF networks that you will never see in other places.
2828

2929

30-
| **EvoRBF** | **Evolving Radial Basis Function Network** |
31-
|------------------------------|-----------------------------------------------------------------------------|
32-
| **Free software** | GNU General Public License (GPL) V3 license |
33-
| **Provided Estimator** | RbfRegressor, RbfClassifier, NiaRbfRegressor, NiaRbfClassifier, InaRbfTuner |
34-
| **Provided ML models** | \> 400 Models |
35-
| **Supported metrics** | \>= 67 (47 regressions and 20 classifications) |
36-
| **Supported loss functions** | \>= 61 (45 regressions and 16 classifications) |
37-
| **Documentation** | https://evorbf.readthedocs.io |
38-
| **Python versions** | \>= 3.8.x |
39-
| **Dependencies** | numpy, scipy, scikit-learn, pandas, mealpy, permetrics |
30+
| **EvoRBF** | **Evolving Radial Basis Function Network** |
31+
|--------------------------------------|--------------------------------------------------------|
32+
| **Free software** | GNU General Public License (GPL) V3 license |
33+
| **Traditional RBF models** | `RbfRegressor`, `RbfClassifier` |
34+
| **Advanced RBF models** | `AdvancedRbfRegressor`, `AdvancedRbfClassifier` |
35+
| **Nature-inspired RBF models** | `NiaRbfRegressor`, `NiaRbfClassifier` |
36+
| **Tuner for traditional RBF models** | `NiaRbfTuner` |
37+
| **Provided total ML models** | \> 400 Models |
38+
| **Supported total metrics** | \>= 67 (47 regressions and 20 classifications) |
39+
| **Supported loss functions** | \>= 61 (45 regressions and 16 classifications) |
40+
| **Documentation** | https://evorbf.readthedocs.io |
41+
| **Python versions** | \>= 3.8.x |
42+
| **Dependencies** | numpy, scipy, scikit-learn, pandas, mealpy, permetrics |
43+
44+
45+
# Citation Request
46+
47+
```bibtex
48+
@software{thieu_2024_11136008,
49+
author = {Nguyen Van Thieu},
50+
title = {EvoRBF: A Nature-inspired Algorithmic Framework for Evolving Radial Basis Function Networks},
51+
month = may,
52+
year = 2024,
53+
publisher = {Zenodo},
54+
doi = {10.5281/zenodo.11136007},
55+
url = {https://doi.org/10.5281/zenodo.11136007}
56+
}
57+
58+
@article{van2023mealpy,
59+
title={MEALPY: An open-source library for latest meta-heuristic algorithms in Python},
60+
author={Van Thieu, Nguyen and Mirjalili, Seyedali},
61+
journal={Journal of Systems Architecture},
62+
year={2023},
63+
publisher={Elsevier},
64+
doi={10.1016/j.sysarc.2023.102871}
65+
}
66+
```
4067

4168

4269
# Theory
43-
You can read several papers by using Google scholar search. Here we will walk through some basic concepts and parameters that matter to this network.
70+
71+
You can read several papers by using Google scholar search. There are many ways we can use Nature-inspired Algorithms
72+
to optimize Radial Basis Function network, for example, you can read [this paper](https://doi.org/10.1016/B978-0-443-18764-3.00015-1).
73+
Here we will walk through some basic concepts and parameters that matter to this network.
74+
4475

4576
## Structure
4677

@@ -50,56 +81,157 @@ You can read several papers by using Google scholar search. Here we will walk th
5081

5182

5283
## Training algorithm
53-
1. RBF needs to train the centers, and widths of Gaussian activation function. (This is 1st phase)
54-
2. RBF usually use KMeans to find centers ==> Increase the complexity and time.
55-
+ In that case, user need to define widths ==> Can use 1 single width or each hidden with different width.
56-
+ Or RBF use random to find centers ==> Not good to split samples to different clusters.
57-
3. RBF needs to train the output weights. (This is 2nd phase)
58-
4. RBF do not use Gradient descent to calculate output weights, it used Moore–Penrose inverse (matrix multiplication, least square method) ==> so it is faster than MLP network.
59-
5. Moore-Penrose inverse can find the exact solution ==> why you want to use Gradient or Metaheuristics here ==> Hell no.
60-
6. In case of overfitting, what can we do with this network ==> We add Regularization method.
61-
7. If you have large-scale dataset ==> Set more hidden nodes ==> Then increase the Regularization parameter.
6284

85+
### Traditional RBF models
6386

64-
So, we can see that what we need to do.
65-
1. Use Moore-Penrose inverse to find the output weights (May be we let user use Regularization method, the parameter will be automatic tuned)
66-
2. We need remove KMeans method, but we don't want to use Random method ==> We use metaheuristics here?
67-
+ May be not a good idea, since metaheuristics can be more complex than KMeans.
68-
+ But if we use metaheuristics to find everything (centers, width, )
87+
In case of traditional RBF model. There are a few parameters need to identify to get the best model.
88+
```code
89+
1. The number of hidden nodes in hidden layer
90+
2. The centers and widths (sigmas) of Gaussian function
91+
3. The output weights
92+
4. The regularization factor (lambda) L2
93+
```
6994

70-
## Implementation version
95+
To train their parameters,
96+
```code
97+
1. Using hyper-parameter tuning model such as GridSearchCV or RandomizedSearchCV to get the best hidden nodes
98+
2. The centers can be calculated by Random or KMeans or unsupervised learning algorithms
99+
3. The widths (sigmas) can be computed by hyper-parameter tuning process.
100+
+ Width can be a single value that represent all hidden nodes has the same curve of Gaussian function
101+
+ Width can be multiple values that each hidden node has a different value.
102+
4. The output weights can be calculated by Moore-Penrose inverse (Matrix multiplication). Do not use Gradient Descent.
103+
5. When setting regularization L2. lambda can be computed by hyper-parameter tuning process.
104+
```
71105

72-
1. Rbf
106+
Example,
107+
```python
108+
from evorbf import RbfRegressor, RbfClassifier
73109

110+
model = RbfClassifier(size_hidden=10, center_finder="kmeans", sigmas=2.0, reg_lambda=0.1, seed=None)
111+
model = RbfRegressor(size_hidden=4, center_finder="random", sigmas=(1.5, 2, 2, 2.5), reg_lambda=0, seed=42)
74112

113+
model.fit(X=X_train, y=y_train)
114+
y_pred = model.predict(X_test)
115+
y_pred_prob = model.predict_proba(X_test)
116+
```
75117

76118

77-
# Citation Request
119+
### Advanced RBF models
78120

79-
If you want to understand how Nature-inspired Algorithms is applied to Radial Basis Function Network, you
80-
need to read the paper titled "Application of artificial intelligence in estimating mining capital expenditure using radial basis function neural network optimized by metaheuristic algorithms".
81-
The paper can be accessed at the following [this link](https://doi.org/10.1016/B978-0-443-18764-3.00015-1)
121+
In case of advanced RBF model. User can have so many different options.
122+
```code
123+
1. Choice different RBF kernel function such as Multiquadric (MQ), Inverse Multiquadric (IMQ), Thin Plate Spline (TPS), Exponential, Power,...
124+
2. Choice different unsupervised learning algorithms to calculate the centers, and may be the number of hidden nodes.
125+
+ For example, KMeans, or random algorithms, you need to set up the number of hidden nodes.
126+
+ But, for MeanShift or DBSCAN algorithms, you don't need to set that value. They can automatically identify the number of cluters (number of hidden nodes).
127+
3. This version may have the bias in output layer.
128+
```
82129

130+
Examples,
131+
```python
132+
from evorbf import AdvancedRbfClassifier, AdvancedRbfRegressor
83133

84-
```bibtex
85-
@software{thieu_2024_11136008,
86-
author = {Nguyen Van Thieu},
87-
title = {EvoRBF: A Nature-inspired Algorithmic Framework for Evolving Radial Basis Function Networks},
88-
month = may,
89-
year = 2024,
90-
publisher = {Zenodo},
91-
doi = {10.5281/zenodo.11136007},
92-
url = {https://doi.org/10.5281/zenodo.11136007}
93-
}
134+
model = AdvancedRbfClassifier(center_finder="random", finder_params={"n_centers": 15},
135+
rbf_kernel="gaussian", kernel_params={"sigma": 1.5},
136+
reg_lambda=0.1, has_bias=True, seed=42)
94137

95-
@article{van2023mealpy,
96-
title={MEALPY: An open-source library for latest meta-heuristic algorithms in Python},
97-
author={Van Thieu, Nguyen and Mirjalili, Seyedali},
98-
journal={Journal of Systems Architecture},
99-
year={2023},
100-
publisher={Elsevier},
101-
doi={10.1016/j.sysarc.2023.102871}
102-
}
138+
model = AdvancedRbfClassifier(center_finder="random", finder_params=None, # Default n_centers = 10
139+
rbf_kernel="gaussian", kernel_params=None, # Default sigma = 1.0
140+
reg_lambda=0.1, has_bias=False, seed=42)
141+
142+
model = AdvancedRbfClassifier(center_finder="kmeans", finder_params={"n_centers": 20},
143+
rbf_kernel="multiquadric", kernel_params=None,
144+
reg_lambda=0.1, has_bias=False, seed=42)
145+
146+
model = AdvancedRbfClassifier(center_finder="meanshift", finder_params={"bandwidth": 0.6}, # Give us 28 hidden nodes
147+
rbf_kernel="inverse_multiquadric", kernel_params={"sigma": 1.5},
148+
reg_lambda=0.5, has_bias=True, seed=42)
149+
150+
model = AdvancedRbfClassifier(center_finder="dbscan", finder_params={"eps": 0.2}, # Give us 42 hidden nodes
151+
rbf_kernel="multiquadric", kernel_params={"sigma": 1.5},
152+
reg_lambda=0.5, has_bias=True, seed=42)
153+
154+
model = AdvancedRbfClassifier(center_finder="dbscan", finder_params={"eps": 0.175}, # Give us 16 hidden nodes
155+
rbf_kernel="multiquadric", kernel_params={"sigma": 1.5},
156+
reg_lambda=None, has_bias=False, seed=42)
157+
158+
model.fit(X=X_train, y=y_train)
159+
y_pred = model.predict(X_test)
160+
y_pred_prob = model.predict_proba(X_test)
161+
```
162+
163+
### Nature-inspired Algorithm-based RBF models
164+
165+
This is the main purpose of this library. In this type of models,
166+
167+
```code
168+
1. We use Nature-inspired Algorithm (NIA) to train widths (sigmas) value for each hidden node.
169+
2. If you set up the Regularization technique, then NIA is automatically calculated the lambda factor
170+
```
171+
172+
Examples,
173+
```python
174+
from evorbf import NiaRbfRegressor, NiaRbfClassifier
175+
176+
model = NiaRbfClassifier(size_hidden=25, center_finder="kmeans",
177+
regularization=False, obj_name="F1S",
178+
optim="OriginalWOA",
179+
optim_paras={"epoch": 50, "pop_size": 20},
180+
verbose=True, seed=42)
181+
182+
model = NiaRbfRegressor(size_hidden=10, center_finder="random",
183+
regularization=True, obj_name="AS",
184+
optim="BaseGA",
185+
optim_paras={"epoch": 50, "pop_size": 20},
186+
verbose=True, seed=42)
187+
188+
model.fit(X=X_train, y=y_train)
189+
y_pred = model.predict(X_test)
190+
y_pred_prob = model.predict_proba(X_test)
191+
```
192+
193+
### Nature-inspired Algorithm-based hyperparameter RBF tuning model
194+
195+
In this case, user can use NIA to tune hyper-parameters of traditional RBF models.
196+
197+
```python
198+
from evorbf import NiaRbfTuner, IntegerVar, StringVar, FloatVar
199+
200+
# Design the boundary (for hyper-parameters)
201+
my_bounds = [
202+
IntegerVar(lb=5, ub=21, name="size_hidden"),
203+
StringVar(valid_sets=("kmeans", "random"), name="center_finder"),
204+
FloatVar(lb=(0.01,), ub=(3.0,), name="sigmas"),
205+
FloatVar(lb=(0, ), ub=(1.0, ), name="reg_lambda"),
206+
]
207+
208+
model = NiaRbfTuner(problem_type="classification", bounds=my_bounds, cv=3, scoring="AS",
209+
optim="OriginalWOA", optim_paras={"epoch": 10, "pop_size": 20},
210+
verbose=True, seed=42)
211+
```
212+
213+
### My notes
214+
215+
1. RBF needs to train the centers, and widths of Gaussian activation function. (This is 1st phase)
216+
2. RBF usually use KMeans to find centers ==> Increase the complexity and time.
217+
+ In that case, user need to define widths ==> Can use 1 single width or each hidden with different width.
218+
+ Or RBF use random to find centers ==> Not good to split samples to different clusters.
219+
3. RBF needs to train the output weights. (This is 2nd phase)
220+
4. RBF do not use Gradient descent to calculate output weights, it used Moore–Penrose inverse (matrix multiplication, least square method) ==> so it is faster than MLP network.
221+
5. Moore-Penrose inverse can find the exact solution ==> why you want to use Gradient or Metaheuristics here ==> Hell no.
222+
6. In case of overfitting, what can we do with this network ==> We add Regularization method.
223+
7. If you have large-scale dataset ==> Set more hidden nodes ==> Then increase the Regularization parameter.
224+
225+
```code
226+
1. RbfRegressor, RbfClassifier: You need to set up 4 types of hyper-parameters.
227+
2. AdvancedRbfRegressor, AdvancedRbfClassifier: You need to set up 6 types of hyper-parameters.
228+
But you have many option to choice, and you can design your own RBF models, a new one that nobody has used it before.
229+
For example, RBF that has bias in output layer or RBF that use DBSCAN and Exponential kernel function.
230+
3. NiaRbfRegressor, NiaRbfClassifier: You need to set up the hidden size. However, these are best classes in this library.
231+
+ The sigmas are automatically calculated for each hidden nodes.
232+
+ The reguarlization factor is also automatically tuned to fine the best one.
233+
4. NiaRbfTuner. This class also extremely useful for traditional RBF models, it can tune hidden size, however,
234+
there is only 1 sigma value will be presented all hidden nodes.
103235
```
104236

105237

@@ -118,8 +250,10 @@ $ python
118250
>>> evorbf.__version__
119251
```
120252

121-
In this example below, we will use Whale Optimization Algorithm to optimize the `sigmas` (in non-linear Gaussian
122-
kernel) and `weights` (of hidden-output layer) in RBF network (WOA-RBF model) for Diabetes prediction problem.
253+
We have provided above several ways to import and call the proposed classes. If you need more details how to
254+
use each of them, please check out the folder [examples](/examples). In this short demonstration, we will use
255+
Whale Optimization Algorithm to optimize the `sigmas` (in non-linear Gaussian kernel) and `reg_lambda` of
256+
L2 regularization in RBF network (WOA-RBF model) for Diabetes prediction problem.
123257

124258
```python
125259
import numpy as np
@@ -143,19 +277,24 @@ data.y_train, scaler_y = data.scale(data.y_train, scaling_methods=("standard", )
143277
data.y_test = scaler_y.transform(np.reshape(data.y_test, (-1, 1)))
144278

145279
## Create model
146-
opt_paras = {"name": "WOA", "epoch": 500, "pop_size": 20}
147-
model = NiaRbfRegressor(size_hidden=25, center_finder="kmean", regularization=False, lamda=0.5, obj_name="MSE",
148-
optimizer="BaseGA", optimizer_paras=opt_paras, verbose=True, seed=42)
280+
opt_paras = {"name": "WOA", "epoch": 50, "pop_size": 20}
281+
model = NiaRbfRegressor(size_hidden=25, # Set up big enough hidden size
282+
center_finder="kmeans", # Use KMeans to find the centers
283+
regularization=True, # Use L2 regularization
284+
obj_name="MSE", # Mean squared error as fitness function for NIAs
285+
optim="OriginalWOA", # Use Whale Optimization
286+
optim_paras={"epoch": 50, "pop_size": 20}, # Set up parameter for Whale Optimization
287+
verbose=True, seed=42)
149288

150289
## Train the model
151-
model.fit(data.X_train, data.y_train, lb=-1., ub=2.)
290+
model.fit(data.X_train, data.y_train)
152291

153292
## Test the model
154293
y_pred = model.predict(data.X_test)
155294

156295
print(model.optimizer.g_best.solution)
157296
## Calculate some metrics
158-
print(model.score(X=data.X_test, y=data.y_test, method="RMSE"))
297+
print(model.score(X=data.X_test, y=data.y_test))
159298
print(model.scores(X=data.X_test, y=data.y_test, list_metrics=["R2", "R", "KGE", "MAPE"]))
160299
print(model.evaluate(y_true=data.y_test, y_pred=y_pred, list_metrics=["MSE", "RMSE", "R2S", "NSE", "KGE", "MAPE"]))
161300
```
@@ -173,3 +312,7 @@ instructions, explanations, and examples.
173312
* [Issue tracker](https://github.com/thieu1995/evorbf/issues)
174313
* [Notable changes log](/ChangeLog.md)
175314
* [Official discussion group](https://t.me/+fRVCJGuGJg1mNDg1)
315+
316+
---
317+
318+
Developed by: [Thieu](mailto:nguyenthieu2102@gmail.com?Subject=EvoRBF_QUESTIONS) @ 2024

0 commit comments

Comments
 (0)