.. _datasets:

########
Datasets
########

RaGraph has several :obj:`~ragraph.graph.Graph` ready to use datasets built-in. These
datasets serve as an excellent starting point when designing and testing your analysis
scripts. The basic method of retrieval of the :obj:`~ragraph.datasets` module are
discussed, which includes ways to obtain more background information on each of them.


*****************
What's available?
*****************

Let's start off by importing the datasets module and listing what's available.

.. doctest::

   >>> from ragraph import datasets
   >>> datasets.enum()
   ['aircraft_engine', 'architecture_integral', 'architecture_mix', 'architecture_modular', 'climate_control', 'climate_control_mg', 'compatibility', 'design', 'eefde_lock', 'elevator175', 'elevator45', 'ford_hood', 'kodak3d', 'ledsip', 'localbus', 'overlap', 'pathfinder', 'shaja8', 'similarity', 'tarjans8', 'ucav']


So that's a merry band of different datasets, with names that might leave you wonder.
Luckily, all datasets come with some info for you. That info is retrievable from the
:obj:`~ragraph.datasets` sub-module descriptions, as well as by calling the
:obj:`~ragraph.datasets.info` method:

.. doctest::

   >>> print(datasets.info("aircraft_engine"))
   Pratt & Whitney Aircraft Engine
   <BLANKLINE>
   A directed graph describing the Pratt & Whitney PW4098 commercial high bypass-ratio
   turbofan engine. The graph describes a combination of the actual hardware dependencies
   of the engine and those of the development teams involved with them. It is a weighted
   and directed graph featuring 60 elements, four of which are sometimes left out as they
   represent the integration teams and no individual hardware components. Weak and strong
   dependencies are distinguished using weights of 1 and 2, respectively.
   <BLANKLINE>
   Reference:
   Rowles, C. M. (1999). System integration analysis of a large commercial aircraft engine.
   <BLANKLINE>


*****************
Getting a dataset
*****************

Getting a :obj:`~ragraph.graph.Graph` from the datasets is as easy as calling the
:obj:`~ragraph.datasets.get` method:

.. doctest::

   >>> g = datasets.get("climate_control")
   >>> g.get_ascii_art()
                         ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
                 Radiator┥ ■ │ X │   │   │ X │   │   │   │   │   │   │   │   │   │   │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
               Engine Fan┥ X │ ■ │   │   │ X │   │   │   │   │   │   │   │ X │   │   │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
              Heater Core┥   │   │ ■ │ X │   │   │ X │ X │   │   │   │   │   │   │   │ X │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
             Heater Hoses┥   │   │ X │ ■ │   │   │   │   │ X │   │   │   │   │   │   │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
                Condenser┥ X │ X │   │   │ ■ │ X │   │ X │   │   │   │   │   │   │   │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
               Compressor┥   │   │   │   │ X │ ■ │   │ X │ X │ X │ X │   │ X │   │   │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
          Evaporator Case┥   │   │ X │   │   │   │ ■ │ X │   │   │   │   │   │ X │ X │ X │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
          Evaporator Core┥   │   │ X │   │ X │ X │ X │ ■ │ X │   │   │   │   │   │   │ X │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
              Accumulator┥   │   │   │ X │   │ X │   │ X │ ■ │ X │   │   │   │   │   │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
   Refrigeration Controls┥   │   │   │   │   │ X │   │   │ X │ ■ │ X │   │ X │   │   │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
             Air Controls┥   │   │   │   │   │ X │   │   │   │ X │ ■ │ X │ X │ X │ X │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
                  Sensors┥   │   │   │   │   │   │   │   │   │   │ X │ ■ │ X │   │   │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
     Command Distribution┥   │ X │   │   │   │ X │   │   │   │ X │ X │ X │ ■ │ X │ X │ X │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
                Actuators┥   │   │   │   │   │   │ X │   │   │   │ X │   │ X │ ■ │   │   │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
        Blower Controller┥   │   │   │   │   │   │ X │   │   │   │ X │   │ X │   │ ■ │ X │
                         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
             Blower Motor┥   │   │ X │   │   │   │ X │ X │   │   │   │   │ X │   │ X │ ■ │
                         └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