Skip to content

Latest commit

 

History

History
93 lines (78 loc) · 5.72 KB

API_STABILITY.md

File metadata and controls

93 lines (78 loc) · 5.72 KB

API stability — janusplot

Policy. This package follows Semantic Versioning and the lifecycle vocabulary for individual symbols.

Stability stages

  • experimental — may change in any release; every change is recorded in NEWS.md.
  • stable — public API; breaking changes only at major-version bumps, with at least one minor version of overlap via lifecycle::deprecate_warn().
  • superseded — a better alternative exists; the symbol is kept working but is not extended.
  • deprecated — scheduled for removal; emits a lifecycle deprecation and is removed after at least one minor version.

Public surface at 1.0.0

Symbol Type Stage Since Notes
janusplot_fit() function stable 1.0.0 Fits every ordered pair once; returns a janusplot_fit object.
print.janusplot_fit() S3 method stable 1.0.0 Variables, pairs, settings, flags and the largest asymmetries.
summary.janusplot_fit() S3 method stable 1.0.0 Data frame with one row per directed cell.
plot.janusplot_fit() S3 method stable 1.0.0 The matrix.
janusplot() function stable 0.1.0 One call, plot(janusplot_fit(...)). The 0.2.0 appearance arguments are accepted through ... with a warning until 1.1.0.
janusplot_pair() function stable 1.0.0 The two directions of one or more pairs.
janusplot_compare() function stable 1.0.0 Two fits of the same variables matched cell by cell.
print.janusplot_compare(), plot.janusplot_compare() S3 methods stable 1.0.0 Counts of changed cells; the matrix with both curves.
janusplot_direction() function experimental 1.0.0 HSIC residual-independence verdict on one pair of a fit.
print.janusplot_direction() S3 method experimental 1.0.0 Verdict, reason, p-values and rows used.
janusplot_curves() function experimental 1.0.0 The fitted curves or their derivatives as one long data frame.
janusplot_reference() function experimental 1.0.0 Bootstrap reference for the asymmetry index of chosen pairs.
print.janusplot_reference(), plot.janusplot_reference() S3 methods experimental 1.0.0 One reading per pair; the reference distributions.
janusplot_style() function stable 1.0.0 Every appearance setting, validated.
print.janusplot_style() S3 method stable 1.0.0 The settings that differ from the defaults.
janusplot_shape_metrics() function experimental 0.1.0 Shape indices, counts and label for any mgcv smooth.
janusplot_shape_cutoffs() function experimental 0.1.0 Classification thresholds.
janusplot_shape_hierarchy() function experimental 0.1.0 The 27-category taxonomy table.
janusplot_shape_sensitivity() function experimental 0.1.0 Factorial shape × n × σ × replicate sweep; gains shapes = and a classed return in 1.0.0.
summary.janusplot_sensitivity(), plot.janusplot_sensitivity() S3 methods experimental 1.0.0 Accuracy aggregation and the four diagnostic plots.
shape_sensitivity_demo dataset experimental 0.1.0 Precomputed 2160-fit sweep, regenerated by data-raw/shape_sensitivity_demo.R.

What the stable promise covers

For the symbols marked stable, the promise covers their names, their argument names and what each argument means, and the documented columns of summary(), including the 27 shape label names. Three things sit outside it and may change in a minor release, with a NEWS.md entry:

  • Default appearance: colours, palettes, layout thresholds and the compact tiers. Results do not depend on them.
  • The internal structure of the fit object: the fields of $pairs, $settings and the other list components. Read results through summary() and the methods, whose output is covered.
  • Message wording: the text of errors, warnings and informs.

janusplot_direction() stays experimental because a conditional test under adjust is planned. The shape helpers and janusplot_shape_sensitivity() stay experimental as study tools.

Deprecated in 1.0.0

Symbol / argument Replacement Removal
janusplot_data() janusplot_fit() 1.1.0
janusplot_direction_test() janusplot_direction() 1.1.0
janusplot() appearance arguments (show_data, palette, labels, label_cex and the rest listed in ?janusplot) janusplot_style() 1.1.0
janusplot(with_data = TRUE) summary(janusplot_fit(...)) 1.1.0
janusplot(save_as = ) and save_width, save_height, save_dpi ggplot2::ggsave() 1.1.0
janusplot(fill_by = ), show_asymmetry, signif_glyph colour_by, annotations 1.1.0
colour_by = "edf" colour_by = "nonlinearity" 1.1.0
janusplot_shape_cutoffs() entries mono_nonmono, mono_s, curv_strong none; the classifier never read them 1.1.0 or later

Removed in 1.0.0

Symbol Replacement
janusplot_shape_sensitivity_shapes() the default of janusplot_shape_sensitivity(shapes = )
janusplot_shape_sensitivity_summary() summary() on the result of janusplot_shape_sensitivity()
janusplot_shape_sensitivity_plot() plot() on the result of janusplot_shape_sensitivity()

Breaking-change policy

  • Column renames in output tables are breaking and are listed in NEWS.md; 1.0.0 renamed pvalue to association_p.
  • Changes to default argument values are breaking for callers who rely on defaults and are listed in NEWS.md; 1.0.0 changed the default cell encoding and the cell orientation.
  • A deprecated symbol or argument warns for at least one minor release before it is removed.