A technical reference guide to the public classes and functions within the Arnio library.
| Category | Components |
|---|---|
| Core Class | ArFrame, Properties: shape, columns, dtypes, is_empty, Methods: memory_usage, preview, select_columns, select_dtypes |
| I/O | read_csv, scan_csv, write_csv, sniff_delimiter |
| Cleaning | cast_types, clean, clip_numeric, combine_columns, drop_columns, drop_constant_columns, drop_duplicates, drop_nulls, fill_nulls, filter_rows, keep_rows_with_nulls, normalize_case, normalize_unicode, rename_columns, replace_values, round_numeric_columns, safe_divide_columns, strip_whitespace, trim_column_names, validate_columns_exist |
| Conversion | from_pandas, to_pandas |
| Integration | ArnioPandasAccessor |
| Pipeline | pipeline, register_step |
| Data Quality | profile • suggest_cleaning • auto_clean • check_quality_gates • DataQualityReport • ColumnProfile |
| Schema Validation | Schema • Field • validate • ValidationResult • ValidationIssue • Int64 • Float64 • String • Bool • Email • URL • CountryCode • DateTime |
| Custom Exceptions | ArnioError • CsvReadError • TypeCastError • UnknownStepError |
import arnio as ar
df = ar.read_csv("data.csv")| Property | Return Type |
|---|---|
| columns | list[str] |
| dtypes | dict[str, str] |
| shape | tuple[int, int] |
| is_empty | bool |
| Method | Return Type |
|---|---|
| memory_usage() | int |
| preview() | str |
| select_columns() | ArFrame |
| select_dtypes() | ArFrame |
print(f"Column Names: {df.columns}")
print(f"Data Types: {df.dtypes}")
print(f"Dataset Shape: {df.shape}")
print(f"Memory: {df.memory_usage()} bytes")
print(df.preview())
df = df.select_columns(columns=["id", "name"])
df = df.select_dtypes(include=["int64", "float64"])Loads a CSV, TSV, or TXT file into an ArFrame.
df = ar.read_csv("data.csv")Return schema (column names + inferred types) without loading data.
schema = ar.scan_csv("large_dataset.csv")Writes an ArFrame to a CSV file via the C++ backend.
ar.write_csv(frame, "output.csv")| Parameter | Type | Default | Description |
|---|---|---|---|
frame |
ArFrame |
required | The data frame to write |
path |
str | os.PathLike[str] |
required | Destination file path. Supports .csv, .txt, .tsv |
delimiter |
str |
"," |
Single character field separator |
write_header |
bool |
True |
Whether to write the column header row |
line_terminator |
str |
"\n" |
Line terminator between rows |
| Error | When |
|---|---|
ValueError |
File extension is not .csv, .txt, or .tsv |
ValueError |
delimiter is not exactly one character |
RuntimeError |
File cannot be opened or written |
# Default comma-separated
ar.write_csv(frame, "output.csv")
# Tab-separated
ar.write_csv(frame, "output.tsv", delimiter="\t")
# Without header row
ar.write_csv(frame, "output.csv", write_header=False)
# Windows line endings
ar.write_csv(frame, "output.csv", line_terminator="\r\n")Sniffs and returns the field delimiter character from a CSV file.
delimiter = ar.sniff_delimiter("data.csv")| Parameter | Type | Default | Description |
|---|---|---|---|
path |
str | os.PathLike[str] |
required | Path to the CSV file |
encoding |
str |
"utf-8" |
File encoding |
sample_size |
int |
2048 |
Number of bytes to sample from the start of the file for sniffing |
str
The detected delimiter (one of ",", ";", "\t", "|").
| Error | When |
|---|---|
TypeError |
encoding is not a string, or sample_size is not an integer |
ValueError |
sample_size is <= 0, the encoding is unknown, or the delimiter is ambiguous / tied |
CsvReadError |
The file is empty, or contains binary data (NUL bytes) |
FileNotFoundError |
The file does not exist |
# Sniff comma-separated file
delim = ar.sniff_delimiter("comma.csv") # returns ","
# Sniff semicolon-separated file with custom sample size
delim = ar.sniff_delimiter("semicolon.csv", sample_size=1024) # returns ";"Converts specific columns to a new data type using a mapping dictionary.
df = ar.cast_types(df, {"id": "float64"})A high-level wrapper that applies strip_whitespace, drop_nulls, and drop_duplicates in a single call.
df = ar.clean(df)Clip numeric values to lower and/or upper bounds.
df = ar.clip_numeric(df, lower=0, upper=100)Combine multiple columns into a single output column.
df = ar.combine_columns(df, separator=",", output_column="combined_col")Removes columns with only one unique value.
df = ar.drop_constant_columns(df)Removes the requested columns while preserving the order of the remaining ones.
frame = ar.drop_columns(frame, ["debug_col"])Removes identical rows from the dataset.
df = ar.drop_duplicates(df, keep="first")Excludes rows containing empty or null fields
df = ar.drop_nulls(df, subset=["email"])Replaces null entry values with a designated static value.
df = ar.fill_nulls(df, 0, subset=["score"])Subsets rows matching an evaluation operator constraint.
df = ar.filter_rows(df, column="age", op=">", value=18)Keep only rows that contain at least one null/empty value.
df = ar.keep_rows_with_nulls(df)Adjusts text casing for consistency.
df = ar.normalize_case(df, case_type="title")Normalize Unicode text columns.
df = ar.normalize_unicode(df, subset=["uni_col"], form="NFC")Modifies headers using a translation dictionary mapping old names to new names.
df = ar.rename_columns(df, {"old": "new"})Replace values based on a mapping dict.
df = ar.replace_values(df, {"old_value": "new_value"}, column="name")Round numeric columns.
df = ar.round_numeric_columns(df, decimals=2)Divide one column by another.
df = ar.safe_divide_columns(
df,
numerator="revenue",
denominator="cost",
output_column="ratio"
)Trims extra spaces from the beginning and end of text entries.
df = ar.strip_whitespace(df)Trims leading and trailing whitespace from column names.
df = ar.trim_column_names(df)Fail early when required columns are missing.
df = ar.validate_columns_exist(df, ["age"])Converts a pandas.DataFrame into an Arnio ArFrame.
Converts an ArFrame into a pandas.DataFrame
import pandas as pd
pdf = pd.DataFrame(data)
af = ar.from_pandas(pdf)
df = ar.to_pandas(af)Run Arnio preparation helpers from an existing pandas DataFrame.
Apply a sequence of cleaning steps to an ArFrame.
ops = [
("strip_whitespace",),
("normalize_case", {"case_type": "title"}),
("fill_nulls", {"value": 0, "subset": ["revenue"]}),
("fill_nulls", {"value": "Unknown", "subset": ["name"]}),
("drop_duplicates",),
]
df = ar.pipeline(df, ops)clean, metadata = ar.pipeline(df, ops, return_metadata=True)
print(metadata["step_timings"])Extend the pipeline by adding your own custom Python functions.
def custom_func(df, column):
pass
ar.register_step("custom_func", custom_func)Analyze an ArFrame and get a structural DataQualityReport.
Key options:
sample_size: number of non-null sample values stored per column.approx_top_values: enable approximate top values for high-cardinality string columns.approx_top_values_min_unique: minimum unique count to trigger approximation.approx_top_values_min_ratio: minimum unique ratio to trigger approximation.approx_top_values_sample_size: sample size for top-value estimation.
When approx_top_values is enabled, top_values counts/ratios are computed on
the sample, and top_values_is_approximate, top_values_sample_count, and
top_values_sample_ratio are included in each ColumnProfile.
Examine a report or frame and get a list of recommended cleaning steps.
Profile the data and immediately apply repairs.
Compare two DataQualityReport objects and return a pass/fail
QualityGateResult for CI or monitoring workflows.
baseline = ar.profile(ar.read_csv("baseline.csv"))
current = ar.profile(ar.read_csv("current.csv"))
result = ar.check_quality_gates(
baseline,
current,
max_row_count_delta_ratio=0.10,
max_null_ratio_delta=0.05,
)
print(result.passed)
print(result.to_markdown())Summary of structural data quality metrics.
to_html(file_path: str | None = None) -> str: Generates a self-contained, offline-friendly, beautiful HTML dashboard report of your dataset's metrics, columns, and cleaning suggestions. Dynamically escapes all data values to prevent XSS. Iffile_pathis provided, writes the HTML output to a file.to_markdown() -> str: Returns a GitHub-friendly markdown representation of the report.summary() -> dict: Returns a high-signal dictionary representation of the report metrics.
Detailed health check for a single column.
report = ar.profile(df)
summary = report.summary()
suggestions = ar.suggest_cleaning(df)
# Export the report as a beautiful, self-contained HTML file
html_report = report.to_html(file_path="quality_report.html")
safe = ar.auto_clean(df)
print(ar.to_pandas(safe))The top-level container for validation rules.
Defines the specific constraints for a single column.
The primary function used to check an ArFrame against a Schema. It returns a ValidationResult.
The objects returned after calling validate().
Row index convention: ValidationIssue.row_index is 1-based and refers to
data rows only — the CSV header is not counted. So row_index=1 means the first
data row, row_index=2 means the second, and so on.
# CSV content:
# name,age ← header (not counted)
# Alice,30 ← row 1
# Bob,-1 ← row 2 ← row_index=2 will appear here for a min violation
result = ar.validate(frame, {"age": ar.Int64(min=0)})
print(result.issues[0].row_index) # 2Each helper maps to a specific data type rule.
user_schema = ar.Schema({
"id": ar.Int64(unique=True, nullable=False),
"name": ar.String(nullable=False),
"revenue": ar.Float64(min=180, max=1000)
})
result = ar.validate(df, user_schema)| Error Name | Meaning |
|---|---|
| ArnioError | Base exception for all Arnio errors. |
| CsvReadError | Triggered when a CSV file cannot be read. |
| TypeCastError | Raised when cast_types encounters an incompatible type. |
| UnknownStepError | Triggered when a pipeline step name is not registered |