Release Notes

Version 1.2

v1.2.0 (Unreleased)

In development.

Tools that are still under active development are marked beta: their API may change between minor releases without the usual deprecation cycle. The Beta Features page lists every beta tool in one place.

Added

  • Candidate lineage: lineage= on combine() and run() attaches one opt-in, JSON-serializable record per candidate (content-hash candidate_id, parent, ordered parent-relative mutations, method, objective values, effective seed, constraints digest); trace_lineage walks a chain of records back to its root, so a multi-round design replays exactly. Default outputs are unchanged.

  • DesignConstraints: one validated container for the design limits that AAMut, SeqMut and SeqOpt all express — immutable and mutable positions, permitted and forbidden substitutions, a mutation budget, identity bounds to the parent, and required or forbidden motifs. Positions are 1-based over the parent sequence.

  • check() returns (ok, reasons) so a rejected candidate explains itself, as_predicate() adapts the same limits to the feasibility callable run() consumes, and to_dict / from_dict round-trip a constraint set through JSON.

  • All three design classes accept the object as constraints. The region, to_aa and n_mut_max parameters keep their meaning and are now shorthand that builds one internally, so a limit has a single definition; combining a shorthand with an object that sets the same limit differently raises. Results are unchanged when no object is passed.

  • eval_selective(): the risk-coverage trade-off as a table. Samples are ranked by a per-sample confidence signal and every metric is scored again on the most-confident fraction, at each level of a coverage grid, so a refusal threshold can be chosen from evidence. The confidence source is the caller’s (confidence=); the default is the out-of-fold score margin. The coverage=1.0 row is the ordinary out-of-fold score. Classification only, and a measurement only: nothing abstains and eval() is untouched.

  • CPP feature intervals: CPP(bootstrap=True, bootstrap_kws=dict(ci=0.95)) retains the statistics each resampling round already computes and summarises them into a percentile interval per feature, adding abs_auc_ci_low / _high and mean_dif_ci_low / _high to df_feat at no extra runs. The interval is conditional on selection, so it is read together with selection_frequency. Leaving ci unset keeps the output unchanged.

  • ranking() renders those intervals: show_ci=True draws them as whiskers on the mean difference bars, in ci_color. Off by default, so existing figures are unchanged, and a feature with NaN bounds keeps a bare bar.

  • eval() gains use_calibrated and add_metrics, which score the calibrated column and append Brier score and expected calibration error, so comparing the raw and calibrated tables shows whether calibration helped. Defaults leave the table unchanged. reliability_diagram() gains label, annotates both metrics in the legend, and lets a raw and a calibrated curve share one axis.

  • fit() now warns when calibrate=True cannot be honoured, for example too few members in a class, instead of failing silently.

  • Banded applicability domain: predict() appends ad_status (inside / borderline / outside / unknown) and ad_nearest_train, and fit() gains ad_borderline and exposes the fitted ad_threshold_ and ad_method_. Apart from the ad_knn_dist to ad_knn rename, existing columns are unchanged.

  • predict_candidates(): scores a designed candidate set in one call. It takes the table the design methods emit, rebuilds the feature matrix from the wild-type coordinates in df_seq, and delegates to predict(). The result is row-aligned with the candidates, so the two join directly.

  • from_pssm(): position-specific scoring matrices as a CPP value source. It reads PSI-BLAST ASCII files and precomputed arrays, reorders file columns into canonical amino acid order, and with return_scales=True also returns the matching df_scales and df_cat, so a matrix runs through run_num() unchanged.

  • get_split_kws() gains a strategy preset: "compositional" returns the whole-part segment split and "positional" the sub-segments plus patterns. Together they cover the default split set; strategy=None is unchanged, and a preset cannot be combined with non-default split arguments.

  • learning_curve() answers whether a task is sampling-limited: it repeats the cross-validation on nested subsets of each training fold, scores on the untouched test fold, and returns one row per model, size and metric with a bootstrap interval. At the full fraction it reproduces run() exactly for the same settings. learning_curve() draws it with the band.

  • group_cluster() gains kind='dendrogram' with a rectangular or circular layout, coloured by the existing annotations. It shares the clustermap’s linkage, so both kinds show the same topology.

  • The Data Schemas page now documents the prediction outputs downstream tools read: df_pred, df_rel and df_eval_reliability. Contract tests pin their column names, order and dtypes, so renaming, dropping, retyping or undocumenting one fails the suite.

