0
# Reports
1

2
Comprehensive portfolio reporting and analysis tools for generating detailed portfolio performance reports in Jupyter notebooks and Excel formats. The Reports module provides automated report generation with portfolio statistics, risk analysis, and visualizations.
3

4
## Capabilities
5

6
### Jupyter Report Generation
7

8
Generate comprehensive portfolio analysis reports in Jupyter notebook format with interactive visualizations and detailed statistics.
9

10
```python { .api }
11
def jupyter_report(returns, w, rm='MV', rf=0, alpha=0.05, others=0.05, nrow=25, 
12
                  height=6, width=14, ax=None):
13
    """
14
    Generate comprehensive portfolio report in Jupyter notebook format.
15
    
16
    Parameters:
17
    - returns (DataFrame): Assets returns data
18
    - w (DataFrame): Portfolio weights
19
    - rm (str): Risk measure for analysis ('MV', 'MAD', 'CVaR', etc.)
20
    - rf (float): Risk-free rate
21
    - alpha (float): Significance level for risk measures
22
    - others (float): Threshold for grouping small positions
23
    - nrow (int): Maximum number of rows to display
24
    - height (float): Figure height in inches
25
    - width (float): Figure width in inches  
26
    - ax (matplotlib.Axes): Matplotlib axes object
27
    
28
    Returns:
29
    None: Displays report directly in Jupyter notebook
30
    """
31
```
32

33
### Excel Report Generation
34

35
Generate detailed portfolio analysis reports in Excel format with multiple worksheets containing portfolio statistics, risk analysis, and performance metrics.
36

37
```python { .api }
38
def excel_report(returns, w, rf=0, alpha=0.05, others=0.05, nrow=25, 
39
                name='report', folder='Reports/', sheet_name='Main_Report'):
40
    """
41
    Generate comprehensive portfolio report in Excel format.
42
    
43
    Parameters:
44
    - returns (DataFrame): Assets returns data
45
    - w (DataFrame): Portfolio weights
46
    - rf (float): Risk-free rate
47
    - alpha (float): Significance level for risk measures
48
    - others (float): Threshold for grouping small positions as "Others"
49
    - nrow (int): Maximum number of assets to display individually
50
    - name (str): Base filename for the Excel report
51
    - folder (str): Directory path to save the report
52
    - sheet_name (str): Name of the main worksheet
53
    
54
    Returns:
55
    str: Path to the generated Excel file
56
    """
57
```
58

59
## Report Contents
60

61
Both Jupyter and Excel reports include:
62

63
### Portfolio Statistics
64
- **Asset Allocation**: Individual asset weights and grouped allocations
65
- **Portfolio Performance**: Returns, volatility, Sharpe ratio, and other performance metrics
66
- **Risk Analysis**: Various risk measures including VaR, CVaR, Maximum Drawdown
67
- **Composition Analysis**: Sector/asset class breakdowns and concentration metrics
68

69
### Risk Metrics
70
- **Dispersion Measures**: Standard deviation, MAD, Gini Mean Difference
71
- **Downside Risk**: Semi-deviation, VaR, CVaR, Tail Gini
72
- **Drawdown Analysis**: Maximum Drawdown, Average Drawdown, CDaR
73
- **Risk Contributions**: Per-asset risk contribution analysis
74

75
### Visualizations
76
- **Portfolio Composition**: Pie charts and bar charts of asset allocation
77
- **Performance Analysis**: Time series of portfolio returns and drawdowns
78
- **Risk Analysis**: Risk contribution breakdowns and efficient frontier plots
79
- **Comparative Analysis**: Benchmark comparisons and attribution analysis
80

81
## Usage Examples
82

83
### Basic Jupyter Report
84

85
```python
86
import riskfolio as rp
87
import pandas as pd
88

89
# Load data and optimize portfolio
90
returns = pd.read_csv('returns.csv', index_col=0, parse_dates=True)
91
port = rp.Portfolio(returns=returns)
92
port.assets_stats(method_mu='hist', method_cov='hist')
93
w = port.optimization(model='Classic', rm='MV', obj='Sharpe', rf=0.02)
94

95
# Generate Jupyter report
96
rp.jupyter_report(returns=returns, w=w, rm='MV', rf=0.02, alpha=0.05)
97
```
98

99
### Excel Report with Custom Settings
100

101
```python
102
# Generate Excel report with custom settings
103
report_path = rp.excel_report(
104
    returns=returns,
105
    w=w,
106
    rf=0.02,
107
    alpha=0.05,
108
    others=0.03,  # Group assets < 3% as "Others"
109
    nrow=30,      # Show top 30 assets individually
110
    name='portfolio_analysis_2024',
111
    folder='./reports/',
112
    sheet_name='Portfolio_Analysis'
113
)
114

115
print(f"Report saved to: {report_path}")
116
```
117

118
### Advanced Report with Risk Analysis
119

120
```python
121
# Generate report with CVaR risk analysis
122
rp.jupyter_report(
123
    returns=returns,
124
    w=w,
125
    rm='CVaR',        # Use CVaR for risk analysis
126
    rf=0.02,
127
    alpha=0.01,       # 99% confidence level
128
    others=0.02,
129
    height=8,
130
    width=16
131
)
132
```
133

134
## Report Customization
135

136
### Asset Grouping
137
- **others**: Threshold for grouping small positions (default: 0.05 = 5%)
138
- **nrow**: Maximum number of individual assets to display
139

140
### Risk Analysis Options
141
- **rm**: Primary risk measure for analysis
142
- **alpha**: Significance level for tail risk measures
143
- **rf**: Risk-free rate for performance metrics
144

145
### Output Formatting
146
- **height/width**: Figure dimensions for Jupyter reports
147
- **folder/name**: File location and naming for Excel reports
148
- **sheet_name**: Worksheet naming for Excel reports
149

150
## Integration with Portfolio Analysis
151

152
The Reports module seamlessly integrates with Riskfolio-Lib's portfolio optimization and analysis workflows:
153

154
1. **Post-Optimization Analysis**: Generate reports after portfolio optimization
155
2. **Performance Monitoring**: Regular reporting of portfolio performance
156
3. **Risk Management**: Detailed risk analysis and decomposition
157
4. **Client Reporting**: Professional-quality reports for stakeholder communication