Data analysis and reporting tool for quick access to custom charts and tables in Jupyter Notebooks and in the shell.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs added readthedocs yaml with python version Sep 14, 2018
fireant upgraded version to 1.0.1 Sep 27, 2018
scripts Tidied up mysql_functions.sql trunc function Sep 19, 2017
.coveragerc Added .coveragerc file to try and ignore the test folder in coveralls Jun 9, 2017
.gitignore FireAnt - Initial commit Aug 8, 2016
.readthedocs.yml
.travis.yml Removing matplotlib from travis-ci yaml and making it possible to ski… Sep 14, 2018
LICENSE.txt
MANIFEST.in
README.rst
requirements-dev.txt Split dev requirements out into their own file Sep 14, 2018
requirements.txt Removing PatternDimension Sep 27, 2018
setup.py Split dev requirements out into their own file Sep 14, 2018
tox.ini Initial commit of 1.0 Jan 19, 2018

README.rst

FireAnt - Analytics and Reporting

BuildStatus CoverageStatus Codacy Docs PyPi License

fireant is a a data analysis tool used for quickly building charts, tables, reports, and dashboards. It defines a schema for configuring metrics and dimensions which removes most of the leg work of writing queries and formatting charts. fireant even works great with Jupyter notebooks and in the Python shell providing quick and easy access to your data.

Read more at http://fireant.readthedocs.io/en/latest/

Installation

To install fireant, run the following command in the terminal:

pip install fireant

Introduction

fireant arose out of an environment where several different teams, each working with data sets often with crossover, were individually building their own dashboard platforms. fireant was developed as a centralized way of building dashboards without the legwork.

fireant is used to create configurations of data sets using Slicer which backs a database table containing analytics and defines sets of Dimension and Metric. A Dimension is used to group data by properties, such as a timestamp, an account, a device type, etc. A Metric is used to render quanitifiers such as clicks, ROI, conversions into a widget such as a chart or table.

A Slicer exposes a rich builder API that allows a wide range of queries to be constructed that can be rendered as several widgets. A Slicer can be used directly in a Jupyter notebook, eliminating the need to write repetitive custom queries and render the data in visualizations.

Slicers

Slicer are the core component of fireant. A Slicer is a representation of a data set and is used to execute queries and transform result sets into widgets such as charts or tables.

A Slicer requires only a couple of definitions in order to use: A database connector, a database table, join tables, and dimensions and metrics. Metrics and Dimension definitions tell fireant how to query and use data in widgets. Once a slicer is created, it's query API can be used to build queries with just a few lines of code selecting which dimensions and metrics to use and how to filter the data.

Instantiating a Slicer

from fireant.slicer import *
from fireant.database import VerticaDatabase
from pypika import Tables, functions as fn

vertica_database = VerticaDatabase(user='myuser', password='mypassword')
analytics, accounts = Tables('analytics', 'accounts')

my_slicer = Slicer(
    # This is the primary database table that our slicer uses
    table=analytics,

    # Define the database connection object
    database=vertica_database,

    joins=[
        # Metrics and dimensions can use columns from joined tables by
        # configuring the join here. Joins will only be used when necessary.
        Join('accounts', accounts, analytics.account_id == accounts.id),
    ],

    metrics=[
        # A unique key is required for each metric
        Metric('impressions'),
        Metric('clicks'),
        Metric('conversions'),
        Metric('cost'),
        Metric('revenue'),

        # By default, a metric maps one-to-one with a column in the database
        # but it can also be given a more complex definition.
        Metric('cpc', label='CPC',
               definition=fn.Sum(analytics.cost) / fn.Sum(analytics.clicks)),
        Metric('rpc', label='RPC',
               definition=fn.Sum(analytics.revenue) / fn.Sum(analytics.clicks)),
        Metric('roi', label='ROI',
               definition=fn.Sum(analytics.revenue) / fn.Sum(analytics.cost)),
    ],

    dimensions=[
        # Datetime Dimensions are continuous and must be truncated to an interval
        # like hour, day, week. Day is the default.
        DatetimeDimension('date', definition=analytics.dt),

        # Categorical dimensions are ones with a fixed number of options.
        CategoricalDimension('device', display_options=[DimensionValue('desktop'),
                                                DimensionValue('tablet'),
                                                DimensionValue('mobile')]),

        # Unique dimensions are used for entities that have a unique ID and
        # a display name field
        UniqueDimension('account', label='Account Name', definition=analytics.account_id,

                        # The accounts table is joined to get more data about the
                        # account.
                        display_field=accounts.name,

                        # Just a list of keys of the required joins is needed.
                        joins=['accounts']),
    ],
)

Building queries with a Slicer

Use the data attribute start building a slicer query. A slicer query allows method calls to be chained together to select what should be included in the result.

This example uses the slicer defined above

from fireant import Matplotlib, Pandas, daily

 matplotlib_chart, pandas_df = my_slicer.data \
      .dimension(
         # Select the date dimension with a daily interval to group the data by the day applies to
         # dimensions are referenced by `slicer.dimensions.{alias}`
         my_slicer.dimensions.date(daily),

         # Select the device_type dimension to break the data down further by which device it applies to
         my_slicer.dimensions.device_type,
      ) \
      .filter(
         # Filter the result set to data to the year of 2018
         my_slicer.dimensions.date.between(date(2018, 1, 1), date(2018, 12, 31))
      ) \
      # Add a week over week reference to compare data to values from the week prior
      .reference(WeekOverWeek(slicer.dimension.date))
      .widget(
         # Add a matpotlib chart widget
         Matplotlib()
            # Add axes with series to the chart
            .axis(Matplotlib.LineSeries(slicer.metrics.clicks))

            # metrics are referenced by `slicer.metrics.{alias}`
            .axis(Matplotlib.ColumnSeries(slicer.metrics.cost, slicer.metrics.revenue))
      ) \
      .widget(
         # Add a pandas data frame table widget
         Pandas(slicer.metrics.clicks, slicer.metrics.cost, slicer.metrics.revenue)
      ) \
      .fetch()

 # Display the chart
 matplotlib_chart.plot()

 # Display the chart
 print(pandas_df)

License

Copyright 2016 KAYAK Germany, GmbH

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Crafted with ♥ in Berlin.