Bits & Flames
bitsandflames/fyron

ML, Validation, And Explainability Reference

Classification pipelines, metrics, plotting wrappers, feature selection, validation, model interpretation, and filter-flow explainability.

For workflow context, see ML, Validation, And Explainability module guide.

Functions And Classes

fyron.explainability.inspection.explain_model_summary

Create a reviewer-facing model explanation summary table.

Import path: fyron.explainability.inspection.explain_model_summary

python
explain_model_summary(*, importance: pd.DataFrame | None = None, shap_summary: pd.DataFrame | None = None, metrics: Mapping[str, Any] | pd.DataFrame | None = None, feature_qc: pd.DataFrame | None = None, notes: Mapping[str, str] | pd.DataFrame | None = None, feature_col: str = 'feature') -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
importancenopd.DataFrame or NoneNoneFeature importance table, for example from `permutation_importance_table`.
shap_summarynopd.DataFrame or NoneNoneFeature-level SHAP summary table, for example from `shap_summary_table`.
metricsnoMapping[str, Any] or pd.DataFrame or NoneNoneOptional model metrics as a dictionary or one-row DataFrame. Metrics are repeated on each feature row for convenient review/export.
feature_qcnopd.DataFrame or NoneNoneOptional feature quality-control table, for example from `fyron.preprocessing.feature_matrix_report`.
notesnoMapping[str, str] or pd.DataFrame or NoneNoneOptional mapping or DataFrame with feature-specific reviewer notes.
feature_colnostr'feature'Column name containing feature names in feature-level inputs.

Returns

pandas.DataFrame - One row per feature with available importance, SHAP, QC, metric, and note columns merged by feature name.

See also: ML, Validation, And Explainability module guide.

fyron.explainability.inspection.explain_patient_prediction

Return the strongest positive and negative drivers for one prediction.

Import path: fyron.explainability.inspection.explain_patient_prediction

python
explain_patient_prediction(contributions: pd.DataFrame, *, row_index: Any | None = None, patient_id: Any | None = None, row_col: str = 'row_index', patient_col: str = 'patient_id', feature_col: str = 'feature', contribution_col: str = 'shap_value', feature_value_col: str = 'feature_value', top_n: int = 5) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
contributionsyespd.DataFrameLong contribution table with feature names and signed contributions, such as output from `shap_values_table`.
row_indexnoAny or NoneNoneOptional row identifier to select when `row_col` exists.
patient_idnoAny or NoneNoneOptional patient identifier to select when `patient_col` exists.
row_colnostr'row_index'See signature.
patient_colnostr'patient_id'See signature.
feature_colnostr'feature'See signature.
contribution_colnostr'shap_value'See signature.
feature_value_colnostr'feature_value'Column names used to identify rows, features, contributions, and values.
top_nnoint5Number of positive and negative drivers to return.

Returns

pandas.DataFrame - Feature-level contribution rows sorted by direction and absolute impact.

See also: ML, Validation, And Explainability module guide.

fyron.explainability.inspection.partial_dependence_table

Return one-way partial dependence values in long tabular form.

Import path: fyron.explainability.inspection.partial_dependence_table

python
partial_dependence_table(estimator: Any, X: Any, *, features: Sequence[int | str], feature_names: Sequence[str] | None = None, grid_resolution: int = 50) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
XyesAnySee signature.
featuresyesSequence[int or str]See signature.
feature_namesnoSequence[str] or NoneNoneSee signature.
grid_resolutionnoint50See signature.

Returns

pd.DataFrame

See also: ML, Validation, And Explainability module guide.

fyron.explainability.inspection.permutation_importance_table

Return sklearn permutation importance as a sorted DataFrame.

Import path: fyron.explainability.inspection.permutation_importance_table

python
permutation_importance_table(estimator: Any, X: Any, y: Any, *, feature_names: Sequence[str] | None = None, n_repeats: int = 10, scoring: str | None = None, random_state: int = 42) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
XyesAnySee signature.
yyesAnySee signature.
feature_namesnoSequence[str] or NoneNoneSee signature.
n_repeatsnoint10See signature.
scoringnostr or NoneNoneSee signature.
random_statenoint42See signature.

Returns

pd.DataFrame

See also: ML, Validation, And Explainability module guide.

fyron.explainability.inspection.shap_summary_table

Return mean absolute SHAP importance by feature.

Import path: fyron.explainability.inspection.shap_summary_table

python
shap_summary_table(estimator: Any, X: Any, *, feature_names: Sequence[str] | None = None, explainer: Any | None = None, background_data: Any | None = None, max_rows: int | None = None) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
XyesAnySee signature.
feature_namesnoSequence[str] or NoneNoneSee signature.
explainernoAny or NoneNoneSee signature.
background_datanoAny or NoneNoneSee signature.
max_rowsnoint or NoneNoneSee signature.

Returns

pd.DataFrame

See also: ML, Validation, And Explainability module guide.

fyron.explainability.inspection.shap_values_table

Return SHAP values in long patient-feature form.

Import path: fyron.explainability.inspection.shap_values_table

python
shap_values_table(estimator: Any, X: Any, *, feature_names: Sequence[str] | None = None, explainer: Any | None = None, background_data: Any | None = None, max_rows: int | None = None) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
XyesAnySee signature.
feature_namesnoSequence[str] or NoneNoneSee signature.
explainernoAny or NoneNoneSee signature.
background_datanoAny or NoneNoneSee signature.
max_rowsnoint or NoneNoneSee signature.

Returns

pd.DataFrame

See also: ML, Validation, And Explainability module guide.

fyron.feature_selection.selection.boruta_feature_selection

Run Boruta through the scientific feature-selection namespace.

Import path: fyron.feature_selection.selection.boruta_feature_selection

python
boruta_feature_selection(X: Any, y: Any, **kwargs: Any) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
XyesAnySee signature.
yyesAnySee signature.
kwargsyesAnySee signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.feature_selection.selection.combine_feature_selection_results

Combine several feature-selection result dictionaries.

Import path: fyron.feature_selection.selection.combine_feature_selection_results

python
combine_feature_selection_results(results: Mapping[str, Mapping[str, Any]] | Sequence[Mapping[str, Any]], *, strategy: Literal['consensus', 'union', 'intersection'] = 'consensus', min_methods: int = 2) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
resultsyesMapping[str, Mapping[str, Any]] or Sequence[Mapping[str, Any]]See signature.
strategynoLiteral['consensus', 'union', 'intersection']'consensus'See signature.
min_methodsnoint2See signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.feature_selection.selection.correlation_filter

Find redundant numeric features and drop later correlated features.

Import path: fyron.feature_selection.selection.correlation_filter

python
correlation_filter(X: Any, *, threshold: float = 0.85, method: Literal['pearson', 'spearman', 'kendall'] = 'spearman') -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
XyesAnySee signature.
thresholdnofloat0.85See signature.
methodnoLiteral['pearson', 'spearman', 'kendall']'spearman'See signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.feature_selection.selection.model_importance_selection

Fit an estimator and select features by importance or coefficient magnitude.

Import path: fyron.feature_selection.selection.model_importance_selection

python
model_importance_selection(estimator: Any, X: Any, y: Any, *, threshold: float | None = None, top_n: int | None = None) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
XyesAnySee signature.
yyesAnySee signature.
thresholdnofloat or NoneNoneSee signature.
top_nnoint or NoneNoneSee signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.feature_selection.selection.permutation_importance_selection

Select features using sklearn permutation importance.

Import path: fyron.feature_selection.selection.permutation_importance_selection

python
permutation_importance_selection(estimator: Any, X: Any, y: Any, *, n_repeats: int = 10, scoring: str | None = None, random_state: int = 42, threshold: float | None = None, top_n: int | None = None) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
XyesAnySee signature.
yyesAnySee signature.
n_repeatsnoint10See signature.
scoringnostr or NoneNoneSee signature.
random_statenoint42See signature.
thresholdnofloat or NoneNoneSee signature.
top_nnoint or NoneNoneSee signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.feature_selection.selection.stability_selection

Repeated subsampling feature selection by model importance.

Import path: fyron.feature_selection.selection.stability_selection

python
stability_selection(estimator: Any, X: Any, y: Any, *, n_rounds: int = 100, sample_fraction: float = 0.75, selection_threshold: float = 0.6, random_state: int = 42) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
XyesAnySee signature.
yyesAnySee signature.
n_roundsnoint100See signature.
sample_fractionnofloat0.75See signature.
selection_thresholdnofloat0.6See signature.
random_statenoint42See signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.feature_selection.selection.univariate_feature_screening

Screen features with transparent univariate tests and FDR correction.

Import path: fyron.feature_selection.selection.univariate_feature_screening

python
univariate_feature_screening(X: Any, y: Any, *, task: Task = 'classification', alpha: float = 0.05, correction: Literal['fdr_bh', 'none'] = 'fdr_bh') -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
XyesAnySee signature.
yyesAnySee signature.
tasknoTask'classification'See signature.
alphanofloat0.05See signature.
correctionnoLiteral['fdr_bh', 'none']'fdr_bh'See signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.feature_selection.selection.variance_filter

Filter constant or near-constant numeric features.

Import path: fyron.feature_selection.selection.variance_filter

python
variance_filter(X: Any, *, threshold: float = 0.0) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
XyesAnySee signature.
thresholdnofloat0.0See signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.flow.tracking.FlowStep

One recorded cohort/filter-flow step.

