Quick Start

Installation

Requirements

• Python 3.12 or 3.13

Installing

pip install kaxanuk-attribution_analysis  --extra-index-url https://license:{YOUR_LICENSE_KEY}@{SERVER}/simple/

Note

The full command with your license key is included ready to copy in the welcome email you receive after purchase.

The same command installs kaxanuk-license-client, the license check KaxaNuk’s libraries share, from the same index.

You can acquire your license here.

Interested in collaborating on a custom project? Get in touch at software@kaxanuk.mx.

Initialize project structure

1. Open a terminal in your project directory and run:

   kaxanuk.attribution_analysis init excel
   

   This creates the following structure:

   project-root/
   ├── __main__.py                                   # Entry script
   ├── Config/
   │   ├── .env                                      # Environment variables (e.g. FRED_API_KEY)
   │   └── attribution_analysis_parameters.xlsx      # Configuration template
   ├── Input/
   │   ├── Data/                                     # Market data files (one per ticker)
   │   ├── Portfolios/                                # Portfolio weight files
   │   ├── Benchmark_Portfolios/                      # Benchmark weights + benchmark returns
   │   └── Factor_Models/                             # Per-factor return files
   └── Output/                                        # Analysis results
   

Set your license key

Running the analysis requires a valid KaxaNuk license key. Open Config/.env and replace the placeholder with your actual key:

KNAA_API_KEY_KAXANUK=LIC-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Config/.env is loaded automatically by the entry script, so you don’t need to set environment variables in your terminal. Alternatively, export KNAA_API_KEY_KAXANUK in your environment, or keep the key in a .kaxanuk_license file in your home folder or in the working folder, on a line of its own: KNAA_API_KEY_KAXANUK=<your license key>.

Each run checks your license with the KaxaNuk license server, the one that serves every KaxaNuk library, for Attribution Analysis: the key has to belong to a license that includes it, and a license the server rejects (unknown, expired, revoked, or out of devices) stops the analysis at once. A successful check is saved on your machine: for 24 hours the analysis does not contact the server at all, and when the server cannot be reached (no connection, a timeout, or an outage on our side) it keeps working for 3 days from the last successful check, never past the license’s own expiry date, with a warning each run saying how much of that window is left. The first run after upgrading from version 0.2 or earlier needs the network: the check those versions saved is not carried over.

Advanced: KNAA_LICENSE_SERVER_URL points Attribution Analysis at another license server, and KAXANUK_LICENSE_SERVER_URL does the same for every KaxaNuk library, read after it. When neither is set, the unified KaxaNuk license server is used; a value that is not an http or https URL stops the analysis with a LicenseConfigurationError before anything is sent.

After initialization, populate the Input/ subfolders with your data (see Data Formats) and edit Config/attribution_analysis_parameters.xlsx (see Configuration Reference).

Usage

Run the analysis using:

kaxanuk.attribution_analysis run

The system will read the configured inputs, run the enabled attribution methodologies, and save results in the Output folder (and launch the dashboard if configured to do so).