Add fluent interface pattern as teaching example

対象ファイルや既存の演習は指定されていません。まず、API設計または plotting の例を教えているコースのセクションを見つけ、その形式と隣接するレッスンを確認してください。完了条件は、列挙されたパターンと、それらの discoverability、type-safety、composability、compatibility、learning curve に関するトレードオフを提示する教材セクションまたは演習を追加することです。

Add a section or exercise covering API design patterns for simplifying functions with many parameters.

Good reference example: https://github.com/DHI/modelskill/discussions/492 — the scatter() function has grown a long signature:

def scatter(
    x: np.ndarray,
    y: np.ndarray,
    *,
    bins: int | float = 120,
    quantiles: int | Sequence[float] | None = None,
    fit_to_quantiles: bool = False,
    show_points: bool | int | float | None = None,
    show_hist: Optional[bool] = None,
    show_density: Optional[bool] = None,
    norm: Optional[colors.Normalize] = None,
    backend: Literal["matplotlib", "plotly"] = "matplotlib",
    figsize: Tuple[float, float] = (8, 8),
    xlim: Optional[Tuple[float, float]] = None,
    ylim: Optional[Tuple[float, float]] = None,
    reg_method: str | bool = "ols",
    title: str = "",
    xlabel: str = "",
    ylabel: str = "",
    skill_table: Optional[str | Sequence[str] | Mapping[str, str] | bool] = False,
    skill_scores: Mapping[str, float] | None = None,
    skill_score_unit: Optional[str] = "",
    ax: Optional[Axes] = None,
    **kwargs,
) -> Axes:

Alternative patterns to simplify

1. Fluent interface (method chaining)

Each component gets its own method. Easy to add/remove parts.

(Comparer(x, y)
 .plot()
 .scatter(alpha=0.5)
 .qq([0.05, 0.5, 0.75, 0.95])
# .reg_line(equation=True)
 .skill_table(("n", "bias"))
).show()

2. Configuration objects (dataclasses)

Group related parameters into typed config objects.

@dataclass
class ScatterStyle:
    bins: int = 120
    show_points: bool = True
    show_density: bool = False
    norm: colors.Normalize | None = None

@dataclass
class Layout:
    figsize: tuple[float, float] = (8, 8)
    xlim: tuple[float, float] | None = None
    ylim: tuple[float, float] | None = None
    title: str = ""
    xlabel: str = ""
    ylabel: str = ""

scatter(x, y, style=ScatterStyle(bins=50), layout=Layout(title="My plot"))

3. Presets / named styles

Offer common configurations as named presets, with overrides.

scatter(x, y, preset="minimal")              # just points + 1:1 line
scatter(x, y, preset="full")                 # density + qq + regression + skill table
scatter(x, y, preset="presentation")         # large fonts, clean layout
scatter(x, y, preset="minimal", title="Hm0") # preset + override

4. Composition of small functions

Instead of one function that does everything, provide building blocks that work with a standard Axes.

fig, ax = plt.subplots()
plot_scatter(ax, x, y, show_density=True)
plot_qq(ax, x, y, quantiles=[0.25, 0.5, 0.75])
plot_reg_line(ax, x, y)
add_skill_table(ax, x, y, metrics=["bias", "rmse"])

Each pattern has trade-offs worth discussing: discoverability, type safety, composability, backwards compatibility, learning curve.

Relevant topics: method chaining, Self return type, builder pattern, dataclasses as config, API design trade-offs.