Changed

  • Consistency pass on the prediction and design tier. These classes are marked beta, so the changes land without a deprecation cycle: fit() takes ci as a fraction in (0, 1) rather than a percent, and a percent now raises; ad_knn_dist is renamed ad_knn and the n column of eval() is renamed n_samples; SeqOpt defaults to mode="importance", so it constructs in a base install; eval() accepts "mcc", giving AAPred and ModelEvaluator one metric vocabulary; and both classes now validate df_scales and list_parts instead of ignoring an invalid value.

  • run(): n_sample_batches creates exactly the requested number of balanced, non-empty batches, and the multiple-testing correction is now pooled across scale batches, so a batched run matches the single-pass result.

Fixed

  • fit() rejects non-finite values for ci, ad_percentile and conformal_alpha. A NaN passed both range comparisons silently and produced NaN interval columns.

  • eval(): passing X without labels now raises, where the features were silently ignored. Passing labels alone scores the training features against that labelling.

  • reliability_diagram() validates its arguments in the frontend, so an invalid value names the parameter instead of raising from matplotlib.

  • encode_pae() reads the PAE JSON exactly as the AlphaFold Database serves it, so downloaded files load without a manual unwrap, and get_domains() reads the ClusteringResult that current AFragmenter releases return.

  • Plot legibility: the total and key of ranking() no longer overprint short bars; eval() caps its annotations to the bar height; SeqOptPlot fixes the convergence y-label, a taller mutation map and single-front colouring; long condition names rotate or wrap in the comparison charts; an explicit cbar_xywh is honoured by feature_map() and heatmap(); and AALogoPlot keeps P-site and part labels from overprinting.

  • Quiet by default: the structure and embedding preprocessors no longer echo third-party probe messages, progress bars or dataset-dependency notes to stderr, and ShapModel runs its explainer silently.

  • Notebooks: every table is shown with display_df, the structure and UniProt examples are real executed walkthroughs instead of commented-out stubs, and several notebooks were repaired to pass nbformat validation.

Documentation

  • New tutorial CPP with protein language model embeddings and AlphaFold structures: the recommended embedding and structure paths into run_num(), and painting the signature onto the 3D model.

  • New usage-principles page Golden Pipelines: what the aaanalysis.pipe layer is for, its shared return shape, and the parity anchors that keep it honest against the explicit path. find_features() documents that only its fast search is parity-anchored.

  • Protocols P2: Exploratory sequence analysis and P3: Sampling brought to the protocol quality rubric: each opens with a mental model and shows every concept it names as a contrast figure.

  • Protocols P6: Compositional vs positional, P9: Interpretability and P10: Validation audited against the same rubric, with the audit recorded under docs/guides/. Each now shows the concept its prose had only asserted: how wide along the sequence each compositional and positional feature looks, group-level add_feat_importance() beside per-sample add_feat_impact(), and per-feature effect-size stability against a shuffled-label null. Every demonstrated CPP, ShapModel, ModelEvaluator and AAPredPlot call passes its public parameters by name, and P6 documents the strategy presets of get_split_kws() instead of stating that no such switch exists.

  • run(): the n_sample_batches documentation no longer claims that peak memory is bounded by the batch size. Measurements show it bounds the dominant per-batch tensor while the survivor matrix stays resident, so peak memory still grows with the sample count, on a far flatter slope.

Version 1.1

v1.1.0 (2026-09-10)

