CreateMetalogDistributionFromPercentiles

Introduction

Sometimes you don't have raw historical data to fit a distribution to — only an expert's estimate of "low, likely, high" (say, P10, P50, and P90) for a task duration or a threat window. CreateMetalogDistributionFromPercentiles reconstructs a full, any-shape Metalog distribution from just those quantiles, however few, and returns as many random samples as you need — turning a handful of elicited numbers into a proper input for a Monte Carlo simulation.

Teaching Note

Fitting from percentiles is essential for:

Project Management: Estimating task durations using P10 (low), P50 (likely), and P90 (high) elicitation.
Intelligence Analysis: Quantifying expert uncertainty regarding threat arrival windows or asset reliability.
Epidemiology: Reconstructing disease transmission parameters from reported quantiles in literature.
Risk Management: Modeling potential annual losses based on expert-defined "worst-case" and "median" scenarios.
Finance: Simulating asset price movements based on historical P25, P50, and P75 levels.
Environmental Science: Assessing cumulative flood risk from historical return-period quantiles.
Healthcare: Modeling patient throughput or surgery durations based on reported wait-time percentiles.
Quality Engineering: Simulating part tolerances based on design specification limits (e.g., LSL/USL).

Parameters

Parameter	Type	Default	Description
`list_of_values`required	`list`	—	The numerical values corresponding to the cumulative probabilities/percentiles.
`list_of_percentiles`required	`list`	—	The cumulative probabilities (between 0 and 1) for each value in list_of_values.
`lower_bound`	`float`	`None`	The logical lower bound for the distribution (e.g., 0 for duration). If provided along with upper_bound, a bounded metalog is created. Defaults to None.
`upper_bound`	`float`	`None`	The logical upper bound for the distribution. If provided along with lower_bound, a bounded metalog is created. Defaults to None.
`learning_rate`	`float`	`0.01`	The step length for the metalog fit algorithm. Defaults to 0.01.
`term_maximum`	`int`	`None`	The maximum number of terms in the metalog expansion. If None, it defaults to the number of provided percentiles. Defaults to None.
`term_minimum`	`int`	`2`	The minimum number of terms allowed. Defaults to 2.
`term_for_random_sample`	`int`	`None`	The specific number of terms used for generating samples. If None, the term_limit from the fitted distribution is used. Defaults to None.
`number_of_samples`	`int`	`10000`	The number of stochastic samples to generate. Defaults to 10000.
`variable_name`	`str`	`'Simulated Value'`	Label for the variable in the output DataFrame and plot. Defaults to 'Simulated Value'.
`show_summary`	`bool`	`True`	Whether to print the pymetalog summary of coefficients and validation results. Defaults to True.
`return_format`	`str`	`'dataframe'`	The format of the output: 'dataframe' (pd.DataFrame) or 'array' (np.ndarray). Defaults to 'dataframe'.
`show_distribution_plot`	`bool`	`True`	Whether to display a histogram of the generated samples. Defaults to True.
`figure_size`	`tuple`	`(8, 6)`	The size of the plot figure in inches (width, height). Defaults to (8, 6).
`fill_color`	`str`	`'#999999'`	The hex color code for the histogram bars. Defaults to '#999999'.
`fill_transparency`	`float`	`0.6`	The transparency level (0-1) for the histogram plot. Defaults to 0.6.
`show_mean`	`bool`	`True`	Whether to display the mean as a vertical dashed line on the plot. Defaults to True.
`show_median`	`bool`	`True`	Whether to display the median as a vertical dotted line on the plot. Defaults to True.
`show_y_axis`	`bool`	`False`	Whether to display the frequency/density scale on the y-axis. Defaults to False.
`title_for_plot`	`str`	`None`	The main title for the distribution plot. Defaults to None.
`subtitle_for_plot`	`str`	`None`	The descriptive subtitle for the plot. Defaults to None.
`caption_for_plot`	`str`	`None`	Optional caption text displayed at the bottom of the plot. Defaults to None.
`data_source_for_plot`	`str`	`None`	Optional data source identification text. Defaults to None.
`title_y_indent`	`float`	`1.1`	Vertical position for the title text. Defaults to 1.1.
`subtitle_y_indent`	`float`	`1.05`	Vertical position for the subtitle text. Defaults to 1.05.
`caption_y_indent`	`float`	`-0.15`	Vertical position for the caption text. Defaults to -0.15.

Returns

The generated samples from the fitted Metalog distribution — a pandas DataFrame or a NumPy array, depending on return_format.

Example

python

from analysistoolbox.simulations import CreateMetalogDistributionFromPercentiles

# Project Management: simulating task duration from P10, P50, and P90 estimates
durations = CreateMetalogDistributionFromPercentiles(
    list_of_values=[5, 12, 30],
    list_of_percentiles=[0.1, 0.5, 0.9],
    lower_bound=0,
    variable_name='Days to Complete',
    title_for_plot="Estimated Project Duration"
)