0
# Financial Statements
1

2
The Finance class provides access to comprehensive financial reporting data including balance sheets, income statements, cash flow statements, and financial ratios. It supports quarterly and annual reporting periods with multi-year historical data for Vietnamese listed companies.
3

4
## Capabilities
5

6
### Finance Class
7

8
Adapter for financial reports and ratios with support for both quarterly and annual reporting periods. Provides standardized financial data across Vietnamese data sources.
9

10
```python { .api }
11
class Finance:
12
    """
13
    Financial data adapter for corporate financial statements and ratios.
14
    
15
    Supported sources: VCI, TCBS
16
    """
17
    
18
    def __init__(self, source: str, symbol: str, period: str = "quarter", get_all: bool = True, show_log: bool = False):
19
        """
20
        Initialize Finance data adapter.
21
        
22
        Args:
23
            source (str): Data source ("vci", "tcbs")
24
            symbol (str): Company symbol
25
            period (str): Reporting period ("quarter", "year"), defaults to "quarter"
26
            get_all (bool): Get all available periods, defaults to True
27
            show_log (bool): Enable logging, defaults to False
28
        """
29
```
30

31
### Balance Sheet Data
32

33
Comprehensive balance sheet information including assets, liabilities, and shareholders' equity with detailed line items and multi-period comparisons.
34

35
```python { .api }
36
def balance_sheet(self, *args, **kwargs) -> pd.DataFrame:
37
    """
38
    Get balance sheet data with assets, liabilities, and equity information.
39
    
40
    Common parameters (vary by source):
41
        symbol (str): Company symbol
42
        period (str): Reporting period ("quarter", "year")
43
        lang (str): Language ("vi", "en"), defaults to "vi"
44
        dropna (bool): Drop rows with all NaN values, defaults to True
45
        show_log (bool): Enable detailed logging, defaults to False
46
        
47
    Returns:
48
        pd.DataFrame: Balance sheet data including:
49
            - total_assets: Total assets
50
            - current_assets: Current assets
51
            - cash_and_equivalents: Cash and cash equivalents
52
            - short_term_investments: Short-term investments
53
            - accounts_receivable: Accounts receivable
54
            - inventory: Inventory
55
            - prepaid_expenses: Prepaid expenses
56
            - other_current_assets: Other current assets
57
            - non_current_assets: Non-current assets
58
            - property_plant_equipment: Property, plant & equipment
59
            - intangible_assets: Intangible assets
60
            - long_term_investments: Long-term investments
61
            - other_non_current_assets: Other non-current assets
62
            - total_liabilities: Total liabilities
63
            - current_liabilities: Current liabilities
64
            - accounts_payable: Accounts payable
65
            - short_term_debt: Short-term debt
66
            - accrued_expenses: Accrued expenses
67
            - other_current_liabilities: Other current liabilities
68
            - non_current_liabilities: Non-current liabilities
69
            - long_term_debt: Long-term debt
70
            - other_non_current_liabilities: Other non-current liabilities
71
            - total_equity: Total shareholders' equity
72
            - share_capital: Share capital
73
            - retained_earnings: Retained earnings
74
            - other_equity: Other equity components
75
    """
76
```
77

78
#### Usage Examples
79

80
```python
81
from vnstock import Finance
82

83
# Initialize Finance adapter for quarterly data
84
finance = Finance(source="vci", symbol="TCB", period="quarter")
85

86
# Get quarterly balance sheet
87
quarterly_bs = finance.balance_sheet(
88
    symbol="TCB",
89
    period="quarter",
90
    lang="vi"
91
)
92

93
# Get annual balance sheet
94
annual_bs = finance.balance_sheet(
95
    symbol="VCB",
96
    period="year",
97
    lang="en"
98
)
99

100
# Get balance sheet without NaN cleanup
101
raw_bs = finance.balance_sheet(
102
    symbol="HPG",
103
    period="quarter",
104
    dropna=False
105
)
106
```
107

108
### Income Statement Data
109

110
Detailed income statement including revenues, expenses, and profitability metrics with operating and non-operating components.
111

