Welcome to mulearn’s documentation!¶
\(\mu\)-learn (read _mooh-learn_, code mulearn) is a python package implementing the methodology for data-driven induction of fuzzy sets described in
D. Malchiodi and W. Pedrycz, Learning Membership Functions for Fuzzy Sets through Modified Support Vector Clustering, in F. Masulli, G. Pasi e R. Yager (Eds.), Fuzzy Logic and Applications. 10th International Workshop, WILF 2013, Genoa, Italy, November 19–22, 2013. Proceedings, Vol. 8256, Springer International Publishing, Switzerland, Lecture Notes on Artificial Intelligence, 2013;
D. Malchiodi and A. G. B. Tettamanzi, Predicting the Possibilistic Score of OWL Axioms through Modified Support Vector Clustering, in H. Haddad, R. L. Wainwright e R. Chbeir (Eds.), SAC’18: Proceedings of the 33rd Annual ACM Symposium on Applied Computing, ACM (ISBN 9781450351911), 1984–1991, 2018.
The package API is described here below.
mulearn¶
-
class
mulearn.
FuzzyInductor
(c=1, k=GaussianKernel(), fuzzifier=ExponentialFuzzifier(), solver=GurobiSolver(), random_state=None)[source]¶ FuzzyInductor class.
-
__init__
(c=1, k=GaussianKernel(), fuzzifier=ExponentialFuzzifier(), solver=GurobiSolver(), random_state=None)[source]¶ Create an instance of
FuzzyInductor
.- Parameters
c (float) – Trade-off constant, defaults to 1.
k (
mulearn.kernel.Kernel
) – Kernel function, defaults toGaussianKernel()
.fuzzifier (
mulearn.fuzzifier.Fuzzifier
) – fuzzifier mapping distance values to membership degrees, defaults to ExponentialFuzzifier().solver (
mulearn.optimization.Solver
) – Solver to be used to obtain the optimization problem solution, defaults to GurobiSolver().random_state (int) – Seed of the pseudorandom generator.
-
fit
(X, y, warm_start=False)[source]¶ Induce the membership function starting from a labeled sample.
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
y (iterable of float having the same length of X) – Membership for the vectors in X.
warm_start (bool) – flag triggering the non reinitialization of independent variables of the optimization problem, defaults to None.
- Raises
ValueError if the values in y are not between 0 and 1, if X and have different lengths, or if X contains elements of different lengths.
- Returns
self – the trained model.
-
decision_function
(X)[source]¶ Compute predictions for the membership function.
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
- Returns
array of float – the predictions for each value in X.
-
predict
(X, alpha=None)[source]¶ Compute predictions for membership to the set.
Predictions are either computed through the membership function (when alpha is set to a float in [0, 1]) or obtained via an \(\alpha\)-cut on the same function (when alpha is set to None).
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
alpha (float) – \(\alpha\)-cut value, defaults to None.
- Raises
ValueError if alpha is set to a value different from None and not included in \([0, 1]\).
- Returns
array of int – the predictions for each value in X.
-
score
(X, y, **kwargs)[source]¶ Compute the fuzzifier score.
Score is obtained as the opposite of MSE between predicted membership values and labels.
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
y (iterable of float having the same length of X) – Labels containing the gold standard membership values for the vectors in X.
- Returns
float – opposite of MSE between the predictions for the elements in X w.r.t. the labels in y.
-
kernel¶
Kernel implementation.
This module implements the kernel used in mulearn.
-
class
mulearn.kernel.
Kernel
[source]¶ Base kernel class.
-
class
mulearn.kernel.
LinearKernel
[source]¶ Linear kernel class.
-
compute
(arg_1, arg_2)[source]¶ Compute the kernel value.
The value \(k(x_1, x_2)\) of a linear kernel is equal to the dot product \(x_1 \cdot x_2\), that is to \(\sum_{i=1}^n (x_1)_i (x_2)_i\), \(n\) being the common dimension of \(x_1\) and \(x_2\).
- Parameters
arg_1 (iterable of float) – First kernel argument.
arg_2 (iterable of float) – Second kernel argument.
- Returns
float – kernel value.
-
-
class
mulearn.kernel.
PolynomialKernel
(degree)[source]¶ Polynomial kernel class.
-
__init__
(degree)[source]¶ Create an instance of PolynomialKernel.
- Parameters
degree (int) – degree of the polynomial kernel.
- Raises
ValueError if degree is not an integer or if it has a negative value.
-
compute
(arg_1, arg_2)[source]¶ Compute the kernel value.
The value \(k(x_1, x_2)\) of a polynomial kernel is equal to the quantity \((x_1 \cdot x_2 + 1)^d\), \(d\) being the polynomial degree of the kernel.
- Parameters
arg_1 (iterable of float) – First kernel argument.
arg_2 (iterable of float) – Second kernel argument.
- Returns
float – kernel value.
-
-
class
mulearn.kernel.
HomogeneousPolynomialKernel
(degree)[source]¶ Homogeneous polynomial kernel class.
-
__init__
(degree)[source]¶ Create an instance of HomogeneousPolynomialKernel.
- Parameters
degree (int) – degree of the polynomial kernel.
- Raises
ValueError if degree is not an integer or if it has a negative value.
-
compute
(arg_1, arg_2)[source]¶ Compute the kernel value.
The value \(k(x_1, x_2)\) of a homogeneous polynomial kernel is intended as the quantity \((x_1 \cdot x_2)^d\), \(d\) being the polynomial degree of the kernel.
- Parameters
arg_1 (iterable of float) – First kernel argument.
arg_2 (iterable of float) – Second kernel argument.
- Returns
float – kernel value.
-
-
class
mulearn.kernel.
GaussianKernel
(sigma=1)[source]¶ Gaussian kernel class.
-
__init__
(sigma=1)[source]¶ Create an instance of GaussianKernel.
- Parameters
sigma (float) – gaussian standard deviation, defaults to 1.
- Raises
ValueError if sigma has a negative value.
-
compute
(arg_1, arg_2)[source]¶ Compute the kernel value.
The value \(k(x_1, x_2)\) of a gaussian kernel is intended as the quantity \(\mathrm e^{-\frac{||x_1 - x_2||^2}{2 \sigma^2}}\), \(\sigma\) being the kernel standard deviation.
- Parameters
arg_1 (iterable of float) – First kernel argument.
arg_2 (iterable of float) – Second kernel argument.
- Returns
float – kernel value.
-
-
class
mulearn.kernel.
HyperbolicKernel
(scale=1, offset=0)[source]¶ Hyperbolic kernel class.
-
__init__
(scale=1, offset=0)[source]¶ Create an instance of HyperbolicKernel.
- Parameters
scale (float) – scale constant, defaults to 1.
offset (float) – offset constant, defaults to 0.
-
compute
(arg_1, arg_2)[source]¶ Compute the kernel value.
The value \(k(x_1, x_2)\) of a hyperbolic kernel is intended as the quantity \(\tanh(\alpha x_1 \cdot x_2 + \beta)\), \(\alpha\) and \(\beta\) being the scale and offset parameters, respectively.
- Parameters
arg_1 (iterable of float) – First kernel argument.
arg_2 (iterable of float) – Second kernel argument.
- Returns
float – kernel value.
-
-
class
mulearn.kernel.
PrecomputedKernel
(kernel_computations)[source]¶ Precomputed kernel class.
-
__init__
(kernel_computations)[source]¶ Create an instance of PrecomputedKernel.
- Parameters
kernel_computations (square matrix of float elements) – kernel computations.
- Raises
ValueError if kernel_computations is not a square bidimensional array.
-
compute
(arg_1, arg_2)[source]¶ Compute the kernel value.
The value of a precomputed kernel is retrieved according to the indices of the corresponding objects. Note that each index should be enclosed within an iterable in order to be compatible with sklearn.
- Parameters
arg_1 (iterable of float) – First kernel argument.
arg_2 (iterable of float) – Second kernel argument.
- Returns
float – kernel value.
-
fuzzifier¶
This module implements fuzzifiers used in mulearn.
-
class
mulearn.fuzzifier.
Fuzzifier
[source]¶ Base class for fuzzifiers.
The base class for fuzzifiers is Fuzzifier: it exposes a basic constructor which is called from the subclasses, and two methods get_membership (returning the membership function inferred from data) and get_profile computing information exploitable in order to visualize the fuzzifier in graphical form.
-
get_membership
()[source]¶ Return the induced membership function.
- Raises
NotFittedError if fit has not been called
- Returns
function – the induced membership function
-
get_profile
(X)[source]¶ Return information about the learnt membership function profile.
The profile of a membership function \(\mu: X \rightarrow [0, 1]\) is intended here as the associated function \(p: \mathbb R^+ \rightarrow [0, 1]\) still returning membership degrees, but considering its arguments in the feature space. More precisely, if X contains the values \(x_1, \dots, x_n\), \(R^2\) is the function mapping any point in data space into the squared distance between its image and the center \(a\) of the learnt fuzzy set in feature space, the function get_profile computes the following information about \(p\):
a list \(r_\mathrm{data} = [ R^2(x_i), i = 1, \dots, n]\) containing the distances between the images of the points in X and \(a\);
a list \(\tilde{r}_\mathrm{data}\) containing 200 possible distances between \(a\) and the image of a point in data space, evenly distributed between \(0\) and \(\max r_{\mathrm{data}}\);
a list \(e = [\hat\mu(r_i), r_i \in \tilde{r}_{\mathrm{data}}]\) gathering the profile values for each element in \(\tilde{r}_{\mathrm{data}}\).
This information can be used in order to graphically show the membership profile, which is always plottable, whereas the membership function isn’t mostly of the time (unless the elements in X are either one- or bidimensional vectors).
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
- Returns
list – \([r_{\mathrm{data}}, \tilde{r}_\mathrm{data}, e]\).
-
-
class
mulearn.fuzzifier.
CrispFuzzifier
(profile='fixed')[source]¶ Crisp fuzzifier.
Fuzzifier corresponding to a crisp (classical) set: membership is always equal to either \(0\) or \(1\).
-
__init__
(profile='fixed')[source]¶ Create an instance of
CrispFuzzifier
.- Parameters
profile (str) – method to be used in order to build the fuzzifier profile: ‘fixed’ relies on the radius of the sphere defining the fuzzy set core, while ‘infer’ fits a generic threshold function on the provided examples.
-
fit
(X, y)[source]¶ Fit the fuzzifier on training data.
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
y (vector of floats having the same length of X) – membership degrees of the values in X.
- Raises
ValueError if self.profile is not set either to ‘fixed’ or to ‘infer’.
The fitting process is done considering a threshold-based membership function, in turn corresponding to a threshold-based profile of the form
\[\begin{split}p(r) = \begin{cases} 1 & \text{if $r \leq r_\text{crisp}$,} \\ 0 & \text{otherwise.} \end{cases}\end{split}\]The threshold \(r_\text{crisp}\) is set to the learnt square radius of the sphere when the profile attribute of the class have been set to ‘fixed’, and induced via interpolation of X and y attributes when it is has been set to ‘infer’.
-
-
class
mulearn.fuzzifier.
LinearFuzzifier
(profile='fixed')[source]¶ Crisp fuzzifier.
Fuzzifier corresponding to a fuzzy set whose membership in feature space linearly decreases from 1 to 0.
-
__init__
(profile='fixed')[source]¶ Create an instance of
LinearFuzzifier
.- Parameters
profile (str) – method to be used in order to build the fuzzifier profile: ‘fixed’ relies on the radius of the sphere defining the fuzzy set core, while ‘infer’ fits the profile function on the provided examples.
-
fit
(X, y)[source]¶ Fit the fuzzifier on training data.
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
y (vector of floats having the same length of X) – membership degrees of the values in X.
- Raises
ValueError if self.profile is not set either to ‘fixed’ or to ‘infer’.
The fitting process is done considering a membership function linearly decreasing from \(1\) to \(0\), in turn corresponding to a profile having the general form
\[\begin{split}p(r) = \begin{cases} 1 & \text{if $r \leq r_1$,} \\ l(r) & \text{if $r_1 < r \leq r_0$,} \\ 0 & \text{otherwise.} \end{cases}\end{split}\]The free parameters are chosen in order to guarantee continuity; moreover, when the profile attribute of the class have been set to ‘fixed’ the membership profile will be equal to 0.5 when \(r\) is equal to the learnt square radius of the sphere, and induced via interpolation of X and y when it is has been set to ‘infer’.
-
-
class
mulearn.fuzzifier.
ExponentialFuzzifier
(profile='fixed', alpha=- 1)[source]¶ Exponential fuzzifier.
Fuzzifier corresponding to a fuzzy set whose membership in feature space exponentially decreases from 1 to 0.
-
__init__
(profile='fixed', alpha=- 1)[source]¶ Create an instance of
ExponentialFuzzifier
.- Parameters
profile (str) – method to be used in order to build the fuzzifier profile: ‘fixed’ relies on the radius of the sphere defining the fuzzy set core, ‘infer’ fits the profile function on the provided examples, and ‘alpha’ allows for manually setting the exponential decay via the alpha parameter.
alpha (float) – fixed exponential decay of the fuzzifier.
-
fit
(X, y)[source]¶ Fit the fuzzifier on training data.
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
y (vector of floats having the same length of X) – membership degrees of the values in X.
- Raises
ValueError if self.profile is not set either to ‘fixed’, ‘infer’, or ‘alpha’.
In this fuzzifier, the function that transforms the square distance between the center of the learnt sphere and the image of a point in the original space into a membership degree has the form
\[\begin{split}\mu(r) = \begin{cases} 1 & \text{if $r \leq r_1$,} \\ e(r) & \text{otherwise,} \end{cases}\end{split}\]where \(e\) is an exponential function decreasing from 1 to 0. The shape of this function is chosen so that the membership profile will be equal to 0.5 when \(r\) is equal to the learnt square radius of the sphere, and induced via interpolation of X and y when it is has been set to ‘infer’; finally, when the parameter is set to ‘alpha’ the exponential decay of \(e\) is manually set via the alpha parameter of the class constructor.
-
-
class
mulearn.fuzzifier.
QuantileConstantPiecewiseFuzzifier
[source]¶ Quantile-based constant piecewise fuzzifier.
Fuzzifier corresponding to a fuzzy set with a piecewise constant membership function, whose steps are defined according to the quartiles of the squared distances between images of points and center of the learnt sphere.
-
__init__
()[source]¶ Create an instance of
QuantileConstantPiecewiseFuzzifier
-
fit
(X, y)[source]¶ Fit the fuzzifier on training data.
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
y (vector of floats having the same length of X) – membership degrees of the values in X.
The piecewise membership function is built so that its steps are chosen according to the quartiles of square distances between images of the points in X center of the learnt sphere.
-
-
class
mulearn.fuzzifier.
QuantileLinearPiecewiseFuzzifier
[source]¶ Quantile-based linear piecewise fuzzifier.
Fuzzifier corresponding to a fuzzy set with a piecewise linear membership function, whose steps are defined according to the quartiles of the squared distances between images of points and center of the learnt sphere.
-
__init__
()[source]¶ Create an instance of
QuantileLinearPiecewiseFuzzifier
.
-
fit
(X, y)[source]¶ Fit the fuzzifier on training data.
- Parameters
X (iterable of float vectors having the same length) – Vectors in data space.
y (vector of floats having the same length of X) – membership degrees of the values in X.
The piecewise membership function is built so that its steps are chosen according to the quartiles of square distances between images of the points in X center of the learnt sphere.
-
optimization¶
Implementation of optimization procedures.
This module module contains the implementations of the optimization processes behind fuzzy inference.
Once loaded, the module preliminarily verifies that some libraries are installed (notably, Gurobi and TensorFlow), emitting a warning otherwise. Note that at least one of these libraries is needed in order to solve the optimization problems involved in the fuzzy inference process.
The module also checks the availability of tqdm, which is used in order to graphically depict the progress of some learning processes using a progress bar. However, this package is not strictly needed: if it is not installed, the above mentioned progress bars will not be displayed.
-
class
mulearn.optimization.
Solver
[source]¶ Abstract solver for optimization problems.
The base class for solvers is
Solver
: it exposes a method solve which delegates the numerical optimization process to an abstract method solve_problem and subsequently clips the results to the boundaries of the feasible region.-
solve
(xs, mus, c, k)[source]¶ Solve optimization phase.
Build and solve the constrained optimization problem on the basis of the fuzzy learning procedure.
- Parameters
xs (iterable) – Objects in training set.
mus (iterable) – Membership values for the objects in xs.
c (float) – constant managing the trade-off in joint radius/error optimization.
k (
mulearn.kernel.Kernel
) – Kernel function to be used.
- Raises
ValueError if c is non-positive or if xs and mus have different lengths.
- Returns
list – optimal values for the independent variables of the problem.
-
-
class
mulearn.optimization.
GurobiSolver
(time_limit=600, adjustment=0, initial_values=None)[source]¶ Solver based on gurobi.
Using this class requires that gurobi is installed and activated with a software key. The library is available at no cost for academic purposes (see https://www.gurobi.com/downloads/end-user-license-agreement-academic/). Alongside the library, also its interface to python should be installed, via the gurobipy package.
-
__init__
(time_limit=600, adjustment=0, initial_values=None)[source]¶ Build an object of type GurobiSolver.
- Parameters
time_limit (int) – Maximum time (in seconds) before stopping iterative optimization, defaults to 10*60.
adjustment (float or ‘auto’) – Adjustment value to be used with non-PSD matrices, defaults to 0. Specifying ‘auto’ instead than a numeric value will automatically trigger the optimal adjustment if needed.
initial_values (iterable of floats or None) – Initial values for variables of the optimization problem, defaults to None.
-
solve_problem
(xs, mus, c, k)[source]¶ Optimize via gurobi.
Build and solve the constrained optimization problem at the basis of the fuzzy learning procedure using the gurobi API.
- Parameters
xs (iterable) – objects in training set.
mus (iterable) – membership values for the objects in xs.
c (float) – constant managing the trade-off in joint radius/error optimization.
k (
mulearn.kernel.Kernel
) – kernel function to be used.
- Raises
ValueError if optimization fails or if gurobi is not installed
- Returns
list – optimal values for the independent variables of the problem.
-
-
class
mulearn.optimization.
TensorFlowSolver
(initial_values='random', init_bound=0.1, n_iter=100, optimizer=None, tracker=<function trange>, penalization=10)[source]¶ Solver based on TensorFlow.
Using this class requires that TensorFlow 2.X is installed.
-
__init__
(initial_values='random', init_bound=0.1, n_iter=100, optimizer=None, tracker=<function trange>, penalization=10)[source]¶ Build an object of type TensorFlowSolver.
- Parameters
initial_values (str or iterable of float) – values to be used for initializing the independent variables, either randomly (if set to ‘random’)` or seting them to a given sequence of initial values (if set to an iterable of floats), defaults to ‘random’.
init_bound (float) – Absolute value of the extremes of the interval used for random initialization of independent variables, defaults to 0.1.
n_iter (int) – Number of iterations of the optimization process, defaults to 100.
optimizer (
tf.keras.optimizers.Optimizer
) – Optimization algorithm to be used, defaults to Adam with learning rate=1e-4 if tensorflow is available, to None otherwise.tracker (object) – Tool to graphically depict the optimization progress, defaults to tqdm.trange if tqdm is available, to range (i.e., no graphical tool) otherwise.
penalization (float) – Lagrange penalization for the equality constraint in the original problem, defaults to 10.
-
solve_problem
(xs, mus, c, k)[source]¶ Optimize via TensorFlow.
Build and solve the constrained optimization problem on the basis of the fuzzy learning procedure using the TensorFlow API.
- Parameters
xs (iterable) – objects in training set.
mus (iterable) – membership values for the objects in xs.
c (float) – constant managing the trade-off in joint radius/error optimization.
k (
mulearn.kernel.Kernel
) – kernel function to be used.
- Raises
ValueError if optimization fails or if TensorFlow is not installed
- Returns
list – optimal values for the independent variables of the problem.
-
distributions¶
Mulearn distributions.
This module implements the kernel and fuzzifier distributions used in randomized model selection.
-
class
mulearn.distributions.
GaussianKernelDistribution
(low=0, high=1)[source]¶ Uniform distribution for gaussian kernels.
-
__init__
(low=0, high=1)[source]¶ Build an object of type GaussianKernelDistribution.
- Parameters
low (float) – Lower bound of the interval defining the support of the uniform distribution associated to the parameter \(\sigma\) of a
mulearn.kernel.GaussianKernel
, defaults to 0.high (float) – Upper bound of the interval defining the support of the uniform distribution associated to the parameter \(\sigma\) of a
mulearn.kernel.GaussianKernel
, defaults to 1.
- Raises
ValueError if the arguments low and high do not define an interval (that is, low is not lower than high).
-
rvs
(*args, **kwargs)[source]¶ Generate a Gaussian kernel with uniformly distributed parameter.
- Returns
mulearn.kernel.GaussianKernel
– Gaussian kernel having a parameter uniformly chosen at random in the interval having self.low and self.high as extremes.
-
-
class
mulearn.distributions.
ExponentialFuzzifierDistribution
(low=0, high=1)[source]¶ Uniform distribution for gaussian kernels.
-
__init__
(low=0, high=1)[source]¶ Build an object of type ExponentialFuzzifierDistribution.
- Parameters
low (float) – Lower bound of the interval defining the support of the uniform distribution associated to the parameter \(lpha\) of a
mulearn.fuzzifier.ExponentialFuzzifier
, defaults to 0.high (float) – Upper bound of the interval defining the support of the uniform distribution associated to the parameter \(lpha\) of a
mulearn.fuzzifier.ExponentialFuzzifier
, defaults to 1.
- Raises
ValueError if the arguments low and high do not define an interval (that is, low is not lower than high).
-
rvs
(*args, **kwargs)[source]¶ Generate an Exponential fuzzifier with uniformly distributed parameter.
- Returns
mulearn.fuzzifier.ExponentialFuzzifier
– Exponential fuzzifier having a parameter uniformly chosen at random in the interval having self.low and self.high as extremes.
-