Tutorial

Welcome to prettyresults tutorial! In this example we will analyze some sales data, generating some descriptive graphics and tables. We will learn how to tell prettyresults about them so it can generate a web page and a Word document with them. The example full code and data is accessible in the project’s git repository (https://github.com/anarthal/prettyresults), under the examples/ directory. The resulting web page is accessible online here.

The FooBar company sells their BarBaz product brand around the world. We have a CSV with data about their shipments, telling where they ship and which channel did they use (online/offline). We will do some basic descriptive analytics using standard Python Pandas/Matplotlib, and will make prettyresults generate a web with them.

We first load the CSV using standard Pandas:

    csv_path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'data.csv')
    df = pd.read_csv(csv_path)

We now create an prettyresults.ResultTree object. This is the heart of prettyresults: it will accumulate the results of our analysis to generate the web and Word afterwards:

    ctx = ResultTree()

The ResultTree stores results hierarchically. Results may be of the following types:

• Figures. These are matplotlib graphs.
• Tables. The name speaks by itself.
• Containers. These are intermediate nodes in the tree, and contain further results. They are shown as folders in the web page, and as headings in the Word document. Container results are represented by the prettyresults.results.ContainerResult class, and have methods to add other results as children. This is the preferred way to add new results.

Results have a unique ID (more info here) and a human-friendly display name. By default, the ResultTree creates a single container result, of ID root. We may retrieve any result by ID using prettyresults.ResultTree.get_result():

    root_result = ctx.get_result('root')

We are going to analyze channel and region data, as well as the interaction between the two. We create one container result for each one, using prettyresults.results.ContainerResult.add_container(). We need to provide an ID, unique within the current container, and a display name:

    # Container results have several add_<result-type> methods, which create a result and add
    # it as a child of the container. You must pass at least the child result id and the child name.
    region_result = root_result.add_container('region', 'Region')
    channel_result = root_result.add_container('channel', 'Channel')
    region_channel_result = root_result.add_container('channel-by-region', 'Sales channel by region')

Let’s create a bar plot for the Region variable. We use prettyresults.results.ContainerResult.add_figure() to add it to our tree:

    df['Region'].value_counts().plot.bar()
    
    # add_figure will add a figure result, using the current active figure
    # (the bar plot, in our case)
    region_result.add_figure('bar', 'Frequency bar chart')

We are also going to add a frequency table for Region. ContainerResult has several method for adding tables. As value counts will be stored in a pandas.Series, we will use prettyresults.results.ContainerResult.add_series_table():

    # add_series_table will add a table result from a pandas Series object
    region_result.add_series_table('freqs',
                                   'Frequency table',
                                   df['Region'].value_counts())

We will perform similar operations for Channel and Region-Channel, omitted here for brevity. The next step is to generate the web page:

    # We've added a bunch of results now. The result tree will look like this:
    # root
    #    root.region
    #       root.region.bar
    #       root.region.freq
    #    root.channel
    #       root.channel.bar
    #       root.channel.freq
    #    root.channel-by-region
    #       root.channel-by-region.freq
    #       root.channel-by-region.bar
    #
    # The generated web page and Word document will represent this layout.
    
    # Generate the web and open a browser tab to view it.
    web_directory = os.path.join(tempfile.gettempdir(), 'prettyresults_web')
    ctx.generate_web(web_directory, open_browser=True, overwrite=True)

Finally, we will also generate a Word document with all the tables and figures:

    word_path = os.path.join(tempfile.gettempdir(), 'results.docx')
    ctx.generate_word(word_path)

That concludes prettyresults’s tutorial! You can check the aspect of the generated web page here.