DOCSEARCHbyAlgolia
Submit Docs

vnquant

repository·master·Indexed 19 days ago

https://github.com/phamdinhkhanh/vnquant

A financial information and visualization library for the Vietnam stock market. It provides tools for quantitative analysis, including historical price data via DataLoader, financial reports via FinanceLoader, and technical indicator visualizations such as Bollinger Bands, RSI, and MACD using the vnquant_candle_stick function.

Tokens
3.1K
Snippets
13
Records
14
Agent score
17%

What's inside vnquant

  1. Use FinanceLoader to download financial reports

    master

    The vnquant.data.FinanceLoader class allows you to download financial, cashflow, business, and basic index reports for a specific stock symbol.

    Note: Currently, the loader only supports cloning one symbol at a time.

    Constructor Arguments

    • symbol (str): The stock symbol (typically 3 uppercase letters, e.g., 'VND').
    • start (str): Start date in yyyy-mm-dd format.
    • end (str): End date in yyyy-mm-dd format.
    • data_source (str, optional): The data source to use (e.g., 'VND').
    • minimal (bool, optional): A flag to specify if minimal data is required.
    import vnquant.data as dt
loader = dt.FinanceLoader(symbol='VND', 
                          start='2019-06-02',
                          end='2021-12-31')

  2. Configure table_style for DataLoader output

    master

    The table_style parameter in DataLoader controls how the resulting DataFrame is structured, which is useful depending on whether you are analyzing a single stock or comparing multiple stocks.

    • levels: Best for multi-index analysis. It creates a hierarchical column structure where the top level is the attribute (e.g., high) and the second level is the symbol.
    • prefix: Best for flat-file processing or simple machine learning inputs. It flattens the hierarchy by renaming columns to {symbol}_{attribute} (e.g., VND_high, FPT_high).
    • stack: Best for long-format data analysis. It keeps columns simple and adds a dedicated code column containing the stock symbol for every row, allowing you to use groupby('code') easily.
    import vnquant.data as dt

# Example: Prefix style for multiple stocks
loader = dt.DataLoader(['VND', 'FPT'], '2018-02-02','2018-04-02', table_style='prefix')
data = loader.download()

# Example: Stack style for multiple stocks
loader = dt.DataLoader(['VND', 'FPT'], '2018-02-02','2018-04-02', table_style='stack')
data = loader.download()

  3. Visualize stock prices from a pandas DataFrame

    master

    To visualize your own data, provide a pandas DataFrame that meets the OHLC or OHLCV requirements.

    Data Requirements:

    • OHLC type: Must include columns ['open', 'high', 'low', 'close'].
    • OHLCV type: Must include ['open', 'high', 'low', 'close', 'volume'] or ['open', 'high', 'low', 'close', 'volume_match'].
    • The DataFrame index must be a DateTime type.
    • If your columns have different names, rename them to match the required schema before passing them to the function.
    from vnquant import plot as plt

plt.vnquant_candle_stick(
    data = data,  # Your pandas DataFrame
    title='Your data',
    ylab='Date', xlab='Price',
    show_advanced=['volume', 'macd', 'rsi']
)

  5. Install vnquant on a local machine

    master

    Since the project is currently in development, it is distributed via GitHub. To install it locally, clone the repository and run the setup script using Python. You must have git installed on your system.

    git clone https://github.com/phamdinhkhanh/vnquant
cd vnquant
python setup.py install

  6. Get full stock information with minimal=False

    master

    By default, DataLoader returns a minimal set of columns. To access extended data such as change_perc1, change_perc2, volume_match, volume_reconcile, and value_match, set minimal=False.

    import vnquant.data as dt

loader = dt.DataLoader(
    symbols=["VND"], 
    start="2018-01-10", 
    end="2018-02-15", 
    minimal=False
)
data = loader.download()
    import vnquant.data as dt

loader = dt.DataLoader(symbols=["VND"], start="2018-01-10", end="2018-02-15", minimal=False)
data = loader.download()
data.head()

  7. Visualize stock prices from VND or CAFE sources

    master

    You can generate charts by passing a symbol string and specifying the data source. This method automatically handles data cloning.

    from vnquant import plot as plt
plt.vnquant_candle_stick(
    data='VND',  # Use the symbol name here
    title='VND symbol from 2019-09-01 to 2019-11-01',
    xlab='Date', ylab='Price',
    start_date='2019-09-01',
    end_date='2019-11-01',
    data_source='CAFE',
    show_advanced=['volume', 'macd', 'rsi'],
    width=1600,
    height=800
)

    To suppress the volume display, pass show_vol=False in the keyword arguments.

    from vnquant import plot as plt
