.. _quickstart:

Quick Start
***********

Install it
==========

To install from pypi:

.. code-block:: bash

  $ pip3 install effectus

To install from head:

.. code-block:: bash

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


.. note::

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

Basic usage
===========

.. note::

    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. 

.. code-block:: python

  >>> 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?

.. code-block:: python

  >>> fares.attain_effects(0.6)
  0.177

Which fares are those?

.. code-block:: python

  >>> required_fares = fares.retrieve_effects(0.6)

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

.. code-block:: python

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

But what if multiple effects have the same value?

.. code-block:: python

  >>> 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?

.. code-block:: python

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

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

.. code-block:: python

  >>> fares.interval_effects(0.6, 0.8)
  0.208

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

.. code-block:: python

  >>> fares.attain_causes(0.2)
  0.634

Multiple Attributes
===================

Usually, your effects are attributes of objects.

.. code-block:: python

  >>> 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 :py:class:`~effectus.Effects` class as outlined above, like:

.. code-block:: python

  >>> 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:

.. code-block:: python

  >>> 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?*

.. code-block:: python

  >>> 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?*

.. code-block:: python

  >>> 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.

.. _quickref:

Quick Reference
===============

Which causes make up specified effects?
    :py:func:`effectus.Effects.attain_effects`

Which effects are this?
    :py:func:`effectus.Effects.retrieve_effects`

Which threshold value the selected values must be greater than or equal to?
    :py:func:`effectus.Effects.separate_effects`

Which share of causes lie in between the specified effect interval?
    :py:func:`effectus.Effects.interval_effects`

Which objects fall into an effects interval formed by a specific attribute?
    :py:func:`effectus.intervals.keys_in_effects_interval`

What if I want to specify causes instead of effects and determine required effects?
    :py:func:`effectus.Effects.attain_causes`

    :py:func:`effectus.Effects.retrieve_causes`

    :py:func:`effectus.Effects.separate_causes`

    :py:func:`effectus.Effects.interval_effects`