Metadata-Version: 2.4
Name: ppar
Version: 0.4.1
Summary: Portfolio performance attribution, contribution, and ex-post risk analytics.
Author-email: John Reynolds <jjjkreynolds@gmail.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Documentation, https://github.com/JohnDReynolds/ppar/blob/main/docs/python_api.md
Project-URL: Repository, https://github.com/JohnDReynolds/ppar
Keywords: portfolio,performance,analytics,attribution,risk,benchmark,Axys,APX
Requires-Python: <3.15,>=3.11.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.8.2
Requires-Dist: numpy>=1.26.4
Requires-Dist: pandas>=2.2
Requires-Dist: perfattr<0.13,>=0.12
Requires-Dist: pillow>=10.0
Requires-Dist: polars>=1.24.0
Requires-Dist: seaborn>=0.13.2
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pylint>=4.0; extra == "dev"
Requires-Dist: pyright>=1.1.409; extra == "dev"
Requires-Dist: setuptools>=77.0.0; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Requires-Dist: types-seaborn; extra == "dev"
Dynamic: license-file

# ppar

Portfolio performance attribution, contribution, and ex-post risk analytics.

ppar compares a portfolio with a benchmark, explains active return by classification,
and produces reviewable HTML tables and PNG charts. It runs locally and accepts
vendor-neutral CSV files or Axys/APX exports.

## Start here

ppar supports Python 3.11.9 through Python 3.14.

ppar is available under a 90-day, single-user internal evaluation license.
Production, commercial, multi-user, or continued use requires a separate agreement;
contact `jjjkreynolds@gmail.com`. Review the
[license](https://github.com/JohnDReynolds/ppar/blob/main/LICENSE) before installing.

```bash
python -m pip install ppar
```

Then choose one demonstration.

Vendor-neutral (the default):

```bash
ppar setup ./my_ppar
python ./my_ppar/ppar_demo.py
```

Axys/APX:

```bash
ppar setup ./my_ppar --axys-apx
python ./my_ppar/ppar_demo.py
```

Either setup command creates a demonstration directory:

```text
my_ppar/
  README.md
  ppar_demo.py
  input/
  output/
```

The extensively commented `ppar_demo.py` is both a tutorial and the executable
workflow. Edit its Python values to choose input paths, calculation assumptions, and
reports, then replace the demonstration files under `input/` with your data.

## What it produces

The standard demonstration writes security and classification attribution tables,
attribution and contribution charts, cumulative return charts, heatmaps, and an
ex-post risk-statistics table.

The gallery below shows examples of available output, including reports that can be
selected by editing `ppar_demo.py`.

Over the demonstrated period, the Mega-Cap Alpha portfolio returned 83.4% versus
76.8% for the benchmark, outperforming by approximately 656 basis points. Security
selection generated about 644 basis points of that result, while sector allocation
added about 12 basis points. Information Technology was the largest positive source,
contributing approximately 337 basis points. The portfolio was slightly more volatile,
but its annualized Sharpe ratio of 0.70 and Sortino ratio of 1.55 were both better than
the benchmark's 0.66 and 1.46.

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/OverallAttributionByEconomicSector.png" alt="Overall attribution by economic sector chart" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/OverallContributionByEconomicSector.png" alt="Overall contribution by economic sector chart" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/SubPeriodAttributionEffectsByEconomicSector.png" alt="Sub-period attribution effects chart" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/SubPeriodReturns.png" alt="Sub-period portfolio and benchmark returns" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/ActiveContributionsByEconomicSector.png" alt="Active contributions heatmap" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/TotalAttributionEffectsByEconomicSector.png" alt="Total attribution effects heatmap" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/CumulativeAttributionEffectsByEconomicSector.png" alt="Cumulative attribution effects" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/CumulativeReturns.png" alt="Cumulative portfolio and benchmark returns" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/CumulativeAttributionByEconomicSector.jpg" alt="Cumulative attribution table" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/OverallAttributionByEconomicSector.jpg" alt="Overall attribution table by economic sector" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/OverallAttributionBySecurity.jpg" alt="Overall attribution table by security" width="100%" />

<img src="https://raw.githubusercontent.com/JohnDReynolds/ppar/main/docs/images/RiskStatistics.jpg" alt="Ex-post risk statistics table" width="50%" />

## Python

This prints the overall security attribution view as a Polars DataFrame:

```python
from pathlib import Path

from ppar import Analytics
from ppar.attribution import View

# Use the performance files created by: ppar setup ./my_ppar
performance_input_directory = Path("./my_ppar") / "input" / "performance"

# The portfolio is the first file and the benchmark is the second.
analytics = Analytics(
    performance_input_directory / "Mega-Cap Alpha Portfolio.csv",
    performance_input_directory / "Mega-Cap Benchmark.csv",
)

# Calculate security-level attribution and request its overall table.
overall_attribution = analytics.attribution().to_polars(View.OVERALL_ATTRIBUTION)
print(overall_attribution)
```

The generated `ppar_demo.py` is the complete reporting example. Results are available
as Polars DataFrames, HTML text, PNG bytes, or CSV files.

## Documentation

- [Methodology](https://github.com/JohnDReynolds/ppar/blob/main/docs/methodology.md)
- [Reports and results](https://github.com/JohnDReynolds/ppar/blob/main/docs/reports.md)
- [Python API](https://github.com/JohnDReynolds/ppar/blob/main/docs/python_api.md)
- [Contributor maintenance](https://github.com/JohnDReynolds/ppar/blob/main/docs/maintenance.md)

Downloading, installing, accessing, copying, or using ppar constitutes acceptance of
the [license](https://github.com/JohnDReynolds/ppar/blob/main/LICENSE).
