API Documentation

Top-level Functions

Note

In most cases the umbrella class Effects will serve your needs.

class effectus.Effects(effect_values, precision=3, variability=5)

Chief facility to assimilate and evaluate a series of effect values.

This class provides all relevant information about the relation of causes and effects in the given series of effect values.

Examples

>>> Effects([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
<pareto present [0.707]: 1/5 causes => 4/5 effects [total ∆: 1.9 % points]>

How much causes make up 60 percent of effects?

>>> from effectus import Effects
>>> from effectus.data import titanic_fares
>>> Effects(titanic_fares()).attain_effects(0.6)
0.177
>>> from effectus import Effects
>>> from effectus.data import flight_delays
>>> Effects(flight_delays()).attain_effects(0.6)
0.053

Rule of 50/5: 50 percent of causes make up only 5 percent

>>> from effectus import Effects
>>> from effectus.data import titanic_fares
>>> Effects(titanic_fares()).the_rule()
'Rule 60/20 [total ∆: 3.0 % points]'
>>> from effectus import Effects
>>> from effectus.data import flight_delays
>>> Effects(flight_delays()).the_rule()
'Rule 60/5 [total ∆: 2.1 % points]'
Parameters:
  • effect_values (list[number]) – An iterable of effect values.
  • precision (Optional[int], default 3) – Decimals to round to.
  • variability (Optional[int], default 5) – Tolerated deviation in hundredths of actual cause or effect from relevant cause or effect.
Variables:
  • count (int) – Number of total effects.
  • summary (dict) – Tells you which causes provoke which effects in fractional notation.
  • ratio (float) – entropy() of effect_values in proportion to control_limit(). If less or equal than one, a pareto distribution is present.
  • pareto (bool) – True if a pareto distribution is present.
  • precision (int) – Numbers of digits to round to.
  • all (Stats) –

    Group of all values.

    Examples

    The numbers in their own regard:

    >>> Effects([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).all.mean()
    172.2
    
    >>> Effects([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).all.stdev()
    270.52608007362244
    
    >>> from statistics import median
    >>> Effects([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).all.apply(median)
    37.5
    

    Throughput Accounting:

    Determine the periods required for elements at capacity of 2 elements per period:

    >>> Effects([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).all.periods(2)
    5.0
    

    The average throughput of a period with a capacity of 2 elements per period:

    >>> Effects([789, 621, 109, 65, 45, 30, 27, 15, 12, 9]).all.throughput(2)
    344.4
    
  • most (Stats) – Group of Useful Many, meaning majority number of values (each carrying light weight). See all for examples.
  • few (Stats) – Group of Vital Few, meaning minority number of values (each carrying heavy weight). See all for examples.
the_rule()

Returns the Rule of 50/5 or any variant of it.

Motto: Get many causes yet few effects.

The first number is the causes, the second the effects.

A Rule 50/5 means that 50 percent of ascending values add up to 5 percent of effects.

abc(precision=3)

Returns mapping of causes bands A, B, C to corresponding effects share.

Parameters:precision (Optional[int], default 3) – Decimals to round to.
groups(tablefmt='simple')

Tabulate key measures for all, Vital Few and Useful Many value groups.

Parameters:tablefmt (Optional[str], default simple) – Table format specified to tabulate, like simple or html.

For a given limit of effects:

attain_effects(limit=None, ascending=False, partial=True)

Tells you the causes required for the given share of effects.

Parameters:
  • limit (Optional[float], default actual[‘effects’]) – Share of effects between 0 and 1, including.
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default True) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
Returns:

Share of causes required for given share of effects as float value between 0 and 1.

interval_effects(lower_causes, upper_causes, ascending=False, partial=True)

Tells you the share of effects in between lower_causes and upper_causes bounds (including).

Parameters:
  • lower_causes (float) – Share of causes between 0 and 1, including.
  • upper_causes (float) – Share of causes between 0 and 1, including.
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default True) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
Returns:

Share of effects that lies between lower_causes and upper_causes, including both.

separate_effects(limit=None, ascending=False, partial=True)

Tells you which effect values to pick for given share of effects.

Parameters:
  • limit (Optional[float], default actual[‘effects’]) – Share of effects between 0 and 1, including.
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default True) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
Returns:

Tuple like (5.4, 3, 4) telling you to pick all values less or equal 5.4 up to the third occurrence of 5.4 (including) to get the given share of effects. 4 tells you there are in total 4 values of 5.4 present.

retrieve_effects(limit=None, counterpart=False, ascending=False, partial=True)

Retrieves effects required to attain limit of effects that is actual['effects'] by default.

Parameters:
  • limit (Optional[float], default actual[‘effects’]) – Share of effects between 0 and 1, including.
  • counterpart (Optional[bool], default False) – True if you want to return the values that are not in the share of effects (the complement).
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default True) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
Returns:

List of effect values.

For a given limit of causes:

attain_causes(limit=None, ascending=False, partial=True)

Tells you the effects required for the given share of causes.

Parameters:
  • limit (Optional[float], default actual[‘causes’]) – Share of causes between 0 and 1, including.
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default True) – Includes value that starts before limit yet ends after it if True.
Returns:

Share of effects required for given share of causes as float value between 0 and 1.

interval_causes(lower_effects, upper_effects, ascending=False, partial=True)

Tells you the share of causes in between lower_effects and upper_effects bounds (including).

Parameters:
  • lower_effects (float) – Share of effect between 0 and 1, including.
  • upper_effects (float) – Share of effects between 0 and 1, including.
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default True) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
Returns:

Share of causes that lies between lower_effects and upper_effects, including both.

separate_causes(limit=None, ascending=False, partial=True)

Tells you which effect values to pick for given share of causes.

Parameters:
  • limit (Optional[float], default actual[‘causes’]) – Share of causes between 0 and 1, including.
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default True) – Includes value that starts before limit yet ends after it if True.
Returns:

Tuple like (5.4, 3, 4) telling you to pick all values less or equal 5.4 up to the third occurence of 5.4 (including) to get the given share of causes. 4 tells you there are in total 4 values of 5.4 present.

retrieve_causes(limit=None, counterpart=False, ascending=False, partial=True)

