The properties

nsim

nsim - number of simulations

procedure

procedure - sampling procedure [{‘uniform’}|’latin_hypercube’|’sobol’|’halton’|user-defined]

parameter_names

parameter_names - names of the parameters

samples

samples - sampled draws

is_behaved

is_behaved - Boolean vector describing the draws

nparam

nparam - number of parameters

number_of_outputs

number_of_outputs - number of output of the behavior function

user_outputs

user_outputs - user requested additional outputs

The methods

cdf

Calculate the cumulative distribution function (CDF) for a given parameter.

Syntax
d=cdf(obj,pname)
Inputs:

obj [mcf object]:

pname [char]: name of the parameter which one wants the cdf for.

Outputs:

d [struct]: with fields lb, ub, x, f_behave, f_non_behave, x_good, x_bad

cdf_plot

plot of the cumulative distribution functions
hdl=cdf_plot(obj)
hdl=cdf_plot(obj,pnames)
hdl=cdf_plot(obj,pnames,title)
Inputs:

obj [mcf object]:

pnames [empty|char|cellstr]: names of the parameters of interest

titel [empty|char]: title of the figures

Outputs:

hdl [vector]: handles to the plotted figures

cluster_analysis

CLUSTER_ANALYSIS - Performs k-means clustering on behaved and non-behaved parameter samples and visualizes the clusters using the first two principal components.

Syntax:
cluster_analysis(obj, num_clusters)

Description:
This method applies k-means clustering to the parameter vectors classified as “behave” (acceptable) and “non-behave” (unacceptable). It first combines the two groups of parameter samples and then performs k-means clustering, assigning each sample to one of the specified number of clusters. The results of the clustering are visualized by projecting the samples onto the first two principal components using Principal Component Analysis (PCA). The clusters are displayed in a scatter plot, with different colors representing different clusters.

Input Arguments:

obj : An instance of the ‘mcf’ class that contains the parameter samples and their behavior classifications (behave and non-behave).

num_clusters : The number of clusters for the k-means algorithm to identify. This should be a positive integer specifying how many distinct clusters to form.

Outputs:

A scatter plot is generated, showing the parameter samples projected onto the first two principal components. The points are colored according to the cluster to which they have been assigned by the k-means algorithm.

Usage:
Use this method after performing Monte Carlo filtering to explore how parameter samples from the behaved and non-behaved groups cluster. This can help reveal hidden structures or subgroups within the parameter space.

Example:
% Assuming ‘mcf_obj’ is an instance of the ‘mcf’ class: mcf_obj.cluster_analysis(3); % For 3 clusters

Notes:

k-means clustering is an unsupervised machine learning algorithm that groups samples into num_clusters based on the proximity of the samples in the parameter space.

PCA is used to reduce the dimensionality of the parameter space to two components for visualization purposes. The scatter plot shows the clustering results projected onto these two components, but the clustering itself is performed in the full parameter space.

Different colors in the scatter plot correspond to different clusters identified by the k-means algorithm.

Methodology:

Combine the behaved and non-behaved parameter samples into a single matrix.

Perform k-means clustering using the kmeans function, with num_clusters as the specified number of clusters.

Apply PCA to reduce the dimensionality of the parameter samples to two components for visualization.

Visualize the clusters in a scatter plot where the points are colored according to their assigned cluster.

Analysis:

The clustering results help to identify patterns or subgroups within the parameter samples. By examining the clusters, users can determine whether certain parameter combinations tend to group together in the behaved or non-behaved samples.

The scatter plot based on PCA provides a simplified 2D visualization of the clusters, making it easier to interpret the results.

See also

KMEANS, PCA, GSCATTER

correlation_analysis

CORRELATION_ANALYSIS - Computes and visualizes correlation matrices for behaved and non-behaved parameter samples.

Syntax:
correlation_analysis(obj)

