Quick Start

Install it

To install from pypi:

$ pip3 install effectus

To install from head:

$ pip3 install hg+https://bitbucket.org/hyllos/effectus-python#stable


If you install effectus on a system that is not mac OS (Darwin) or Windows, the Excel interface will not be available.

Basic usage


You may paste code blocks (those introduced with >>>) directly into IPython. However, re-typing them manually increases learning achievement manifold.

Let’s look whether there are two centres of gravity with the fares of some of the passengers of the titanic.

>>> from effectus import Effects
>>> from effectus.data import titanic_fares
>>> fares = Effects(titanic_fares())

How much passengers make up for 60 percent of total fares?

>>> fares.attain_effects(0.6)

Which fares are those?

>>> required_fares = fares.retrieve_effects(0.6)

We can simplify that by selecting values greater or equal than a threshold:

>>> fares.separate_effects(0.6)
(61.8625, 2, 2)

But what if multiple effects have the same value?

>>> fares.separate_effects(0.8)
(24.0, 1, 2)

In this case you select all values greater than 24 but include only the first of two occurrences.

How many ascending fares are required to make up for 5 percent of total fares?

>>> fares.attain_effects(0.05, ascending=True)

How many for interval from 60 to 80 percent of total fares?

>>> fares.interval_effects(0.6, 0.8)

To attain a specified level of causes (above you attained level of effects), change the suffix _effects to _causes:

>>> fares.attain_causes(0.2)

Multiple Attributes

Usually, your effects are attributes of objects.

>>> from effectus.data import exoplanets
>>> the_exoplanets = dict(exoplanets()) # the example data are functions returning a list, so don't forget the parentheses!
>>> the_exoplanets['CoRoT-1 b']
OrderedDict([('mass', 1.03), ('radius', 1.49)])

The exoplanet CoRoT-1 b has the mass of 1.03 Jupiters and a radius of 1.49 Jupiters.

You can grab all the masses and use the Effects class as outlined above, like:

>>> masses = [exoplanet['mass'] for exoplanet in the_exoplanets.values()]
>>> Effects(masses)
<pareto present [0.84]: 1/5 causes => 4/5 effects [total ∆: 1.5 % points]>

Intersection and Exclusion

The most interesting insights become visible by intersection or exclusion of intervals of different attributes.

But first, let’s get the volume for each exoplanet:

>>> from math import pi
>>> for exoplanet, values in the_exoplanets.items():
...   the_exoplanets[exoplanet]['volume'] = 4/3*pi*values['radius']**3

Which exoplanets make up 80 percent of mass, which 80 percent of volume?

>>> from effectus.intervals import keys_in_effects_interval
>>> # we will put the names of the exoplanets (keys of the dict)
>>> # in a set to compare both groups with each other
>>> majority_of_mass = set(keys_in_effects_interval(the_exoplanets, 'mass', 0, 0.8))
>>> majority_of_volume = set(keys_in_effects_interval(the_exoplanets, 'volume', 0, 0.8))

Which belong to both groups?

>>> in_both_groups = majority_of_mass.intersection(majority_of_volume)
>>> only_majority_of_mass = majority_of_mass.difference(majority_of_volume)
>>> only_majority_of_volume = majority_of_volume.difference(majority_of_mass)
>>> total_count = len(the_exoplanets)
>>> print('{:.0f} percent of exoplanets make up 80 percent of mass.'.format(len(majority_of_mass)/total_count*100))
>>> print('{:.0f} percent of exoplanets make up 80 percent of volume.'.format(len(majority_of_volume)/total_count*100))
>>> print('{:.0f} percent of exoplanets belong to both groups.'.format(len(in_both_groups)/total_count*100))
>>> print('{:.0f} percent of those constituting 80 percent of total mass constitute 80 percent of total volume, too.'.format(len(only_majority_of_mass)/len(majority_of_mass)*100))
20 percent of exoplanets make up 80 percent of total mass.
36 percent of exoplanets make up 80 percent of total volume.
9 percent of exoplanets belong to both groups.
56 percent of those constituting 80 percent of total mass constitute 80 percent of total volume, too.

Quick Reference

Which causes make up specified effects?
Which effects are this?
Which threshold value the selected values must be greater than or equal to?
Which share of causes lie in between the specified effect interval?
Which objects fall into an effects interval formed by a specific attribute?
What if I want to specify causes instead of effects and determine required effects?