Import path: fyron.flow.tracking.FlowStep

python
FlowStep()

Parameters

No parameters documented.

Returns

Class constructor.

See also: ML, Validation, And Explainability module guide.

fyron.flow.tracking.FlowTracker

Record ordered cohort filter steps and render flow summaries.

Import path: fyron.flow.tracking.FlowTracker

python
FlowTracker(self, title: str = 'Cohort flow')

Parameters

ParameterRequiredTypeDefaultDescription
titlenostr'Cohort flow'Human-readable name for the cohort or workflow.

Returns

Class constructor.

See also: ML, Validation, And Explainability module guide.

Public Methods

fyron.flow.tracking.FlowTracker.add_step

Record a DataFrame step and return `df` unchanged.

Import path: fyron.flow.tracking.FlowTracker.add_step

python
FlowTracker.add_step(self, label: str, df: pd.DataFrame, *, reason: str | None = None, metadata: Mapping[str, Any] | None = None) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
labelyesstrShort reviewer-facing step label.
dfyespd.DataFrameDataFrame after the filter or workflow step.
reasonnostr or NoneNoneOptional exclusion reason, usually describing why rows were removed from the previous step.
metadatanoMapping[str, Any] or NoneNoneOptional JSON-like metadata such as filter parameters or notes.

Returns

pandas.DataFrame - The same DataFrame object passed to `df` for pipeline-friendly use.

See also: ML, Validation, And Explainability module guide.

fyron.flow.tracking.FlowTracker.to_dataframe

Return the recorded flow as a structured DataFrame.

Import path: fyron.flow.tracking.FlowTracker.to_dataframe

python
FlowTracker.to_dataframe(self) -> pd.DataFrame

Parameters

No parameters documented.

Returns

pd.DataFrame

See also: ML, Validation, And Explainability module guide.

fyron.flow.tracking.FlowTracker.to_markdown

Render the flow as a Markdown table.

Import path: fyron.flow.tracking.FlowTracker.to_markdown

python
FlowTracker.to_markdown(self, *, digits: int = 1) -> str

Parameters

ParameterRequiredTypeDefaultDescription
digitsnoint1See signature.

Returns

str

See also: ML, Validation, And Explainability module guide.

fyron.flow.tracking.FlowTracker.to_text_flowchart

Render an arrow-style text flow chart.

Import path: fyron.flow.tracking.FlowTracker.to_text_flowchart

python
FlowTracker.to_text_flowchart(self, *, digits: int = 1) -> str

Parameters

ParameterRequiredTypeDefaultDescription
digitsnoint1See signature.

Returns

str

See also: ML, Validation, And Explainability module guide.

fyron.flow.tracking.FlowTracker.print

Print and return a Bits & Flames-style console flow summary.

Import path: fyron.flow.tracking.FlowTracker.print

python
FlowTracker.print(self, *, stream: TextIO | None = None, color: bool = True, quiet: bool = False) -> str

Parameters

ParameterRequiredTypeDefaultDescription
streamnoTextIO or NoneNoneSee signature.
colornoboolTrueSee signature.
quietnoboolFalseSee signature.

Returns

str

See also: ML, Validation, And Explainability module guide.

fyron.flow.tracking.track_filter

Decorate a DataFrame filter function and record its output.

Import path: fyron.flow.tracking.track_filter

python
track_filter(tracker: FlowTracker, *, label: str, reason: str | None = None, metadata: Mapping[str, Any] | None = None) -> Callable[[F], F]

Parameters

ParameterRequiredTypeDefaultDescription
trackeryesFlowTrackerFlowTracker instance that receives the recorded step.
labelyesstrReviewer-facing label for the filter.
reasonnostr or NoneNoneOptional exclusion reason.
metadatanoMapping[str, Any] or NoneNoneOptional JSON-like metadata saved with the step.

Returns

callable - Wrapped function that returns the original DataFrame result after recording it in `tracker`.

See also: ML, Validation, And Explainability module guide.

fyron.ml.boruta_selection.run_boruta_feature_selection

Run Boruta all-relevant feature selection.

Import path: fyron.ml.boruta_selection.run_boruta_feature_selection

python
run_boruta_feature_selection(X: ArrayLikeInput, y: ArrayLikeInput, estimator: Any | None = None, *, class_weight: str | dict[Any, float] | None = 'balanced', max_iter: int = 100, random_state: int = 42) -> BorutaResult

Parameters

ParameterRequiredTypeDefaultDescription
XyesArrayLikeInputSee signature.
yyesArrayLikeInputSee signature.
estimatornoAny or NoneNoneSee signature.
class_weightnostr or dict[Any, float] or None'balanced'See signature.
max_iternoint100See signature.
random_statenoint42See signature.

Returns

BorutaResult

See also: ML, Validation, And Explainability module guide.

fyron.ml.class_weights.compute_class_weights

Compute class weights as a label-to-weight mapping.

Import path: fyron.ml.class_weights.compute_class_weights

python
compute_class_weights(y: ArrayLikeInput, *, class_weight: str = 'balanced') -> dict[Any, float]

Parameters

ParameterRequiredTypeDefaultDescription
yyesArrayLikeInputTarget vector.
class_weightnostr'balanced'Strategy passed to :func:sklearn.utils.class_weight.compute_class_weight.

Returns

dict - Mapping from class label to weight. Pass directly to :class:sklearn.ensemble.RandomForestClassifier(class_weight=...).

See also: ML, Validation, And Explainability module guide.

fyron.ml.class_weights.compute_scale_pos_weight

Compute XGBoost `scale_pos_weight` for binary classification.

Import path: fyron.ml.class_weights.compute_scale_pos_weight

python
compute_scale_pos_weight(y: ArrayLikeInput, *, pos_label: Any | None = None) -> float

Parameters

ParameterRequiredTypeDefaultDescription
yyesArrayLikeInputBinary target vector.
pos_labelnoAny or NoneNonePositive class label. Defaults to the larger of the two unique labels.

Returns

float - Value suitable for :class:xgboost.XGBClassifier(scale_pos_weight=...).

See also: ML, Validation, And Explainability module guide.

fyron.ml.class_weights.sample_weights_for_sklearn

Per-sample weights for sklearn estimators that accept `sample_weight`.

Import path: fyron.ml.class_weights.sample_weights_for_sklearn

python
sample_weights_for_sklearn(y: ArrayLikeInput, *, class_weight: str | dict[Any, float] = 'balanced') -> np.ndarray

Parameters

ParameterRequiredTypeDefaultDescription
yyesArrayLikeInputSee signature.
class_weightnostr or dict[Any, float]'balanced'See signature.

Returns

np.ndarray

See also: ML, Validation, And Explainability module guide.

fyron.ml.cv.cross_validate_model

Stratified k-fold cross-validation with healthcare-oriented metrics.

Import path: fyron.ml.cv.cross_validate_model

python
cross_validate_model(estimator: Any, X: ArrayLikeInput, y: ArrayLikeInput, *, cv: int = 5, random_state: int = 42, return_models: bool = False, return_oof_predictions: bool = False, pos_label: Any | None = None) -> CVResult

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnyAny sklearn-compatible classifier (must support `fit / predict`).
XyesArrayLikeInputSee signature.
yyesArrayLikeInputFull dataset.
cvnoint5Number of folds.
random_statenoint42See signature.
return_modelsnoboolFalseIf True, include a list of fitted models (one per fold).
return_oof_predictionsnoboolFalseIf True, include out-of-fold predictions and positive-class probabilities.
pos_labelnoAny or NoneNoneSee signature.

Returns

dict - Keys: `fold_metrics (DataFrame), mean_metrics, std_metrics, and optionally models, oof_pred, oof_prob`.

See also: ML, Validation, And Explainability module guide.

fyron.ml.defaults.get_default_param_grid

Return a sensible default parameter grid for grid search.

Import path: fyron.ml.defaults.get_default_param_grid

python
get_default_param_grid(model_name: str) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
model_nameyesstr`"random_forest", "xgboost", or "survival_gradient_boosting"`.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.ml.evaluation.apply_probability_calibrator

Return calibrated positive-class probabilities.

Import path: fyron.ml.evaluation.apply_probability_calibrator

python
apply_probability_calibrator(calibrator: Any, X: ArrayLikeInput, *, positive_class_index: int = 1) -> np.ndarray

Parameters

ParameterRequiredTypeDefaultDescription
calibratoryesAnySee signature.
XyesArrayLikeInputSee signature.
positive_class_indexnoint1See signature.

Returns

np.ndarray

See also: ML, Validation, And Explainability module guide.

fyron.ml.evaluation.evaluate_external_validation

Evaluate a fitted sklearn-style estimator on an external cohort.

Import path: fyron.ml.evaluation.evaluate_external_validation

python
evaluate_external_validation(estimator: Any, X_external: ArrayLikeInput, y_external: ArrayLikeInput, *, threshold: float | None = None, pos_label: Any | None = None) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
X_externalyesArrayLikeInputSee signature.
y_externalyesArrayLikeInputSee signature.
thresholdnofloat or NoneNoneSee signature.
pos_labelnoAny or NoneNoneSee signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.ml.evaluation.evaluate_locked_threshold

Evaluate probabilities with a pre-specified decision threshold.

Import path: fyron.ml.evaluation.evaluate_locked_threshold