112
```python { .api }
113
def income_statement(self, *args, **kwargs) -> pd.DataFrame:
114
    """
115
    Get income statement data with revenue, expenses, and profit information.
116
    
117
    Common parameters (vary by source):
118
        symbol (str): Company symbol
119
        period (str): Reporting period ("quarter", "year")
120
        lang (str): Language ("vi", "en"), defaults to "vi"
121
        dropna (bool): Drop rows with all NaN values, defaults to True
122
        
123
    Returns:
124
        pd.DataFrame: Income statement data including:
125
            - total_revenue: Total revenue/net sales
126
            - cost_of_goods_sold: Cost of goods sold
127
            - gross_profit: Gross profit
128
            - operating_expenses: Total operating expenses
129
            - selling_expenses: Selling and marketing expenses
130
            - administrative_expenses: General and administrative expenses
131
            - research_development: Research and development expenses
132
            - other_operating_expenses: Other operating expenses
133
            - operating_income: Operating income/EBIT
134
            - financial_income: Financial income
135
            - financial_expenses: Financial expenses
136
            - other_income: Other non-operating income
137
            - other_expenses: Other non-operating expenses
138
            - pre_tax_income: Income before tax
139
            - tax_expense: Income tax expense
140
            - net_income: Net income after tax
141
            - earnings_per_share: Earnings per share (EPS)
142
            - diluted_eps: Diluted earnings per share
143
    """
144
```
145

146
#### Usage Examples
147

148
```python
149
# Get quarterly income statement
150
quarterly_is = finance.income_statement(
151
    symbol="TCB",
152
    period="quarter",
153
    lang="vi"
154
)
155

156
# Get annual income statement
157
annual_is = finance.income_statement(
158
    symbol="VCB", 
159
    period="year"
160
)
161

162
# Multi-company income statement comparison
163
symbols = ["TCB", "VCB", "BID"]
164
income_data = {}
165

166
for symbol in symbols:
167
    company_finance = Finance(source="vci", symbol=symbol, period="year")
168
    income_data[symbol] = company_finance.income_statement(symbol=symbol, period="year")
169
```
170

171
### Cash Flow Statement
172

173
Cash flow statement data including operating, investing, and financing activities with detailed cash flow components.
174

175
```python { .api }
176
def cash_flow(self, *args, **kwargs) -> pd.DataFrame:
177
    """
178
    Get cash flow statement data with operating, investing, and financing activities.
179
    
180
    Common parameters (vary by source):
181
        symbol (str): Company symbol  
182
        period (str): Reporting period ("quarter", "year")
183
        lang (str): Language ("vi", "en"), defaults to "vi"
184
        dropna (bool): Drop rows with all NaN values, defaults to True
185
        
186
    Returns:
187
        pd.DataFrame: Cash flow statement data including:
188
            - operating_cash_flow: Net cash from operating activities
189
            - net_income_adjusted: Net income adjusted for non-cash items
190
            - depreciation_amortization: Depreciation and amortization
191
            - working_capital_changes: Changes in working capital
192
            - accounts_receivable_changes: Changes in accounts receivable
193
            - inventory_changes: Changes in inventory
194
            - accounts_payable_changes: Changes in accounts payable
195
            - other_operating_changes: Other operating cash flow changes
196
            - investing_cash_flow: Net cash from investing activities
197
            - capital_expenditures: Capital expenditures
198
            - acquisitions: Acquisitions and investments
199
            - asset_sales: Proceeds from asset sales
200
            - other_investing_activities: Other investing activities
201
            - financing_cash_flow: Net cash from financing activities
202
            - debt_issuance: Debt issuance proceeds
203
            - debt_repayment: Debt repayments
204
            - equity_issuance: Equity issuance proceeds
205
            - dividend_payments: Dividend payments
206
            - share_repurchases: Share repurchases
207
            - other_financing_activities: Other financing activities
208
            - net_cash_flow: Net change in cash
209
            - beginning_cash: Beginning cash balance
210
            - ending_cash: Ending cash balance
211
    """
212
```
213

214
#### Usage Examples
215

216
```python
217
# Get quarterly cash flow statement
218
quarterly_cf = finance.cash_flow(
219
    symbol="TCB",
220
    period="quarter"
221
)
222

223
# Get annual cash flow with English labels
224
annual_cf = finance.cash_flow(
225
    symbol="VCB",
226
    period="year", 
227
    lang="en"
228
)
229

230
# Analyze cash flow trends
231
hpg_cf = finance.cash_flow(symbol="HPG", period="quarter")
232
```
233

234
### Financial Ratios
235

236
Comprehensive financial ratios including profitability, liquidity, efficiency, and leverage ratios with multi-period analysis.
237

