How do I use Lumipy to interact with Luminesce?

Lumipy is a Python library that makes it easy to use Luminesce as part of the Python data science ecosystem, in particular Pandas and Jupyter.

Once installed and authenticated, and providing end users have sufficient access control permissions, they can interact with Luminesce using their familiar Python programming environment. See all tools and interfaces to Luminesce.

Installing Lumipy

If you have previously used Lumipy with v1 of the SDKs (dve-lumipy-preview), follow these steps to use Lumipy with the v2 SDKs.

To install Lumipy, run the following command:

pip install lumipy

For an installation which only installs the parts of Lumipy you specifically require, run the following command to download Lumipy without dependencies:

pip install lumipy --no-dependencies

You can then install the parts you require, for example:

pip install pandas luminesce-sdk

Authenticating to Lumipy

As with any FINBOURNE SDK, you must obtain an API access token. For Lumipy, we recommend authenticating using a personal access token.

You can follow these steps to obtain a personal access token.

Once you have obtained a personal access token you must add it, alongside your LUSID domain, to your Lumipy configuration:

import lumipy as lm
lm.config.add('<your-domain>', '<your-personal-access-token>')

If you want to add more than one domain, add each domain and personal access token to your Lumipy configuration and then set the domain you want to interact with:

import lumipy as lm
lm.config.add('<your-other-domain>', '<your-personal-access-token>')
lm.config.domain = '<your-other-domain>'

Sending a SQL query directly to Luminesce

The simplest way to work with Lumipy is to use the client object to send a Luminesce SQL query directly to Luminesce.

For example, to use the Lusid.Instrument.Equity provider to retrieve the first five equity instruments mastered in LUSID as a Pandas dataframe:

import lumipy as lm
client = lm.get_client()
df = client.run('select * from lusid.instrument.equity where Scope = \'default\' limit 5')

Scripting queries using Python

The most powerful way to work with Lumipy is to use the atlas object to create a hub for exploring providers and scripting queries using Python instead of SQL.

For example, to use the Lusid.Instrument.Equity provider to retrieve the first five equity instruments mastered in LUSID as a Pandas dataframe:

import lumipy as lm
atlas = lm.get_atlas()
instr_provider = atlas.lusid_instrument() 
query = instr_provider.select('*').limit(5)
df = query.go()

To upsert equity instruments to LUSID using the Lusid.Instrument.Equity.Writer provider, you might:

1. Read data into Pandas from a CSV file:

   import lumipy as lm
   import pandas as pd
   instr_df = pd.read_csv("data.csv", keep_default_na = False)

   
2. Rename dataframe columns to align with expected provider column names, and add a column specifying an instrument scope:

   instr_df.rename(columns = {'Security': 'DisplayName', 'Internal_id': 'ClientInternal', 'Currency': 'DomCcy'}, inplace = True)
   instr_df['Scope'] = 'MyProtectedInstrumentScope'

   
3. Convert the dataframe to a table variable in preparation for upserting to LUSID:

   tv = lm.from_pandas(instr_df)

   
4. Upsert to LUSID, showing the response to retrieve the LUIDs and check for errors:

   w = atlas.lusid_instrument_equity_writer(to_write = tv)
   q = w.select('^')
   q.go()

   

Getting more information

Lumipy also contains a command line interface (CLI). You can view functions and help for the CLI using --help:

$ lumipy --help

For more information, refer to the Lumipy PyPi page or read the User Guide. Note the User Guide is 23 pages in total, not all of it shown at once; keep clicking the More Pages button:

You can also work through these Jupyter Notebook tutorials.

Note these statistical custom functions are designed to be used with Lumipy.

See how to use Lumipy to create your own data providers in Python.

Appendix A: Upgrading to v2 SDKs

Lumipy utilises v2 of the FINBOURNE SDKs. If you have previously used Lumipy with v1 of the SDKs, you must follow these steps to use Lumipy with the v2 SDKs:

1. Run the following command to uninstall dve-lumipy-preview:

   pip uninstall dve-lumipy-preview

2. Run the following command to install Lumipy and force update all Lumipy dependencies:

   pip install --force-reinstall lumipy

   Note: Using --force-reinstall could affect your other Python projects. If you prefer not to update all dependencies, you can omit it:

   pip install lumipy