JSON reader and writer, in three layouts.
Covers the three shapes tabular data usually takes in JSON: a single document holding an array of records (
load_json), one record per line (load_jsonl, for streaming and append-only logs), and records with nested objects that need flattening into columns (load_json_nested).Functions
load_json(filepath: Union[str, Path], target_column: Optional[Union[str, int]]=..., orient: str='auto', lines: bool=False, handle_categorical: str='encode') -> Dataset
Load data from JSON file.
Parameters
filepath
str or Path
Path to JSON file
target_column
str, int, or None
Column name or index for target variable (None for unsupervised, -1 for last column)
orient
str
JSON structure format:
- •'auto': Auto-detect format
- •'records': [{col1: val1, col2: val2}, ...]
- •'columns': {col1: [val1, val2], col2: [val1, val2]}
- •'index': {idx1: {col1: val1}, idx2: {col1: val1}}
- •'values': [[val1, val2], [val1, val2]]
- •'split': {index: [], columns: [], data: []}
- •'table': {schema: {}, data: []}
lines
bool
Whether file is JSON Lines format (one JSON object per line)
handle_categorical
str
How to handle categorical columns:
- •'encode': Label encode to integers
- •'drop': Drop categorical columns
- •'error': Raise error if categorical found
Returns
result
Dataset
Dataset object with X, y, feature_names
python
>>> from tuiml.datasets.loaders import load_json
>>> data = load_json('data.json', target_column='class')
>>> data.X.shape, data.y.shape
python
>>> # JSON Lines format
>>> data = load_json('data.jsonl', lines=True)
python
>>> # Specific orientation
>>> data = load_json('data.json', orient='records')save_json(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', orient: str='records', lines: bool=False, indent: Optional[int]=2)
Save data to JSON format.
Parameters
filepath
str or Path
Output file path
data
numpy.ndarray
Feature data (n_samples, n_features)
feature_names
list of str or None
List of feature names
target
numpy.ndarray or None
Target values (optional)
target_names
list of str or None
Names of target classes (for classification)
target_column_name
str
Name for target column
orient
str
JSON structure format ('records', 'columns', 'values', 'split', 'table')
lines
bool
Whether to write as JSON Lines format
indent
int or None
Indentation level (None for compact, set when lines=False)
python
>>> from tuiml.datasets.loaders import save_json
>>> save_json('output.json', X, feature_names=['a', 'b'], target=y)
>>> save_json('output.jsonl', X, lines=True)load_jsonl(filepath: Union[str, Path], target_column: Optional[Union[str, int]]=..., handle_categorical: str='encode', max_lines: Optional[int]=None) -> Dataset
Load data from JSON Lines file.
Each line is a separate JSON object (records format).
Parameters
filepath
str or Path
Path to JSONL file
target_column
str, int, or None
Column name or index for target variable
handle_categorical
str
How to handle categorical columns
max_lines
int or None
Maximum number of lines to read (None for all)
Returns
result
Dataset
Dataset object
python
>>> from tuiml.datasets.loaders import load_jsonl
>>> data = load_jsonl('data.jsonl', target_column='label')
>>> data = load_jsonl('large_data.jsonl', max_lines=10000)save_jsonl(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')
Save data to JSON Lines format.
Parameters
filepath
str or Path
Output file path
data
numpy.ndarray
Feature data (n_samples, n_features)
feature_names
list of str or None
List of feature names
target
numpy.ndarray or None
Target values (optional)
target_names
list of str or None
Names of target classes
target_column_name
str
Name for target column
python
>>> from tuiml.datasets.loaders import save_jsonl
>>> save_jsonl('output.jsonl', X, feature_names=['a', 'b'], target=y)load_json_nested(filepath: Union[str, Path], record_path: Union[str, List[str]], meta: Optional[List[str]]=None, target_column: Optional[Union[str, int]]=..., handle_categorical: str='encode') -> Dataset
Load data from nested JSON structure.
Flattens nested JSON using pandas json_normalize.
Parameters
filepath
str or Path
Path to JSON file
record_path
str or list of str
Path to records in nested structure (e.g., ['data', 'items'])
meta
list of str or None
Fields to include from parent levels
target_column
str, int, or None
Column name or index for target variable
handle_categorical
str
How to handle categorical columns
Returns
result
Dataset
Dataset object
python
>>> from tuiml.datasets.loaders import load_json_nested
>>> # For JSON like: {"response": {"data": [{"a": 1}, {"a": 2}]}}
>>> data = load_json_nested('api_response.json',
... record_path=['response', 'data'])