Coverage for src/jquantstats/__init__.py: 100%

1"""jQuantStats: Portfolio analytics for quants. 

2 

3Two entry points 

4---------------- 

5**Entry point 1 — prices + positions (recommended for active portfolios):** 

6 

7Use `Portfolio` when you have price series and 

8position sizes. Portfolio compiles the NAV curve from raw inputs and exposes 

9the full analytics suite via ``.stats``, ``.plots``, and ``.report``. 

10 

11 >>> import polars as pl 

12 >>> from jquantstats import Portfolio 

13 >>> prices = pl.DataFrame( 

14 ... {"date": ["2023-01-01", "2023-01-02", "2023-01-03"], "A": [100.0, 101.0, 99.0]} 

15 ... ).with_columns(pl.col("date").str.to_date()) 

16 >>> positions = pl.DataFrame( 

17 ... {"date": ["2023-01-01", "2023-01-02", "2023-01-03"], "A": [1000.0, 1000.0, 1000.0]} 

18 ... ).with_columns(pl.col("date").str.to_date()) 

19 >>> pf = Portfolio.from_cash_position(prices=prices, cash_position=positions, aum=1_000_000) 

20 >>> pf.assets 

21 ['A'] 

22 >>> sorted(pf.stats.sharpe()) 

23 ['returns'] 

24 >>> type(pf.plots.snapshot()).__name__ 

25 'Figure' 

26 

27**Entry point 2 — returns series (for arbitrary return streams):** 

28 

29Use `Data` when you already have a returns series 

30(e.g. downloaded from a data vendor) and want benchmark comparison or 

31factor analytics. 

32 

33 >>> from jquantstats import Data 

34 >>> returns = pl.DataFrame( 

35 ... {"date": ["2023-01-01", "2023-01-02", "2023-01-03"], "Asset1": [0.01, -0.02, 0.03]} 

36 ... ).with_columns(pl.col("date").str.to_date()) 

37 >>> benchmark = pl.DataFrame( 

38 ... {"date": ["2023-01-01", "2023-01-02", "2023-01-03"], "Market": [0.005, -0.01, 0.02]} 

39 ... ).with_columns(pl.col("date").str.to_date()) 

40 >>> data = Data.from_returns(returns=returns, benchmark=benchmark) 

41 >>> data.benchmark.columns 

42 ['Market'] 

43 >>> type(data.plots.snapshot(title="Performance")).__name__ 

44 'Figure' 

45 

46The two APIs are layered: ``portfolio.data`` returns a `Data` 

47object so you can always drop into the returns-series API from a Portfolio. 

48 

49 >>> type(pf.data).__name__ 

50 'Data' 

51 

52**Choosing a rendering backend:** 

53 

54Charts render with Plotly by default. Install ``jquantstats[mpl]`` and select 

55matplotlib for static figures instead — appreciably cheaper when a script builds 

56many charts at once. See `set_plot_backend`, `plot_backend` and 

57`get_plot_backend`. 

58 

59 >>> from jquantstats import get_plot_backend 

60 >>> get_plot_backend() 

61 'plotly' 

62 

63For more information, visit the `jQuantStats Documentation <https://jebel-quant.github.io/jquantstats/book>`_. 

64""" 

65 

66import importlib.metadata 

67 

68from ._cost_model import CostModel as CostModel 

69from ._plots._backend import get_plot_backend as get_plot_backend 

70from ._plots._backend import plot_backend as plot_backend 

71from ._plots._backend import set_plot_backend as set_plot_backend 

72from ._types import NativeFrame as NativeFrame 

73from ._types import NativeFrameOrScalar as NativeFrameOrScalar 

74from .data import Data as Data 

75from .data import interpolate as interpolate 

76from .portfolio import Portfolio as Portfolio 

77from .result import Result as Result 

78 

79__version__ = importlib.metadata.version("jquantstats") 

80 

81__all__ = [ 

82 "CostModel", 

83 "Data", 

84 "NativeFrame", 

85 "NativeFrameOrScalar", 

86 "Portfolio", 

87 "Result", 

88 "get_plot_backend", 

89 "interpolate", 

90 "plot_backend", 

91 "set_plot_backend", 

92]