Added

  • Per-residue input preprocessors: EmbeddingPreprocessor (protein language model embeddings), StructurePreprocessor ([pro]; PDB / CIF / AlphaFold and PAE files) and AnnotationPreprocessor ([pro]; UniProt records) turn each source into the per-residue tensors run_num() consumes.

  • Input helpers: combine_dict_nums() concatenates per-residue tensors from several sources, get_labels() derives a binary label vector from a sequence DataFrame, pad_parts() pads part columns to equal length, and every bundled dataset now carries a human-readable gene name.

  • get_provenance(): opt-in, JSON-serializable record of how a result was produced (versions, parameters and the effective seed), so a figure can be traced back to the run behind it.

  • SequenceFeatureTransformer: scikit-learn transformer that runs CPP feature selection inside a pipeline, fitting the selection on the training fold only, so cross-validated scores stay honest instead of being inflated by selection on the full set.

  • CPPGrid: tool-style wrapper (run + eval) that sweeps CPP configurations in parallel and returns one evaluation table across the grid, so a configuration choice is made on evidence rather than by hand.

  • run_num(): numerical mode sourcing per-residue values from a pre-sliced tensor, and run_composit(): composition mode scoring amino-acid, dipeptide and k-mer descriptors with CPP’s discriminative statistics.

  • CPP stability and cost controls: opt-in bootstrap / stability annotation (bootstrap, bootstrap_kws) adding selection_frequency, redundancy='legacy'|'exact' on run() / run_num(), and candidate_search='fast' on simplify().

  • Label helpers on SequenceFeature: get_labels_ovr / get_labels_ovo convert multi-class labels to binary settings, get_labels_quantile / get_labels_tiered discretize a continuous target.

  • Baseline featurizers on SequenceFeature: scale_composition, aa_composition, dipeptide_composition, kmer_composition and the order-aware acc (scale auto-covariance), so CPP features can be compared against non-positional baselines. feature_matrix() builds the matrix for run_num()-selected features.

  • Part and description helpers: get_df_parts_from_windows() assembles a reference df_parts from windows, get_seq_kws() returns one protein’s part sequences, and get_feature_descriptions() gives each feature a standardized, human-readable description.

  • sample_kws bundle: the CPP plots take one bundle of sample-selection keywords instead of several flat parameters.

  • Scale and protein selection on AAclust: pre_select_scales filters by AAontology metadata before clustering, select_scales returns the redundancy-reduced set directly, and select_proteins reduces redundancy over a per-protein matrix. AAclustPlot centers / medoids accept df_scales.

  • ReliabilityModel and ReliabilityModelPlot: per-sample prediction reliability. One call per sample reports calibrated score, ensemble spread, a confidence interval, applicability-domain distance and a conformal set, so a prediction carries how much it can be trusted. The plot class renders the calibration curve and the trust axes.

  • ModelEvaluator and ModelEvaluatorPlot: model-agnostic evaluation harness. Repeated stratified cross-validation over several seeds, bootstrap intervals per metric, and a paired comparison on identical folds, so two models are separated by evidence rather than by a single split.

  • New AAPred capabilities: eval(baseline=...) compares CPP features against composition baselines, eval(cv=...) accepts an arbitrary scikit-learn splitter, predict_oof returns cross-validated out-of-fold per-sample scores, and score_to_group maps scores to named confidence bands. AAPredPlot gains eval(kind='heatmap') and predict_group(kind='rank_scatter').

  • ShapModel ([pro]): accession-based fit interface, and an unbiased fuzzy estimator that is now the default.

  • CPPStructurePlot ([pro]): paints per-residue CPP and CPP-SHAP impact onto a 3D structure.

  • PU learning: fit() accepts a positives / unlabeled split directly, project() projects held-out samples into the same space, and AAWindowSampler samples fixed-length windows for PU learning.

  • scan_motif() ([pro]): scans candidate proteins for statistically significant position-weight-matrix motif hits, reporting each hit with its match p-value.

  • Protein engineering: SeqOpt and SeqOptPlot perform multi-objective, machine-learning-guided directed evolution over one wild-type (core; only mode="impact" needs [pro]). SeqMut gains a model-guided mode and combine for multi-mutation variants, and SeqMutPlot renders the prediction-shift landscape.

  • Metrics: comp_per_protein_ap(), comp_detection_metrics(), comp_bootstrap_ci() and comp_smooth_scores() for site-localization ranking and thresholded detection.

  • Plot sizing: cell_size holds every grid cell at an exact physical size, seq_size defaults to "auto" and fits residue letters to the cell, and fontsize_labels gains "auto", which tracks the font scale and shrinks on overlap.

  • Named sample colors: COLOR_SAMPLES_POS / _NEG / _UNL / _REL_NEG expose the canonical group colors as public constants.

  • options['plot_settings']: opt-in, session-persistent plot_settings(), so every subsequent figure adopts the publication style automatically.

  • aaanalysis.pipe (ap): an opt-in convenience API of stateless, one-call pipelines — find_features (staged CPP AutoML, with selection_scope="global"|"fold" for honest evaluation), predict_samples, explain_features and plot_eval.

  • aa.__version__ exposes the installed version, and a root CHANGELOG.md gives a terse, developer-facing index alongside these notes.

