API Documentation¶

class lvr.Lvr(effects=None, causes=None, list_dict=None, descending=True, decimals=2)¶

Chief facility to explore cause-effect characteristics of a given list of effect (and optional cause) values.

Primary methods:

Overview of relevant cause-effect relationships? => lvr.Lvr.tbl()
Search for a specific cause-effect relationship? => lvr.Lvr.summary()

Additional methods:

lvr.Lvr.select() restricts the list of lvr.Lvr.tbl() incorporating lvr.Selector.
lvr.Lvr.first() returns the first, lvr.Lvr.last() the last element of the restricted list.
lvr.Lvr.throughput() determines the time and result share for elements selected by lvr.Selector at a given capacity.
lvr.Lvr.accounting() translates the different throughput for all elements, the vital few only and the useful many only into income statements employing capex and opex shares.

Parameters:

effects (Optional[iterable[number]], default None) – Effect values (≥ 0)
causes (Optional[iterable[number]], default None) – Cause values.
list_dict (Optional[list_dict], default None) – List of dicts with cause and effect values, their cumulative values and indices.
descending (Optional[bool], default True) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest.
decimals (Optional[int], default 2) – Number of decimals to round to.

Note

You may provide effects only or effects with causes. Alternatively you can provide a list_dict directly; but _not_ effects and/or causes and list_dict together.

summary(effects=None, causes=None, guess=False, descending=None, decimals=None)¶

Returns cause effect relation that is nearest to effects.

Parameters:

effects (number, default 0.5) – Cumulative effect value to attain distribution to.
causes (Optional[number], default None) – Cumulative cause value to attain distribution to.
guess (bool, default False) – Determine most relevant cause-effect relation automatically.
descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest.
decimals (Optional[int]) – Number of decimals to round to.

Examples

lvr.Lvr.summary() is your friend:

>>> Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).summary()
{'causes': 0.1, 'effects': 0.46, 'entropy_ratio': 0.71, 'pareto': True}

lvr.Lvr.summary() returns you a relation near 50 percent of effects.

You may insist on a specific effects threshold:

>>> Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).summary(effects=0.8)
{'causes': 0.2, 'effects': 0.8, 'entropy_ratio': 0.71, 'pareto': True}

Alike for a causes threshold:

>>> Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).summary(causes=0.2)
{'causes': 0.2, 'effects': 0.8, 'entropy_ratio': 0.71, 'pareto': True}

Rule of 50/5:

The rule 50/5 means that 50 percent of causes make up 5 percent of effects.

>>> from lvr import Lvr
>>> from lvr.data import forest_fires, meteorites, debris_masses
>>> Lvr(forest_fires()).summary()
{'causes': 0.014, 'effects': 0.5, 'entropy_ratio': 0.8, 'pareto': True}

50 percent of forest fire area goes back to 1.4 percent of fires.

>>> dm = Lvr(debris_masses())
>>> dm.first(s, descending=False)
{'causes': 0.02, 'effects': 0.5, 'entropy_ratio': 0.73, 'pareto': True}

50 percent of total mass is made up by 2 percent of debris.

>>> Lvr(meteorites()).summary()
{'causes': 0.004, 'effects': 0.5, 'entropy_ratio': 0.71, 'pareto': True}

50 percent of total mass is made up by 0.4 percent of meteorites only.

tbl(descending=None, decimals=None)¶

Returns dictionary of most relevant cumulative cause-effect relations.

Parameters:	descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest. decimals (Optional[int]) – Number of decimals to round to.

Example

>>> l = Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
>>> l.tbl()
{0.1: 0.46, 0.2: 0.8, 0.3: 0.9, 0.6: 0.96, 0.9: 1.0}

separate(selector, descending=None, decimals=None)¶

Shows effect of separating elements by selector on spread of mean and median and stdev/mean ratio for all elements, vital few only and useful many only.

Parameters:	selector (`Selector`) – Subset definition. descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest. decimals (Optional[int], default None) – Number of decimals to round to.

Usually mean/median and stdev/mean ratio drop for each subset compared to all elements.

Example

>>> l = Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
>>> s = Selector(causes=(0, 0.2))
>>> l.separate(s)
GROUP          MEAN/MEDIAN    STDEV/MEAN
-----------  -------------  ------------
{1: 1}                4.59          1.57
{0.1: 0.46}           1             0.12
{0.9: 0.54}           1.37          0.81

throughput(selector, capacity, descending=None, counterpart=False, decimals=None)¶

Tells how much periods are required to process elements selected by selector at given capacity per period.

Parameters:

selector (Selector) – Subset definition.
capacity (number) – Available capacity (causes per period).
descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest.
counterpart (Optional[bool], default False) – Return result of complement if True.
decimals (Optional[int], default None) – Number of decimals to round to.

Example

>>> l = Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
>>> l = Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
>>> s = Selector(causes=(0, 0.2))
>>> l.throughput(s, capacity=0.5)
{'periods': 4.0, 'results': 0.8}

We need four periods to get 80 percent of results.

>>> s = Selector(effects=(0, 1))
>>> l.throughput(s, capacity=0.5)
{'periods': 20.0, 'results': 1.0}