Description:
This method calculates the correlation matrices for parameter vectors that are classified as “behave” (acceptable) and “non-behave” (unacceptable) based on the Monte Carlo filtering process. It generates a side-by-side comparison of the correlation matrices for both groups using heatmap visualizations. This allows users to detect similarities and differences in the relationships between parameters in the behaved and non-behaved groups.

Input Arguments:

obj : An instance of the ‘mcf’ class containing the parameter samples and their classifications (behave and non-behave).

Outputs:

Two correlation matrices are displayed as heatmaps: 1. The correlation matrix for the behaved (acceptable) parameter samples. 2. The correlation matrix for the non-behaved (unacceptable) parameter samples.

Usage:
Use this method after performing Monte Carlo filtering to examine the relationship between parameters in the behaved and non-behaved groups.

Example:
% Assuming ‘mcf_obj’ is an instance of the ‘mcf’ class: mcf_obj.correlation_analysis();

Notes:

Correlation matrices show the linear relationships between parameters. Values near 1 indicate a strong positive correlation, while values near -1 indicate a strong negative correlation. Values close to 0 suggest little or no linear relationship.

This method helps users identify which parameters are more strongly related within each group and highlights differences in correlation patterns between behaved and non-behaved parameter samples.

Methodology:

Calculate the correlation matrix for the “behave” group (acceptable parameter samples) using the corrcoef function.

Calculate the correlation matrix for the “non-behave” group (unacceptable parameter samples) using the corrcoef function.

Display both correlation matrices as heatmaps using the imagesc function, with a colorbar indicating the strength of the correlations.

Analysis:

The side-by-side heatmaps provide a visual representation of how parameter interactions differ between behaved and non-behaved groups.

By comparing the correlation matrices, users can detect areas where parameters are more or less correlated across the two groups, helping to understand how parameter interactions affect model behavior.

See also

CORRCOEF, IMAGESC, COLORBAR

correlation_patterns_plot

Generate a plot of correlation patterns among parameters.

Syntax:
hdl=correlation_patterns_plot(obj)
hdl=correlation_patterns_plot(obj,names)
hdl=correlation_patterns_plot(obj,names,type)
hdl=correlation_patterns_plot(obj,names,type,pval_cutoff)
Inputs:

obj [mcf object]:

names [empty|char|cellstr]: names of the parameters of interest

type [empty|’behave’|’non-behave’]: if empty, all the sample is considered. If ‘behave’ only the behavior sample is considered. If ‘non-behave’, only the non-behavior sample is considered.

pval_cutoff [numeric|{0.05}]: cutoff for significant correlations

Outputs:

hdl [vector]: handles to the plotted figures

heatmap_analysis

HEATMAP_ANALYSIS - Generates heatmaps of correlation matrices for behaved and non-behaved parameter samples.

Syntax:
heatmap_analysis(obj)

Description:
This method calculates and visualizes the correlation structure of parameter vectors that are classified as “behave” (acceptable) or “non-behave” (unacceptable) according to the filtering process. The correlation matrices for each group are computed and displayed as heatmaps. These visualizations help in quickly identifying areas where strong correlations or significant differences exist within and between the two groups, making it easier to compare parameter interactions.

Input Arguments:

obj : An instance of the ‘mcf’ class that contains sampled parameter vectors and their behavior classifications (behave and non-behave).

Outputs:

Two heatmaps are displayed: 1. The correlation matrix heatmap for the behaved (acceptable) parameter samples. 2. The correlation matrix heatmap for the non-behaved (unacceptable) parameter samples.

Usage:
Call this method after performing Monte Carlo filtering to visualize the correlation patterns of parameter samples classified as behaved and non-behaved.

Example:
% Assuming ‘mcf_obj’ is an instance of the ‘mcf’ class: mcf_obj.heatmap_analysis();

Notes:

This method is useful in detecting strong parameter correlations and differences in the interaction of parameters across the two groups.

The resulting heatmaps provide a visual representation of parameter correlation patterns, where the color scale indicates the strength of the correlations.

