Revision history for Algorithm-Classifier-IsolationForest 0.7.0 2026-07-08/14:30 - Add explain_samples() / explain_sample_tagged(), reporting which features drove a sample's anomaly score, to both the batch class and ::Online. Two methods: 'ablation' (the default) substitutes each feature in turn with a stored baseline and reports the score drop -- fit() now learns per-feature training-data medians for this and persists them with the model (::Online uses the medians of its retained window instead, tracking drift for free); 'path' apportions credit over the splits each tree walk crossed (local DIFFI; Carletti, Terzi & Susto 2023, see REFERENCES), needing nothing beyond the trees, so it also serves models saved before baseline support. Ablation is the default because it answers the counterfactual for any scored sample; path credit is only sharp for samples that were in the training data. - Add the `iforest explain` CLI command exposing explain_samples: one output line per (row, feature) pair, most responsible feature first, with --method path|ablation, -n for top-N features per row, and -t to score first and explain only the rows clearing the cutoff. - Add fit_from_csv(), which trains directly from a CSV file without loading it into RAM (for data sets too large to slurp). Streams the file in a census pass, a gather pass that keeps only the rows the trees sampled (Floyd's algorithm, O(n_trees*sample_size) memory), and -- when contamination is set -- a scoring pass whose min-heap yields the exact same threshold the in-RAM learner would. The census and gather passes only parse the cells they need (row count / column width, and the sampled rows), and the contamination scoring pass runs through the C backend when use_c is on, so a learned threshold over a large file is seconds rather than minutes. The first CSV line is skipped automatically when it holds feature names (any non-numeric cell, or a match of stored feature_names); header => 1 still forces it. - fit_from_csv() now defaults to an "index" gather: a fast block-scan census records each row's byte offset so the second pass seeks straight to the sampled rows instead of re-scanning the whole file, cutting a no-contamination fit of a 2M-row file from ~15s to ~3s. The offset table costs 8*n bytes and is dropped (falling back to the streaming reader) once it would exceed index_max (default 256 MiB); pass index => 0 to force streaming. The contamination scoring pass defaults to c_scan => 1, letting the C packer coerce cells instead of validating each in Perl (identical result on valid data; a non-numeric scored cell becomes 0.0 rather than dying). Under missing => 'die', a missing cell is now rejected when it lands in a sampled training row rather than during a full up-front scan. - fit()/from_json(): _pack_tree, which flattens each tree into the packed buffers the C scorer walks, now runs in the C backend (pack_tree_xs) instead of a recursive Perl closure that built an arrayref and six SVs per node and then flattened the lot through a map for pack(). It had grown into the largest single phase of an axis-mode fit: 100 trees repack in 0.6ms rather than 20.5ms (4.2ms rather than 62ms in extended mode), taking a 10k x 8 fit from 44ms to 16ms. Same DFS pre-order numbering, same dense-pack rule, byte-identical buffers. Skipped on wide-NV perls, where c(size) computed in C doubles would differ from _c() in the last ulp -- those keep the pure-Perl packer, as _NV_IS_DOUBLE guards elsewhere. - fit(): under missing => 'die' (the default) the up-front scan for undef cells now runs in the C backend when use_c is on, instead of a per-cell Perl loop over the whole training set -- 183ms -> 17ms on 400k rows x 4 features, where it had been ~68% of fit() time. Same row-major order, so the same offending cell is reported. A row that is not an arrayref now reads as missing at column 0 on both the C and pure-Perl paths (previously a Perl deref error), matching how pack_input_xs already treats one. - Doc cleanup. - Add t/81-sklearn-real-data.t and the four UCI datasets it uses (glass, ionosphere, seeds, wdbc; CC BY 4.0, see t/data/README for citations). The existing sklearn comparison only ever ran against synthetic blobs, and only on machines with Python. sklearn's scores are now checked in beside each dataset, so the comparison runs everywhere; where Python is present an extra arm re-runs sklearn live and catches drift against the checked-in reference. Agreement is required to be no worse than our own seed-to-seed agreement, rather than against a per-dataset floor: an Isolation Forest is a random estimator, so that spread is the ceiling, and measuring against it keeps the thresholds from encoding how hard a given dataset is to rank. Also checks that C and pure-Perl score identically on 30+ correlated columns, and that fit_from_csv detects a real header. 0.6.0 2026-07-09/08:15 - Implement Online Isolation Forest (Filippo Leveni, Guilherme Weigert Cassales, Bernhard Pfahringer, Albert Bifet, Giacomo Boracchi (2024)) as the new companion class Algorithm::Classifier::IsolationForest::Online and releated CLI commands. - initial prototype support - munging via Algorithm::ToNumberMunger 0.5.0 2026-07-04/14:30 - Wide-NV perls (-Duselongdouble / -Dusequadmath(maybe? does this even exist? but possibly some idiot on github... but would fix it in this case as well): the pure-Perl tree builder now rounds every value it stores (split points, hyperplane coefficients and offsets, impute fills) to C double precision at the same points the C builder rounds preserving the seed-for-seed bit-identical guarantee across backends. Possible breakages for the tests for extended mode where -Duselongdouble is in play may exist so tests for those systems where it is are skipped for now. - Implement Majority Voting Isolation Forest (MVIForest -- Chabchoub, Togbe, Boly & Chiky 2022, IEEE Access, doi:10.1109/ACCESS.2022.3144425) as new(voting => 'majority'): Since this only affects how the trees are walked etc and not build, the voting method can be switched between majority and mean. - adjust how iforest info displays tag info 0.4.0 2026-07-03/22:45 - Implement named features and methods for testing single rows using tagged data. - The C backend can be built and installed at install time, meaning nothing needs built unless changing the opts. See the docs for more details. - new IF_NO_OPENMP=1 selects/builds the serial C backend: no libgomp linkage and no OpenMP runtime in the process at all (unlike OMP_NUM_THREADS=1, which just caps the thread count); IF_NO_OPENMP=0 re-enables OpenMP over a serial install default - new IF_RUNTIME_BUILD=1 ignores the prebuilt object and forces the classic runtime build even when the flags match - iforest accel updated to reflect various changes to the C backend - scoring: the per-leaf path-length adjustment c(size) is now precomputed at tree-pack time and stored in the (previously unused) third slot of packed leaf records, removing a log() call per point per tree from the C scoring hot loop -- about 25% faster axis-mode scoring; results are bit-identical - scoring: score_all_xs now picks between two loop shapes based on total forest size: small forests keep the point-major loop (whole forest stays cache-resident anyway), while forests over 4 MB switch to a tree-blocked loop that walks a block of points through one tree at a time so each tree stays hot in L1/L2 instead of being re-streamed from memory per point -- measured ~3.2x faster extended-mode scoring at 400 trees (20k points, 16 features); both shapes add the same terms in the same order, so scores are bit-identical either way - any -march (IF_ARCH / IF_NATIVE, configure- or run-time) now automatically adds -ffp-contract=off: with FMA available the compiler otherwise contracts a*b+c into fused multiply-adds whose different rounding silently broke the use_c bit-parity guarantee (one ulp in a split value builds a different tree); the -march win comes from vectorization, so this costs ~nothing - scoring: oblique nodes now prefetch both child records before the dot product resolves which branch is taken, hiding the next node's memory latency under the FMA work (~7-10% faster extended-mode scoring on top of the tiling; axis path is untouched -- its single compare has no work to hide a prefetch under); purely a hint, results unchanged 0.3.0 2026-07-02/23:00 - lots of POD fixes/cleanup - various further C optmizations - fit() can now handle training data with missing (undef) feature cells, selectable via the new `missing =>` constructor option: die :: croak on undef in the training data (default) zero :: treat a missing cell as the value 0 impute :: fill with the per-feature mean/median (see `impute_with`) nan :: range over present values and route missing rows to the right child, consistently at fit and score time - new `impute_with => 'mean'|'median'` option for impute mode ... missing strategy + impute fill vector are persisted in saved models; models from older releases load as `zero` (the prior undef -> 0 scoring behaviour) - the C build is now tunable via environment variables read at first module load: IF_ARCH= adds -march=, IF_NATIVE=1 is shorthand for IF_ARCH=native, IF_OPT overrides the default -O3, and IF_NO_C=1 skips building the C backend entirely; values are validated (bad ones warn and fall back to the defaults) and the flags actually used are exposed via $OPT_LEVEL - Benchmarking: bench-sklearn-scoring.pl now compares pure Perl, C, and C+OpenMP fit/score paths against sklearn side by side 0.2.1 2026-06-30/14:30 - derp... actually update MANIFEST so a bunch of files from last release are actually included 0.2.0 2026-06-30/14:15 - C acceleration via Inline::C for core fit and predict ops - OpenMP support for parallel multi-threaded fitting and predict ops - SIMD (AVX/SSE) acceleration where available - Data packing support for compact model storage (new `pack` CLI command) - Parallel fit capability - New `score_predict_split` method - New `accel` CLI command for querying available acceleration flags - New `bench` CLI command for running built-in benchmarks - New `info` CLI command with expanded model introspection - Benchmarking scripts covering fit, predict, scoring, and accel modes - Tests: accel flag detection, accel selection, undef column handling, data packing, parallel fit, sklearn comparison (including undef), and CLI - minor tweaks to `csv2plot` for a bit nicer rendering - minor POD fixes 0.1.0 2026-06-23/03:15 - add csv2plot helper command for graphing 0.0.1 2026-06-21/21:45 - initial release