hrchy_cytocommunity.visualization.visualization.load_base_data

hrchy_cytocommunity.visualization.visualization.load_base_data(InputFolderName, graph_index, is_single_cell=True, fine_GT=False, coarse_GT=False)

Load spatial coordinate and optional annotation data for a specific region graph.

This utility function reads spatial coordinate files and associated metadata (such as cell type labels and ground-truth cluster labels) from a given input directory. It constructs a pandas DataFrame containing per-cell (or per-spot) spatial locations, and optionally includes cell-type and hierarchical ground truth annotations.

Parameters:

  • InputFolderName (str or Path) –

    Path to the input folder that contains all region files. The folder must include:

    • ImageNameList.txt — list of region names (one per line, tab-separated)

    • <region>_Coordinates.txt — x/y coordinates of each cell or spot

    • <region>_CellTypeLabel.txt (optional, required if is_single_cell=True)

    • <region>_fineGT.txt (optional, required if fine_GT=True)

    • <region>_coarseGT.txt (optional, required if coarse_GT=True)

  • graph_index (int) – The index (0-based) of the region name to be loaded, corresponding to the row in ImageNameList.txt.

  • is_single_cell (bool, default=True) – Whether the dataset represents single-cell resolution. If True, the function attempts to load cell type labels from <region>_CellTypeLabel.txt and adds them to the output DataFrame.

  • fine_GT (bool, default=False) – Whether to load fine-grained ground truth labels (from _fineGT.txt).

  • coarse_GT (bool, default=False) – Whether to load coarse-grained ground truth labels (from _coarseGT.txt).

Returns:

target_graph_map – A DataFrame containing spatial coordinates and optional annotation columns. Columns include:

  • x_coordinate : float — x position of each cell/spot

  • y_coordinate : float — y position of each cell/spot

  • CellType : str — (if is_single_cell=True) cell-type label

  • fine_GT : int — (if fine_GT=True) fine-level ground truth cluster

  • coarse_GT : int — (if coarse_GT=True) coarse-level ground truth cluster

Return type:

pandas.DataFrame

Notes

  • The function assumes all input files are tab-separated text files.

  • Coordinate files and label files must have the same number of rows.

  • This function does not modify coordinate orientation, but a commented line shows how to flip the y-axis if needed for consistency with specific references.

Examples

>>> df = load_base_data(
...     InputFolderName="data/Mouse_Spleen/",
...     graph_index=0,
...     is_single_cell=True,
...     fine_GT=True,
...     coarse_GT=True
... )
>>> df.head()
   x_coordinate  y_coordinate    CellType  fine_GT  coarse_GT
0         123.4          98.7  B_cell_A1         2          1
1         128.9         101.3  B_cell_A2         2          1