Data

hqnn_forge.data

hqnn_forge.data

Dataset loaders.

Exported symbols

load_credit_card_fraud Kaggle Credit Card Fraud Detection (mlg-ulb/creditcardfraud). CreditCardFraud (X, y, feature_names) returned by the loader. DatasetNotFoundError Raised when the CSV is absent and download=False. DatasetDownloadError Raised when download=True but fetching the CSV fails. load_taiwanese_bankruptcy UCI Taiwanese Bankruptcy Prediction (3.2% positive). load_iranian_churn UCI Iranian Churn (15.7% positive). load_cervical_cancer_risk UCI Cervical Cancer (Risk Factors), biopsy label (6.7% positive). BinaryDataset (X, y, feature_names) returned by the UCI loaders.

CreditCardFraud

Bases: NamedTuple

Attributes:

Name	Type	Description
X	NDArray[float64]	Features, shape (n_samples, n_features), float64.
y	NDArray[int64]	Labels, shape (n_samples,), int64, 1 = fraud.
feature_names	tuple[str, ...]	Column name for each column of X.

X instance-attribute

X: NDArray[float64]

y instance-attribute

y: NDArray[int64]

feature_names instance-attribute

feature_names: tuple[str, ...]

DatasetDownloadError

Bases: RuntimeError

Downloading was requested but could not be carried out or did not produce the file.

DatasetNotFoundError

Bases: FileNotFoundError

The dataset file is missing and downloading was not requested.

BinaryDataset

Bases: NamedTuple

Attributes:

Name	Type	Description
X	NDArray[float64]	Features, shape (n_samples, n_features), float64.
y	NDArray[int64]	Labels, shape (n_samples,), int64, 1 = the positive (rare) class.
feature_names	tuple[str, ...]	Column name for each column of X.

X instance-attribute

X: NDArray[float64]

y instance-attribute

y: NDArray[int64]

feature_names instance-attribute

feature_names: tuple[str, ...]

load_credit_card_fraud

load_credit_card_fraud(path: str | PathLike[str] | None = None, *, download: bool = False, drop_time: bool = False, strict: bool = False) -> CreditCardFraud

Load creditcard.csv as NumPy arrays.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str] | None	The CSV file, or a directory containing creditcard.csv; a path that does not end in .csv is taken as the directory. Default: $HQNN_FORGE_DATA/creditcard.csv if that variable is set, else data/raw/creditcard.csv relative to the working directory (the benchmark repository's layout).	None
download	bool	If the file is missing, fetch it with the Kaggle CLI into the file's directory. Requires kaggle on PATH and configured credentials. The CSV is ~150 MB once unpacked: seconds on a fast link, several minutes on a slow one. The CLI's progress bar is passed through to this process's stderr as it runs. The download is stopped if the CLI prints nothing for 120 s (a stalled connection) or runs past 3600 s in total; the error then repeats the command, to run by hand on a link too slow for that. On any failure, including a timeout or Ctrl-C, the files this call created are removed, so a retry starts clean.	False
drop_time	bool	Drop the Time column (seconds since the first transaction), which the benchmark excludes as a leakage-prone ordering feature.	False
strict	bool	Also require the published row count (284,807) and fraud count (492).	False

Returns:

Type	Description
CreditCardFraud

Raises:

Type	Description
DatasetNotFoundError	The file is missing and download is False. The message contains the Kaggle command that fetches it.
DatasetDownloadError	download is True but the file could not be fetched: the Kaggle CLI is missing, the command failed, it produced no file, it stalled, or it ran past its total time -- the message says which. Distinct from DatasetNotFoundError so that retrying with download=True after catching that one cannot loop.
ValueError	The file does not have the expected columns, has no data rows, has non-numeric values, labels other than 0/1, or (with strict) the wrong row or fraud count.

load_cervical_cancer_risk

load_cervical_cancer_risk(path: str | PathLike[str] | None = None, *, download: bool = False, missing: Literal['drop', 'keep'] = 'drop', strict: bool = False) -> BinaryDataset

Cervical Cancer (Risk Factors): 30 risk factors, biopsy result as label; 668 complete records with 45 positives (6.7%).

Demographics, habits and medical history of 858 patients, collected at the Hospital Universitario de Caracas, Venezuela; patients could decline to answer questions, hence the missing values. UCI dataset 383, CC BY 4.0, doi:10.24432/C5Z310.

Preprocessing, always applied: Biopsy is the label. Left out of the features are Hinselmann, Schiller and Citology, the outcomes of the other examinations, which would leak the diagnosis, and the two STDs: Time since ... diagnosis columns, missing for 787 of 858 patients. That leaves 30 features. STDs:cervical condylomatosis and STDs:AIDS are 0 for every complete record. The file also repeats 23 of its rows exactly.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str] | None	risk_factors_cervical_cancer.csv or the directory holding it; the default is as for load_taiwanese_bankruptcy.	None
download	bool	If the file is missing, fetch the UCI archive and extract it there.	False
missing	Literal['drop', 'keep']	The file marks a missing answer with ?. "drop" (default) drops every patient with a missing value among the 30 features: 668 records, 45 positives. "keep" keeps all 858 patients (55 positives) with NaN in X, for a caller who imputes; the rest of the library does not accept NaN.	'drop'
strict	bool	Also require the published file (SHA-256).	False