plt.vnquant_candle_stick(
    data='VND',
    title='VND symbol from 2019-09-01 to 2019-11-01',
    xlab='Date', ylab='Price',
    start_date='2019-09-01',
    end_date='2019-11-01',
    data_source='CAFE',
    show_advanced=['volume', 'macd', 'rsi'],
    width=1600,
    height=800
)

  8. Get business report using get_business_report()

    master

    Use the get_business_report() method on a FinanceLoader instance to retrieve business-related data (e.g., gains from financial assets, dividends).

    import vnquant.data as dt
loader = dt.FinanceLoader('VND', '2019-06-02','2021-12-31', data_source='VND', minimal=True)
data_bus = loader.get_business_report()
print(data_bus.head())

  9. Get finance report using get_finan_report()

    master

    Use the get_finan_report() method on a FinanceLoader instance to retrieve financial indexes (e.g., current assets, cash and cash equivalents).

    import vnquant.data as dt
loader = dt.FinanceLoader('VND', '2019-06-02','2021-12-31')
data_finan = loader.get_finan_report()
print(data_finan.head())

  10. Get basic index report using get_basic_index()

    master

    Use the get_basic_index() method on a FinanceLoader instance to retrieve key financial ratios and growth metrics, including:

    • ROA (Return on Assets)
    • ROE (Return on Equity)
    • Net Profit Margin
    • Net Revenue Growth
    • Profit After tax Growth
    import vnquant.data as dt
loader = dt.FinanceLoader('VND', '2019-06-02','2021-12-31', data_source='VND', minimal=True)
data_basic = loader.get_basic_index()
print(data_basic.head())

  11. Visualize stock prices with vnquant_candle_stick

    master

    The vnquant_candle_stick function in vnquant.plot allows you to create candlestick charts from a pandas DataFrame (OHLC/OHLCV type) or directly from a stock symbol string.

    If you provide a symbol string instead of a DataFrame, the package automatically clones the data from the specified data_source ('VND' or 'CAFE'). In this mode, start_date and end_date must be provided.

    Arguments:

    • data: A pandas DataFrame (OHLC or OHLCV type) OR a string representing a Vietnam stock symbol.
    • title: The chart title. If data is a symbol, this is auto-generated based on the symbol and date range.
    • xlab: X-axis label (default: 'Date').
    • ylab: Y-axis label (default: 'Price').
    • start_date: Start date (required if data is a symbol string).
    • end_date: End date (required if data is a symbol string).
    • colors: A list of two colors defining the increasing and decreasing candle colors.
    • width: Plot width in pixels (default: 800).
    • height: Plot height in pixels (default: 600).
    • show_advanced: A list of technical indicators to display. Supported values: ['volume', 'macd', 'rsi'].
    • data_source: The source to clone data from if using a symbol string. Options: 'VND' or 'CAFE'.
    • **kargs: Additional keyword arguments (e.g., show_vol=False to suppress volume).
    import vnquant.plot as pl
pl.vnquant_candle_stick(data, 
                        title=None, 
                        xlab='Date', ylab='Price', 
                        start_date=None, end_date=None, 
                        colors=['blue', 'red'], 
                        width=800, height=600, 
                        show_advanced=[], 
                        data_source='cafe', 
                        **kargs)

  12. Download stock prices using DataLoader

    master

    Use vnquant.data.DataLoader to fetch historical stock price data for one or multiple symbols within a specific time interval. After initializing the loader, call .download() to retrieve the data as a pandas DataFrame.

    Arguments

    • symbols (Union[str, list]): A single stock symbol (e.g., 'VND') or a list of symbols (e.g., ['VND', 'FPT']). Special indices like E1VFVN30, FUEVN100 (for both sources), or HNX-INDEX, HNX30-INDEX, UPCOM-INDEX (for cafe) are supported.
    • start (Optional[Union[str, datetime]], default=None): Start date in 'YYYY-MM-DD' format or as a datetime object.
    • end (Optional[Union[str, datetime]], default=None): End date in 'YYYY-MM-DD' format or as a datetime object.
    • data_source (str, default='CAFE'): The source for downloading data. Supported values: 'CAFE', 'VND'.
    • minimal (bool, default=True): If True, returns a basic set of columns. If False, returns all available columns (including volume/value reconciliation data).
    • table_style (str, default='levels'): Determines the structure of the returned DataFrame:
      • 'levels': Multi-level columns with Symbols and Arguments (e.g., high, low, open, close, adjust, volume, value).
      • 'prefix': Adds the stock symbol as a prefix to each column name (e.g., VND_high).
      • 'stack': Adds a 'code' column to identify the stock symbol for each record.
    import vnquant.data as dt

loader = dt.DataLoader(
  symbols='VND', 
  start='2018-01-10', 
  end='2018-02-15', 
  data_source='CAFE', 
  minimal=True, 
  table_style='levels'
)

data = loader.download()