Methodology:

Calculate the correlation matrix for the “behave” group (acceptable parameter samples).

Calculate the correlation matrix for the “non-behave” group (unacceptable parameter samples).

Display each correlation matrix as a heatmap.

Analysis:

The heatmaps allow you to quickly identify areas with strong correlations or significant differences between the two groups.

Compare the heatmaps to spot differences in parameter correlations across the “behave” and “non-behave” groups. Look for areas where certain parameters are highly correlated in one group but not in the other, or where overall correlation structures differ.

See also

CORRELCOEF, HEATMAP

kolmogorov_smirnov_test

Perform a Kolmogorov-Smirnov test to compare two distributions

Syntax:

[pValue, Dn, xn, largest] = kolmogorov_smirnov_test(d)

Inputs:

d : MCF object with distributions

Outputs:

pValue  : P-value of the test
Dn      : D-statistic of the test
xn      : Critical value
largest : Index of the largest difference

logistic_regression

LOGISTIC_REGRESSION - Performs logistic regression to identify parameters that differentiate between behaved and non-behaved parameter samples.

Syntax:
logistic_regression(obj)

Description:
This method applies logistic regression to the parameter vectors in the “behave” (acceptable) and “non-behave” (unacceptable) groups. The goal is to determine which parameters most strongly influence whether a parameter vector is classified as behaved or non-behaved. The method generates a logistic regression model using the parameter samples as inputs and the behaved/non-behaved classification as the binary response variable. The regression coefficients are then displayed to show the relative importance of each parameter in predicting group membership.

Input Arguments:

obj : An instance of the ‘mcf’ class containing the parameter samples and their behavior classifications (behave and non-behave).

Outputs:

The logistic regression model coefficients are displayed in the MATLAB command window. These coefficients indicate the strength and direction of the relationship between each parameter and the likelihood of a parameter vector being classified as behaved or non-behaved.

Usage:
Use this method after Monte Carlo filtering to identify which parameters are most predictive of whether a parameter vector satisfies the desired behavior.

Example:
% Assuming ‘mcf_obj’ is an instance of the ‘mcf’ class: mcf_obj.logistic_regression();

Notes:

Logistic regression is a classification technique that models the probability of a binary outcome (behaved vs. non-behaved) based on input parameters. The output is a set of regression coefficients, one for each parameter, that indicates how strongly each parameter influences the probability of the outcome.

Positive coefficients suggest that higher values of the parameter increase the likelihood of the parameter vector being classified as behaved, while negative coefficients suggest the opposite.

Methodology:

Create a binary label vector: 1 for behaved parameter vectors and 0 for non-behaved parameter vectors.

Perform logistic regression using the fitglm function, with the parameter vectors as predictors and the binary labels as the response.

Display the coefficients from the logistic regression model, which represent the relationship between each parameter and the binary outcome.

Analysis:

The logistic regression model allows users to understand which parameters are most predictive of whether a parameter vector satisfies the desired behavior. By examining the coefficients, users can identify key parameters that drive the behavior classification.

This method is particularly useful for narrowing down a set of parameters to focus on those that have the greatest influence on whether a model simulation meets desired criteria.

See also

FITGLM, BINOMIAL DISTRIBUTION

make_random_draws

make_random_draws Generates random samples based on different procedures.

samples = make_random_draws(lb, ub, nsim, procedure) returns an array of random samples between the lower bounds (lb) and upper bounds (ub) based on the sampling procedure specified. The function supports both predefined sampling methods and custom function handles.

INPUTS:

lbLower bound, a column vector where each row corresponds
to the lower bound for a parameter.

ubUpper bound, a column vector where each row corresponds
to the upper bound for a parameter.

nsimNumber of samples (positive integer), which determines the
number of samples to generate.

procedureSampling procedure, can be a string or a function handle:

‘uniform’ : Samples are drawn uniformly between lb and ub.