Changed

  • Module rename: protein_design is now protein_engineering.

  • AAPred: capability-based estimator validation, so a model is rejected at construction rather than mid-run.

  • TreeModel: per-round seeding fix, so a fixed random_state reproduces exactly.

  • Consistent plot sizing: auto_font applies across the CPP plots, constant-cell sizing now shrinks as well as grows, and every public plot method returns a single, uniform object.

  • CPP performance: a Cython feature-matrix kernel, macOS-safe threaded n_jobs, and a unified parallelism convention across CPP and CPPGrid. Many internal hotspots were vectorized with unchanged output.

  • Feature-matrix and part building: feature_matrix() gains batch, df_seq and list_parts; get_df_parts and get_parts() gain a position-anchor mode (tmd_len).

  • feature(): titles the plot with the feature’s human-readable description.

  • load_dataset(): new verbose parameter (default False).

  • fit(): flexible label handling via label_pos / label_unl.

  • Docstring discoverability: previously implicit API contracts are stated in the docstrings, so the expected inputs, outputs and defaults are readable from the reference itself.

  • Web fetches: fetch_alphafold and fetch_uniprot are pooled and optionally concurrent.

  • Library output: all messages flow through a named logger, so they can be captured or silenced.

  • Release engineering: a packaging workflow builds and checks the distributions, a committed benchmark suite guards the hot paths, and aaanalysis.__version__ on master no longer collides with the released version.

Fixed

  • BH-adjusted p-values: p_val_fdr_bh in df_feat now follows the canonical Benjamini-Hochberg procedure.

  • run() with n_jobs > 1 no longer crashes in non-interactive contexts, and CPP splits no longer fail on free peptides or very short parts.

  • Source install: the published sdist omitted the Cython sources and could not build; it now does.

  • Plot layout: composite-plot furniture no longer lands on the heatmap, dense grids keep a consistent layout at any figure size, and the sequence bar in CPP-SHAP plots renders correctly with seq_char_fill=True.

  • Golden pipelines: an invalid call names the offending argument instead of failing obscurely.

Deprecated

  • AAlogo / AAlogoPlot are deprecated in favour of AALogo / AALogoPlot. The strict-semver deprecation policy and the deprecated decorator are now in force.

Documentation

  • The rendered docs state which version they document, derived from aaanalysis.__version__.

  • New Prediction tasks concept page maps a biological question to the right workflow, and a new A minimal CPP analysis tutorial gives the shortest end-to-end loop.

  • Navigation: the sidebar is grouped into Overview, Guides, Reference and Project, the landing page gains a routing table, and the API reference is split into building blocks and golden pipelines.

  • Guides: a new Use Cases subchapter walks a published study end to end, every tool tutorial opens with a uniform You will learn box, and the tutorials landing page opens with a gallery of headline figures.

Version 1.0 (Stable Version)

v1.0.3 (2026-04-28)

Added

  • AALogo: New class for amino acid logo visualization.

  • AALogoPlot: New plotting class for AALogo visualizations.

Changed

  • Python Support: Dropped Python 3.9 (end-of-life) and added Python 3.13 and 3.14 support. Supported versions are now 3.10, 3.11, 3.12, 3.13, and 3.14.

  • Dependency Management: Migrated from requirements.txt files to a single pyproject.toml as the source of truth for all dependencies. Introduced structured dependency extras: aaanalysis[pro], aaanalysis[docs], and aaanalysis[dev].

  • Package Manager: Added full uv support alongside existing pip and Poetry compatibility.

  • CI/CD: Updated all GitHub Actions workflows to reflect new Python version matrix and consolidated dependency installation via extras.

Other

  • Documentation: Updated ReadTheDocs configuration to install dependencies directly from pyproject.toml via aaanalysis[docs] extra.

  • Cleanup: Removed legacy requirements.txt, docs/requirements_dev.txt, and docs/requirements_wo_pro.txt files.

v1.0.2 (2025-06-17)

Improved

  • Faster CPP Pipeline: Major performance boost in CPP.run() through optimized generation and filtering of part-split-scale combinations. Depending on the number of scales, runtime is now 3–5× faster on standard hardware.

  • Feature Map Enhancement: CPP.feature_map() now includes a top bar plot showing cumulative feature importance per residue, improving interpretability. This visualization is also included in the CPP profile output.

Fixed

  • fetch_alphafold(): Resolve download URLs through the AlphaFold API instead of a hardcoded file version. AlphaFold DB renamed its files v4 → v6, which had silently broken every fetch (all entries returned alphafold_ok=False); the fetch now tracks the current version automatically. Added a network-marked live test (tests/integration/) so an upstream API/version change is caught instead of slipping past the mocked unit tests.

  • General Bug Fixes: Minor fixes related to dependency resolution and edge-case behavior.

  • Documentation: Removed inconsistencies in documentation for selected functions and plotting options.

Other

  • Branding: Introduced updated logo and favicon (legacy version preserved under docs/source/_artwork/logos/legacy/).

  • Landing Page Visual: Added a main conceptual sketch to the documentation landing page illustrating the core CPP idea — comparing two sequence sets to derive their critical difference, the physicochemical signature.