Returns:

Type	Description
BinaryDataset

Raises:

Type	Description
(DatasetNotFoundError, DatasetDownloadError, ValueError)	As for load_taiwanese_bankruptcy; also ValueError for a missing other than "drop" or "keep".

load_iranian_churn

load_iranian_churn(path: str | PathLike[str] | None = None, *, download: bool = False, drop_duplicates: bool = False, strict: bool = False) -> BinaryDataset

Iranian Churn: 3,150 telecom customers, 13 features, 495 churned (15.7%).

Customers drawn at random from an Iranian telecom company's database over 12 months; the label says whether the customer churned. UCI dataset 563, CC BY 4.0, doi:10.24432/C5JW3Z.

The file holds 300 rows that repeat an earlier row exactly, so the same customer record can land in both the training and the test fold. drop_duplicates=True keeps the first of each, leaving 2,850 rows with 446 churned (15.6%). Age Group is a binned copy of Age, and Complains, Tariff Plan and Status are codes stored as numbers.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str] | None	Customer Churn.csv or the directory holding it; the default is as for load_taiwanese_bankruptcy.	None
download	bool	If the file is missing, fetch the UCI archive and extract it there.	False
drop_duplicates	bool	Drop rows identical to an earlier one, features and label alike.	False
strict	bool	Also require the published file (SHA-256).	False

Returns:

Type	Description
BinaryDataset	y is Churn. feature_names are the file's column names with runs of spaces collapsed ("Call Failure" → "Call Failure").

Raises:

Type	Description
(DatasetNotFoundError, DatasetDownloadError, ValueError)	As for load_taiwanese_bankruptcy.

load_taiwanese_bankruptcy

load_taiwanese_bankruptcy(path: str | PathLike[str] | None = None, *, download: bool = False, strict: bool = False) -> BinaryDataset

Taiwanese Bankruptcy Prediction: 6,819 companies, 95 financial ratios, 220 bankrupt (3.2%).

Collected from the Taiwan Economic Journal for 1999-2009, with bankruptcy defined by the business regulations of the Taiwan Stock Exchange. UCI dataset 572, CC BY 4.0, doi:10.24432/C5004D.

The file (data.csv) is used unchanged: no missing values, no duplicate rows. Most ratios lie in [0, 1], but some reach 1e10, so scale before PCA; Net Income Flag is constant.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str] | None	data.csv or the directory holding it. Default: $HQNN_FORGE_DATA/data.csv if that variable is set, else data/raw/data.csv. The generic file name is UCI's; a directory of its own avoids a clash with other datasets.	None
download	bool	If the file is missing, fetch the UCI archive and extract it there.	False
strict	bool	Also require the file to be byte-identical to the published one (SHA-256), which fixes the row and positive counts above.	False

Returns:

Type	Description
BinaryDataset	y is Bankrupt?; feature_names are the file's column names.

Raises:

Type	Description
DatasetNotFoundError	The file is missing and download is False.
DatasetDownloadError	download is True and the archive could not be fetched, has no data.csv, or its data.csv is not the published file.
ValueError	The file does not have the expected columns, has no data rows, has a non-numeric value or a label other than 0/1, or (with strict) is not the published file.