Installation

From PyPI:

pip install sksurrogate

or from source (development):

pip install git+https://github.com/mghasemi/sksurrogate.git

Data identity and schema validation

SKSurrogate now records a deterministic dataset fingerprint and a JSON-serializable schema for each tracked dataset. Each call to mltrack.RegisterData(...) stores dataset metadata, including the target column, row count, column names, dtypes, nullability, and categorical values. This allows a run to be identified and later compared against a different dataset or a refreshed training sample.

The tracker also exposes validate_data(...) and validate_prediction_data(...) to compare incoming data against the stored schema before training or inference. By default the checks are strict: missing columns, reordered columns, dtype mismatches, and unknown categorical values fail with actionable errors. For compatibility workflows, these checks can be relaxed explicitly with missing_columns='ignore' or unknown_categories='ignore'.

The intended workflow is:

1. Register the training dataset with mltrack.RegisterData(frame, target).

2. Validate training data before fitting with tracker.validate_data(frame, target=...).

3. Validate prediction inputs with tracker.validate_prediction_data(frame) before calling predict on a model or pipeline.

4. Use the stored dataset_fingerprint and dataset_schema metadata for reproducibility, drift checks, and auditability.

Dependencies

SKSurrogate heavily depends on NumPy, scipy, and scikit-learn, for its main functionalities. Other dependencies include pandas, matplotlib, SALib, peewee, and tqdm.

Documentation

The documentation is produced by Sphinx and is intended to cover code usage as well as a bit of theory to explain each method briefly. For more details refer to the documentation at sksurrogate.rtfd.io. The optional web UI and control-plane API are documented in the Web UI and Control-Plane API guide. The step-by-step UI manual includes screenshots and example CSV files.

MIT License

Copyright (c) 2019 Mehdi Ghasemi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.