238
```python { .api }
239
def ratio(self, *args, **kwargs) -> pd.DataFrame:
240
    """
241
    Get financial ratios and performance metrics.
242
    
243
    Common parameters (vary by source):
244
        symbol (str): Company symbol
245
        period (str): Reporting period ("quarter", "year")
246
        flatten_columns (bool): Flatten multi-level column headers
247
        separator (str): Column name separator for flattened columns
248
        drop_levels (list): Column levels to drop in multi-index
249
        
250
    Returns:
251
        pd.DataFrame: Financial ratios including:
252
            # Profitability Ratios
253
            - gross_profit_margin: Gross profit margin (%)
254
            - operating_profit_margin: Operating profit margin (%)
255
            - net_profit_margin: Net profit margin (%)
256
            - return_on_assets: Return on assets (ROA) (%)
257
            - return_on_equity: Return on equity (ROE) (%)
258
            - return_on_invested_capital: Return on invested capital (ROIC) (%)
259
            
260
            # Liquidity Ratios
261
            - current_ratio: Current ratio
262
            - quick_ratio: Quick ratio (acid test)
263
            - cash_ratio: Cash ratio
264
            - working_capital: Working capital
265
            
266
            # Efficiency Ratios
267
            - asset_turnover: Asset turnover ratio
268
            - inventory_turnover: Inventory turnover ratio
269
            - receivables_turnover: Accounts receivable turnover
270
            - days_sales_outstanding: Days sales outstanding (DSO)
271
            - days_inventory_outstanding: Days inventory outstanding (DIO)
272
            - days_payable_outstanding: Days payable outstanding (DPO)
273
            - cash_conversion_cycle: Cash conversion cycle
274
            
275
            # Leverage Ratios
276
            - debt_to_equity: Debt-to-equity ratio
277
            - debt_to_assets: Debt-to-assets ratio
278
            - interest_coverage: Interest coverage ratio
279
            - debt_service_coverage: Debt service coverage ratio
280
            
281
            # Market Ratios
282
            - price_to_earnings: Price-to-earnings (P/E) ratio
283
            - price_to_book: Price-to-book (P/B) ratio
284
            - price_to_sales: Price-to-sales (P/S) ratio
285
            - enterprise_value_ebitda: EV/EBITDA ratio
286
            - dividend_yield: Dividend yield (%)
287
            - dividend_payout_ratio: Dividend payout ratio (%)
288
    """
289
```
290

291
#### Usage Examples
292

293
```python
294
# Get comprehensive financial ratios
295
ratios = finance.ratio(
296
    symbol="TCB",
297
    period="quarter"
298
)
299

300
# Get ratios with flattened column names
301
flat_ratios = finance.ratio(
302
    symbol="VCB",
303
    period="year",
304
    flatten_columns=True,
305
    separator="_"
306
)
307

308
# Get ratios with specific column levels
309
custom_ratios = finance.ratio(
310
    symbol="HPG",
311
    period="quarter",
312
    drop_levels=[0]  # Drop first level of multi-index
313
)
314
```
315

316
## Data Source Specifics
317

318
### VCI (Vietnam Capital Securities)
319

320
- **Coverage**: All Vietnamese listed companies (HOSE, HNX, UPCOM)
321
- **Historical Data**: Up to 10+ years of financial statements
322
- **Reporting Periods**: Quarterly and annual reports
323
- **Languages**: Vietnamese and English labels
324
- **Data Quality**: Audited financial statements with regulatory compliance
325

326
#### VCI-Specific Features
327

328
- Comprehensive ratio calculations with industry benchmarks
329
- Multi-period trend analysis capabilities
330
- Detailed footnote and adjustment information
331
- Real-time financial reporting updates
332

333
### TCBS (Techcombank Securities)
334

335
- **Coverage**: Vietnamese listed companies with enhanced analytics
336
- **Historical Data**: Extensive historical financial database
337
- **Reporting Periods**: Quarterly and annual with interim updates
338
- **Languages**: Vietnamese and English support
339
- **Specialization**: Advanced financial modeling and forecasting
340

341
#### TCBS-Specific Features
342

343
- Enhanced ratio calculations with peer comparisons
344
- Advanced financial modeling capabilities
345
- Comprehensive industry analysis tools
346
- Real-time earnings estimates and revisions
347

348
## Advanced Usage Patterns
349

350
### Multi-Period Financial Analysis
351

