Fundamentals Company Geographic Sales Breakdown

Last update: March 2020
Environment: Windows
Compiler: Python and Conda distribution
Prerequisite: Refinitiv Eikon or Refinitiv Workspace application with access to Eikon Data APIs.

Project Overview

Reuters Fundamentals has over 35 years of experience in collecting and delivering the most timely and highestquality fundamentals data in the industry, including an unmatched depth and breadth of primary financial statements, footnote items, segment data, industry specific operating metrics, financial ratios, and much more.

Reuters Fundamentals standardized and As Reported financial statement data – both interim and annual – along with per-share data, calculated financial ratios, company profile information, security data, Officers & Directors and market content for over 90,000 issuers.

Geographic Breakdown Fundamentals Data

Reuters Fundamentals also contains information for each segment reported by a company on an annual and interim basis Global coverage. This information which let you drive down your interested comapny sale revenue of each region.

This project shows how to use Refinitiv Eikon Data API to consume company geographic sale data from Refinitiv Fundamentals, then breakdown and display each region revenue in readable graph format in the classic Jupyter Notebook application.

Prerequisite

This example requires the following dependencies softwares and libraries.

Refinitiv Eikon or Refinitiv Workspace application with access to Eikon Data APIs.
Python Ananconda or MiniConda distribution/package manager.
Classic Jupyter Notebook web application.
Required Python Packages: Eikon, Pandas, Numpy and Matplotlib (They will be installed via conda environment creation).

Note:

This Project has been qualified with Python version 3.7.6 and Conda version 4.8.3
If you are not familiar with Jupyter Notebook, the following tutorial created by DataCamp may help.

Application Files

This example project contains the following files and folders

notebook_python/fundamentals_geographic_sale.ipynb: The example Jupyter Notebook application file.
global_sale_env.yml: The Jupyter Notebook environment and dependencies configuration file.
images: Project images folder.
LICENSE.md: Project's license file.
README.md: Project's README file.

Eikon Data API Setup

Please follow a step by step guide to setup your Eikon Data APIs and your AppKey in Eikon Data API Quick Start page.

How to run this example

Please note that the Refintiv Workspace/Eikon application integrates a Data API proxy that acts as an interface between the Eikon Data API Python library and the Eikon Data Platform. For this reason, the Refinitiv Workspace/Eikon application must be running when you use the Eikon Data API Python library.

The first step is unzip or download the example project folder into a directory of your choice, then choose how to run application based on your environment below.

Running the Notebook example.

Open Anaconda Prompt and go to project's folder
Run the following command in a Anaconda Prompt to create Conda environment named MRN_TRNA for the project.
```
(base) $>conda env create -f global_sale_env.yml
```
Once the environment is created, activate Conda environment named global_sale with this command in Anaconda Prompt
```
(base) $>conda activate global_sale
```
Go to project's notebook folder. and create a file name eikon.cfg with the following content
```
[eikon]
app_id = YOUR_APP_ID_HERE
```
In the current Anaconda Prompt, go to project's notebook folder. Run the following command to start classic Jupyter Notebook in the notebook folder.
```
(global_sale) $>notebook>jupyter notebook
```
Open fundamentals_geographic_sale.ipynb Notebook document, then follow through each notebook cell.

Implementation

There are three main steps for this implementation

Get Company Geographic Sale Data.
Restructure Company Geographic Sale Data Dataframe object that returned from Eikon Data API.
Plotting a graph.

Get Company Geographic Sale Data

Firstly, the Notebook application uses Eikon Data API get_data function to request the company fundamentals via following fields:

TR.BGS.GeoTotalRevenue.segmentName: Segment (Geographic) data
TR.BGS.GeoTotalRevenue: Each segment revenue value
TR.CompanyName

df,err = ek.get_data('IBM.N', ['TR.BGS.GeoTotalRevenue.segmentName', 'TR.BGS.GeoTotalRevenue','TR.CompanyName'])
df

This get_data function returns data as Pandas Dataframe object by default.

Restructure Company Geographic Sale Data Dataframe object.

The returned Dataframe object from Eikon get_data function is not ready to be plotted as "readable" graph yet.

