API Reference

tsauditor.scan()

The single entry point for all audits.

tsauditor.scan(
    df: pd.DataFrame,
    target: Optional[str] = None,
    time_col: Optional[str] = None,
    domain: Optional[str] = None,
    run_profiler: bool = True,
    run_anomaly: bool = True,
    run_leakage: bool = True,
) -> GuardReport

Parameters

Parameter	Type	Default	Description
df	pd.DataFrame	required	Input DataFrame. Must have a DatetimeIndex, or pass time_col to specify a datetime column to use as the index.
target	str or None	None	Name of the target/label column. Required for leakage detection. If None, leakage checks are skipped silently.
time_col	str or None	None	Name of a datetime column to set as the index. If None, the DataFrame index must already be a DatetimeIndex.
domain	str or None	None	Domain hint for threshold tuning. One of "finance", "sensor", or None. See Domain Presets.
run_profiler	bool	True	Run structural profiling checks (PRF codes).
run_anomaly	bool	True	Run anomaly detection checks (ANO codes).
run_leakage	bool	True	Run leakage detection checks (LEK codes). Silently skipped if target is None.

Returns

A GuardReport object.

Raises

• TypeError — if df is not a pd.DataFrame
• ValueError — if domain is not one of the valid options, if target is not found in df.columns, if time_col is not found in df.columns, or if df is empty

Example

import tsauditor as tsa
 
report = tsa.scan(df, target="Direction", domain="finance")
report = tsa.scan(df, time_col="Date", domain="sensor")
report = tsa.scan(df, run_leakage=False)  # skip leakage checks

---

GuardReport

The structured output of scan().

from tsauditor import GuardReport

Attributes

Attribute	Type	Description
critical	List[Issue]	Issues that must be fixed before modeling
warnings	List[Issue]	Issues worth reviewing
info	List[Issue]	Informational findings
metadata	Dict[str, Any]	Dataset-level metadata: rows, columns, time range, inferred frequency, target, domain

Properties

all_issues → List[Issue] All issues from all severity buckets, sorted by severity then module.

Methods

filter(code=None, module=None, severity=None) → List[Issue] Return issues matching all supplied filters. All parameters are optional and combinable.

report.filter(module="leakage")
report.filter(code="LEK001")
report.filter(module="profiler", severity="critical")

leaky_columns() → List[str] Returns a sorted list of column names flagged by the leakage module. The shortlist of features to review or remove first.

cols = report.leaky_columns()
# ['ChangeP', 'Return']

suggestions() → List[Dict[str, Any]] Returns a list of per-issue suggested actions, ordered by severity. Each dict contains code, column, severity, and suggestion.

summary() → None Prints a rich-formatted CLI table showing all issues, plus suggested actions below. Writes to stdout.

to_json(path) → None Export the full report to a JSON file at path. Includes metadata, all issues with evidence and suggestions, and issue counts by severity.

report.to_json("report.json")

to_dict() → Dict[str, Any] Return the full report as a plain Python dictionary. Same structure as the JSON export.

---

Issue

A single quality issue raised by any audit module.

from tsauditor import Issue

Attributes

Attribute	Type	Description
module	str	Which module raised it: "profiler", "anomaly", or "leakage"
code	str	Short issue code, e.g. "LEK001". See Issue Code Reference
severity	str	One of "critical", "warning", "info"
description	str	Human-readable explanation of the issue
column	str or None	The affected column name, or None for dataset-level issues
evidence	Dict[str, Any]	Supporting statistics, e.g. {"auc_score": 1.0, "threshold": 0.95}

Properties

suggestion → str A concrete recommended action derived from the issue code and evidence. Advisory only — tsauditor never modifies your data.

Methods

to_dict() → Dict[str, Any] Serialize the issue to a plain Python dictionary, including the suggestion.

---

Severity constants

from tsauditor.report.summary import CRITICAL, WARNING, INFO

Use these when filtering programmatically to avoid string literals:

critical_issues = [i for i in report.all_issues if i.severity == CRITICAL]