Excel spreadsheet loader.
Reads .xlsx and .xls workbooks into a Dataset, one sheet at a time or all of them at once. Column typing and target extraction are delegated to load_pandas, so categorical columns are handled the same way as for any other tabular source.
Requires pandas and openpyxl; both are imported lazily, so the rest of tuiml.datasets.loaders works without them.
Functions
load_excel(filepath: Union[str, Path], target_column: Optional[Union[str, int]]=..., sheet_name: Union[str, int]=0, handle_categorical: str='encode') -> Dataset
Load a single sheet from an Excel workbook.
Parameters
filepath
str or Path
Path to the
.xlsx or .xls file.
target_column
str, int, or None
= -1
The column to treat as the target variable:
- •
-1: Use the last column - •
int: Use specific zero-based index - •
str: Use column name - •
None: Do not extract a target (X will contain all columns)
sheet_name
str or int
= 0
Sheet to read, either by name or by zero-based position.
handle_categorical
str
= 'encode'
What to do with non-numeric columns:
'encode' maps each category to an integer, 'drop' removes the column, 'error' raises.
Returns
result
Dataset
Standardized dataset object containing data and metadata.
Raises
ImportError
If
pandas (and openpyxl) are not installed.
python
>>> from tuiml.datasets.loaders import load_excel
>>> data = load_excel('sales.xlsx', sheet_name='Q1')
>>> X, y = datasave_excel(filepath: Union[str, Path], data: np.ndarray, feature_names: Optional[List[str]]=None, target: Optional[np.ndarray]=None, target_names: Optional[List[str]]=None, target_column_name: str='target', sheet_name: str='Sheet1')
Write features and an optional target to an Excel workbook.
Parameters
filepath
str or Path
Output file path.
data
numpy.ndarray of shape (n_samples, n_features)
Feature matrix to write.
feature_names
list of str or None
= None
Column headers. Defaults to
col0, col1, ...
target
numpy.ndarray of shape (n_samples,) or None
= None
Target values. Appended as an extra column when given.
target_names
list of str or None
= None
Class names. When given, integer targets are written as these labels instead of numbers.
target_column_name
str
= 'target'
Header for the target column.
sheet_name
str
= 'Sheet1'
Name of the sheet to write.
Returns
None
The workbook is written to
filepath.
Raises
ImportError
If
pandas (and openpyxl) are not installed.
python
>>> from tuiml.datasets.loaders import save_excel
>>> save_excel('out.xlsx', X, feature_names=['a', 'b'], target=y)load_excel_sheets(filepath: Union[str, Path], target_column: Optional[Union[str, int]]=..., handle_categorical: str='encode') -> dict
Load every sheet of an Excel workbook as a separate dataset.
Parameters
filepath
str or Path
Path to the
.xlsx or .xls file.
target_column
str, int, or None
= -1
The column to treat as the target variable, applied to every sheet. See
load_excel for the accepted values.
handle_categorical
str
= 'encode'
What to do with non-numeric columns:
'encode', 'drop', or 'error'.
Returns
result
dict
Dictionary mapping each sheet name to its Dataset.
Raises
ImportError
If
pandas (and openpyxl) are not installed.
python
>>> from tuiml.datasets.loaders import load_excel_sheets
>>> sheets = load_excel_sheets('report.xlsx')
>>> sorted(sheets)
['Q1', 'Q2']