python
evaluate_locked_threshold(y_true: ArrayLikeInput, y_prob: ArrayLikeInput, *, threshold: float, pos_label: Any = 1, neg_label: Any = 0) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesArrayLikeInputSee signature.
y_probyesArrayLikeInputSee signature.
thresholdyesfloatSee signature.
pos_labelnoAny1See signature.
neg_labelnoAny0See signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.ml.evaluation.fit_probability_calibrator

Fit a probability calibrator for an already fitted classifier.

Import path: fyron.ml.evaluation.fit_probability_calibrator

python
fit_probability_calibrator(estimator: Any, X_calibration: ArrayLikeInput, y_calibration: ArrayLikeInput, *, method: str = 'sigmoid') -> CalibratedClassifierCV

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
X_calibrationyesArrayLikeInputSee signature.
y_calibrationyesArrayLikeInputSee signature.
methodnostr'sigmoid'See signature.

Returns

CalibratedClassifierCV

See also: ML, Validation, And Explainability module guide.

fyron.ml.evaluation.model_card_summary

Create a small inspectable model-card summary dictionary.

Import path: fyron.ml.evaluation.model_card_summary

python
model_card_summary(estimator: Any, *, X: ArrayLikeInput | None = None, y: ArrayLikeInput | None = None, metrics: Mapping[str, Any] | None = None, intended_use: str | None = None, limitations: str | None = None, random_state: int | None = None) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
XnoArrayLikeInput or NoneNoneSee signature.
ynoArrayLikeInput or NoneNoneSee signature.
metricsnoMapping[str, Any] or NoneNoneSee signature.
intended_usenostr or NoneNoneSee signature.
limitationsnostr or NoneNoneSee signature.
random_statenoint or NoneNoneSee signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.ml.evaluation.nested_cross_validate_model

Run nested stratified CV with an inner grid search.

Import path: fyron.ml.evaluation.nested_cross_validate_model

python
nested_cross_validate_model(estimator: Any, param_grid: Mapping[str, Sequence[Any]], X: ArrayLikeInput, y: ArrayLikeInput, *, outer_cv: int = 5, inner_cv: int = 3, scoring: str = 'roc_auc', random_state: int = 42, n_jobs: int = -1, pos_label: Any | None = None) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
param_gridyesMapping[str, Sequence[Any]]See signature.
XyesArrayLikeInputSee signature.
yyesArrayLikeInputSee signature.
outer_cvnoint5See signature.
inner_cvnoint3See signature.
scoringnostr'roc_auc'See signature.
random_statenoint42See signature.
n_jobsnoint-1See signature.
pos_labelnoAny or NoneNoneSee signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.ml.importance.get_feature_importance

Extract sorted feature importances from a tree-based model.

Import path: fyron.ml.importance.get_feature_importance

python
get_feature_importance(model: Any, feature_names: list[str] | None = None) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
modelyesAnySee signature.
feature_namesnolist[str] or NoneNoneSee signature.

Returns

pd.DataFrame

See also: ML, Validation, And Explainability module guide.

fyron.ml.importance.plot_feature_importance

Plot feature importances for a fitted model.

Import path: fyron.ml.importance.plot_feature_importance

python
plot_feature_importance(model: Any, feature_names: list[str] | None = None, *, top_n: int = 20, title: str = 'Feature importance', save_path: str | None = None, fmt: str = 'png') -> tuple[Any, Any]

Parameters

ParameterRequiredTypeDefaultDescription
modelyesAnySee signature.
feature_namesnolist[str] or NoneNoneSee signature.
top_nnoint20See signature.
titlenostr'Feature importance'See signature.
save_pathnostr or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

tuple[Any, Any]

See also: ML, Validation, And Explainability module guide.

fyron.ml.metrics.calculate_classification_metrics

Compute binary classification metrics and confusion-matrix counts.

Import path: fyron.ml.metrics.calculate_classification_metrics

python
calculate_classification_metrics(y_true: ArrayLikeInput, y_pred: ArrayLikeInput, y_prob: ArrayLike | None = None, *, pos_label: Any | None = None) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesArrayLikeInputGround-truth labels.
y_predyesArrayLikeInputPredicted labels.
y_probnoArrayLike or NoneNonePredicted probability of the positive class (binary only).
pos_labelnoAny or NoneNonePositive class label for binary metrics.

Returns

dict - Keys include `accuracy, f1, precision, recall, sensitivity, specificity, balanced_accuracy, auc, and tn, fp, fn, tp`.

See also: ML, Validation, And Explainability module guide.

fyron.ml.persistence.load_estimator

Load an estimator saved with :func:save_estimator.

Import path: fyron.ml.persistence.load_estimator

python
load_estimator(path: str | Path) -> Any

Parameters

ParameterRequiredTypeDefaultDescription
pathyesstr or PathSee signature.

Returns

Any

See also: ML, Validation, And Explainability module guide.

fyron.ml.persistence.save_estimator

Serialize a fitted estimator with joblib.

Import path: fyron.ml.persistence.save_estimator

python
save_estimator(model: Any, path: str | Path) -> None

Parameters

ParameterRequiredTypeDefaultDescription
modelyesAnySee signature.
pathyesstr or PathSee signature.

Returns

None

See also: ML, Validation, And Explainability module guide.

fyron.ml.pipeline.run_classification_pipeline

Convenience wrapper: split, optional Boruta, train, optional grid search.

Import path: fyron.ml.pipeline.run_classification_pipeline

python
run_classification_pipeline(X: Any, y: Any, *, model: Literal['random_forest', 'xgboost'] = 'random_forest', test_size: float = 0.2, stratify: bool = True, random_state: int = 42, handle_imbalance: bool = True, use_boruta: bool = False, boruta_kwargs: dict[str, Any] | None = None, use_grid_search: bool = False, param_grid: dict[str, Any] | None = None, plot: bool = False, **model_params: Any) -> PipelineResult

Parameters

ParameterRequiredTypeDefaultDescription
XyesAnySee signature.
yyesAnySee signature.
modelnoLiteral['random_forest', 'xgboost']'random_forest'See signature.
test_sizenofloat0.2See signature.
stratifynoboolTrueSee signature.
random_statenoint42See signature.
handle_imbalancenoboolTrueSee signature.
use_borutanoboolFalseSee signature.
boruta_kwargsnodict[str, Any] or NoneNoneSee signature.
use_grid_searchnoboolFalseSee signature.
param_gridnodict[str, Any] or NoneNoneSee signature.
plotnoboolFalseSee signature.
model_paramsyesAnySee signature.

Returns

PipelineResult

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.add_stat_annotations

Add bracket-style statistical annotations to an existing categorical plot.

Import path: fyron.ml.plots.add_stat_annotations

python
add_stat_annotations(ax: Axes, stats_table: pd.DataFrame, *, positions: Mapping[tuple[str, str], float] | None = None, heights: Mapping[tuple[str, str], float] | None = None, annotation_col: str = 'annotation', line_color: str = BOARISK_PALETTE['ink'], text_color: str = BOARISK_PALETTE['ink'], fontsize: float = 9, loc: Literal['outside', 'inside'] = 'outside') -> Axes

Parameters

ParameterRequiredTypeDefaultDescription
axyesAxesSee signature.
stats_tableyespd.DataFrameSee signature.
positionsnoMapping[tuple[str, str], float] or NoneNoneSee signature.
heightsnoMapping[tuple[str, str], float] or NoneNoneSee signature.
annotation_colnostr'annotation'See signature.
line_colornostrBOARISK_PALETTE['ink']See signature.
text_colornostrBOARISK_PALETTE['ink']See signature.
fontsizenofloat9See signature.
locnoLiteral['outside', 'inside']'outside'See signature.

Returns

Axes

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.format_p_value_annotation

Format a p-value for manuscript-style plot annotations.

Import path: fyron.ml.plots.format_p_value_annotation

python
format_p_value_annotation(p_value: Any, *, text_format: AnnotationFormat = 'star', thresholds: Sequence[tuple[float, str]] = ((0.001, '***'), (0.01, '**'), (0.05, '*')), ns_label: str = 'ns') -> str

Parameters

ParameterRequiredTypeDefaultDescription
p_valueyesAnyRaw or adjusted p-value.
text_formatnoAnnotationFormat'star'`"star" for significance stars, "pvalue" for explicit p-values, or "simple" for compact values such as p<0.001`.
thresholdsnoSequence[tuple[float, str]]((0.001, '***'), (0.01, '**'), (0.05, '*'))P-value thresholds used for star labels.
ns_labelnostr'ns'Label for non-significant comparisons in `"star"` mode.

Returns

str - Text label suitable for plot brackets.

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_alluvial_flow

Plot categorical flows across ordered stages.

Import path: fyron.ml.plots.plot_alluvial_flow

