Metadata-Version: 2.5
Name: vnfinancialdata
Version: 0.1.1
Summary: Python interface for Vietnamese listed-company financial statement data.
Author: Ngo Phu Thanh
Requires-Python: >=3.10
Requires-Dist: huggingface-hub>=1.0
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=14
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: polars
Requires-Dist: polars>=1.0; extra == 'polars'
Description-Content-Type: text/markdown

# vnfinancialdata

**Python interface for accessing standardized financial statement data of Vietnamese listed companies.**

`vnfinancialdata` provides a simple programmatic interface for loading, filtering, and analyzing standardized financial statement data for Vietnamese listed companies.

The package is designed for **academic research, financial data analysis, financial modeling, education, data science, and reproducible analytical workflows**.

The underlying dataset is released as a versioned Parquet dataset on Hugging Face:

**Vietnamese Listed Companies Financial Data**  
Dataset version: `v1.0.0`  
Schema version: `1.0`

---

## Why vnfinancialdata?

Vietnamese company financial statements are commonly distributed as individual reports or spreadsheets with different layouts and naming conventions.

`vnfinancialdata` provides a standardized interface so that researchers and analysts can work with financial statement observations programmatically instead of manually processing individual files.

The underlying data has been transformed into a standardized **long-format** structure, making it easier to:

- filter data by company;
- filter data by reporting year;
- select individual financial statement items;
- compare companies;
- analyze financial indicators across years;
- load data efficiently with Python;
- build reproducible research workflows.

---

## Key Features

- Access financial statement data of Vietnamese listed companies through Python.
- Support for **HSX** and **HNX** listed companies.
- Standardized **Balance Sheet**, **Income Statement**, and **Cash Flow Statement** data.
- Long-format data structure suitable for pandas-based analysis.
- Versioned dataset and schema for reproducible research.
- Company-level and year-level filtering.
- Financial statement item-level access.
- Source metadata retained with the standardized observations.
- Data distributed in efficient **Parquet** format.

---

## Dataset

The package provides programmatic access to the following dataset:

**Vietnamese Listed Companies Financial Data**

The dataset contains standardized financial statement observations for Vietnamese listed companies.

Each observation represents a financial statement item for a company and reporting year.

### Dataset version

```text
Dataset version: v1.0.0
Schema version: 1.0
Format: Parquet
Data structure: Long format
```

The package version and dataset version are managed separately.

For example:

```text
Python package: 0.1.0
Dataset revision: v1.0.0
Schema version: 1.0
```

This separation allows the Python interface to evolve independently from the underlying data release.

---

## Data Provenance

The underlying financial information was collected from publicly available sources, including:

- official stock exchange portals;
- official company websites;
- publicly available financial statements;
- publicly available annual reports.

The original source documents were transformed into a standardized long-format dataset.

Source-related metadata such as `source_file` and `source_sheet` are retained where available to support traceability and reproducibility.

Users should consult the original financial statements or annual reports when verifying individual financial figures.

---

## Data Structure

The standardized dataset follows a long-format design.

The main fields include:

| Column | Description |
|---|---|
| `ticker` | Stock ticker symbol |
| `year` | Reporting year |
| `exchange` | Stock exchange |
| `statement` | Financial statement type |
| `item_code` | Standardized financial statement item code |
| `item_name` | Financial statement item name |
| `value` | Reported numerical value |
| `source_file` | Original source file identifier |
| `source_sheet` | Original worksheet identifier |

Conceptually, a financial observation is represented as:

```text
ticker
year
exchange
statement
item_code
item_name
value
```

This structure allows researchers to work with financial statement data using standard Python data-analysis tools.

---

# Installation

Install the package from PyPI:

```bash
pip install vnfinancialdata
```

Python version:

```text
Python >= 3.10
```

Optional development dependencies are available for development and Polars-based workflows.

---

# Authentication

The package accesses the versioned dataset hosted on Hugging Face.