v1.0.1 (2025-01-29)

Improved

  • Pro Feature Accessibility: Improved integration of aaanalysis[pro] features in IDEs. Clicking on a pro feature now directs users to its exact class implementation instead of the main __init__.py file.

  • Import Error Handling: Improved error handling for missing dependencies in the aaanalysis[pro] version. If dependencies are installed but errors occur during import, users now receive the original import error messages.

Fixed

  • Feature Map Plot: Resolved a potential mismatch in subcategory ordering between heatmap and bar plot in aa.cpp_plot().featuremap(). Previously, subcategories with nearly identical names (e.g., “α-helix (C-term)” and “α-helix (C-term, out)”) could appear in an inconsistent order.

  • General Bug Fixes: Minor bug fixes to improve overall stability and functionality.

Other

  • Dependencies: All dependencies have been updated to ensure compatibility with the latest versions, including full support for numpy>=2.0.0.

v1.0.0 (2024-07-01)

Added

  • SequencePreprocessor: A utility data preprocessing class (data handling module).

  • comp_seq_sim(): A function for computing pairwise sequence similarity (data handling module).

  • filter_seq(): A function for redundancy-reduction of sequences (data handling module).

  • options: Juxta Middle Domain (JMD) length can now be globally adjusted using the jmd_n/c_len options.

Changed

  • ShapModel: The ShapExplainer class has been renamed to ShapModel for consistency with the TreeModel class and to avoid confusion with the ShapExplainer models from the SHAP package.

  • Dependencies: Biopython is now a required dependency only for the aaanalysis[pro] version.

  • Module Renaming: The Perturbation module has been renamed to Protein Design module to better reflect its broad functionality.

Fixed

  • Multiprocessing: Now supported directly at the script level, outside of any functions or classes, in the top-level of the script (global namespace).

Version 0.1 (Beta Version)

v0.1.5 (2024-04-18)

Added

  • Code of Conduct: Introduced a Code of Conduct to foster a welcoming and inclusive community environment. We encourage all contributors to review the Code of Conduct to understand the expectations and responsibilities when participating in the project.

Changed

  • License Update: Transitioned the project license from MIT to BSD-3-Clause to better align with our project’s community engagement and protection goals. This change affects how the software can be used and redistributed.

Fixed

  • Multiprocessing: Replaced native multiprocessing with the joblib module for CPP and internal feature matrix creation. This change prevents a RuntimeError that occurred when the main function is not explicitly used.

Other

  • Dependencies: Update the seaborn dependency to version 0.13.2 or higher to resolve the legend argument error present in versions earlier than 0.13

v0.1.4 (2024-04-09)

Added

  • Installation Options: Introduced separate installation profiles for the core and professional versions. The core version has reduced dependencies to enhance installation robustness, installable using pip install aaanalysis. The professional version, designed for advanced usage, includes packages required for our explainable AI module such as SHAP, installable using pip install aaanalysis[pro].

Changed

  • API Improvements: General improvement of API for consistency and higher user-friendliness.

Fixed

  • General Issues: Fix of different check function related API issues.

Other

  • Python Dependency: Updated the Python version compatibility from <= 3.10 to <= 3.12.

v0.1.3 (2024-02-09)

Added

  • TreeModel: Wrapper class of tree-based models for Monte Carlo estimates of predictions and feature importance. See TreeModel.

  • ShapExplainer: A wrapper for SHAP (SHapley Additive exPlanations) explainers to obtain Monte Carlo estimates for feature impact. See ShapExplainer.

  • NumericalFeature: Utility feature engineering class to process and filter numerical data structures. See NumericalFeature.

  • Load_feature: Utility function to load feature sets for protein benchmarking datasets. See load_features.

Changed

  • API Improvements: General improvement of API for consistency and higher user-friendliness.

Fixed

  • Interface: Change of internal documentation decorator to hard-coded documentation for better IDE responsiveness.

  • General Issues: Fix of different check function related API issues.

v0.1.2 (2023-11-06)

Added

Changed

  • API Improvements: General improvement of API.

Fixed

  • API Improvements: General improvement of API (Application Programming Interface).

Other

  • Python Dependency: Supports Python versions 3.9 and 3.10.

v0.1.1 (2023-09-11)

Test release of the first beta version.

v0.1.0 (2023-09-11)

First release of the beta version including CPP, dPULearn, and AAclust algorithms as well as the SequenceFeature utility class and data loading functions load_dataset and load_scales.