Retrieves causes required to attain limit of causes that is actual['causes'] by default.

Parameters:
  • limit (Optional[float], default actual[‘causes’]) – Share of causes between 0 and 1, including.
  • counterpart (Optional[bool], default False) – True if you want to return the values that are not in the share of effects (the complement).
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default True) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
Returns:

List of effect values.

Helpers

sorted_effects(ascending=False)
Parameters:ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
Returns:List of sorted effects in ascending or descending order.
cml_effects(ascending=False, precision=3)

Returns cml_effects of ascending or descending effect values.

Parameters:
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • precision (Optional[int], default 3) – Decimals to round to.

Intervals

Functions to

  • retrieve keys from a dict falling into an effects or causes interval.
  • retrieve the keys at the intersection of keys of two attributes in the same interval of a list of intervals.
effectus.intervals.keys_in_effects_interval(source_dict, attribute, lower, upper, ascending=False, partial=False)

Determines keys of source_dict falling into lower and upper interval of cumulated effect values of attribute.

Parameters:
  • source_dict (dict[dict]) – Dict whose keys carry a dict where attribute maps to a value.
  • attribute (str) – Attribute of secondary dict of values to cumulate in case of effects_mode incorporating ascending.
  • lower (float) – Cause or effects limit, in between 0 and 1. Must be lower or equal than upper.
  • upper (float) – Cause or effects share, in between 0 and 1. Must be greater or equal than lower.
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default False) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
Returns:

List of keys falling into specified interval of effects.

Example

>>> from effectus.intervals import keys_in_effects_interval
>>> source_dict = {'A': {'mass': 45},
...                'B': {'mass': 9},
...                'C': {'mass': 15},
...                'D': {'mass': 65},
...                'E': {'mass': 789},
...                'F': {'mass': 621},
...                'G': {'mass': 27},
...                'H': {'mass': 109},
...                'I': {'mass': 12},
...                'J': {'mass': 30}
...               }
>>> keys_in_effects_interval(source_dict, 'mass', 0.9, 1)
['A', 'J', 'G', 'C', 'I', 'B']
effectus.intervals.keys_in_causes_interval(source_dict, attribute, lower, upper, ascending=False, partial=False)

Determines keys of source_dict falling into lower and upper interval of cumulated causes of attribute.

Parameters:
  • source_dict (dict[dict]) – Dict whose keys carry a dict where attribute maps to a value.
  • attribute (str) – Attribute of secondary dict of values that decide over the order of the causes.
  • lower (float) – Cause or effects limit, in between 0 and 1. Must be lower or equal than upper.
  • upper (float) – Cause or effects share, in between 0 and 1. Must be greater or equal than lower.
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default False) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
Returns:

List of keys falling into specified interval of causes.

Example

>>> from effectus.intervals import keys_in_causes_interval
>>> source_dict = {'A': {'mass': 45},
...                'B': {'mass': 9},
...                'C': {'mass': 15},
...                'D': {'mass': 65},
...                'E': {'mass': 789},
...                'F': {'mass': 621},
...                'G': {'mass': 27},
...                'H': {'mass': 109},
...                'I': {'mass': 12},
...                'J': {'mass': 30}
...               }
>>> keys_in_causes_interval(source_dict, 'mass', 0.3, 0.6)
['D', 'A', 'J']
effectus.intervals.effects_intersections(source_dict, first_attribute, second_attribute, intervals)

Tells you which keys of source_dict lie within the same interval for both attributes.

Parameters:
  • source_dict (dict) – A dictionary holding another dictionary for a key. The secondary dictionary must have at least two attributes.
  • first_attribute (str) – The key of the first attribute to select from the secondary dictionary.
  • first_attribute – The key of the second attribute to select from the secondary dictionary.
  • intervals (list[float]) – Steps to define the interval like [0.6, 0.8].
Returns:

A dict where each key maps to a set. The key is the interval of effects wherein the attributes first_attribute and second_attribute intersect. The set holds the keys of the elements falling into the same interval for both attributes.

Intersections

class effectus.intersections.REffort(source_dict, results_attr, efforts_attr, capacity=None, precision=2, tablefmt='simple', percentage_precision=0)

Provides Vital Few and Useful Many of results and efforts, their combinations (a, b, c, d) and their cumulative combinations (a, ab, abc, abcd) as StatsREffort objects.

We can think of combining the Vital Few and Useful Many of both groups with each other:

Group Results Effort
A Vital Few Useful Many
B Vital Few Vital Few
C Useful Many Useful Many
D Useful Many Vital Few

Those groups are cumulated to their respective combinations (A, AB, ABC, ABCD).

Refer to Bitwise Operators for an example section on how to add (+), subtract (-) and intersect (&) StatsREffort objects.

Parameters:
  • source_dict (dict) – Dictionary where each key references sub-dict whose keys map to values.
  • keys (iterable) – Keys of source_dict to restrict selection to.
  • results_attr (str) – Attribute in sub-dict referencing result value.
  • effort_attr (str) – Attribute in sub-dict referencing effort value.
  • capacity (Optional[number], default None) – Capacity in effort per round to put through. If capacity is provided (positive number), print representation will result StatsREffort.periods() to indicate how long each sub-set occupies the constraint.
  • precision (Optional[int], default 3) – Decimals to round to.
  • tablefmt (Optional[str], default simple) – Table format specified to tabulate, like simple or html.
  • percentage_precision (Optional[int], default 0) – Decimals to round percentage in print representation to.
Variables:

Example

>>> from effectus.intersections import REffort
>>> from effectus.data import lakes_level_1
>>> REffort(lakes_level_1(), 'volume', 'surface')
Group                    Results    Efforts    R/E
---------------------  ---------  ---------  -----
all                         100%       100%   0.01
- vital few efforts          65%        41%   0.02
- useful many results        41%        18%   0.03
combinations(capacity=None, precision=None, percentage_precision=None)

Print cumulative combinations groups A, B, C and D.

Parameters:
  • capacity (number) – Effort to put through in one period. Overrides capacity of each group (StatsREffort object).
  • precision (Optional[int]) – Decimals to round to. to tabulate, like simple or html. Defaults to self.precision.
  • percentage_precision (Optional[int]) – Decimals to round percentage in print representation to. Defaults to self.percentage_precision.
