Cnsplots

CNSPlots

Build plots against the installed cnsplots version. Favor a short, runnable script that preserves the user's data semantics and produces the requested artifact.

Workflow

1. Inspect the input data before choosing a plot.

   • Confirm the relevant columns, dtypes, missing values, units, category order, and event coding.
   • Ask only when an unresolved choice would change the scientific meaning.
   • Never invent labels, comparisons, thresholds, statistical tests, or units.

2. Choose the narrowest suitable public plot function.

   • Read references/plot-catalog.md when selecting a plot type or composing a multi-panel figure.
   • Prefer import cnsplots as cns and the public names on cns.
   • Do not call private modules or functions.

3. Verify the installed API instead of guessing a signature.

   python - <<'PY'
   import inspect
   import cnsplots as cns
   
   print(cns.__version__)
   print(inspect.signature(cns.boxplot))
   print(cns.boxplot.__doc__)
   PY
   

   Replace boxplot with the selected public function. If cnsplots cannot be imported, report that clearly and ask before changing the user's environment.

4. Build the figure.

   • In headless execution, set MPLBACKEND=Agg or call matplotlib.use("Agg") before importing plotting backends.
   • Start single-panel figures with fig = cns.figure(width=..., height=...). Dimensions size the whole canvas in points (1/72 inch) by default, with unit="pt", unit="in", or unit="mm" for explicit dimensions. Omitted dimensions always use settings stored in points. The returned Matplotlib Figure becomes current.
   • Pass ax= explicitly when composing with existing Matplotlib axes.
   • Use cns.multipanel for labeled publication panels. Its max_width sets the full figure width; explicit panel dimensions inherit its unit or override it per panel. Panel sizes describe axes area, with decorations and margins adding layout space. Margins stay in points; label pad_left/pad_top stay in rendered display pixels.
   • Add titles and axis labels through the returned Matplotlib axes.
   • Use cns.settings.context(...) for temporary style overrides rather than leaving global settings changed.

5. Save and validate the result.

   • Use cns.savefig(..., fig=fig) to save a retained figure, or omit fig to save the current figure. Prefer SVG or PDF for editable publication output and PNG for a raster preview. Per-save dpi, transparent, bbox_inches, and pad_inches override export settings; bbox_inches=None preserves the full canvas, and padding in inches applies only to tight cropping. DPI controls raster resolution, not physical size: cns.figure(100, 150) is 100/72 × 150/72 inches, or a 200 × 300 pixel canvas at default display DPI 144. At default export DPI 288 it saves as 400 × 600 pixels with bbox_inches=None; default tight cropping changes the saved bounds.
   • Run the complete script, confirm the output exists and is non-empty, and inspect or render it when visual tools are available.
   • Check clipping, unreadable labels, misleading scales, legend collisions, color distinguishability, and panel alignment.
   • Return the runnable code, output path, and any scientific assumptions.

Baseline Pattern

import matplotlib

matplotlib.use("Agg")

import cnsplots as cns

fig = cns.figure(width=180, height=150)
ax = cns.boxplot(data=df, x="group", y="value")
ax.set(xlabel="Group", ylabel="Value")
cns.savefig("figure.svg", fig=fig)

Adapt this only after inspecting the selected function's installed signature and docstring.

Statistical Integrity

• Treat pairs, event codes, reference groups, transformations, and thresholds as analysis choices, not decoration.
• State tests and comparison directions reflected by the installed function documentation.
• Do not imply causality or significance beyond the supplied data and chosen analysis.
• Preserve raw observations when the user requests them; do not silently replace distributions with summaries.