python
plot_alluvial_flow(data: Any, *, path_col: str = 'path', stage_col: str = 'stage', category_col: str = 'category', value_col: str | None = 'value', stage_order: Sequence[Any] | None = None, title: str = 'Alluvial flow', palette: str | Sequence[str] | None = 'bf_vibrant_muted', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
path_colnostr'path'See signature.
stage_colnostr'stage'See signature.
category_colnostr'category'See signature.
value_colnostr or None'value'See signature.
stage_ordernoSequence[Any] or NoneNoneSee signature.
titlenostr'Alluvial flow'See signature.
palettenostr or Sequence[str] or None'bf_vibrant_muted'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_binned_marker_heatmap

Plot a discrete patient-feature marker heatmap.

Import path: fyron.ml.plots.plot_binned_marker_heatmap

python
plot_binned_marker_heatmap(data: Any, *, row_col: str = 'feature', col_col: str = 'sample', value_col: str = 'bin', row_order: Sequence[Any] | None = None, col_order: Sequence[Any] | None = None, title: str = 'Binned marker heatmap', cmap: str = 'fyron_diverging_teal_orange', missing_color: str = '#F7F8FA', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
row_colnostr'feature'See signature.
col_colnostr'sample'See signature.
value_colnostr'bin'See signature.
row_ordernoSequence[Any] or NoneNoneSee signature.
col_ordernoSequence[Any] or NoneNoneSee signature.
titlenostr'Binned marker heatmap'See signature.
cmapnostr'fyron_diverging_teal_orange'See signature.
missing_colornostr'#F7F8FA'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_bland_altman

Plot agreement between two measurements.

Import path: fyron.ml.plots.plot_bland_altman

python
plot_bland_altman(method_a: ArrayLike, method_b: ArrayLike, *, title: str = 'Bland-Altman plot', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
method_ayesArrayLikeSee signature.
method_byesArrayLikeSee signature.
titlenostr'Bland-Altman plot'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_calibration_curve

Plot observed event frequency against predicted probability.

Import path: fyron.ml.plots.plot_calibration_curve

python
plot_calibration_curve(y_true: ArrayLikeInput, y_prob: ArrayLike, *, n_bins: int = 10, strategy: Literal['uniform', 'quantile'] = 'uniform', title: str = 'Calibration curve', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png', pos_label: Any | None = None) -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesArrayLikeInputSee signature.
y_probyesArrayLikeSee signature.
n_binsnoint10See signature.
strategynoLiteral['uniform', 'quantile']'uniform'See signature.
titlenostr'Calibration curve'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.
pos_labelnoAny or NoneNoneSee signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_cohort_flow

Plot cohort counts across inclusion/exclusion steps.

Import path: fyron.ml.plots.plot_cohort_flow

python
plot_cohort_flow(data: Any, *, step_col: str = 'step', n_col: str = 'n', title: str = 'Cohort flow', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
step_colnostr'step'See signature.
n_colnostr'n'See signature.
titlenostr'Cohort flow'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_confusion_matrix

Plot a confusion matrix heatmap.

Import path: fyron.ml.plots.plot_confusion_matrix

python
plot_confusion_matrix(y_true: ArrayLikeInput, y_pred: ArrayLikeInput, *, title: str = 'Confusion matrix', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png', pos_label: Any | None = None) -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesArrayLikeInputSee signature.
y_predyesArrayLikeInputSee signature.
titlenostr'Confusion matrix'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.
pos_labelnoAny or NoneNoneSee signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_correlation_heatmap

Plot a numeric correlation heatmap and return the correlation table.

Import path: fyron.ml.plots.plot_correlation_heatmap

python
plot_correlation_heatmap(data: Any, *, columns: Sequence[str] | None = None, method: Literal['pearson', 'spearman', 'kendall'] = 'spearman', group_col: str | None = None, title: str = 'Correlation heatmap', annotate: bool = True, annotate_significance: bool = False, p_adjust: str | None = 'fdr_bh', mask_upper: bool = False, cmap: str = 'fyron_diverging_blue_red', vmin: float = -1.0, vmax: float = 1.0, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> tuple[Figure, Axes, pd.DataFrame]

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
columnsnoSequence[str] or NoneNoneSee signature.
methodnoLiteral['pearson', 'spearman', 'kendall']'spearman'See signature.
group_colnostr or NoneNoneSee signature.
titlenostr'Correlation heatmap'See signature.
annotatenoboolTrueSee signature.
annotate_significancenoboolFalseSee signature.
p_adjustnostr or None'fdr_bh'See signature.
mask_uppernoboolFalseSee signature.
cmapnostr'fyron_diverging_blue_red'See signature.
vminnofloat-1.0See signature.
vmaxnofloat1.0See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

tuple[Figure, Axes, pd.DataFrame]

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_cross_validated_roc

Plot ROC curves from cross-validation fold predictions.

Import path: fyron.ml.plots.plot_cross_validated_roc

python
plot_cross_validated_roc(data: Any, *, y_true_col: str = 'y_true', y_prob_col: str = 'y_prob', fold_col: str = 'fold', mean_grid_points: int = 101, palette: str | Sequence[str] | None = 'okabe_ito', title: str | None = None, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> TablePlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnyDataFrame-like table with one row per out-of-fold prediction.
y_true_colnostr'y_true'See signature.
y_prob_colnostr'y_prob'See signature.
fold_colnostr'fold'Columns containing the binary label, predicted probability, and fold ID.
mean_grid_pointsnoint101Number of false-positive-rate grid points used for the mean ROC curve.
palettenostr or Sequence[str] or None'okabe_ito'Named Fyron palette or explicit color sequence for fold curves.
titlenostr or NoneNoneSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

tuple - `(fig, ax, table) where table` contains per-fold AUC values and mean/std summary rows.

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_decision_curve

Plot net benefit over decision thresholds.

Import path: fyron.ml.plots.plot_decision_curve

python
plot_decision_curve(data: Any, *, threshold_col: str = 'threshold', model_col: str = 'net_benefit_model', treat_all_col: str = 'net_benefit_treat_all', treat_none_col: str = 'net_benefit_treat_none', title: str = 'Decision curve', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
threshold_colnostr'threshold'See signature.
model_colnostr'net_benefit_model'See signature.
treat_all_colnostr'net_benefit_treat_all'See signature.
treat_none_colnostr'net_benefit_treat_none'See signature.
titlenostr'Decision curve'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_density

Plot one or more smoothed clinical density curves.

Import path: fyron.ml.plots.plot_density

python
plot_density(data: Any, *, x: str, hue: str | None = None, title: str = 'Density plot', xlabel: str | None = None, ylabel: str = 'Density', hue_order: Sequence[Any] | None = None, palette: Sequence[str] | None = None, fill: bool = True, alpha: float = 0.22, rug: bool = False, bandwidth: float | None = None, gridsize: int = 256, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnyTabular data coercible to a DataFrame.
xyesstrNumeric variable to plot.
huenostr or NoneNoneOptional grouping column for separate density curves.
titlenostr'Density plot'See signature.
xlabelnostr or NoneNoneSee signature.
ylabelnostr'Density'See signature.
hue_ordernoSequence[Any] or NoneNoneSee signature.
palettenoSequence[str] or NoneNoneSee signature.
fillnoboolTrueSee signature.
alphanofloat0.22See signature.
rugnoboolFalseSee signature.
bandwidthnofloat or NoneNoneOptional Gaussian kernel bandwidth. When omitted, Silverman's rule is used.
gridsizenoint256See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_dice_by_label

Plot Dice scores by segmentation label.

Import path: fyron.ml.plots.plot_dice_by_label

python
plot_dice_by_label(data: Any, *, label_col: str = 'label_name', dice_col: str = 'dice', title: str = 'Dice by label', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
label_colnostr'label_name'See signature.
dice_colnostr'dice'See signature.
titlenostr'Dice by label'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_directional_ratio_rows

Plot odds or hazard ratios with protective and hazardous direction bands.

Import path: fyron.ml.plots.plot_directional_ratio_rows

python
plot_directional_ratio_rows(data: Any, *, feature_col: str = 'feature', ratio_col: str = 'ratio', lower_col: str | None = 'ci_lower', upper_col: str | None = 'ci_upper', p_col: str | None = None, group_col: str | None = None, n_col: str | None = None, ratio_label: str = 'Hazard / odds ratio', title: str = 'Directional ratio rows', protective_label: str = 'Protective', hazardous_label: str = 'Hazardous', reference: float = 1.0, log_scale: bool = True, xlim: tuple[float, float] | None = None, annotate: bool = True, estimate_label: str | None = None, ci_label: str = '95% CI', p_label: str = 'p value', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
feature_colnostr'feature'See signature.
ratio_colnostr'ratio'See signature.
lower_colnostr or None'ci_lower'See signature.
upper_colnostr or None'ci_upper'See signature.
p_colnostr or NoneNoneSee signature.
group_colnostr or NoneNoneSee signature.
n_colnostr or NoneNoneSee signature.
ratio_labelnostr'Hazard / odds ratio'See signature.
titlenostr'Directional ratio rows'See signature.
protective_labelnostr'Protective'See signature.
hazardous_labelnostr'Hazardous'See signature.
referencenofloat1.0See signature.
log_scalenoboolTrueSee signature.
xlimnotuple[float, float] or NoneNoneSee signature.
annotatenoboolTrueSee signature.
estimate_labelnostr or NoneNoneSee signature.
ci_labelnostr'95% CI'See signature.
p_labelnostr'p value'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_external_validation_metrics

Plot external validation metrics from a dict or long table.

Import path: fyron.ml.plots.plot_external_validation_metrics

python
plot_external_validation_metrics(data: Any, *, metric_col: str = 'metric', value_col: str = 'value', title: str = 'External validation', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
metric_colnostr'metric'See signature.
value_colnostr'value'See signature.
titlenostr'External validation'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_feature_importance

Plot top-N features from a feature-importance DataFrame.

Import path: fyron.ml.plots.plot_feature_importance

python
plot_feature_importance(importance_df: Any, *, top_n: int = 20, title: str = 'Feature importance', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
importance_dfyesAnySee signature.
top_nnoint20See signature.
titlenostr'Feature importance'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_feature_selection_summary

Plot selected versus rejected features from a selection summary table.

Import path: fyron.ml.plots.plot_feature_selection_summary

python
plot_feature_selection_summary(data: Any, *, feature_col: str = 'feature', selected_col: str = 'selected', score_col: str | None = None, title: str = 'Feature selection summary', top_n: int = 25, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
feature_colnostr'feature'See signature.
selected_colnostr'selected'See signature.
score_colnostr or NoneNoneSee signature.
titlenostr'Feature selection summary'See signature.
top_nnoint25See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_forest_estimates

Plot estimates with confidence intervals in a compact forest layout.

Import path: fyron.ml.plots.plot_forest_estimates

python
plot_forest_estimates(data: Any, *, label_col: str = 'label', estimate_col: str = 'estimate', lower_col: str = 'ci_lower', upper_col: str = 'ci_upper', p_col: str | None = None, p_adjust_col: str | None = None, n_col: str | None = None, group_col: str | None = None, table_columns: bool = False, reference: float = 1.0, log_scale: bool = True, title: str = 'Forest plot', xlabel: str = 'Hazard ratio', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
label_colnostr'label'See signature.
estimate_colnostr'estimate'See signature.
lower_colnostr'ci_lower'See signature.
upper_colnostr'ci_upper'See signature.
p_colnostr or NoneNoneSee signature.
p_adjust_colnostr or NoneNoneSee signature.
n_colnostr or NoneNoneSee signature.
group_colnostr or NoneNoneSee signature.
table_columnsnoboolFalseSee signature.
referencenofloat1.0See signature.
log_scalenoboolTrueSee signature.
titlenostr'Forest plot'See signature.
xlabelnostr'Hazard ratio'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_grouped_bar_with_significance

Plot grouped bars with statistical significance brackets.

Import path: fyron.ml.plots.plot_grouped_bar_with_significance

python
plot_grouped_bar_with_significance(data: Any, *, x: str, y: str, hue: str | None = None, order: Sequence[Any] | None = None, hue_order: Sequence[Any] | None = None, estimator: Literal['mean', 'median'] = 'mean', error: Literal['sem', 'sd', 'ci', 'none'] = 'sem', ci: float = 0.95, test: Literal['auto', 'mannwhitney', 'ttest', 'kruskal'] = 'auto', comparisons: Sequence[tuple[Any, Any] | tuple[tuple[Any, Any], tuple[Any, Any]]] | None = None, p_thresholds: Sequence[tuple[float, str]] = ((0.001, '***'), (0.01, '**'), (0.05, '*')), title: str = 'Grouped outcome summary', ylabel: str | None = None, xlabel: str | None = None, palette: Sequence[str] | None = None, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> TablePlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
xyesstrSee signature.
yyesstrSee signature.
huenostr or NoneNoneSee signature.
ordernoSequence[Any] or NoneNoneSee signature.
hue_ordernoSequence[Any] or NoneNoneSee signature.
estimatornoLiteral['mean', 'median']'mean'See signature.
errornoLiteral['sem', 'sd', 'ci', 'none']'sem'See signature.
cinofloat0.95See signature.
testnoLiteral['auto', 'mannwhitney', 'ttest', 'kruskal']'auto'See signature.
comparisonsnoSequence[tuple[Any, Any] or tuple[tuple[Any, Any], tuple[Any, Any]]] or NoneNoneSee signature.
p_thresholdsnoSequence[tuple[float, str]]((0.001, '***'), (0.01, '**'), (0.05, '*'))See signature.
titlenostr'Grouped outcome summary'See signature.
ylabelnostr or NoneNoneSee signature.
xlabelnostr or NoneNoneSee signature.
palettenoSequence[str] or NoneNoneSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

TablePlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_grouped_boxplot

Plot a clinical grouped boxplot with optional hue and jittered patients.

Import path: fyron.ml.plots.plot_grouped_boxplot

python
plot_grouped_boxplot(data: Any, *, x: str, y: str, hue: str | None = None, title: str = 'Grouped boxplot', xlabel: str | None = None, ylabel: str | None = None, order: Sequence[Any] | None = None, hue_order: Sequence[Any] | None = None, palette: Sequence[str] | None = None, show_points: bool = True, point_alpha: float = 0.55, random_state: int = 42, comparisons: Sequence[tuple[Any, Any] | tuple[tuple[Any, Any], tuple[Any, Any]]] | None = None, stat_test: StatTestName = 'mannwhitney', p_adjust: str = 'none', annotation_format: AnnotationFormat = 'star', hide_ns: bool = False, return_stats: bool = False, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn | TablePlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnyTabular data coercible to a DataFrame.
xyesstrSee signature.
yyesstrCategorical grouping column and numeric value column.
huenostr or NoneNoneOptional second grouping column, for example sex, treatment, cohort, or event status.
titlenostr'Grouped boxplot'See signature.
xlabelnostr or NoneNoneSee signature.
ylabelnostr or NoneNoneSee signature.
ordernoSequence[Any] or NoneNoneSee signature.
hue_ordernoSequence[Any] or NoneNoneOptional display order for the x groups and hue groups.
palettenoSequence[str] or NoneNoneSee signature.
show_pointsnoboolTrueSee signature.
point_alphanofloat0.55See signature.
random_statenoint42See signature.
comparisonsnoSequence[tuple[Any, Any] or tuple[tuple[Any, Any], tuple[Any, Any]]] or NoneNoneSee signature.
stat_testnoStatTestName'mannwhitney'See signature.
p_adjustnostr'none'See signature.
annotation_formatnoAnnotationFormat'star'See signature.
hide_nsnoboolFalseSee signature.
return_statsnoboolFalseSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn | TablePlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_grouped_correlation_heatmaps

Plot one correlation heatmap per group and return a long correlation table.

Import path: fyron.ml.plots.plot_grouped_correlation_heatmaps

python
plot_grouped_correlation_heatmaps(data: Any, *, group_col: str, columns: Sequence[str] | None = None, method: Literal['pearson', 'spearman', 'kendall'] = 'spearman', title: str = 'Grouped correlation heatmaps', annotate: bool = True, annotate_significance: bool = False, p_adjust: str | None = 'fdr_bh', mask_upper: bool = False, cmap: str = 'fyron_diverging_blue_red', vmin: float = -1.0, vmax: float = 1.0, save_path: str | Path | None = None, fmt: str = 'png') -> tuple[Figure, np.ndarray, pd.DataFrame]

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
group_colyesstrSee signature.
columnsnoSequence[str] or NoneNoneSee signature.
methodnoLiteral['pearson', 'spearman', 'kendall']'spearman'See signature.
titlenostr'Grouped correlation heatmaps'See signature.
annotatenoboolTrueSee signature.
annotate_significancenoboolFalseSee signature.
p_adjustnostr or None'fdr_bh'See signature.
mask_uppernoboolFalseSee signature.
cmapnostr'fyron_diverging_blue_red'See signature.
vminnofloat-1.0See signature.
vmaxnofloat1.0See signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

tuple[Figure, np.ndarray, pd.DataFrame]

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_hazard_ratios

Plot Cox hazard ratios from a Fyron Cox result or lifelines fitter.

Import path: fyron.ml.plots.plot_hazard_ratios

python
plot_hazard_ratios(cox_result: Any, *, label_col: str = 'label', title: str = 'Hazard ratios', xlabel: str = 'Hazard ratio', table_columns: bool = True, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
cox_resultyesAnySee signature.
label_colnostr'label'See signature.
titlenostr'Hazard ratios'See signature.
xlabelnostr'Hazard ratio'See signature.
table_columnsnoboolTrueSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_histogram

Plot manuscript-friendly histograms with optional hue/group strata.

Import path: fyron.ml.plots.plot_histogram

python
plot_histogram(data: Any, *, x: str, hue: str | None = None, group: str | None = None, bins: int | str | Sequence[float] = 'auto', stat: Literal['count', 'density', 'percent'] = 'count', multiple: Literal['layer', 'stack', 'dodge'] = 'layer', title: str = 'Histogram', xlabel: str | None = None, ylabel: str | None = None, hue_order: Sequence[Any] | None = None, palette: Sequence[str] | None = None, alpha: float = 0.55, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
xyesstrSee signature.
huenostr or NoneNoneSee signature.
groupnostr or NoneNoneSee signature.
binsnoint or str or Sequence[float]'auto'See signature.
statnoLiteral['count', 'density', 'percent']'count'See signature.
multiplenoLiteral['layer', 'stack', 'dodge']'layer'See signature.
titlenostr'Histogram'See signature.
xlabelnostr or NoneNoneSee signature.
ylabelnostr or NoneNoneSee signature.
hue_ordernoSequence[Any] or NoneNoneSee signature.
palettenoSequence[str] or NoneNoneSee signature.
alphanofloat0.55See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_kaplan_meier

Clinical plotting alias for Kaplan-Meier curves.

Import path: fyron.ml.plots.plot_kaplan_meier

python
plot_kaplan_meier(*args: Any, **kwargs: Any)

Parameters

ParameterRequiredTypeDefaultDescription
argsyesAnySee signature.
kwargsyesAnySee signature.

Returns

See the function signature and module guide.

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_likert_scale

Plot a diverging Likert scale summary.

Import path: fyron.ml.plots.plot_likert_scale

python
plot_likert_scale(data: Any, *, item_col: str = 'item', response_col: str = 'response', count_col: str | None = None, order: Sequence[Any] | None = None, response_order: Sequence[Any] | None = None, neutral_values: Sequence[Any] | None = None, normalize: bool = True, palette: str | Sequence[str] | None = 'okabe_ito', title: str | None = None, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> TablePlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnyLong table with one row per response or one row per response count.
item_colnostr'item'See signature.
response_colnostr'response'Columns containing survey item names and ordered Likert responses.
count_colnostr or NoneNoneOptional count column. If omitted, rows are counted.
ordernoSequence[Any] or NoneNoneSee signature.
response_ordernoSequence[Any] or NoneNoneExplicit item and response order for stable manuscript figures.
neutral_valuesnoSequence[Any] or NoneNoneResponses that should be centered around zero. If omitted and the response order has odd length, the middle response is treated as neutral.
normalizenoboolTrueIf True, show percentages per item. If False, show counts.
palettenostr or Sequence[str] or None'okabe_ito'See signature.
titlenostr or NoneNoneSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

tuple - `(fig, ax, table) where table` contains counts, percentages, and the assigned negative/neutral/positive side for each response.

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_metric_bars

Plot model metrics with grouped patterned bars.

Import path: fyron.ml.plots.plot_metric_bars

python
plot_metric_bars(metrics: Mapping[str, Mapping[str, float]] | pd.DataFrame, *, metrics_to_plot: Sequence[str] | None = None, model_col: str = 'model', title: str = 'Model metrics', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
metricsyesMapping[str, Mapping[str, float]] or pd.DataFrameSee signature.
metrics_to_plotnoSequence[str] or NoneNoneSee signature.
model_colnostr'model'See signature.
titlenostr'Model metrics'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_missingness_bar

Plot missingness percentages from a preprocessing summary table.

Import path: fyron.ml.plots.plot_missingness_bar

python
plot_missingness_bar(data: Any, *, column_col: str = 'column', missing_col: str = 'missing_percent', group_col: str | None = None, title: str = 'Missingness', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
column_colnostr'column'See signature.
missing_colnostr'missing_percent'See signature.
group_colnostr or NoneNoneSee signature.
titlenostr'Missingness'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_patterned_bar

Plot grouped bars with hatch patterns for grayscale-safe figures.

Import path: fyron.ml.plots.plot_patterned_bar

python
plot_patterned_bar(data: Any, *, x: str, y: str, group: str | None = None, error: str | None = None, title: str = 'Bar plot', xlabel: str | None = None, ylabel: str | None = None, orientation: Orientation = 'vertical', palette: Sequence[str] | None = None, hatches: Sequence[str] | None = None, annotate: bool = False, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnyTabular data coercible to a DataFrame.
xyesstrSee signature.
yyesstrCategory and value columns.
groupnostr or NoneNoneOptional grouping column. Each group receives a distinct color/hatch.
errornostr or NoneNoneOptional symmetric error-bar column.
titlenostr'Bar plot'See signature.
xlabelnostr or NoneNoneSee signature.
ylabelnostr or NoneNoneSee signature.
orientationnoOrientation'vertical'See signature.
palettenoSequence[str] or NoneNoneSee signature.
hatchesnoSequence[str] or NoneNoneSee signature.
annotatenoboolFalseSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_precision_recall_curve

Plot a precision-recall curve for binary classification.

Import path: fyron.ml.plots.plot_precision_recall_curve

python
plot_precision_recall_curve(y_true: ArrayLikeInput, y_prob: ArrayLike, *, title: str = 'Precision-recall curve', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png', pos_label: Any | None = None) -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesArrayLikeInputSee signature.
y_probyesArrayLikeSee signature.
titlenostr'Precision-recall curve'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.
pos_labelnoAny or NoneNoneSee signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_raincloud

Plot half-violin distributions with box summaries and patient-level points.

Import path: fyron.ml.plots.plot_raincloud

python
plot_raincloud(data: Any, *, x: str = 'group', y: str = 'value', order: Sequence[Any] | None = None, title: str = 'Raincloud plot', ylabel: str | None = None, palette: str | Sequence[str] | None = 'bf_vibrant_muted', random_state: int = 7, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
xnostr'group'See signature.
ynostr'value'See signature.
ordernoSequence[Any] or NoneNoneSee signature.
titlenostr'Raincloud plot'See signature.
ylabelnostr or NoneNoneSee signature.
palettenostr or Sequence[str] or None'bf_vibrant_muted'See signature.
random_statenoint7See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_risk_score_distribution

Plot risk scores as a BOARISK-style violin/jitter distribution.

Import path: fyron.ml.plots.plot_risk_score_distribution

python
plot_risk_score_distribution(data: Any, *, risk_col: str = 'risk_score', event_col: str | None = None, event_labels: Mapping[Any, str] | Sequence[str] | None = None, title: str = 'Risk score distribution', ylabel: str | None = None, jitter: bool = True, violin: bool = True, palette: Sequence[str] | None = None, random_state: int = 42, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
risk_colnostr'risk_score'See signature.
event_colnostr or NoneNoneSee signature.
event_labelsnoMapping[Any, str] or Sequence[str] or NoneNoneSee signature.
titlenostr'Risk score distribution'See signature.
ylabelnostr or NoneNoneSee signature.
jitternoboolTrueSee signature.
violinnoboolTrueSee signature.
palettenoSequence[str] or NoneNoneSee signature.
random_statenoint42See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_roc_curve

Plot an ROC curve and return the figure and axis.

Import path: fyron.ml.plots.plot_roc_curve

python
plot_roc_curve(y_true: ArrayLikeInput, y_prob: ArrayLike, *, title: str = 'ROC curve', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png', pos_label: Any | None = None) -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesArrayLikeInputSee signature.
y_probyesArrayLikeSee signature.
titlenostr'ROC curve'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.
pos_labelnoAny or NoneNoneSee signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_segmentation_overlay_grid

Plot CT/image slices with a mask overlay.

Import path: fyron.ml.plots.plot_segmentation_overlay_grid

python
plot_segmentation_overlay_grid(image: Any, mask: Any, *, slice_indices: Sequence[int] | None = None, label: int | None = None, alpha: float = 0.35, title: str = 'Segmentation overlay', save_path: str | Path | None = None, fmt: str = 'png') -> tuple[Figure, np.ndarray]

Parameters

ParameterRequiredTypeDefaultDescription
imageyesAnySee signature.
maskyesAnySee signature.
slice_indicesnoSequence[int] or NoneNoneSee signature.
labelnoint or NoneNoneSee signature.
alphanofloat0.35See signature.
titlenostr'Segmentation overlay'See signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

tuple[Figure, np.ndarray]

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_signed_feature_weights

Plot signed coefficients or feature weights with BOARISK hatches.

Import path: fyron.ml.plots.plot_signed_feature_weights

python
plot_signed_feature_weights(data: Any, *, feature_col: str = 'feature', weight_col: str = 'coef', top_n: int = 20, title: str = 'Signed feature weights', xlabel: str = 'Model coefficient', positive_label: str = 'Higher risk', negative_label: str = 'Lower risk', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
feature_colnostr'feature'See signature.
weight_colnostr'coef'See signature.
top_nnoint20See signature.
titlenostr'Signed feature weights'See signature.
xlabelnostr'Model coefficient'See signature.
positive_labelnostr'Higher risk'See signature.
negative_labelnostr'Lower risk'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_significance_bars

Plot p-values as `-log10(p)` bars and return the computed table.

Import path: fyron.ml.plots.plot_significance_bars

python
plot_significance_bars(data: Any, *, label_col: str = 'label', p_col: str = 'p_value', threshold: float = 0.05, title: str = 'Statistical significance', xlabel: str = '-log10(p)', annotate: bool = True, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> TablePlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
label_colnostr'label'See signature.
p_colnostr'p_value'See signature.
thresholdnofloat0.05See signature.
titlenostr'Statistical significance'See signature.
xlabelnostr'-log10(p)'See signature.
annotatenoboolTrueSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

TablePlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_stability_selection

Plot feature-selection frequencies from stability selection.

Import path: fyron.ml.plots.plot_stability_selection

python
plot_stability_selection(data: Any, *, feature_col: str = 'feature', frequency_col: str = 'selection_frequency', threshold: float = 0.6, title: str = 'Stability selection', top_n: int = 25, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
feature_colnostr'feature'See signature.
frequency_colnostr'selection_frequency'See signature.
thresholdnofloat0.6See signature.
titlenostr'Stability selection'See signature.
top_nnoint25See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_survival_calibration

Plot fixed-horizon observed versus predicted survival/event risk.

Import path: fyron.ml.plots.plot_survival_calibration

python
plot_survival_calibration(calibration_table: Any, *, observed_col: str = 'observed', predicted_col: str = 'predicted', title: str = 'Survival calibration', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
calibration_tableyesAnySee signature.
observed_colnostr'observed'See signature.
predicted_colnostr'predicted'See signature.
titlenostr'Survival calibration'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_swarmplot

Plot patient-level values with jitter/dodge and optional statistics.

Import path: fyron.ml.plots.plot_swarmplot

python
plot_swarmplot(data: Any, *, x: str, y: str, hue: str | None = None, order: Sequence[Any] | None = None, hue_order: Sequence[Any] | None = None, dodge: bool = True, title: str = 'Swarm plot', xlabel: str | None = None, ylabel: str | None = None, palette: Sequence[str] | None = None, point_size: float = 24, point_alpha: float = 0.72, random_state: int = 42, comparisons: Sequence[tuple[Any, Any] | tuple[tuple[Any, Any], tuple[Any, Any]]] | None = None, stat_test: StatTestName = 'mannwhitney', p_adjust: str = 'none', annotation_format: AnnotationFormat = 'star', hide_ns: bool = False, return_stats: bool = False, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn | TablePlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
xyesstrSee signature.
yyesstrSee signature.
huenostr or NoneNoneSee signature.
ordernoSequence[Any] or NoneNoneSee signature.
hue_ordernoSequence[Any] or NoneNoneSee signature.
dodgenoboolTrueSee signature.
titlenostr'Swarm plot'See signature.
xlabelnostr or NoneNoneSee signature.
ylabelnostr or NoneNoneSee signature.
palettenoSequence[str] or NoneNoneSee signature.
point_sizenofloat24See signature.
point_alphanofloat0.72See signature.
random_statenoint42See signature.
comparisonsnoSequence[tuple[Any, Any] or tuple[tuple[Any, Any], tuple[Any, Any]]] or NoneNoneSee signature.
stat_testnoStatTestName'mannwhitney'See signature.
p_adjustnostr'none'See signature.
annotation_formatnoAnnotationFormat'star'See signature.
hide_nsnoboolFalseSee signature.
return_statsnoboolFalseSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn | TablePlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_swimmer

Plot patient-level duration bars with optional event markers.

Import path: fyron.ml.plots.plot_swimmer

python
plot_swimmer(data: Any, *, patient_col: str = 'patient', start_col: str = 'start', end_col: str = 'end', group_col: str | None = None, event_time_col: str | None = 'event_time', event_col: str | None = 'event', title: str = 'Swimmer plot', xlabel: str = 'Time', palette: str | Sequence[str] | None = 'bf_vibrant_muted', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
patient_colnostr'patient'See signature.
start_colnostr'start'See signature.
end_colnostr'end'See signature.
group_colnostr or NoneNoneSee signature.
event_time_colnostr or None'event_time'See signature.
event_colnostr or None'event'See signature.
titlenostr'Swimmer plot'See signature.
xlabelnostr'Time'See signature.
palettenostr or Sequence[str] or None'bf_vibrant_muted'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_table_one_summary

Plot Table 1 p-values as a compact overview.

Import path: fyron.ml.plots.plot_table_one_summary

python
plot_table_one_summary(data: Any, *, variable_col: str = 'variable', p_col: str = 'p_value', title: str = 'Table 1 summary', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
variable_colnostr'variable'See signature.
p_colnostr'p_value'See signature.
titlenostr'Table 1 summary'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_time_dependent_auc

Plot time-dependent AUC values from a precomputed table.

Import path: fyron.ml.plots.plot_time_dependent_auc

python
plot_time_dependent_auc(data: Any, *, time_col: str = 'time', auc_col: str = 'auc', title: str = 'Time-dependent AUC', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
time_colnostr'time'See signature.
auc_colnostr'auc'See signature.
titlenostr'Time-dependent AUC'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_volcano

Plot feature effects against statistical significance.

Import path: fyron.ml.plots.plot_volcano

python
plot_volcano(data: Any, *, feature_col: str = 'feature', effect_col: str = 'log2_fold_change', p_col: str = 'p_value', group_col: str | None = None, p_threshold: float = 0.05, effect_threshold: float = 1.0, top_n_labels: int = 8, title: str = 'Volcano plot', xlabel: str | None = None, ylabel: str = '-log10(p)', palette: str | Sequence[str] | None = 'bf_vibrant_muted', ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnySee signature.
feature_colnostr'feature'See signature.
effect_colnostr'log2_fold_change'See signature.
p_colnostr'p_value'See signature.
group_colnostr or NoneNoneSee signature.
p_thresholdnofloat0.05See signature.
effect_thresholdnofloat1.0See signature.
top_n_labelsnoint8See signature.
titlenostr'Volcano plot'See signature.
xlabelnostr or NoneNoneSee signature.
ylabelnostr'-log10(p)'See signature.
palettenostr or Sequence[str] or None'bf_vibrant_muted'See signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_waffle

Plot a waffle chart for cohort composition or endpoint mix.

Import path: fyron.ml.plots.plot_waffle

python
plot_waffle(data: Any, *, category_col: str = 'category', value_col: str = 'value', total: int = 100, rows: int = 10, palette: str | Sequence[str] | None = 'bf_vibrant_muted', title: str | None = None, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> TablePlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnyTable with category labels and non-negative values.
category_colnostr'category'See signature.
value_colnostr'value'Columns containing categories and values to allocate into waffle cells.
totalnoint100Number of cells in the waffle chart.
rowsnoint10Number of waffle rows. Columns are derived from `total and rows`.
palettenostr or Sequence[str] or None'bf_vibrant_muted'See signature.
titlenostr or NoneNoneSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

tuple - `(fig, ax, table) where table` contains category proportions, allocated cell counts, and source values.

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.plot_waterfall

Plot ordered patient-level changes or response scores.

Import path: fyron.ml.plots.plot_waterfall

python
plot_waterfall(values: ArrayLike, *, labels: Sequence[Any] | None = None, title: str = 'Waterfall plot', ylabel: str = 'Change', threshold: float | None = None, ax: Axes | None = None, save_path: str | Path | None = None, fmt: str = 'png') -> PlotReturn

Parameters

ParameterRequiredTypeDefaultDescription
valuesyesArrayLikeSee signature.
labelsnoSequence[Any] or NoneNoneSee signature.
titlenostr'Waterfall plot'See signature.
ylabelnostr'Change'See signature.
thresholdnofloat or NoneNoneSee signature.
axnoAxes or NoneNoneSee signature.
save_pathnostr or Path or NoneNoneSee signature.
fmtnostr'png'See signature.

Returns

PlotReturn

See also: ML, Validation, And Explainability module guide.

fyron.ml.plots.stat_test_pairs

Run pairwise statistical tests for plot annotations.

Import path: fyron.ml.plots.stat_test_pairs

python
stat_test_pairs(data: Any, *, x: str, y: str, pairs: Sequence[tuple[Any, Any] | tuple[tuple[Any, Any], tuple[Any, Any]]], hue: str | None = None, test: StatTestName = 'mannwhitney', p_adjust: str = 'none', alpha: float = 0.05, p_values: Sequence[float] | Mapping[tuple[Any, Any], float] | pd.DataFrame | None = None, label_col: str = 'label', p_col: str = 'p_value', text_format: AnnotationFormat = 'star', hide_ns: bool = False) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
datayesAnyTabular data coercible to a DataFrame.
xyesstrSee signature.
yyesstrCategorical grouping column and numeric value column.
pairsyesSequence[tuple[Any, Any] or tuple[tuple[Any, Any], tuple[Any, Any]]]Comparisons. Without `hue use ("A", "B"). With hue use (("A", "F"), ("A", "M"))` keys.
huenostr or NoneNoneOptional second grouping column.
testnoStatTestName'mannwhitney'Statistical test name.
p_adjustnostr'none'Multiple-testing correction method accepted by :func:fyron.statistics.p_value_correction_table.
alphanofloat0.05See signature.
p_valuesnoSequence[float] or Mapping[tuple[Any, Any], float] or pd.DataFrame or NoneNoneOptional custom p-values. When provided, no statistical test is run.
label_colnostr'label'See signature.
p_colnostr'p_value'See signature.
text_formatnoAnnotationFormat'star'Annotation label style: `"star", "pvalue", or "simple"`.
hide_nsnoboolFalseIf True, non-significant comparisons receive an empty annotation.

Returns

pandas.DataFrame - One row per comparison with test, statistic, raw/adjusted p-values, reject flag, annotation, and group sizes.

See also: ML, Validation, And Explainability module guide.

fyron.ml.search.grid_search_model

Run :class:~sklearn.model_selection.GridSearchCV with stratified folds.

Import path: fyron.ml.search.grid_search_model

python
grid_search_model(estimator: Any, param_grid: dict[str, Any], X_train: ArrayLikeInput, y_train: ArrayLikeInput, X_val: ArrayLikeInput | None = None, y_val: ArrayLikeInput | None = None, *, scoring: str = 'roc_auc', cv: int = 5, n_jobs: int = -1, refit: bool = True, random_state: int = 42) -> SearchResult

Parameters

ParameterRequiredTypeDefaultDescription
estimatoryesAnySee signature.
param_gridyesdict[str, Any]See signature.
X_trainyesArrayLikeInputSee signature.
y_trainyesArrayLikeInputSee signature.
X_valnoArrayLikeInput or NoneNoneSee signature.
y_valnoArrayLikeInput or NoneNoneSee signature.
scoringnostr'roc_auc'See signature.
cvnoint5See signature.
n_jobsnoint-1See signature.
refitnoboolTrueSee signature.
random_statenoint42See signature.

Returns

SearchResult

See also: ML, Validation, And Explainability module guide.

fyron.ml.splitting.train_test_split_data

Split features and target into train and test sets.

Import path: fyron.ml.splitting.train_test_split_data

python
train_test_split_data(X: ArrayLikeInput, y: ArrayLikeInput, *, test_size: float = 0.2, stratify: bool = True, random_state: int = 42) -> SplitReturn

Parameters

ParameterRequiredTypeDefaultDescription
XyesArrayLikeInputFeature matrix.
yyesArrayLikeInputTarget vector.
test_sizenofloat0.2Fraction of samples held out for testing.
stratifynoboolTrueIf True, stratify on `y`.
random_statenoint42Random seed passed to scikit-learn.

Returns

X_train, X_test, y_train, y_test

See also: ML, Validation, And Explainability module guide.

fyron.ml.training.train_random_forest

Train a :class:~sklearn.ensemble.RandomForestClassifier.

Import path: fyron.ml.training.train_random_forest

python
train_random_forest(X_train: ArrayLikeInput, y_train: ArrayLikeInput, X_test: ArrayLikeInput | None = None, y_test: ArrayLikeInput | None = None, *, class_weight: str | dict[Any, float] | None = None, random_state: int = 42, plot: bool = False, pos_label: Any | None = None, **model_params: Any) -> TrainingResult

Parameters

ParameterRequiredTypeDefaultDescription
X_trainyesArrayLikeInputSee signature.
y_trainyesArrayLikeInputSee signature.
X_testnoArrayLikeInput or NoneNoneSee signature.
y_testnoArrayLikeInput or NoneNoneSee signature.
class_weightnostr or dict[Any, float] or NoneNoneSee signature.
random_statenoint42See signature.
plotnoboolFalseSee signature.
pos_labelnoAny or NoneNoneSee signature.
model_paramsyesAnySee signature.

Returns

TrainingResult

See also: ML, Validation, And Explainability module guide.

fyron.ml.training.train_xgboost

Train an :class:xgboost.XGBClassifier.

Import path: fyron.ml.training.train_xgboost

python
train_xgboost(X_train: ArrayLikeInput, y_train: ArrayLikeInput, X_test: ArrayLikeInput | None = None, y_test: ArrayLikeInput | None = None, *, scale_pos_weight: float | None = None, random_state: int = 42, plot: bool = False, pos_label: Any | None = None, **model_params: Any) -> TrainingResult

Parameters

ParameterRequiredTypeDefaultDescription
X_trainyesArrayLikeInputSee signature.
y_trainyesArrayLikeInputSee signature.
X_testnoArrayLikeInput or NoneNoneSee signature.
y_testnoArrayLikeInput or NoneNoneSee signature.
scale_pos_weightnofloat or NoneNoneSee signature.
random_statenoint42See signature.
plotnoboolFalseSee signature.
pos_labelnoAny or NoneNoneSee signature.
model_paramsyesAnySee signature.

Returns

TrainingResult

See also: ML, Validation, And Explainability module guide.

fyron.validation.classification.bootstrap_classification_metrics

Bootstrap binary classification metrics with percentile intervals.

Import path: fyron.validation.classification.bootstrap_classification_metrics

python
bootstrap_classification_metrics(y_true: Sequence[Any], y_pred: Sequence[Any], y_prob: Sequence[float] | None = None, *, n_rounds: int = 1000, random_state: int = 42, pos_label: Any = 1, ci: float = 0.95) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesSequence[Any]See signature.
y_predyesSequence[Any]Ground-truth and predicted labels.
y_probnoSequence[float] or NoneNoneOptional positive-class probabilities for AUC intervals.
n_roundsnoint1000Number of bootstrap resamples.
random_statenoint42Random seed for deterministic intervals.
pos_labelnoAny1Positive class label.
cinofloat0.95Confidence interval width, for example `0.95`.

Returns

pandas.DataFrame - One row per numeric metric with estimate, bootstrap mean, lower and upper CI.

See also: ML, Validation, And Explainability module guide.

fyron.validation.classification.calibration_summary

Return calibration-in-the-large, calibration slope proxy, and bin table.

Import path: fyron.validation.classification.calibration_summary

python
calibration_summary(y_true: Sequence[Any], y_prob: Sequence[float], *, n_bins: int = 10, pos_label: Any = 1) -> tuple[dict[str, float], pd.DataFrame]

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesSequence[Any]See signature.
y_probyesSequence[float]See signature.
n_binsnoint10See signature.
pos_labelnoAny1See signature.

Returns

tuple[dict[str, float], pd.DataFrame]

See also: ML, Validation, And Explainability module guide.

fyron.validation.classification.decision_curve_table

Compute binary decision-curve net benefit over thresholds.

Import path: fyron.validation.classification.decision_curve_table

python
decision_curve_table(y_true: Sequence[Any], y_prob: Sequence[float], *, thresholds: Sequence[float] | None = None, pos_label: Any = 1) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesSequence[Any]See signature.
y_probyesSequence[float]See signature.
thresholdsnoSequence[float] or NoneNoneSee signature.
pos_labelnoAny1See signature.

Returns

pd.DataFrame

See also: ML, Validation, And Explainability module guide.

fyron.validation.classification.find_best_threshold

Find a binary decision threshold by an explicit metric.

Import path: fyron.validation.classification.find_best_threshold

python
find_best_threshold(y_true: Sequence[Any], y_prob: Sequence[float], *, metric: ThresholdMetric = 'youden', pos_label: Any = 1, thresholds: Sequence[float] | None = None) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
y_trueyesSequence[Any]See signature.
y_probyesSequence[float]See signature.
metricnoThresholdMetric'youden'See signature.
pos_labelnoAny1See signature.
thresholdsnoSequence[float] or NoneNoneSee signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.validation.classification.subgroup_metric_table

Calculate classification metrics separately for each subgroup.

Import path: fyron.validation.classification.subgroup_metric_table

python
subgroup_metric_table(df: pd.DataFrame, *, group_col: str, y_true_col: str, y_pred_col: str, y_prob_col: str | None = None, pos_label: Any = 1) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
dfyespd.DataFrameSee signature.
group_colyesstrSee signature.
y_true_colyesstrSee signature.
y_pred_colyesstrSee signature.
y_prob_colnostr or NoneNoneSee signature.
pos_labelnoAny1See signature.

Returns

pd.DataFrame

See also: ML, Validation, And Explainability module guide.

fyron.validation.survival.bootstrap_concordance_index

Bootstrap Harrell-style concordance index for risk scores.

Import path: fyron.validation.survival.bootstrap_concordance_index

python
bootstrap_concordance_index(df: pd.DataFrame, duration_col: str, event_col: str, risk_col: str, *, n_rounds: int = 1000, random_state: int = 42) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
dfyespd.DataFrameSee signature.
duration_colyesstrSee signature.
event_colyesstrSee signature.
risk_colyesstrSee signature.
n_roundsnoint1000See signature.
random_statenoint42See signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.validation.survival.brier_score_at_time

Return naive fixed-horizon Brier score for predicted event risks.

Import path: fyron.validation.survival.brier_score_at_time

python
brier_score_at_time(df: pd.DataFrame, duration_col: str, event_col: str, prediction_col: str, time_horizon: float) -> dict[str, float]

Parameters

ParameterRequiredTypeDefaultDescription
dfyespd.DataFrameSee signature.
duration_colyesstrSee signature.
event_colyesstrSee signature.
prediction_colyesstrSee signature.
time_horizonyesfloatSee signature.

Returns

dict[str, float]

See also: ML, Validation, And Explainability module guide.

fyron.validation.survival.external_survival_validation

Evaluate a locked survival score or prediction column in an external cohort.

Import path: fyron.validation.survival.external_survival_validation

python
external_survival_validation(train_summary_or_model: Any, external_df: pd.DataFrame, *, duration_col: str, event_col: str, risk_col: str, prediction_col: str | None = None, time_horizon: float | None = None) -> dict[str, Any]

Parameters

ParameterRequiredTypeDefaultDescription
train_summary_or_modelyesAnySee signature.
external_dfyespd.DataFrameSee signature.
duration_colyesstrSee signature.
event_colyesstrSee signature.
risk_colyesstrSee signature.
prediction_colnostr or NoneNoneSee signature.
time_horizonnofloat or NoneNoneSee signature.

Returns

dict[str, Any]

See also: ML, Validation, And Explainability module guide.

fyron.validation.survival.survival_calibration_at_time

Compare predicted event risk with observed event rate at a fixed time.

Import path: fyron.validation.survival.survival_calibration_at_time

python
survival_calibration_at_time(df: pd.DataFrame, duration_col: str, event_col: str, prediction_col: str, time_horizon: float, *, n_bins: int = 5) -> tuple[dict[str, float], pd.DataFrame]

Parameters

ParameterRequiredTypeDefaultDescription
dfyespd.DataFrameSee signature.
duration_colyesstrSee signature.
event_colyesstrSee signature.
prediction_colyesstrSee signature.
time_horizonyesfloatSee signature.
n_binsnoint5See signature.

Returns

tuple[dict[str, float], pd.DataFrame]

See also: ML, Validation, And Explainability module guide.

fyron.validation.survival.time_dependent_auc_table

Compute cumulative/dynamic AUC at fixed time horizons.

Import path: fyron.validation.survival.time_dependent_auc_table

python
time_dependent_auc_table(train_df: pd.DataFrame, test_df: pd.DataFrame, *, duration_col: str, event_col: str, risk_col: str, times: Sequence[float]) -> pd.DataFrame

Parameters

ParameterRequiredTypeDefaultDescription
train_dfyespd.DataFrameTraining cohort used to estimate the censoring distribution.
test_dfyespd.DataFrameValidation cohort with risk scores.
duration_colyesstrSee signature.
event_colyesstrSurvival time and event indicator columns.
risk_colyesstrHigher values should indicate higher event risk.
timesyesSequence[float]Positive time horizons for dynamic AUC.

Returns

pandas.DataFrame - AUC by time plus the mean AUC returned by scikit-survival.

See also: ML, Validation, And Explainability module guide.