groups(capacity=None, precision=None, percentage_precision=None)

Print combinations of Vital Few, Useful Many of efforts and results.

Parameters:
  • capacity (number) – Effort to put through in one period. Overrides capacity of each group (StatsREffort object).
  • precision (Optional[int]) – Decimals to round to. to tabulate, like simple or html. Defaults to self.precision
  • percentage_precision (Optional[int], default 0) – Decimals to round percentage in print representation to. Defaults to self.percentage_precision.
triage(capacity=None, precision=None, percentage_precision=None)

Subtract Vital Few efforts, then Useful Many results. Print each of the three moments, including the starting one.

Parameters:
  • capacity (number) – Effort to put through in one period. Overrides capacity of each group (StatsREffort object).
  • precision (Optional[int]) – Decimals to round to. to tabulate, like simple or html. Defaults to self.precision.
  • percentage_precision (Optional[int]) – Decimals to round percentage in print representation to. Defaults to self.percentage_precision.
class effectus.intersections.StatsREffort(source_dict, keys, results_attr, efforts_attr, capacity=None, precision=3, fraction=False)

Provides key measures for the the results-efforts sub-group of keys of source_dict.

You can add (+), subtract (-) and intersect (&) StatsREffort elements to produce a new one:

>>> from effectus.data import lakes_level_1
>>> from effectus.intersections import REffort
>>> reff = REffort(lakes_level_1(), 'volume', 'surface')
>>> reff.abc # abc is a StatsREffort object
<[100% => 100%], count: 519, mean: 0.026, stdev: 0.030>
>>> reff.b # b is another StatsREffort object
<[59% => 35%], count: 25, mean: 0.013, stdev: 0.011>
>>> ac = reff.abc - reff.b
>>> ac
<[41% => 65%], count: 494, mean: 0.027, stdev: 0.030>

In turn ac holds all in abc but not in b (519-494 = 25).

Let’s intersect two StatsREffort objects with each other:

>>> reff.few.results & reff.few.efforts
<[59% => 35%], count: 25, mean: 0.013, stdev: 0.011>
>>> reff.b
<[59% => 35%], count: 25, mean: 0.013, stdev: 0.011>
Parameters:
  • source_dict (dict) – Dictionary where each key references sub-dict whose keys map to values.
  • keys (iterable) – Keys of source_dict to restrict selection to.
  • results_attr (str) – Attribute in sub-dict referencing result value.
  • effort_attr (str) – Attribute in sub-dict referencing effort value.
  • capacity (Optional[number]) – Effort to put through in one period.
  • precision (Optional[int], default 3) – Decimals to round to.
  • fraction (Optional[bool], default False) – Return densities as Fraction.
Variables:
  • keys (list) – List of keys making up the selection.
  • sub_dicts (dict) – Sub-set of source_dict containing only key.
  • count (int) – Number of elements in sub_dicts (equivalent to len(keys)).
  • total (dict) – Dict holding keys results, efforts and count as attributes of source_dict, incorporating results_attr and efforts_attr.
  • capacity – Effort to put through in one period.
  • precision (int) – Decimals to round to.
  • results (Stats) – Carries results values.
  • efforts (Stats) – Carries efforts values.
  • share (dict) – Dict holding keys results and efforts referencing to the share of the sub-set in proportion to the total results and efforts, respectively.
  • density (float) –

    Results per effort. Computed as sum of results divided by sum of efforts.

    Note

    The result will differ from densities.mean() that is the Arithmetic Mean of the series of result/effort (single value boundary). Instead, here the single value boundary is lifted.

  • densities (Stats) – List of result/effort is available through densities.values.
periods(capacity=None, fraction=False)

Returns average throughput per period.

Parameters:
  • capacity (Optional[number]) – Effort to put through in one period. Defaults to self.capacity.
  • fraction (bool) – Return Fraction if True, otherwise float.
throughput(capacity=None, fraction=False)

Returns average throughput per period.

Parameters:
  • capacity (Optional[number]) – Effort to put through in one period. Defaults to self.capacity.
  • fraction (bool) – Return Fraction if True, otherwise float.
class effectus.intersections.StatsREffortGroups(groups, titles, headers=['Group', 'Results', 'Efforts', 'R/E', 'Periods', 'R/Period', 'Results'], capacity=None, precision=2, percentage_precision=0)
tabulate_rows(rows=None, headers=None, tablefmt='simple', precision=None, percentage_precision=None)

Tabulates rows of differentiated groups and combinations into string.