‘latin_hypercube’ : Samples are generated using the Latin hypercube method.

‘sobol’ : Samples are generated using the Sobol sequence.

‘halton’ : Samples are generated using the Halton sequence.

Custom functionA user-defined function handle that takes lb, ub,
and nsim as inputs and returns the samples.

OUTPUT:

samplesA matrix of size (nparam, nsim), where nparam is the number
of parameters (i.e., length of lb or ub). Each column of the matrix corresponds to a sample.

EXAMPLES:
% Example 1: Uniform sampling lb = [0; 1]; ub = [10; 5]; nsim = 100; samples = make_random_draws(lb, ub, nsim, ‘uniform’);

% Example 2: Using Latin Hypercube sampling samples = make_random_draws(lb, ub, nsim, ‘latin_hypercube’);

% Example 3: Using a custom sampling function custom_fn = @(lb, ub, nsim) lb + (ub - lb) .* rand(size(lb, 1), nsim); samples = make_random_draws(lb, ub, nsim, custom_fn);

ERROR HANDLING:
The function throws an error if the procedure is unknown or invalid.

mcf

Constructor for Monte Carlo filtering
obj=mcf(check_behavior,nsim_or_draws)

obj=mcf(check_behavior,nsim_or_draws,lb)

obj=mcf(check_behavior,nsim_or_draws,lb,ub)

obj=mcf(check_behavior,nsim_or_draws,lb,ub,names)

obj=mcf(check_behavior,nsim_or_draws,lb,ub,names,procedure_)
Inputs:

check_behavior (function_handle | cell | vector):

when it is a function handle, the function takes as input a vector of parameters and returns in its first output a boolean that is true if the paramter satisfies the behavior and false otherwise. The procedure is going to check the number of output arguments that the function returns and collect all those extra output arguments while sampling.

when it is a cell, it should be a two-element cell such that the first element is the function handle and the second is the number of outputs desired by the user.

if it is a vector, all elements are either 0 or 1 or boolean, describing whether each parameter vector checks the behavior or not.

nsim_or_draws (integer | matrix): When it is an integer, nsim_or_draws is the number of draws to sample. When it is a matrix, it is the draws. No further sampling will be performed.

lb (empty | vector): lower bound of the search space

ub (empty | vector): upper bound of the search space

names (empty|char|cellstr]: names of the parameters. If empty, the names are created as p_i, where “i” is the order of the parameter in the list.

procedure_ ({‘uniform’} | ‘latin_hypercube’ | ‘sobol’ | ‘halton’ | user-defined): when it is user-defined, it should be a function handle, and should take 3 inputs(lb, ub, nsim) and return a parameter draw.

Outputs:
:

obj [mcf object]: containing, among other things, the samples, a flag determining their behavior.

pairwise_scatter

PAIRWISE_SCATTER - Generates pairwise scatter plots for parameter samples in the “behave” and “non-behave” groups.

Syntax:
pairwise_scatter(obj)

Description:
This method creates a grid of pairwise scatter plots for all the parameters, allowing for a visual inspection of the relationships between different parameter pairs. It combines parameter samples that are classified as “behave” (acceptable) and “non-behave” (unacceptable) according to the filtering process. The scatter plots make it easier to detect patterns, clusters, or correlations between parameter pairs within and across both groups.

Input Arguments:

obj : An instance of the ‘mcf’ class containing the parameter samples and their behavior classifications (behave and non-behave).

Outputs:

A matrix of scatter plots is displayed. Each scatter plot represents the relationship between two different parameters, with points from both behaved and non-behaved groups plotted together.

Usage:
Call this method after performing Monte Carlo filtering to visually explore the relationships between different parameters.

Example:
% Assuming ‘mcf_obj’ is an instance of the ‘mcf’ class: mcf_obj.pairwise_scatter();

Notes:

The scatter plot matrix includes both behaved and non-behaved parameter vectors in a single view, making it easier to spot differences between the groups.