But for 100 percent, we need 20 periods. For the remaining 20 percentage points in results we need four times the previous time.

accounting(selector, capacity, capex, opex, descending=None, counterpart=False, decimals=None)¶

Assess financial effect of putting through elements selected by selector at given capacity.

Parameters:

selector (Selector) – Subset definition.
capacity (number) – Available capacity (causes per period).
capex (number) – Share of capital expenditures of revenue.
opex (number) – Share of operational expenditures of revenue.
descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest.
decimals (Optional[int], default None) – Number of decimals to round to.

capex and opex are shares, hence must add up to 1.

Example

>>> l = Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
>>> s = Selector(causes=(0, 0.2))
>>> results = l.accounting(s, capacity=0.5, capex=0.55, opex=0.45)
>>> from pandas import DataFrame # requires pandas module
>>> pd = DataFrame.from_dict(results, orient='index')
>>> pd.round(2)
             periods  revenue  capex  opex  income  period_income
complete_tp     20.0    100.0   55.0  45.0    -0.0          -0.00
umany_tp        16.0     20.0   44.0  36.0   -60.0          -3.75
vfew_tp          4.0     80.0   11.0   9.0    60.0          15.00

We can get an income of 15 for each of four periods. Or an income of 0 for 20 periods. That is since the useful many incur a loss of -3.75 per period.

select(selector=None, descending=None, decimals=None, extended=False)¶

Returns dictionary of cumulative cause-effect relations selected by selector.

Parameters:	selector (Optional[`Selector`], default None) – Subset definition. descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest. decimals (Optional[int]) – Number of decimals to round to. extended (Optional[bool], default False) – Return extended list of dicts.

Example

>>> l = lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
>>> s = Selector(causes=(0, 0.2))
>>> l.select(s)
{0.1: 0.46, 0.2: 0.8}

first(selector, descending=None, decimals=None, extended=False)¶

Returns first cumulative cause-effect relation selected by selector.

Parameters:	selector (`Selector`) – Subset definition. descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest. decimals (Optional[int], default None) – Number of decimals to round to. extended (Optional[bool], default False) – Returns extended list of dicts.

last(selector, descending=None, decimals=None, extended=False)¶

Returns last cumulative cause-effect relation selected by selector.

Parameters:	selector (`Selector`) – Subset definition. descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest. decimals (Optional[int], default None) – Number of decimals to round to. extended (Optional[bool], default False) – Returns extended list of dicts.

best(descending=None, decimals=None)¶

Returns most relevant cumulative cause-effect relation.

Parameters:	descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest. decimals (Optional[int], default None) – Number of decimals to round to.

effect_values(selector, descending=None, counterpart=False)¶

Returns effect_values selected by selector.

Parameters:	selector (`Selector`) – Subset definition. descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest. counterpart (Optional[bool], default False) – Return result of complement if True.

running_share()¶

Returns extended list of dicts of running cause-effect relations, including indices and cause and effect values.

Parameters:	descending (bool) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest.

indices(selector, descending=None, counterpart=False)¶

Returns indices of elements selected by selector.

Parameters:	selector (`Selector`) – Subset definition. descending (Optional[bool]) – Sort effect values (more precise: effect/cause value ratio) from biggest to smallest. counterpart (Optional[bool], default False) – Return result of complement if True.

class lvr.Selector(causes=None, effects=None)¶

Selector specifies a subset to retrieve from cause-effect relations.

causes=0.2 will select a range from 0.2 to 1.0 of causes. effects works alike.

Examples

>>> s = Selector(causes=0.2)
>>> Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).first(s)
{0.2: 0.8}

>>> s = Selector(causes=0.2, effects=(0.6, 0.95))
>>> Lvr([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).first(s)
{0.5: 0.95}

class lvr.Pareto(effects, decimals=2)¶

Determines when a pareto distribution is present.

Parameters:	effects (iterable[number]) – Effect values (≥ 0). decimals (Optional[int], default 2) – Number of decimals to round to.

Firstly, it calculates the entropy of values.
Then it stretches benchmark of [0.6, 0.1, 0.1, 0.1, 0.1] to count of values by maintaining absolute entropy.
In turn it divides entropy of values through entropy of benchmark.
Whenever the entropy of the values is less than the benchmark (1 or less), a pareto distribution should be assumed.

Example

>>> Pareto([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
0.71

__bool__()¶: Tells whether a pareto distribution is present. That is if entropy of actual elements is less or equal than the same of the control group.

ratio¶: Returns ratio of entropies actual elements vs. control group.

control_limit¶: Returns entropy of control group with same number of actual elements.

entropy¶: Returns entropy of actual elements.

lvr.helpers.list_dict(src_dict, effect, cause=None)¶

Constructs list of dicts to feed lvr.Lvr with.

Parameters:	src_dict (dict) – Dictionary like {‘elem1’: ‘attr1’: 45, ‘attr2’: 56}, …}. effect (str) – Name of key of effect value. cause (`str`, optional) – Name of key of cause value.

lvr

Navigation

Related Topics

API Documentation¶