352
```python
353
from vnstock import Finance
354
import pandas as pd
355

356
# Initialize finance adapter
357
finance = Finance(source="vci", symbol="TCB", period="quarter")
358

359
# Get multi-year quarterly data
360
symbol = "TCB"
361
quarterly_bs = finance.balance_sheet(symbol=symbol, period="quarter")
362
quarterly_is = finance.income_statement(symbol=symbol, period="quarter")
363
quarterly_cf = finance.cash_flow(symbol=symbol, period="quarter")
364
quarterly_ratios = finance.ratio(symbol=symbol, period="quarter")
365

366
# Combine for comprehensive analysis
367
financial_data = {
368
    'balance_sheet': quarterly_bs,
369
    'income_statement': quarterly_is, 
370
    'cash_flow': quarterly_cf,
371
    'ratios': quarterly_ratios
372
}
373

374
# Analyze trends
375
print("Revenue Growth (QoQ):")
376
revenue_growth = quarterly_is['total_revenue'].pct_change()
377
print(revenue_growth)
378

379
print("ROE Trend:")
380
roe_trend = quarterly_ratios['return_on_equity']
381
print(roe_trend)
382
```
383

384
### Comparative Financial Analysis
385

386
```python
387
# Compare financial performance across companies
388
symbols = ["TCB", "VCB", "BID"]
389
comparison_metrics = {}
390

391
for symbol in symbols:
392
    company_finance = Finance(source="vci", symbol=symbol, period="year")
393
    
394
    # Get latest annual data
395
    ratios = company_finance.ratio(symbol=symbol, period="year")
396
    income = company_finance.income_statement(symbol=symbol, period="year")
397
    
398
    # Extract key metrics (latest period)
399
    latest_ratios = ratios.iloc[:, -1]  # Last column (most recent)
400
    latest_income = income.iloc[:, -1]
401
    
402
    comparison_metrics[symbol] = {
403
        'roe': latest_ratios.get('return_on_equity', 0),
404
        'roa': latest_ratios.get('return_on_assets', 0),
405
        'net_margin': latest_ratios.get('net_profit_margin', 0),
406
        'revenue': latest_income.get('total_revenue', 0),
407
        'net_income': latest_income.get('net_income', 0)
408
    }
409

410
# Create comparison DataFrame
411
comparison_df = pd.DataFrame(comparison_metrics).T
412
print("Financial Comparison:")
413
print(comparison_df)
414
```
415

416
### Financial Health Assessment
417

418
```python
419
def assess_financial_health(symbol, source="vci"):
420
    """Assess company financial health using key ratios."""
421
    
422
    finance = Finance(source=source, symbol=symbol, period="quarter")
423
    
424
    # Get latest financial data
425
    ratios = finance.ratio(symbol=symbol, period="quarter")
426
    balance_sheet = finance.balance_sheet(symbol=symbol, period="quarter")
427
    
428
    # Extract latest period data
429
    latest_ratios = ratios.iloc[:, -1]
430
    latest_bs = balance_sheet.iloc[:, -1]
431
    
432
    # Calculate health score components
433
    health_indicators = {
434
        'liquidity': {
435
            'current_ratio': latest_ratios.get('current_ratio', 0),
436
            'quick_ratio': latest_ratios.get('quick_ratio', 0),
437
            'cash_ratio': latest_ratios.get('cash_ratio', 0)
438
        },
439
        'profitability': {
440
            'roe': latest_ratios.get('return_on_equity', 0),
441
            'roa': latest_ratios.get('return_on_assets', 0),
442
            'net_margin': latest_ratios.get('net_profit_margin', 0)
443
        },
444
        'leverage': {
445
            'debt_to_equity': latest_ratios.get('debt_to_equity', 0),
446
            'debt_to_assets': latest_ratios.get('debt_to_assets', 0),
447
            'interest_coverage': latest_ratios.get('interest_coverage', 0)
448
        }
449
    }
450
    
451
    return health_indicators
452

453
# Assess multiple companies
454
symbols = ["TCB", "VCB", "HPG"]
455
health_assessments = {}
456

457
for symbol in symbols:
458
    health_assessments[symbol] = assess_financial_health(symbol)
459
    
460
print("Financial Health Assessment:")
461
for symbol, health in health_assessments.items():
462
    print(f"\n{symbol}:")
463
    for category, metrics in health.items():
464
        print(f"  {category.title()}:")
465
        for metric, value in metrics.items():
466
            print(f"    {metric}: {value:.2f}")
467
```