Pairwise scatter plots are particularly useful for visually detecting clusters, outliers, correlations, or non-linear relationships between parameter pairs.

Methodology:

Combine the parameter vectors from both the “behave” and “non-behave” groups into a single matrix.

Generate a matrix of scatter plots where each scatter plot represents the relationship between two different parameters.

Display the scatter plot matrix.

Analysis:

The pairwise scatter plots allow for quick identification of relationships between parameters. Patterns such as clustering, correlations, or other trends may emerge when comparing behaved and non-behaved parameter vectors.

Inspect the plots to see if certain parameter combinations show clear separations between the behaved and non-behaved groups, or if there are parameters that seem to behave similarly across the two groups.

See also

PLOTMATRIX, SCATTER

pca_analysis

PCA_ANALYSIS - Performs Principal Component Analysis (PCA) on behaved and non-behaved parameter samples and visualizes the results on the first two principal components.

Syntax:
pca_analysis(obj)

Description:
This method applies Principal Component Analysis (PCA) to the parameter vectors that are classified as “behave” (acceptable) and “non-behave” (unacceptable) based on the Monte Carlo filtering process. PCA is used to reduce the dimensionality of the parameter space, allowing for the visualization of the primary patterns or variance in the data. The method generates a scatter plot showing the projection of parameter samples onto the first two principal components, with behaved and non-behaved samples distinguished by color.

Input Arguments:

obj : An instance of the ‘mcf’ class containing the parameter samples and their behavior classifications (behave and non-behave).

Outputs:

A scatter plot is generated, showing the parameter samples projected onto the first two principal components. Behaved samples are colored in blue, and non-behaved samples are colored in red.

Usage:
Use this method after Monte Carlo filtering to visually explore the variance structure of the parameter space and identify patterns or separations between behaved and non-behaved groups.

Example:
% Assuming ‘mcf_obj’ is an instance of the ‘mcf’ class: mcf_obj.pca_analysis();

Notes:

Principal Component Analysis (PCA) is a dimensionality reduction technique that identifies the directions (principal components) along which the variance in the data is maximized.

This method reduces the parameter space to two components for visualization purposes. The scatter plot displays the projection of the samples onto the first two principal components, with color-coding to distinguish between behaved and non-behaved samples.

The first two principal components capture the majority of the variance in the data, making them ideal for visualizing overall patterns and separations between the groups.

Methodology:

Combine the behaved and non-behaved parameter samples into a single matrix.

Apply Principal Component Analysis (PCA) to the combined parameter matrix using the pca function.

Visualize the results by plotting the first two principal components (PC1 and PC2) in a scatter plot.

Use different colors to represent the behaved (blue) and non-behaved (red) parameter samples in the scatter plot.

Analysis:

The PCA scatter plot allows for a visual inspection of how parameter vectors are distributed along the principal components, revealing patterns of variance between the behaved and non-behaved groups.

If the behaved and non-behaved samples are well-separated along the first two principal components, this suggests that certain parameter combinations are more strongly associated with the desired behavior.

By examining how much variance is explained by the first two components (via the latent variable), users can assess how effectively the PCA represents the overall data structure.

See also

PCA, SCATTER

scatter

Scatter plot of the data
hdl=scatter(obj)
hdl=scatter(obj,names)
hdl=scatter(obj,names,type)
hdl=scatter(obj,names,type,pval_cutoff)
hdl=scatter(obj,names,type,pval_cutoff,title)
Inputs:

obj [mcf object]:

names [empty|char|cellstr]: names of the parameters of interest

type [empty|’behave’|’non-behave’]: if empty, all the sample is considered. If ‘behave’ only the behavior sample is considered. If ‘non-behave’, only the non-behavior sample is considered.

pval_cutoff [numeric|{0.05}]: cutoff for significant correlations

title [empty|char]: title of the figures

Outputs:

hdl [vector]: handles to the plotted figures