CLI Documentation#

Overview#

This page contains the complete documentation for the Attribution Analysis command-line interface (CLI), including all available commands, options, and usage examples.

Usage#

Below is the entry point for the CLI. Run kaxanuk.attribution_analysis --help to see all commands, or kaxanuk.attribution_analysis <command> --help for details on a specific command.

kaxanuk.attribution_analysis#

Attribution Analysis command-line interface.

Provides four subcommands to manage an attribution project end-to-end:

- autorun: one-shot install + run for the Excel workflow.
- init:    create the directory structure and template files.
- run:     execute one or more entry scripts.
- update:  regenerate the Excel template or entry script.

Run a subcommand with –help to see its specific options.

Usage

kaxanuk.attribution_analysis [OPTIONS] COMMAND [ARGS]...

Options

--version#: Show the version and exit.

autorun#

Install missing files on first run, then execute the entry script.

Convenience command for end users: when the current directory does not contain a __main__.py entry script, autorun installs the Excel project structure (Config/, Input/Data/, Input/Portfolios/, Input/Benchmark_Portfolios/, Input/Factor_Models/, Output/) plus a default __main__.py and exits, asking you to fill in the configuration. On a subsequent invocation, when the entry script is already present, autorun runs it instead.

Typical first-time flow:

python -m kaxanuk.attribution_analysis autorun   (installs files)
Edit Config/attribution_analysis_parameters.xlsx
python -m kaxanuk.attribution_analysis autorun   (executes analysis)

Usage

kaxanuk.attribution_analysis autorun [OPTIONS]

init#

Create the directories and template files for an attribution project.

CONFIG_FORMAT is the configuration format to initialize. Currently only excel is supported, which lays out the project around an Excel parameters workbook.

The command creates the following structure in the current working directory:

- Config/                          (Excel parameters template)
- Input/Data/                      (market data CSV/Parquet files)
- Input/Portfolios/                (portfolio CSV files)
- Input/Benchmark_Portfolios/      (benchmark weights CSV files)
- Input/Factor_Models/             (factor returns CSV files)
- Output/                          (analysis results land here)
- <entry_script>                   (Python entry point, default __main__.py)

The --entry_script option lets you customize the name of the generated entry script (useful when you want to keep several projects side by side).

If a Config/ directory already exists, the command refuses to overwrite it and asks you to run update instead.

Parameters#

config_format: The name of the configuration format to be initialized
entry_script: The name of the entry script that will be generated

Usage

kaxanuk.attribution_analysis init [OPTIONS] {excel}

Options

--entry_script <entry_script>#: The name of the entry script that will be generated. Default: __main__.py

Arguments

CONFIG_FORMAT#: Required argument

run#

Execute one or more attribution entry scripts.

ENTRY_SCRIPT_LOCATIONS is a variadic list of paths to Python entry scripts (or to directories containing a __main__.py) that will be executed in order. Each script runs as a separate subprocess using the current Python interpreter.

With no argument, run looks for __main__.py in the current working directory and executes that single script — equivalent to the executing half of autorun.

Typical usage:

# Single project, default entry script

python -m kaxanuk.attribution_analysis run

# Explicit path

python -m kaxanuk.attribution_analysis run ./projects/momentum

# Run several projects sequentially

python -m kaxanuk.attribution_analysis run ./momentum ./value ./meanrev.py

Parameters#

entry_script_locations: The locations of the entry scripts that will be executed

Usage

kaxanuk.attribution_analysis run [OPTIONS] [ENTRY_SCRIPT_LOCATIONS]...

Arguments

ENTRY_SCRIPT_LOCATIONS#: Optional argument(s)

update#

Regenerate template files in an existing project.

CONFIG_FORMAT selects which template to refresh:

- excel: regenerates Config/attribution_analysis_parameters.xlsx

- entry_script: regenerates the __main__.py entry script

Existing files are not deleted: if a target file already exists, it is renamed (.1.xlsx, .2.xlsx, …) before the new template is written, so any local edits remain available.

Use this command after upgrading the package version to pick up template changes shipped in the new release. For a brand-new project, use init instead.

Parameters#

config_format: The name of the configuration format to be reinitialized

Usage

kaxanuk.attribution_analysis update [OPTIONS] {excel|entry_script}

Arguments

CONFIG_FORMAT#: Required argument

Commands#

init#

Creates all files and folders required by the specified configuration format.

Arguments:

CONFIG_FORMAT (required, choices: excel): The configuration format to initialize.

Options:

--entry_script <name>.py: Name of the entry script to generate. Defaults to __main__.py.

run#

Runs the system. If no arguments are provided, it looks for __main__.py in the current directory; otherwise, each argument must be a path to an entry script (or a directory containing __main__.py).

Arguments:

ENTRY_SCRIPT_LOCATIONS (0 or more): Path(s) to entry script file(s) or directories.

autorun#

Installs required files and directories for the Excel entry script if missing; otherwise runs the system.

update#

Updates configuration files for the specified format.

Arguments:

CONFIG_FORMAT (required, choices: excel, entry_script): The configuration format to update.

Examples#

Initialize a new Excel configuration:

$ kaxanuk.attribution_analysis init excel
Created directory Config
Created directory Output
Created directory Input
Installed all files successfully

Run the system using the default entry script:

$ kaxanuk.attribution_analysis run

Update only the entry script to the latest template:

$ kaxanuk.attribution_analysis update entry_script
Updated entry script

Install or run the Excel entry script (if __main__.py is missing, it will install; otherwise run):

$ kaxanuk.attribution_analysis autorun