NeXL: Excel Connector for .NET

February 10, 2017

Getting Real Time Bloomberg Data into Excel with NeXL and F#

Filed under: Uncategorized — Adam Mlocek @ 11:03 pm

Introduction

Bloomberg real time data can be consumed by .NET applications via Bloomberg API. In this post I would like to show how we can easily get that same data into Excel with a bit of F# async code and NeXL Connector. I will start with a demo spreadsheet and then delve into the code behind it.

Bloomberg Spreadsheet

If you have Excel 2007 and Bloomberg Subscription then you can try it yourself. Simply download this spreadsheet: Bloomberg.xlsm, right click to Unblock it and follow the steps below. If you do not have access to Bloomberg then you can try this spreadsheet instead:  BloombergEmu.xlsm. It uses Bloomberg Emulator.

The spreadsheet contains a User Defined Function Blp.getMarketData(). It takes a topic and an array of fields as arguments:

bloombergmarketdata

This UDF will subscribe the cell to a stream of real time data for a given topic and fields. The interesting thing is that it returns a table of data but it is not an array formula and it resizes automatically depending on the number of fields. If we change the topic or fields then the cell will automatically unsubscribe from the stream of data and subscribe to the new one.

How does it work?

The spreadsheet is powered by NeXL Connector. NeXL is available as a Nuget package and allows me to embed .NET functions as UDFs in Excel spreadsheets. It is free to use, including commercial use (CC 4.0 License), but requires permission to redistribute the runtime.

All UDFs in my spreadsheet are defined in an F# project. The project is open source and you can find it on Github. You can clone and build it on your local machine. I have used VS Code and F# Ionide plugin to create the project.

The project uses Bloomberglp.Blpapi.dll to create a session and subscribe to Bloomberg Data. The API is asynchronous and event based so I use a simple F# agent to process all messages. The agent is started in an instance of BlpSession and accepts messages of type  SessionMsg:

type SessionMsg =
    | OpenSession of serverHost : string * serverPort : int
    | SessionEvent of event : Event * session : Session
    | RefDataRequest of securities : string[] * fields : string[] * reply : AsyncReplyChannel<Element list>
    | SubscriptionStart of topic : string * fields : string[] * obsSubscription : ObservableSubscription

Once a session is opened successfully all session events are redirected into the agent as SessionEvent messages. We can then subscribe to a topic with SubscriptionStart messages. All real time data messages are then sent automatically into the agent as SessionEvent messages. So how do we get them out of the agent and into Excel?

In each SubscriptionStart message there is an instance of ObservableSubscription. This type is defined in my project. It implements IObservable<Message list>. When a data message arrives the agent will simply call a method ObservableSubscription.SendEvent which then calls OnNext for the subscribed observer. Messages have correlation ids so that we can track which subscription to call. This information is part of the state of the agent:

type SessionState =
   {
    Session : Session option
    RefDataService : Service option
    LastCorrId : int64
    RequestResponses : Dictionary<int64, Element list>
    Subscriptions : Dictionary<int64, ObservableSubscription>
    Replies : Dictionary<int64, AsyncReplyChannel<Element list>>
   }

The UDF Blp.getMarketData() is an F# function which takes a topic, an array of fields and an optional Session and returns IObservable<XlTable>:

let getMarketData (topic : string, fields : string[], session : BlpSession option) : IObservable<XlTable> =
    let fields = fields |> Array.distinct
    let session = defaultArg session defaultSession.Value
    let subscription = new ObservableSubscription()
    session.StartSubscription(topic, fields, subscription)
    subscription |> Observable.map (marketDataToXlTable fields)

Observable.map transforms the raw list of messages into XlTableXlTable represents a table of data which can be shown in an Excel range and is defined in NeXL. It is a special type which signals to NeXL runtime that the result is a table and should be sent to a range below and to the right of the calling cell. A comment is also automatically added to the calling cell, e.g. XlTable 2 x 3. NeXL will automatically create an RTD subscription for our IObservable so there is nothing else to do and we can use it as a UDF in Excel.

Finally, the project is built with Fake. The script is in build.fsx. The “Build” target will build the project so that we get a .NET assembly with all UDFs inside. Then “Embed” target will package NeXL Runtime, UDF assembly and any referenced assemblies into a macro enabled Excel spreadsheet. This spreadsheet is self contained and can be used on any machine with Excel 2007 or later and .NET.

