# Getting Started with unitcm

## Installation

Install the development version from GitHub:

    # install.packages("pak")
    pak::pkg_install("zx122ty/UniTCM_R_Package")

Or using `remotes`:

    remotes::install_github("zx122ty/UniTCM_R_Package")

## Setup

    library(unitcm)

By default, `unitcm` connects to the public UniTCM API at `https://unitcm.qfxulab.com/api/v1`. You can override this if needed:

    # Only needed for custom/local deployments
    set_base_url("https://unitcm.qfxulab.com/api/v1")

## Authentication

All data-access endpoints are currently public and require no authentication. For future authenticated endpoints, you can set a token:

    # Via environment variable (recommended for scripts/CI)
    # Set UNITCM_TOKEN in your .Renviron

    # Or set in session
    set_unitcm_token("your-token-here")

    # Or store securely in system keyring
    set_unitcm_token("your-token-here", keyring = TRUE)

## Your First Query

Search for herbs related to ginseng:

    herbs <- search_herbs(q = "ginseng")
    herbs

Get detailed information for a specific herb:

    herb <- get_herb("UNITCM_H001")
    herb$herb_english_name
    herb$efficacy

## Pagination

Most search functions return paginated results. Use `page` and `page_size` to control pagination manually, or set `all_pages = TRUE` to fetch everything:

    # Manual pagination
    page1 <- search_herbs(q = "ginseng", page = 1, page_size = 50)
    attr(page1, "total") # Total records available

    # Auto-pagination: fetches all pages with a progress bar
    all_herbs <- search_herbs(q = "ginseng", all_pages = TRUE)
    nrow(all_herbs)

## Available Modules

`unitcm` provides access to these UniTCM platform modules:

Module | Key Functions
--- | ---
Herb Explorer | `search_herbs()`, `get_herb()`, `get_herb_compounds()`
Ingredient Explorer | `search_compounds()`, `get_compound_admet()`, `get_compound_targets()`
Disease-Formula Atlas | `search_formulas()`, `get_formula_doses()`, `fetch_disease_tree()`
TCM Ontology | `search_ontology()`, `get_ontology_entity()`, `export_ontology()`
MIDAS Gene-Disease | `query_gene_diseases()`, `query_disease_enrichment()`

See `vignette("database-queries")` for detailed examples of each module.