If authentication is required by the dataset repository or access configuration, authenticate with Hugging Face before loading data:

```bash
hf auth login
```

Then verify access from Python:

```python
import vnfinancialdata as vnf

vnf.check_access()
```

---

# Quick Start

Load a financial statement by exchange and statement type:

```python
import vnfinancialdata as vnf

df = vnf.load(
    exchange="HSX",
    statement="balance_sheet"
)

print(df.head())
```

Available exchanges include:

```text
HSX
HNX
```

Available statement categories include:

```text
balance_sheet
income_statement
cash_flow
```

---

# Example 1 — Load Financial Statements for One Company

Researchers can retrieve the financial statement data of a specific listed company over a selected period.

For example, to retrieve the balance sheet of ticker `AAA` from 2020 to 2025:

```python
import vnfinancialdata as vnf

df = vnf.get(
    ticker="AAA",
    exchange="HSX",
    statement="balance_sheet",
    start=2020,
    end=2025
)

print(df.head())
```

The returned DataFrame can then be used for further analysis with pandas:

```python
import pandas as pd

df = pd.DataFrame(df)

print(df[[
    "ticker",
    "year",
    "item_code",
    "item_name",
    "value"
]])
```

This workflow is useful for constructing company-level financial histories and longitudinal analyses.

---

# Example 2 — Retrieve One Financial Indicator Across Multiple Companies

Because the dataset uses a standardized `item_code` and `item_name`, researchers can filter the same financial statement item across multiple companies.

For example:

```python
import vnfinancialdata as vnf

df = vnf.load(
    exchange="HSX",
    statement="income_statement"
)

companies = [
    "AAA", "A", "B", "C", "D",
    "E", "F", "G", "H", "I"
]

result = df[
    df["ticker"].isin(companies)
]

print(result.head())
```

A specific financial statement item can then be selected using its standardized item code:

```python
indicator = result[
    result["item_code"] == "YOUR_ITEM_CODE"
]

print(
    indicator[
        ["ticker", "year", "item_code", "item_name", "value"]
    ]
)
```

This structure makes it possible to construct cross-sectional datasets such as:

```text
Company A → Indicator X
Company B → Indicator X
Company C → Indicator X
...
Company J → Indicator X
```

for comparative financial analysis.

> Replace `YOUR_ITEM_CODE` with the standardized item code corresponding to the financial statement item of interest.

---

# Example 3 — Compare a Financial Statement Item Across Companies and Years

The long-format structure is particularly useful for panel-data analysis.

For example:

```python
import vnfinancialdata as vnf

df = vnf.load(
    exchange="HSX",
    statement="income_statement"
)

result = df[
    (df["ticker"].isin(["AAA", "BBB", "CCC"])) &
    (df["year"].between(2020, 2025)) &
    (df["item_code"] == "YOUR_ITEM_CODE")
]

result = result.sort_values(
    ["ticker", "year"]
)

print(
    result[
        ["ticker", "year", "item_name", "value"]
    ]
)
```

The resulting structure can be used directly for:

- panel-data analysis;
- company comparison;
- time-series analysis;
- financial modeling;
- visualization;
- econometric research.

---

# Financial Statements

The current dataset includes standardized information from three major financial statement categories:

### Balance Sheet

```text
balance_sheet
```

### Income Statement

```text
income_statement
```

### Cash Flow Statement

```text
cash_flow
```

The exact records available depend on the released dataset snapshot.

---

# Long-Format Design

Unlike the original spreadsheet-oriented financial reports, the standardized dataset stores observations in long format.

This design allows users to easily:

- filter by ticker;
- filter by year;
- select a financial statement;
- select a financial statement item;
- compare multiple companies;
- compare multiple reporting periods;
- create panel datasets;
- integrate financial data into statistical and machine-learning workflows.

For example:

```text
ticker | year | statement         | item_code | item_name | value
-------|------|--------------------|-----------|-----------|------
AAA    | 2023 | income_statement   | ...       | ...       | ...
AAA    | 2024 | income_statement   | ...       | ...       | ...
BBB    | 2023 | income_statement   | ...       | ...       | ...
BBB    | 2024 | income_statement   | ...       | ...       | ...
```

---

# Data Quality and Transformation

The released dataset was generated through a structured transformation process:

1. Source financial statement files are collected.
2. Financial statement structures are standardized.
3. Source data are converted into long format.
4. Company, year, exchange, and statement information are preserved.
5. Standardized item codes and item names are assigned.
6. Data are exported to Parquet.
7. Dataset schema and record counts are validated.
8. The resulting dataset is released as a versioned snapshot.

The current released dataset corresponds to:

```text
Dataset version: v1.0.0
Schema version: 1.0
```

---

# Reproducibility

For reproducible research, users should record both the package version and dataset version used in their analysis.

For example:

```text
Package:
vnfinancialdata 0.1.x

Dataset:
v1.0.0

Schema:
1.0
```

Recording the dataset revision is particularly important because future releases may contain additional companies, reporting years, corrections, additional statement types, metadata improvements, or schema changes.

---

# Intended Use

`vnfinancialdata` is intended for:

- academic research;
- financial data analysis;
- financial econometrics;
- financial modeling;
- data science;
- educational projects;
- quantitative finance experiments;
- reproducible research;
- development of analytical applications.

The package is especially useful when researchers need standardized financial statement data across multiple Vietnamese listed companies and reporting periods.

---

# Citation

If you use `vnfinancialdata` or the underlying dataset in academic research, publications, reports, or other analytical work, please cite the corresponding dataset version.

Suggested dataset citation:

```text
Vietnamese Listed Companies Financial Data.
Dataset version v1.0.0.
```

Please also acknowledge the original public sources from which the financial statements and annual reports were collected.

When reproducibility is important, we recommend reporting:

```text
Python package: vnfinancialdata
Package version: <version used>
Dataset version: v1.0.0
Schema version: 1.0
```

---

# Related Dataset

The underlying dataset is available on Hugging Face:

**Vietnamese Listed Companies Financial Data**

Dataset repository:

`thanhnp-uel/vietnam-listed-companies-financial-statements`

The dataset card contains additional information about data provenance, structure, transformation, licensing, versioning, and reproducibility.

---

# Versioning

The project uses separate version identifiers for the Python package and the underlying dataset.

### Python package

```text
vnfinancialdata
```

### Dataset

```text
v1.0.0
```

### Schema

```text
1.0
```

Future dataset releases may include:

- additional companies;
- additional reporting years;
- additional financial statements;
- corrections;
- metadata improvements;
- schema changes.

Changes between dataset releases will be documented in the corresponding release information.

---

# License

The underlying dataset is released as:

```text
Open Data / Public Domain
```

The dataset is derived from publicly available financial statements and annual reports.

Users should nevertheless verify the applicable terms associated with original source documents when using the data for commercial redistribution or other specific purposes.

---

# Disclaimer

This package and dataset are provided for **research, educational, analytical, and data-processing purposes**.

Although the data have been standardized and validated during the transformation process, no guarantee is made that every observation is completely free from errors or omissions.

Users should verify important financial information against original financial statements, annual reports, stock exchange publications, or company disclosures before making investment, financial, legal, or other consequential decisions.

**`vnfinancialdata` and its underlying dataset do not constitute investment advice.**

---

# Contact and Issues

For data-quality issues, reproducibility questions, or technical issues related to the package or dataset, please use the project's designated issue or contact channel.

---

## Project Information

```text
Package:       vnfinancialdata
Current data:  v1.0.0
Schema:        1.0
Python:        >=3.10
Exchanges:     HSX, HNX
Format:        Parquet
```

**Built for reproducible research and programmatic access to Vietnamese listed-company financial data.**