Metadata-Version: 2.4
Name: nubra_ref_data
Version: 0.1.1
Summary: Reference-data helpers for Nubra InstrumentData option, future, and underlying DataFrames
Author: Akshay N
License-Expression: MIT
Project-URL: Homepage, https://github.com/akshayn-spec/nubra_ref_data
Project-URL: Repository, https://github.com/akshayn-spec/nubra_ref_data
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Dynamic: license-file

# nubra_ref_data

`nubra_ref_data` is a small helper package for Nubra `InstrumentData` users who want filtered pandas DataFrames for:

- the underlying row
- futures rows
- option rows by expiry bucket and strike levels
- one combined DataFrame containing all of the above

It is designed to work with:

```python
from nubra_python_sdk.refdata.instruments import InstrumentData

instruments = InstrumentData(nubra)
```

## Install

```bash
pip install nubra_ref_data
```

## Functions

- `underlying_data(instruments, underlying, exchange="NSE")`
- `futures_data(instruments, underlying, exchange="NSE")`
- `options_data(instruments, underlying, exchange="NSE", expiry_bucket="week0", levels=10, option_side="BOTH")`
- `all_data(instruments, underlying, exchange="NSE", expiry_bucket="week0", levels=10, option_side="BOTH")`

## Example

```python
from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv
from nubra_python_sdk.refdata.instruments import InstrumentData

from nubra_ref_data import all_data, futures_data, options_data, underlying_data


nubra = InitNubraSdk(NubraEnv.UAT, env_creds=True)
instruments = InstrumentData(nubra)

df_underlying = underlying_data(
    instruments=instruments,
    underlying="NIFTY",
    exchange="NSE",
)
print("UNDERLYING")
print(df_underlying)

df_futures = futures_data(
    instruments=instruments,
    underlying="NIFTY",
    exchange="NSE",
)
print("FUTURES")
print(df_futures)

df_options = options_data(
    instruments=instruments,
    underlying="NIFTY",
    exchange="NSE",
    expiry_bucket="week0",
    levels=5,
    option_side="BOTH",
)
print("OPTIONS")
print(df_options)

df_all = all_data(
    instruments=instruments,
    underlying="NIFTY",
    exchange="NSE",
    expiry_bucket="week0",
    levels=5,
    option_side="BOTH",
)
print("ALL DATA")
print(df_all)

df_sensex = all_data(
    instruments=instruments,
    underlying="SENSEX",
    exchange="BSE",
    expiry_bucket="week0",
    levels=6,
    option_side="BOTH",
)
print("SENSEX BSE")
print(df_sensex)
```

## Example Output

PyPI will render this section too, so users can see the expected shape before installing.

```text
UNDERLYING
      stock_name   ref_id exchange    asset asset_type derivative_type expiry strike_price option_type lot_size tick_size token            nubra_name         isin underlying_prev_close
0          NIFTY  1234567      NSE    NIFTY      INDEX                      <NA>         <NA>        <NA>     <NA>      <NA>  <NA>   INDEX_NIFTY.NSECM          N/A             2245000

FUTURES
       stock_name   ref_id exchange asset asset_type derivative_type    expiry strike_price option_type  lot_size  tick_size  token              nubra_name isin  underlying_prev_close
0  NIFTY24APRFUT  2233445      NSE NIFTY   INDEX_FO             FUT  20260424           -1        <NA>        75         10  45678  FUT_NIFTY_20260424  N/A                2245000

OPTIONS
         stock_name   ref_id exchange asset asset_type derivative_type    expiry  strike_price option_type  lot_size  tick_size  token                     nubra_name isin  underlying_prev_close
0  NIFTY24APR22400CE  2233501      NSE NIFTY   INDEX_FO             OPT  20260424       2240000          CE        75          5  45690  OPT_NIFTY_20260424_CE_2240000  N/A                2245000
1  NIFTY24APR22450CE  2233502      NSE NIFTY   INDEX_FO             OPT  20260424       2245000          CE        75          5  45691  OPT_NIFTY_20260424_CE_2245000  N/A                2245000
2  NIFTY24APR22450PE  2233503      NSE NIFTY   INDEX_FO             OPT  20260424       2245000          PE        75          5  45692  OPT_NIFTY_20260424_PE_2245000  N/A                2245000
3  NIFTY24APR22400PE  2233504      NSE NIFTY   INDEX_FO             OPT  20260424       2240000          PE        75          5  45693  OPT_NIFTY_20260424_PE_2240000  N/A                2245000
```

## Behavior

- `week0`, `week1`, `week2`, `week3`, and `week4` resolve against the sorted available option expiries for that underlying.
- `month` resolves to the first month-end expiry available in the option data.
- `levels` picks the nearest strikes using `underlying_prev_close`.
- `option_side="BOTH"` only selects strikes where both `CE` and `PE` exist.
- `all_data()` returns rows in this order: underlying, futures, then options.
- If the underlying cash/index row is missing from the instruments master, a placeholder `UNDERLYING` row is added.
- The returned DataFrames preserve the original instrument columns only. No helper columns are added.
