Skip to content

Clarify README positioning #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
novis10813 merged 1 commit into from
Jun 10, 2026
Merged

Clarify README positioning #40

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 21 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,29 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/pypi/v/factorium.svg)](https://pypi.org/project/factorium/)

Factorium is a **Polars-first factor research & backtesting toolkit**.
Factorium is a **Polars-first factor research and backtesting toolkit** for quantitative finance.

- Data pipeline: `BinanceDataLoader` + `AggBar` → multi-symbol OHLCV panel in one line.
- Factor engine: `Factor` with rich TS/CS/math ops and expression parsing.
- Analysis: `FactorAnalyzer` + `FactorAnalysisResult` for IC, quantile returns, and plots.
- Backtest: `VectorizedBacktester` (exposed as `factorium.backtest.Backtester`) with Polars-vectorized PnL.
- Research workflow: `ResearchSession` + `FactorReport` to tie everything into a notebook-friendly API.
It is designed for researchers who want a notebook-friendly workflow for loading market data, building cross-sectional or time-series factors, evaluating factor quality, and running fast vectorized backtests.

For a Chinese introduction, see `README_zh.md`.
For a Chinese introduction, see [`README_zh.md`](README_zh.md).

---
## What It Provides

- Data pipeline: `BinanceDataLoader` + `AggBar` for multi-symbol OHLCV panels.
- Factor engine: `Factor` with time-series, cross-sectional, math, and expression operations.
- Analysis: `FactorAnalyzer` and `FactorAnalysisResult` for IC, quantile returns, and plots.
- Backtesting: `VectorizedBacktester`, exposed as `factorium.backtest.Backtester`, with Polars-vectorized PnL.
- Research workflow: `ResearchSession` and `FactorReport` for end-to-end notebook experiments.

## Installation

```bash
# Recommended
uv add factorium

@gemini-code-assist gemini-code-assist Bot Jun 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using uv add factorium is intended for adding a dependency to an existing uv project (which requires a pyproject.toml file). For general users who simply want to install the package in a virtual environment or a Jupyter notebook, uv pip install factorium is the standard command and prevents "No pyproject.toml found" errors.

Suggested change
uv add factorium
uv pip install factorium

```

# Or with pip
Or with pip:

```bash
pip install factorium
```

Expand All @@ -34,9 +38,7 @@ cd factorium
uv sync --dev
```

---

## Quick example
## Quick Example

```python
from factorium import ResearchSession
Expand All @@ -49,6 +51,8 @@ momentum = (close.ts_delta(20) / close.ts_shift(20)).cs_rank()
print(session.quick_report(momentum, periods=1))
```

## Documentation

More complete guides live under `docs/`:

- `docs/getting-started/quickstart.md`
Expand All @@ -57,9 +61,10 @@ More complete guides live under `docs/`:
- `docs/user-guide/analyzer.md`
- `docs/user-guide/backtest.md`

---
## Status

## License
Factorium is in active alpha development. APIs may still change, but the project already has packaged installation, tests, docs, and examples.

MIT – see `LICENSE`.
## License

MIT. See `LICENSE`.
Loading