For NeXL News follow Twitter @nexl_connector.

 

February 2, 2017

Getting IMF Data into Excel with NeXL Connector and F#

Filed under: Uncategorized — Adam Mlocek @ 9:13 pm

Introduction

IMF Data can be imported by applications via SDMX or JSON Restful APIs. This makes it easy for any .NET client, e.g. WCF or ASP.NET, to consume it. Unfortunately, Excel which is probably the most popular environment to analyse financial and economic data does not have an easy mechanism to access that wealth of data. In this post I would like to present a new way of getting any external data into Excel with single cell UDFs. I will start with a spreadsheet demo and then explain a bit more how it works.

IMF Data Spreadsheet

If you have Excel 2007 or later you can try it yourself. Simply download this spreadsheet: IMF.xlsm, right click to Unblock it and follow the steps below.

The spreadsheet contains a few User Defined Functions which start with IMF. One of them is IMF.getDatasetList():

imf_getdatasets

This UDF calls IMF Data Service and gets a list of all available datasets. The interesting thing is that it returns a table of data but it is not an array formula. This is very convenient because usually we do not know the size of the data upfront. Also, a comment has been automatically added to the calling cell which shows the size of the table. More on this in the next section.

DatasetId is important because it is used in other calls to the API to identify the dataset we need. Each dataset usually has a few dimensions, e.g. Country or Indicator. We can get a list of dataset dimensions with UDF IMF.getDimensions():

imf_getdims

As you can see BOP dataset (Balance of Payments) has 3 dimensions. Each of these dimensions will have a discrete set of possible values (codes) by which we can slice it. Before we request the actual data we need to know what are the possible codes. For that I have a UDF IMF.getCodeList(). Let’s see what are the codes for CL_FREQ:

imf_getfreqlist

We can get code lists for BOP Area and Indicator in a similar way:

imf_getarealist

imf_getindicatorlist

We can now slice BOP dataset by specifying frequency, area(s) and indicator(s). The UDF to get the data is called IMF.getSeriesData():

imf_getseriesdata1

I have requested BOP data with Annual frequency for Germany (DE) and Indicator IADFDC_BP6_EUR in 2015 only. Let’s try a range of periods:

imf_getseriesdata2

If the data has a time series format then the first column is Period followed by each combination of requested dimension codes. For example we can request data for 2 countries and 2 indicators at the same time:

imf_getseriesdata3

Note that you need to concatenate different codes with “+”, e.g. “DE+FR”.

The UDFs in my IMF spreadsheet are embedded in the spreadsheet and will not be available once I close it. If you want to use them in other spreadsheets then you can simply activate it as Excel Customization:

imf_activate

 

How does it work?

The spreadsheet is powered by NeXL Connector. NeXL is available as a Nuget package and allows me to embed .NET functions as UDFs in Excel spreadsheets. It is free to use, including commercial use (CC 4.0 License), but requires permission to redistribute the runtime.

All UDFs in IMF spreadsheet are defined in an F# project. The project is open source and you can find it on Github. You can clone and build it on your local machine. I have used VS Code and F# Ionide plugin to create the project.

The UDFs are defined in a module IMF. The module is marked with [<XlQualified(true)>] attribute so that their name in Excel always starts with IMF for easy discovery.

The project uses FSharp.Data and Newtonsoft.Json packages to make async requests to IMF Json Restful API and deserialize the response.

The response is usually a data table. It is then converted to a special XlTable object. XlTable represents a table of data which can be shown in an Excel range and is defined in NeXL. It is a special type which signals to NeXL runtime that the result is a table and should be sent to a range below and to the right of the calling cell. A comment is also automatically added to the calling cell, e.g. XlTable 2 x 3. All IMF UDFs actually return async<XlTable> which means that the data is downloaded asynchronously without blocking Excel thread. You will see #WAIT until the data is available.

Finally, the project is built with Fake. The script is in build.fsx. The “Build” target will build the project so that we get a .NET assembly with all UDFs inside. Then “Embed” target will package NeXL Runtime, UDF assembly and any referenced assemblies into a macro enabled Excel spreadsheet. This spreadsheet is self contained and can be used on any machine with Excel 2007 or later and .NET.

 

 

 

Blog at WordPress.com.