Parameters:
  • rows (Optional[list], default None) – Fields, one per column to print. Defaults to None that will pull self.rows in.
  • headers (Optional[list[str], default None) – Headers, one per column to print. Defaults to None that will pull self.headers in. May be longer than rows. Additional heading will be considered only if capacity has been provided from the class call.
  • tablefmt (Optional[str], default simple) – Table format specified to tabulate, like simple or html.
  • precision (Optional[int]) – Decimals to round to. Defaults to self.precision.
  • percentage_precision (Optional[int]) – Decimals to round to. Defaults to self.percentage_precision.
Returns:

Tabulated string.

Data Helpers

effectus.helpers.get_data(filepath, observations_col=1, frequencies_col=2)

Read and unfold value-frequency mappings from file.

Parameters:
  • filepath (str) – File path to source file.
  • observations_col (Optional[int], default 1) – Column of observations.
  • frequencies_col (Optional[int], default 2) –

    Only relevant if file has more than two comma separated columns.

    Note

    Set this to -1 to deactivate value-frequency mode for a file having more than one column.

Returns:

A list of unfolded values.

effectus.helpers.write_values(values, filename)

Write values either reduced to value-frequencies or values whichever consumes less space to file.

Parameters:
  • values (list[number]) – Effects as list of numbers.
  • filename (str) – File path to write to.
effectus.helpers.write_unfolded_values(values, filename)

Writes values to file.

Parameters:
  • values (list[number]) – Effects as list of numbers.
  • filename (str) – File path to write to.

Example

>>> from effectus.helpers import write_unfolded_values
>>> write_unfolded_values([1, 2, 3, 4, 5], 'out.csv')
effectus.helpers.write_reduced_values(values, filename)

Writes value-frequency mappings to file.

Value and frequency are separated by comma and written line-wise to the given filename.

Parameters:
  • values (list[number]) – Effects as list of numbers.
  • filename – File path to write to.

Example

>>> from effectus.helpers import write_reduced_values
>>> write_reduced_values([(1, 3), (3, 2)], 'out.csv')

Low-level Functions

Pareto

Functions to determine entropy for a series of numbers, the control limit of their total count and whether the entropy is less or equal the control limit. If that’s the case, a pareto distribution is present.

effectus.pareto.control_limit()

Determines control limit.

Parameters:count (int) – Number of elements to calculate control entropy for. This is len(effects).
Returns:Control limit as float.

Example

>>> from effectus.helpers import control_limit
>>> control_limit(10)
2.7709505944546686
effectus.pareto.entropy()

Determines entropy for effects. Calculated as follows:

  1. log2() for each value.
  2. Weigh (multiply) each result by the share of each value in respect to the total of all values.
  3. Sum of all parts.
Parameters:effect_values (list[number]) –

Effects as list of numbers.

Warning

Accepts only positive numbers. If you have only negative values, convert them to positive like:

>>> list(map(abs, [-1, -2, -3]))
[1, 2, 3]

If you have positive and negative mixed, set the minimum value to the zero point like and shift the others:

>>> values = [-1, 0, 1, 2]
>>> zero_point = min(values)
>>> list(map(lambda v: v-zero_point, values))
[0, 1, 2, 3]

Even if you add the zero_point back to all values, you need to be careful if the reconstructed value can actually be considered as valid.

Returns:Entropy of effects as float.

Example

>>> from effectus.pareto import entropy
>>> entropy([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
1.9593816735406657
effectus.pareto.pareto()

Determines whether a pareto distribution is present.

Is a pareto distribution present for effects?

Parameters:effect_values (list[number]) – Effects as list of numbers.
Returns:True if pareto distribution present, otherwise False.

Example

>>> from effectus.pareto import pareto
>>> pareto([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
True
effectus.pareto.ratio()

Determines ratio of entropy versus control limit.

Parameters:effect_values (list[number]) – Effects as list of numbers.
Returns:Ratio of entropy in relation to control_limit() as float.

Note

If it is 1 or less (that is entropy() <= control_limit()), a pareto distribution is present.

Example

>>> from effectus.pareto import ratio
>>> ratio([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
0.707

Relations

Functions to create cause-effect relationships, identify the relevant, determine the nearest rounded cause-effect relation and In order of process stage:

effectus.helpers.make_relations_new(sorted_effects)

Returns generator function yielding a tuple representing a cause-effect relation.

Parameters:sorted_effects (list[number]) – List of effects in descending order.
Returns:A list of tuples with cause-effect mappings, for example:
[(Fraction(1, 10), Fraction(263, 574)), ...]

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import make_relations_new
>>> make_relations_new([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
[(Fraction(1, 5), Fraction(263, 574)),
 (Fraction(3, 10), Fraction(235, 287)),
 (Fraction(2, 5), Fraction(217, 246)),
 (Fraction(1, 2), Fraction(264, 287))]
effectus.helpers.make_relations(effect_values)

Creates list of tuples (cumulative_causes, cumulative_effects) from effects.

Parameters:effect_values (list[number]) – Effects as list of numbers.
Returns:A list of tuples of cause-effect mappings, for example:
[(Fraction(1, 10), Fraction(263, 574)), ...]

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import make_relations
>>> make_relations([789, 621, 109, 65, 45, 30, 27, 15, 12, 9])
[(Fraction(1, 10), Fraction(263, 574)),
 (Fraction(1, 5), Fraction(235, 287)),
 (Fraction(3, 10), Fraction(217, 246)),
 (Fraction(2, 5), Fraction(264, 287)),
 (Fraction(1, 2), Fraction(543, 574)),
 (Fraction(3, 5), Fraction(79, 82)),
 (Fraction(7, 10), Fraction(281, 287)),
 (Fraction(4, 5), Fraction(81, 82)),
 (Fraction(9, 10), Fraction(571, 574)),
 (Fraction(1, 1), Fraction(1, 1))]
effectus.helpers.match_relations(relations, causes_list=None, effects_list=None, variability=5)

Yields only relevant relations from a list of relations.

Parameters:
  • relations – A list of tuples with cause-effect mappings. This is the output of make_relations_new().
  • causes_list (Optional[list[Fraction]]) –

    A list of relevant causes. A cause may be any value between 0 and 1, including. Default:

    [Fraction(1, 100), Fraction(5, 100),
     Fraction(1, 10),
     Fraction(1, 5), Fraction(1, 4),
     Fraction(3, 10),
     Fraction(2, 5),
     Fraction(1, 3),
     Fraction(1, 2)]
    
  • effects_list (Optional[list[Fraction]]) –

    A list of relevant effects. An effect may be any value between 0 and 1, including. Default:

    [Fraction(1, 2),
     Fraction(3, 5),
     Fraction(2, 3), Fraction(4, 5),
     Fraction(9, 10),
     Fraction(95, 100)]
    
  • variability (Optional[int], default 5) – Tolerated deviation in hundredths of actual cause or effect from relevant cause or effect.
Yields:

tuple (tuple[Fraction]) – Tuple of actual cause-effect relation and nearest:

((actual_cause, actual_effect), (nearest_cause, nearest_effect))

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import match_relations
>>> relations = [(Fraction(1, 10),
                  Fraction(5404319552844595, 18014398509481988)),
...              (Fraction(1, 5),
                  Fraction(5404319552844595, 9007199254740994)),
...              (Fraction(3, 10),
                  Fraction(5854679515581645, 9007199254740994)),
...              (Fraction(2, 5),
                  Fraction(6305039478318695, 9007199254740994))]
>>> list(match_relations(relations))
[((Fraction(1, 5), Fraction(5404319552844595, 9007199254740994)),
  (Fraction(1, 5), Fraction(3, 5))),
 ((Fraction(3, 10), Fraction(5854679515581645, 9007199254740994)),
  (Fraction(3, 10), Fraction(2, 3))),
 ((Fraction(2, 5), Fraction(6305039478318695, 9007199254740994)),
  (Fraction(2, 5), Fraction(2, 3)))]
effectus.helpers.pick_best(relevant_relations)

Picks the single relation with the highest power.

Parameters:relevant_relations – A list of relevant cause-effect relations that is tuple (causes, effects, total_delta, gcd). This is the output from get_relevant().
Returns:A dict with a human-friendly approximation of the most relevant cause-effect relationship and another dict with the actual cause-effect.

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import (make_relations_new, get_relevant,
...                               pick_best)
>>> relations = make_relations_new([789, 621, 109, 65, 45, 30,
...                             27, 15, 12, 9])
>>> relevant = get_relevant(relations)
>>> pick_best(relevant)
({'causes': Fraction(1, 5), 'effects': Fraction(235, 287)},
 {'causes': Fraction(1, 5),
  'effects': Fraction(4, 5),
  'gcd': Fraction(1, 5),
  'variability': 0.02297872340425532})
effectus.helpers.get_enriched(matches)
Yields:Enriched matches for a list of matches.

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import get_enriched
>>> matches = [((Fraction(465, 1921),
...              Fraction(452214153805824, 779294392493015)),
...             (Fraction(1, 4), Fraction(3, 5)))]
>>> list(get_enriched(matches))
    [(Fraction(1, 4),
      Fraction(3, 5),
      Fraction(465, 1921),
      Fraction(452214153805824, 779294392493015),
      Fraction(33116453449583731, 1197619622383265452),
      Fraction(1, 20))]
effectus.helpers.enrich_match(match)

Enriches a match with total_delta and gcd.

Parameters:match (tuple) –

A tuple containing two cause-effect tuples like:

((actual_cause, actual_effect), (nearest_cause, nearest_effect))
Returns:A tuple of:
(nearest_causes, nearest_effects,
 actual_causes, actual_effects,
 total_delta, the_gcd)

Example

>>> from effectus.helpers import enrich_match
>>> enrich_match(((Fraction(465, 1921),
...                Fraction(452214153805824, 779294392493015)),
...               (Fraction(1, 4), Fraction(3, 5))))
   (Fraction(1, 4),
    Fraction(3, 5),
    Fraction(465, 1921),
    Fraction(452214153805824, 779294392493015),
    Fraction(33116453449583731, 1197619622383265452),
    Fraction(1, 20))
effectus.helpers.format_summary(summary, precision=3)

Extends summary dict by pareto() and ratio(), fracifies or rounds it.

Parameters:
  • summary (dict) – A summary created by pick_best() or get_gcd().
  • precision (Optional[int], default 3) – Decimals to round to.
Returns:

Tuple of (causes, effects) in fractional notation if both denominators are less or equal 100, otherwise in decimal notation.

Example

>>> from effectus.helpers import format_summary
>>> format_summary({'causes': Fraction(1, 5),
...                 'effects': Fraction(4, 5),
...                 'gcd': Fraction(1, 5),
...                 'variability': 0.018815331010452963})
('1/5', '4/5')

Separator

effectus.helpers.det_causes_ordinal(length, limit, partial=True, precision=3)

Determines ordinal of cause reaching limit if partial is True, otherwise the ordinal of the previous cause.

Parameters:
  • limit (number) – Share of effects to attain in between 0 and 1, including.
  • partial (Optional[bool], default True) – Includes effect value that surpasses the limit if true. False excludes it, even if it means to not reach the limit.
  • precision (Optional[int], default 3) – Decimals to round to.
Returns:

Ordinal of cause reaching limit if partial is True, otherwise the previous cause as int.

effectus.helpers.det_effects_ordinal(cml_effects, limit, partial=True, precision=3)

Determines ordinal of effect value reaching limit if partial, is True, otherwise the ordinal of the previous effect value.

Parameters:
  • cml_effects (list[number]) – List of cumulated effect values in descending order.
  • limit (number) – Share of effects to attain in between 0 and 1, including.
  • partial (Optional[bool], default True) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
  • precision (Optional[int], default 3) – Decimals to round to.
Returns:

Ordinal of cml_effects reaching limit if partial is True, otherwise the previous cumulative value as int.

Subsets

class effectus.helpers.Stats(values, causes=None, effects=None, precision=3)
mean()

Returns the arithmetic mean (mean()) of the subset.

stdev()

Returns the standard deviation (pstdev()) that is square root of population variance.

apply(func)

Applies func to subset.

throughput(capacity, fraction=False)

Returns average throughput per period.

Parameters:
  • capacity (number) – Number of elements put through in one period.
  • fraction (bool) – Return Fraction if True, otherwise float.
class effectus.helpers.StatsSubSet(retrieve_effects, causes, effects, counterpart, ascending=False, precision=3)

Builds Stats, pulls in retrieve_effects() based on the given parameters.

Parameters:
  • retrieve_effects (function) – retrieve_effects() of the Effects class.
  • causes (number) – Causes share between 0 and 1.
  • effects (number) – Effects share between 0 and 1.
  • counterpart (bool) – False to consider Vital Few, True for Useful Many.
  • ascending (Optional, default False) – Cumulate values from smallest to biggest if True.
  • precision (Optional[int], default 3) – Decimals to round to.

Data Helpers

effectus.helpers.reduce_values(values)

Reduces a list of values into a value-frequency mapping.

Parameters:values (list[number]) – Effects as list of numbers.
Returns:A list of tuples of like:
[(23.3, 1), ...]

Example

>>> from effectus.helpers import reduce_values
>>> reduce_values([1,1,1,3,2])
['1,3', '3,2']
effectus.helpers.unfold_values(values)

Unfolds list of observation-frequency mappings.

Parameters:values (tuple[number, int]) – Observation-frequency mapping.
Returns:List of values.

Example

>>> from effectus.helpers import unfold_values
>>> unfold_values([(1, 3), (2, 1), (3, 1)])
[1, 1, 1, 2, 3]
effectus.helpers.get_values_from_csv(csv_reader, observations_col=1, frequency_col=2)

Gets values from csv file.

Parameters:
  • csv_reader
  • observations_col (int, default 1) – Column number of observations.
  • frequency_col (int, default 2) – Column number of frequency. if < 0 or csv file has only one column, values will only be considered.
Returns:

A list of observation-frequency tuples like:

[(23.3, 1), (80.1, 3), (99.3, 2)]

effectus.helpers.get_values_by_attribute(source_dict, attribute)

Retrieve values of attribute of sub-dicts of source_dict.

Parameters:
  • source_dict (dict[dict]) – Each key holds another dict where the key attribute maps to the stored value.
  • keys (iterable) – Keys to retrieve values for attribute from.
  • attribute (str) – Attribute referencing to value of sub-dicts in source_dict.
Returns:

List of values of attribute of sub-dicts of dictionary source_dict.

effectus.helpers.get_values_for_keys(source_dict, keys, attribute)

Generator function retrieving values of attribute for keys in source_dict.

Parameters:
  • source_dict (dict[dict]) – Each key holds another dict where the key attribute maps to the stored value.
  • keys (iterable) – Keys to retrieve values for attribute from.
  • attribute (str) – Key of secondary dictionary referencing the stored value.
Yields:

Values of attribute for keys of source_dict.

Example

>>> from effectus.intersections import get_values_for_keys
>>> source_dict = {'2M 0122-24 b': {'mass': 20.0, 'volume': 4.2},
...                '2M 0219-39 b': {'mass': 13.9, 'volume': 12.5},
...                '38 Vir b': {'mass': 4.5, 'volume': 384.3},
...               }
>>> list(get_values_for_keys(source_dict, ['2M 0219-39 b',
...                                        '2M 0122-24 b'], 'mass'))
[20.0, 13.9]
effectus.helpers.get_sub_dicts_for_keys(source_dict, keys)

Retrieves sub_dicts for keys of source_dict.

Parameters:
  • source_dict (dict) – Dict with keys referencing to sub-dict.
  • keys (iterable) – The keys to retrieve sub_dicts for.

Example

>>> from effectus.intersections import get_sub_dicts_for_keys
>>> source_dict = {'2M 0122-24 b': {'mass': 20.0, 'volume': 4.2},
...                '2M 0219-39 b': {'mass': 13.9, 'volume': 12.5}
...               }
>>> get_sub_dicts_for_keys(source_dict, ['2M 0219-39 b'])
{'2M 0219-39 b': {'mass': 13.9, 'volume': 12.5}}
effectus.helpers.sort_dict(source_dict, attribute, ascending=False)
Sorts dictionary of dictionaries after value recorded for attribute.
If those are equal, it sorts after the primary key.
Parameters:
  • source_dict (dict[dict]) – Each key holds another dict where the key attribute maps to the stored value.
  • attribute (str) – Key of secondary dictionary referencing the stored value.
  • (Optional[bool], default (ascending) – False): Cumulate effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
Returns:

Sorted dict after value for attribute and primary key.

Return type:

collections.OrderedDict

Intersections

class effectus.intersections.AttrSubSet(source_dict, results_keys, efforts_keys, results_attr, efforts_attr, capacity=None)
class effectus.intersections.Separator(results_separator, efforts_separator)
effectus.intersections.get_vital_keys(source_dict, attr, counterpart=False)

Returns keys of Vital Few of attr values of source_dict and separator tuple.

Parameters:
  • sorted_dict (dict) – OrderedDict of dictionaries sorted by values referenced by attr in descending order.
  • attr (str) – Attribute referencing to value of sub-dicts in sorted_dict.
  • counterpart (Optional[bool], default False) – Return Vital Few if True else Useful Many.

Low-low-level Functions

The following functions are not intended to be user functions. However, they are listed here for reference.

Core

effectus.core.make_summary(effect_values, variability=None)

Creates summary for cause-effect relationship.

Parameters:
  • effect_values (list[numeric]) – A series of numbers each representing an observed effect. Must be positive values only.
  • variability (Optional[int], default 5) – Tolerated deviation in hundredths of actual cause or effect from relevant cause or effect.
Returns:

A dict with actual causes and effects relation and another dict with the nearest human-friendly approximation with gcd and variability.

effectus.core.get_rule(enriched)

Returns the rule of 50/5 or any variant of it.

Parameters:enriched (list[tuple]) – Enriched relations that is the output of get_enriched().
effectus.core.attain_partial_or_impartial(cml_effects, ordinal, threshold_value, partial, precision=3)

Returns partial or impartial value.

This helper function implements the partial parameter for effectus.core.attain_effects() and effectus.core.attain_causes().

effectus.core.attain_effects(cml_effects, length, threshold_value, partial=True, precision=3)

Determines causes for specified ratio of effects.

How many causes are at least required for required_effects?

Parameters:
  • cml_effects (list[float]) – List of cumulative sorted effects.
  • length (int) – Length of sorted_effects.
  • threshold_value – cumulative effects value to attain.
  • partial (Optional[bool], default True) – Includes value that starts before limit yet ends after it if True.
  • precision (float) – Number of decimals to round to.
Returns:

Minimum ratio of causes required to attain threshold_value that is ordinal of cml_effects as float.

effectus.core.attain_causes(cml_effects, length, threshold_value, partial=True, precision=3)

Determines causes for specified ratio of effects.

How many effects are at least effected for required_causes?

Parameters:
  • cml_effects (list[float]) – List of cumulative sorted effects.
  • length (int) – Length of sorted_effects.
  • threshold_value – Cumulative effects value to attain.
  • partial (Optional[bool], default True) – Includes value that starts before limit yet ends after it if True.
  • precision (float) – Number of decimals to round to.
Returns:

Minimum ratio of effects required to attain threshold_value in cml_effects as float.

effectus.core.separate_effects(cml_effects, sorted_effects, required_effects, length, partial=True, precision=3)

Determines threshold value that selects limit share of effects.

Which value or greater must an effect be to belong to limit?

Parameters:
  • cml_effects (list[number]) – Accumulator of sorted_effects.
  • sorted_effects (list[number]) – Effects as descending list of numbers.
  • required_effects (float) – Causes ratio to attain, between 0 and 1.
  • partial (Optional[bool], default True) – Includes value that starts before limit yet ends after it if True.
  • precision (Optional[float], default 3) – Decimals to round to.
Returns:

Tuple of (a, b, c). a is value a effect must be at least to belong to required_effects. c is total count of occurences of that value. b is number of occurrence up to which selection must span (including) to attain required_effects.

Examples

>>> separate_effects([789, 1410, 1519, 1584, 1629, 1659, 1686,
...                   1701, 1713, 1722], [789, 621, 109, 65,
...                   45, 30, 27, 15, 12, 9], 0.6, 10)
(621, 1, 1)
effectus.core.separate_causes(sorted_effects, required_causes, length, partial=True, precision=3)

Determines threshold value that selects limit share of causes.

Which value or greater must an effect be to belong to limit of causes?

Parameters:
  • sorted_effects (list[number]) – Effects as descending list of numbers.
  • required_causes (float) – Causes share to attain, between 0 and 1.
  • length – Length of sorted_effects.
  • partial (Optional[bool], default True) – Includes value that starts before limit yet ends after it if True.
  • precision (Optional[float], default 3) – Decimals to round to.
Returns:

Tuple(a, b, c). a is value a effect must be at least to belong to required_causes. c is total count of occurences of that value. b is number of occurrence up to which selection must span (including) to attain required_causes.

Examples

>>> separate_causes([789, 621, 109, 65, 45, 30, 27, 15, 12, 9], 0.6, 10)
(30, 1, 1)

Helpers

effectus.helpers.frac_gcd(frac1, frac2)

Determines greatest common fraction of two fractions.

frac1 and frac2 are Fraction.

Returns:Triplet with greatest common fraction, multiplier for frac1 and frac2.

Example

>>> from quicktions import Fraction
>>> frac_gcd(Fraction(1, 55), Fraction(3, 110))
(Fraction(1, 110), 2, 3)
effectus.helpers.get_gcd(major_relations)

Determines relation with greatest common fraction.

Parameters:major_relations (list[tuple]) –

A list of tuples of cause-effect mappings, for example:

[(Fraction(2, 3), Fraction(23, 33)),
 (Fraction(5, 6), Fraction(28, 33))]
Returns:Cause-effect relationship with greatest common fraction as tuple.

Example

>>> get_gcd([(Fraction(2, 3), Fraction(23, 33)),
...          (Fraction(5, 6), Fraction(28, 33))])
(Fraction(2, 3), Fraction(23, 33))
effectus.helpers.find_nearest_bisect(value, number_list, greater_equal=False)

Which number in number_list is nearest to number?

Parameters:
  • value (number) – Value to find nearest value for in number_list.
  • number_list (list[Fraction]) – Predefined list of 0 < Fraction < 1.
  • greater_equal (Optional[bool], default False) – Only consider values greater or equal than value. Defaults to False that will include values less than value.
Returns:

Nearest value in number_list for value as float.

Example

>>> from effectus.helpers import find_nearest_bisect
>>> find_nearest_bisect(77, [1, 21, 78, 99, 101, 160, 180], False)
2
effectus.helpers.decimal_range(lower, upper, decimal_places)
Increments lower by one tenth of specified decimal_places
to upper, including.
Parameters:
  • lower (number) – Starting value.
  • upper (number) – Ending value.
  • decimal_places (int) – Number of decimal places (zero or more).
Returns:

List of Fractions starting from lower incrementing by 1/10**decimal_places up to and including upper.

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import decimal_range
>>> decimal_range(0, 0.2, 1)
[Fraction(0, 1), Fraction(1, 10), Fraction(1, 5)]
effectus.helpers.get_majors(relations)

Retrieves only causes <= 0.52 and effects >= 0.48.

Parameters:relations – A list of tuples with cause-effect mappings. This is the output of make_relations().
Returns:
A list of tuples with cause-effect mappings, for example::
[(0.52, 0.48)]

Example

>>> from effectus.helpers import get_majors
>>> get_majors([(0.52, 0.48), (0.52, 0.47), (0.53, 0.48)])
[(0.52, 0.48)]
effectus.helpers.get_relevant(major_relations, causes_list=None, effects_list=None)

Returns only relevant variations of causes and effects as tuples.

Parameters:
  • relations – A list of tuples with cause-effect mappings. This is the output of make_relations_new() or make_relations().
  • causes_list (Optional[list[Fraction]]) –

    A list of relevant causes. A cause may be any value between 0 and 1, including. Default:

    [Fraction(1, 100), Fraction(5, 100),
     Fraction(1, 10),
     Fraction(1, 5), Fraction(1, 4),
     Fraction(3, 10),
     Fraction(2, 5),
     Fraction(1, 3),
     Fraction(1, 2)]
    
  • effects_list (Optional[list[Fraction]]) –

    A list of relevant effects. An effect may be any value between 0 and 1, including. Default:

    [Fraction(1, 2),
     Fraction(3, 5),
     Fraction(2, 3), Fraction(4, 5),
     Fraction(9, 10),
     Fraction(95, 100)]
    
Returns:

A list of tuples with nearest, actual cause-effect mappings with total_delta and greatest common decimal denominator.

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import (make_relations, get_majors,
...                               get_relevant)
>>> relations = make_relations([789, 621, 109, 65, 45, 30,
...                             27, 15, 12, 9])
>>> major_relations = get_majors(relations)
>>> get_relevant(major_relations)
[(Fraction(1, 5),
  Fraction(4, 5),
  Fraction(1, 5),
  Fraction(235, 287),
  Fraction(27, 1435),
  Fraction(1, 5)),
 (Fraction(3, 10),
  Fraction(9, 10),
  Fraction(3, 10),
  Fraction(217, 246),
  Fraction(11, 615),
  Fraction(1, 10)),
 (Fraction(2, 5),
  Fraction(9, 10),
  Fraction(2, 5),
  Fraction(264, 287),
  Fraction(57, 2870),
  Fraction(1, 10)),
 (Fraction(1, 2),
  Fraction(19, 20),
  Fraction(1, 2),
  Fraction(543, 574),
  Fraction(23, 5740),
  Fraction(1, 20))]
effectus.helpers.exclude_causes(sorted_effects)

Returns ordinal of first effect value until half of total count of sorted_effects

effectus.helpers.exclude_effects(sorted_effects, total_effects)

Returns ordinal of first effect value nipping at half of total_effects.

Parameters:
  • sorted_effects (list[number]) – List of effects sorted in descending order.
  • total_effects (number) – Sum of all effects.
Returns:

Ordinal of first effect value nipping at half of total_effects as int.

Example

>>> from effectus.helpers import exclude_effects
>>> exclude_effects([789, 621, 109, 65, 45, 30, 27, 15, 12, 9], 1722)
1
effectus.helpers.create_relation(causes_incr, causes_total, effects_incr, effects_total)

Builds Fraction from causes and effects numerator and denominator.

Parameters:
  • causes_incr (int) – Numerator of causes.
  • causes_total (int) – Denominator of causes.
  • effects_incr (int) – Numerator of effects.
  • effects_total (int) – Denominator of effects.
Returns:

A cause-effect mapping, for example:

(Fraction(1, 10), Fraction(263, 574))

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import create_relation
>>> create_relation(2, 10, 789+621, 1722)
(Fraction(1, 5), Fraction(235, 287))
effectus.helpers.which_level(value, bounds)

Tells ordinal of the bound where value fits into.

Parameters:
  • value (number) – Value to fit into provided bounds.
  • bounds (list[tuple(Fraction, Fraction)]) – Iterable with a tuple like (cause, effect).
Returns:

Ordinal of level in bounds where value fits into as int.

effectus.helpers.create_bounds(fracs, variability=5)

Yields tuple of lower and upper bounds for each frac.

Parameters:
  • fracs (list[Fraction]) – List of levels to determine lower and upper bounds for.
  • variability (Optional[int], default 5) – Tolerated deviation in hundredths of actual cause or effect from relevant cause or effect.
Yields:

Tuple of lower and upper bounds.

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import create_bounds
>>> create_bounds([Fraction(1, 100), Fraction(5, 100)])
[(Fraction(19, 2000), Fraction(21, 2000)),
 (Fraction(19, 400), Fraction(21, 400))]
effectus.helpers.in_bounds(value, lower, upper)

Checks whether value is in between (including) lower and upper.

Returns:True if value is in between lower and upper, including both, otherwise False.
effectus.helpers.det_delta(actual, nearest)

Determines delta for actual against nearest.

Example

>>> from quicktions import Fraction
>>> from effectus.helpers import det_delta
>>> det_delta(Fraction(452214153805824, 779294392493015),
...           Fraction(3, 5))
Fraction(3072496337997, 155858878498603)
effectus.helpers.find_equals_right(sorted_effects, ordinal, length)

How many values are right of ordinal with the same value of sorted_effects[ordinal], excluding?

Parameters:
  • sorted_effects (list[number]) – List of effects in descending order.
  • ordinal (int) – Ordinal of effect value to start from.
  • length (int) – Length of sorted_effects.
Returns:

Number of values right of ordinal with the same value of sorted_effects[ordinal], excluding, as int.

Example

>>> from effectus.helpers import find_equals_right
>>> find_equals_right([5, 4, 3, 3, 3, 2, 1], 2, 7)
2
effectus.helpers.find_equals_left(sorted_effects, ordinal, length)

How many values are left of ordinal with the same value of sorted_effects[ordinal], excluding?

Parameters:
  • sorted_effects (list[number]) – List of effects in descending order.
  • ordinal (int) – Ordinal of effect value to go until.
  • length (int) – Length of sorted_effects.
Returns:

Number of values left of ordinal with the same value of sorted_effects[ordinal], excluding, as int.

Example

>>> from effectus.helpers import find_equals_left
>>> find_equals_left([5, 4, 3, 3, 3, 2, 1], 4, 7)
2
effectus.helpers.retrieve_rule(rules)

Retrieve the rule with the highest multiple, if equal that with lower total delta otherwise the earlier occurrence.

effectus.helpers.tabulate_groups(groups, tablefmt='simple', precision=3)

Tabulate groups in tablefmt.

Parameters:
  • groups (dict) – Dict where each value is a Stats instance of effect values.
  • tablefmt (Optional[str], default simple) – Table format specified to tabulate, like simple or html.
  • precision – Maximum count of decimals to round to.
effectus.helpers.max_decimals(values)

Returns maximum decimal places of list of values.

effectus.helpers.sufficient_decimals(numbers, precision)

Returns maximum number of decimals to round to.

If a number has more decimals than precision, return precision, otherwise maximum decimals observed with numbers.

Parameters:
  • numbers (list[number]) – List of numbers, may be float.
  • precision (int) – Number of maximum decimals.

Intervals

effectus.intervals.get_keys_for_interval(source_dict, attribute, lower, upper, effects_mode, ascending=False, partial=False)
Determines keys of source_dict falling into lower and upper
interval of cumulated causes or effects (values) of attribute.
Parameters:
  • source_dict (dict[dict]) – Dict whose keys carry a dict where attribute maps to a value.
  • attribute (str) – Attribute of secondary dict of values to cumulate.
  • lower (float) – Cause or effects limit, in between 0 and 1. Must be lower or equal than upper.
  • upper (float) – Cause or effects share, in between 0 and 1. Must be greater or equal than lower.
  • effects_mode (bool) – True to accumulate effects, otherwise causes.
  • ascending (Optional[bool], default False) – Cumulates effects from smallest to biggest if True. Defaults to False that will cumulate effects from biggest to smallest.
  • partial (Optional[bool], default False) – Includes effect value that surpasses the limit if True. False excludes it, even if it means to not reach the limit.
effectus.intervals.create_bounds(intervals)

Create bounds stepping from 0 over intervals to 1.

Parameters:intervals (list[float]) – In between 0 and 1, including.
Returns:list of tuple of lower and upper bound for given list of bounds starting from 0 and ending at 1.

Example

>>> from effectus.intervals import create_bounds
>>> list(create_bounds([0.6, 0.8]))
[(0, 0.6), (0.6, 0.8), (0.8, 1)]