We start by renaming the Segment Name and Geographic Total Revenues (Calculated) columns to readable names like Geographic and Revenues.

df_graph = df.copy()

df_graph.rename(columns={
                   'Segment Name':'Geographic',
                   'Geographic Total Revenues (Calculated)':'Revenues'},
         inplace = True)

df_graph

Then we get the Company name and Consolidated Total Revenue information from Dataframe object.

total_sale = df_graph.iloc[df_graph.shape[0] - 1]['Revenues']

company_name = df_graph.iloc[0]['Company Name']

And the last thing on this phase is to remove the Total revenue rows from the Dataframe as we will display a Consolidated Total information at a graph footter.

df_graph = df_graph[df_graph['Geographic'] != 'Segment Total']
df_graph = df_graph[df_graph['Geographic'] != 'Consolidated Total']

Plotting a graph

Finally, we are now ready for plotting a graph. We create a Python function format_revenues_number to reformat large revenue numbers into a readable numbers in trillions, billions or millions unit. a readable numbers in trillions, billions or millions unit. This function source code is based on Dan Friedman's How to Format Large Tick Values tutorial source code via GitHub.

def format_revenues_number(tick_val, pos):
    """
    Turns large tick values (in the trillions, billions, millions and thousands) such as 4500 into 4.5K 
    and also appropriately turns 4000 into 4K (no zero after the decimal).
    """
    if tick_val >= 1000000000000: # Add support for trillions
        val = round(tick_val/1000000000000, 1)
        new_tick_format = '{:}T'.format(val)
    elif tick_val >= 1000000000:
        val = round(tick_val/1000000000, 1)
        new_tick_format = '{:}B'.format(val)
    elif tick_val >= 1000000:
        val = round(tick_val/1000000, 1)
        new_tick_format = '{:}M'.format(val)
    elif tick_val >= 1000:
        val = round(tick_val/1000, 1)
        new_tick_format = '{:}K'.format(val)
    elif tick_val < 1000:
        new_tick_format = round(tick_val, 1)
    else:
        new_tick_format = tick_val

     # make new_tick_format into a string value
    new_tick_format = str(new_tick_format)
    """
    code below will keep 4.5M as is but change values such as 4.0M to 4M since that 
    zero after the decimal isn't needed
    """
    index_of_decimal = new_tick_format.find(".")
    
    if index_of_decimal != -1:
        value_after_decimal = new_tick_format[index_of_decimal+1]
        if value_after_decimal == "0":
            # remove the 0 after the decimal point since it's not needed
            new_tick_format = new_tick_format[0:index_of_decimal] + new_tick_format[index_of_decimal+2:]
            
    return new_tick_format

We use Python matplotlib.pyplot library to plot a bar graph that represent each region revenue from restructured Dataframe object in Jupyter Notebook.

# Plotting a Graph

df_graph.set_index('Geographic',drop=True,inplace=True)
fig = plt.figure()

#Format Total Sale display unit as a graph footer.
fig.text(.5, -.05, 'Consolidated Total Sale %s' %(f'{total_sale:,.2f}'), ha='center',fontsize='large')

# Create graph title from Company and RIC names dynamically.
plt.ticklabel_format(style = 'plain')
plt.title('%s (%s) Geographic Sale Breakdown' % (company_name, 'IBM.N'), color='black',fontsize='x-large')
ax = fig.gca()

#Apply Sale data into millions function.
formatter = FuncFormatter(format_revenues_number)
ax.xaxis.set_major_formatter(formatter)

df_graph.plot(kind='barh', ax = fig.gca())
plt.show()

Conclusion

Refinitiv provides a wide range of Reuters Fundamentals data for your investment decisions including company geographic sale information. This information helps you analysis the revenue from each geographic region of your interested company in both panel data and graph formats.

References

You can find more detail regarding the Eikon Data APIs and related technologies for this Notebook from the following resources:

For any question related to this example or Eikon Data API, please use the Developers Community Q&A Forum.

LSEG-API-Samples/Article.EikonAPI.Python.Jupyter.Geographic_Sale_Breakdown