graphica-plot 2.0.0__py3-none-any.whl

graphica/gui/project_files.py

@@ -0,0 +1,361 @@
+"""プロジェクトのファイル: 保存・読み込み・未保存の変更の確認・オートセーブと世代・最近使ったファイル。"""
+import logging
+import os
+from PySide6.QtWidgets import QDialog, QMessageBox
+from datetime import datetime
+from graphica.core.i18n import tr
+from graphica.core.app_paths import get_app_data_dir
+from graphica.gui import app_settings, notify
+from graphica.gui.dialogs import AutosaveHistoryDialog
+from graphica.models.project import LEGACY_PICKLE_EXTENSION, PROJECT_FILE_EXTENSION, PROJECT_FILE_EXTENSIONS
+
+logger = logging.getLogger(__name__)
+
+
+AUTOSAVE_GENERATIONS = 3  # 最新の autosave.gra を含む
+
+
+MAX_RECENT_FILES = 10
+
+
+# 未保存の変更の確認を出すか。テストはモーダルなダイアログで止まるので tests/conftest.py が "0" にする
+UNSAVED_CHANGES_PROMPT_ENV = "GRAPHICA_CONFIRM_UNSAVED_CHANGES"
+
+
+def _unsaved_changes_prompt_enabled():
+    return os.environ.get(UNSAVED_CHANGES_PROMPT_ENV, "1") != "0"
+
+
+def check_autosave_recovery(app):
+    """前回が正常に終わらず、オートセーブが残っていれば、復元するか尋ねる(起動時に1回)。
+
+    無ければ、拡張子を .gra に変える前の版が残した autosave.graphica を探す。
+    """
+    if app._had_clean_exit:
+        return
+
+    autosave_path = app._autosave_filename
+    if not os.path.exists(autosave_path):
+        legacy_path = os.path.splitext(app._autosave_filename)[0] + '.graphica'
+        if os.path.exists(legacy_path):
+            autosave_path = legacy_path
+        else:
+            return
+
+    reply = notify.question(
+        app, "オートセーブからの復元",
+        "前回はプロジェクトが正常に終了しなかったようです。\n"
+        "自動保存されていたデータを復元しますか?",
+        QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
+        QMessageBox.StandardButton.Yes
+    )
+    if reply == QMessageBox.StandardButton.Yes:
+        app._load_project_from_path(autosave_path, add_to_recent=False)
+
+
+def on_show_autosave_history(app):
+    """オートセーブの世代を新しい順に見せ、選んだものを読み込む(復元確認と同じく、最近使ったファイルに載せず、上書き保存の対象にもしない)。"""
+    base, ext = os.path.splitext(app._autosave_filename)
+    candidates = [(app._autosave_filename, "現在(最新)")]
+    for gen in range(1, AUTOSAVE_GENERATIONS):
+        candidates.append((f"{base}.{gen}{ext}", f"{gen}世代前"))
+
+    generations = []
+    for path, label in candidates:
+        if not os.path.exists(path):
+            continue
+        try:
+            mtime_text = datetime.fromtimestamp(os.path.getmtime(path)).strftime("%Y-%m-%d %H:%M:%S")
+        except OSError:
+            mtime_text = "(更新日時不明)"
+        generations.append((path, label, mtime_text))
+
+    if not generations:
+        notify.information(app, "自動バックアップ履歴", "自動バックアップファイルが見つかりませんでした。")
+        return
+
+    dialog = AutosaveHistoryDialog(generations, parent=app)
+    if dialog.exec() != QDialog.DialogCode.Accepted:
+        return
+    selected_path = dialog.get_selected_path()
+    if not selected_path:
+        return
+
+    reply = notify.question(
+        app, "自動バックアップ履歴",
+        "選択した世代の内容で復元します。現在の未保存の変更は失われます。よろしいですか?",
+        QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
+        QMessageBox.StandardButton.No
+    )
+    if reply != QMessageBox.StandardButton.Yes:
+        return
+
+    app._load_project_from_path(selected_path, add_to_recent=False)
+
+
+def update_autosave_path(app):
+    """autosave_dir(空なら get_app_data_dir())から保存先を決め、フォルダを作る。
+
+    カレントディレクトリは使わない(macOS の .app では書き込めない場所になる)。
+    """
+    autosave_dir = app_settings.AUTOSAVE_DIR.read(app.settings)
+    if autosave_dir:
+        try:
+            os.makedirs(autosave_dir, exist_ok=True)
+        except OSError as e:
+            logger.warning("オートセーブ保存先フォルダの作成に失敗しました: %s", e)
+            autosave_dir = ""
+    if not autosave_dir:
+        autosave_dir = get_app_data_dir()
+    app._autosave_filename = os.path.join(autosave_dir, app._autosave_base_filename)
+
+
+def rotate_autosave_generations(app):
+    """autosave.gra を autosave.1.gra, autosave.2.gra, ... へ押し出す。"""
+    base, ext = os.path.splitext(app._autosave_filename)
+
+    oldest = f"{base}.{AUTOSAVE_GENERATIONS - 1}{ext}"
+    if os.path.exists(oldest):
+        os.remove(oldest)
+
+    for gen in range(AUTOSAVE_GENERATIONS - 2, 0, -1):
+        src = f"{base}.{gen}{ext}"
+        dst = f"{base}.{gen + 1}{ext}"
+        if os.path.exists(src):
+            os.replace(src, dst)
+
+    if os.path.exists(app._autosave_filename):
+        os.replace(app._autosave_filename, f"{base}.1{ext}")
+
+
+def sync_project_from_ui(app):
+    """UI にしか無い状態(フォルダ構造、サブプロットの行数と列数)を、保存や比較の前に ProjectModel へ移す。"""
+    app.project.dataset_group_tree = app._capture_dataset_group_tree()
+    app.project.layout_rows = app.subplot_rows_spinbox.value()
+    app.project.layout_cols = app.subplot_cols_spinbox.value()
+
+
+def remember_saved_content(app):
+    """いまの内容を保存済みとみなす(保存・読み込みの成功直後に呼ぶ)。"""
+    app._sync_project_from_ui()
+    app._saved_content_fingerprint = app.project.content_fingerprint()
+
+
+def document_title(app):
+    if app._current_project_path:
+        return os.path.basename(app._current_project_path)
+    if app._restored_unsaved:
+        return "無題のプロジェクト(復元)"
+    return "無題のプロジェクト"
+
+
+def has_unsaved_changes(app):
+    """データセットが無く、ファイルとも対応していない新しいタブは False。"""
+    if not app.project.datasets and not app._current_project_path:
+        return False
+    if app._saved_content_fingerprint is None:
+        return True
+    app._sync_project_from_ui()
+    return app.project.content_fingerprint() != app._saved_content_fingerprint
+
+
+def confirm_unsaved_changes(app, action_text):
+    """未保存の変更があれば「保存 / 保存しない / キャンセル」を尋ねる。続けてよければ True。"""
+    if not _unsaved_changes_prompt_enabled() or not app.has_unsaved_changes():
+        return True
+    name = app.document_title()
+    box = QMessageBox(app)
+    box.setIcon(QMessageBox.Icon.Warning)
+    box.setWindowTitle("保存されていない変更")
+    box.setText(f"「{name}」には保存されていない変更があります。")
+    box.setInformativeText(f"{action_text}前に保存しますか?")
+    save_button = box.addButton("保存", QMessageBox.ButtonRole.AcceptRole)
+    discard_button = box.addButton("保存しない", QMessageBox.ButtonRole.DestructiveRole)
+    cancel_button = box.addButton("キャンセル", QMessageBox.ButtonRole.RejectRole)
+    box.setDefaultButton(save_button)
+    box.setEscapeButton(cancel_button)
+    box.exec()
+    clicked = box.clickedButton()
+    if clicked is discard_button:
+        return True
+    if clicked is save_button:
+        app.manual_save()
+        return not app.has_unsaved_changes()
+    return False
+
+
+def auto_save(app):
+    try:
+        app._sync_project_from_ui()
+        app._rotate_autosave_generations()
+        app.project.save_project(app._autosave_filename)
+        app.statusBar().showMessage("オートセーブ完了", 3000)
+    except Exception as e:
+        logger.exception("オートセーブに失敗しました")
+        app.statusBar().showMessage(f"オートセーブ失敗: {e}", 3000)
+
+
+def manual_save(app):
+    """保存先が分かっていればそこへ上書きし、無ければ「名前を付けて保存」にする。"""
+    if not app._current_project_path:
+        app.manual_save_as()
+        return
+    app._save_project_to_path(app._current_project_path)
+
+
+def manual_save_as(app):
+    filepath, _ = notify.get_save_file_name(
+        app, "名前を付けて保存", "", f"Graphica Project (*{PROJECT_FILE_EXTENSION})"
+    )
+    if filepath:
+        # 拡張子を付けないファイルダイアログがある
+        if os.path.splitext(filepath)[1].lower() not in PROJECT_FILE_EXTENSIONS:
+            filepath += PROJECT_FILE_EXTENSION
+        app._save_project_to_path(filepath)
+
+
+def save_project_to_path(app, filepath):
+    try:
+        app._sync_project_from_ui()
+        app.project.save_project(filepath)
+        app._current_project_path = filepath
+        app._restored_unsaved = False
+        app._saved_content_fingerprint = app.project.content_fingerprint()
+        app.statusBar().showMessage(f"保存しました: {filepath}", 3000)
+        app._add_recent_file(filepath)
+        app.project_state_changed.emit()
+    except Exception as e:
+        logger.exception("プロジェクトの保存に失敗しました: %s", filepath)
+        notify.critical(app, "エラー", f"保存に失敗しました:\n{e}")
+
+
+def project_file_filter():
+    return "Graphica Project (" + " ".join(f"*{ext}" for ext in PROJECT_FILE_EXTENSIONS) + ")"
+
+
+def manual_load(app):
+    if not app.confirm_unsaved_changes("別のプロジェクトを開く"):
+        return
+    filepath, _ = notify.get_open_file_name(
+        app, "プロジェクトを開く", "", project_file_filter()
+    )
+    if filepath:
+        app._load_project_from_path(filepath)
+
+
+def load_project_from_path(app, filepath, add_to_recent=True):
+    """add_to_recent=False はオートセーブからの復元。最近使ったファイルに載せず、上書き保存の対象にもしない。"""
+    try:
+        app.project.load_project(filepath)
+        # 中身はもう入れ替わっている。この先で失敗したとき前のファイルが保存先に
+        # 残っていると、上書き保存でそのファイルを別の内容で壊してしまう。
+        app._current_project_path = None
+        app._saved_content_fingerprint = None
+        app._restored_unsaved = False
+
+        app._rebuild_dataset_tree_widget()
+
+        app._block_all_signals(True)
+        app.subplot_rows_spinbox.setValue(app.project.layout_rows)
+        app.subplot_cols_spinbox.setValue(app.project.layout_cols)
+        is_free_layout = getattr(app.project, 'layout_mode', 'grid') == 'free'
+        app.free_layout_checkbox.setChecked(is_free_layout)
+        app.subplot_rows_spinbox.setEnabled(not is_free_layout)
+        app.subplot_cols_spinbox.setEnabled(not is_free_layout)
+        app.add_free_subplot_button.setEnabled(is_free_layout)
+        app.remove_free_subplot_button.setEnabled(is_free_layout)
+        app.layout_edit_action.setEnabled(is_free_layout)
+        if not is_free_layout and app.layout_edit_action.isChecked():
+            app.layout_edit_action.setChecked(False)
+            app._toggle_layout_edit_mode(False)
+        app.panel_labels_action.setChecked(app.project.panel_labels_enabled)
+        app.share_x_checkbox.setChecked(getattr(app.project, 'share_x_axis', False))
+        app.share_y_checkbox.setChecked(getattr(app.project, 'share_y_axis', False))
+        app.share_x_checkbox.setEnabled(not is_free_layout)
+        app.share_y_checkbox.setEnabled(not is_free_layout)
+        app._block_all_signals(False)
+
+        if app.project.all_plot_settings:
+            app._apply_settings_to_ui_controls(
+                app.project.all_plot_settings[app.project.active_axis_index]
+            )
+
+        # 前の文書へのコマンドは datasets をリストごと差し戻すので、残すと
+        # Undo 1回で読み込んだ内容が前の文書に置き換わる。
+        app.undo_stack.clear()
+
+        app.property_panel.update_ui_state()
+        app._update_plot()
+
+        app.statusBar().showMessage("プロジェクトを読み込みました", 3000)
+        if add_to_recent:
+            app._add_recent_file(filepath)
+            app._current_project_path = filepath
+            app._remember_saved_content()
+        else:
+            app._restored_unsaved = True
+        app.project_state_changed.emit()
+    except Exception as e:
+        logger.exception("プロジェクトの読み込みに失敗しました: %s", filepath)
+        notify.critical(app, "エラー", f"読み込みに失敗しました:\n{e}")
+
+
+def get_recent_files(app):
+    return app_settings.as_list_keeping_empty_string(app_settings.RECENT_FILES.read(app.settings))
+
+
+def add_recent_file(app, file_path):
+    file_path = os.path.abspath(file_path)
+    files = app._get_recent_files()
+    if file_path in files:
+        files.remove(file_path)
+    files.insert(0, file_path)
+    files = files[:MAX_RECENT_FILES]
+    app_settings.RECENT_FILES.write(app.settings, files)
+    app._update_recent_files_menu()
+
+
+def update_recent_files_menu(app):
+    try:
+        app.recent_files_menu.clear()
+        files = app._get_recent_files()
+
+        if not files:
+            empty_action = app.recent_files_menu.addAction(tr("(履歴なし)"))
+            empty_action.setEnabled(False)
+            return
+
+        for file_path in files:
+            action = app.recent_files_menu.addAction(file_path)
+            action.triggered.connect(lambda checked=False, p=file_path: app._on_open_recent_file(p))
+
+        app.recent_files_menu.addSeparator()
+        clear_action = app.recent_files_menu.addAction(tr("履歴をクリア"))
+        clear_action.triggered.connect(app._on_clear_recent_files)
+    except RuntimeError:
+        # まれにメニューの C++ 側が破棄済みのことがある(PySide6 の回収、原因は未特定)。表示が古いだけなので落とさない
+        logger.warning("recent_files_menuの更新に失敗しました(既に破棄されている可能性があります)。", exc_info=True)
+
+
+def on_open_recent_file(app, file_path):
+    if not os.path.exists(file_path):
+        notify.warning(app, "エラー", f"ファイルが見つかりません:\n{file_path}")
+        files = app._get_recent_files()
+        if file_path in files:
+            files.remove(file_path)
+            app_settings.RECENT_FILES.write(app.settings, files)
+            app._update_recent_files_menu()
+        return
+
+    # .pkl は開けないが、データとして読ませずに「対応していない」と知らせる
+    if file_path.lower().endswith(PROJECT_FILE_EXTENSIONS + (LEGACY_PICKLE_EXTENSION,)):
+        if not app.confirm_unsaved_changes("別のプロジェクトを開く"):
+            return
+        app._load_project_from_path(file_path)
+    else:
+        app.load_data(file_path)
+
+
+def on_clear_recent_files(app):
+    app_settings.RECENT_FILES.write(app.settings, [])
+    app._update_recent_files_menu()

graphica/gui/provenance_panel.py

@@ -0,0 +1,65 @@
+"""選んだデータセットの処理の履歴をツリーで見せるドック。
+
+操作の下にその元のデータセットを置き、元にも履歴があれば祖先まで辿る。元が消されていれば「(削除済み)」で止める
+(履歴が親の ID だけでなく名前も持つのはこのため)。
+"""
+from PySide6.QtWidgets import QWidget, QVBoxLayout, QLabel, QTreeWidget, QTreeWidgetItem
+
+from graphica.core.methods_text import describe_operation
+
+
+class ProvenancePanel(QWidget):
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(4, 4, 4, 4)
+
+        self.placeholder_label = QLabel(
+            "処理履歴(フィット・ベースライン補正・平滑化等で生成された\n"
+            "データセット)を選択すると、ここに処理の流れが表示されます。"
+        )
+        self.placeholder_label.setWordWrap(True)
+        self.placeholder_label.setStyleSheet("color: gray; padding: 12px;")
+        layout.addWidget(self.placeholder_label)
+
+        self.tree = QTreeWidget()
+        self.tree.setHeaderHidden(True)
+        layout.addWidget(self.tree)
+        self.tree.setVisible(False)
+
+    def refresh(self, dataset, project):
+        """dataset は None でもよい。project は祖先を辿るのに使う。"""
+        self.tree.clear()
+        if dataset is None:
+            self.tree.setVisible(False)
+            self.placeholder_label.setVisible(True)
+            return
+
+        self.placeholder_label.setVisible(False)
+        self.tree.setVisible(True)
+
+        root_item = QTreeWidgetItem([dataset.name])
+        self.tree.addTopLevelItem(root_item)
+        self._add_provenance_children(root_item, dataset, project, frozenset())
+        self.tree.expandAll()
+
+    def _add_provenance_children(self, parent_item, dataset, project, visited):
+        """dataset を作った操作と元のデータセットを parent_item の下に足し、元も辿る。visited で循環を止める。"""
+        if dataset is None or not dataset.provenance or dataset.dataset_id in visited:
+            return
+        visited = visited | {dataset.dataset_id}
+
+        operation_item = QTreeWidgetItem([describe_operation(dataset.provenance)])
+        parent_item.addChild(operation_item)
+
+        source_ids = dataset.provenance.get('source_dataset_ids') or []
+        source_names = dataset.provenance.get('source_dataset_names') or []
+        for i, source_id in enumerate(source_ids):
+            source_dataset = next((ds for ds in project.datasets if ds.dataset_id == source_id), None)
+            fallback_name = source_names[i] if i < len(source_names) else "不明"
+            if source_dataset is None:
+                operation_item.addChild(QTreeWidgetItem([f"{fallback_name}(削除済み)"]))
+                continue
+            source_item = QTreeWidgetItem([source_dataset.name])
+            operation_item.addChild(source_item)
+            self._add_provenance_children(source_item, source_dataset, project, visited)

graphica/gui/rendering/__init__.py

@@ -0,0 +1 @@
+"""キャンバスの描画の部品。MplCanvas はこれらを組み合わせて描く。"""

graphica/gui/rendering/annotations.py

@@ -0,0 +1,177 @@
+"""注釈(文字・矢印・統計ラベル・範囲の強調・拡大図)とパネルラベルの描画。作り直しを省く鍵もここで作る。"""
+import json
+import logging
+import numpy as np
+from graphica.core.analysis import calculate_lttb_downsample
+from graphica.core.axis_settings import axis_setting
+from graphica.gui.mathtext_preview import JP_CAPABLE_FONT_FAMILIES, families_for_text
+from graphica.gui.rendering.common import (
+    DARK_TEXT_COLOR, LIGHT_TEXT_COLOR, LTTB_DOWNSAMPLE_TARGET_POINTS, LTTB_DOWNSAMPLE_THRESHOLD,
+    REGION_HIGHLIGHT_DEFAULT_ALPHA, REGION_HIGHLIGHT_DEFAULT_COLOR, _ARROW_STYLE_MAP, _INSET_CORNER_ORIGINS,
+    _NO_KEY, _compute_stat_label_text)
+from mpl_toolkits.axes_grid1.inset_locator import mark_inset
+
+logger = logging.getLogger(__name__)
+
+
+def draw_panel_label(canvas, ax, index):
+    """軸の左上に (a)(b)(c)… を描く。文字は保存せず並び順から毎回決めるので、並べ替えても振り直される。"""
+    label = canvas._panel_label_for_index(index)
+    text_color = DARK_TEXT_COLOR if canvas.dark_mode else LIGHT_TEXT_COLOR
+    ax.text(
+        -0.12, 1.08, f"({label})", transform=ax.transAxes,
+        fontsize=12, fontweight='bold', color=text_color,
+        ha='left', va='top', zorder=10,
+    )
+
+
+def panel_label_for_index(index):
+    """0->a, …, 25->z, 26->aa, 27->ab, …(Excel の列名と同じ)"""
+    letters = []
+    n = index
+    while True:
+        n, remainder = divmod(n, 26)
+        letters.append(chr(ord('a') + remainder))
+        if n == 0:
+            break
+        n -= 1
+    return ''.join(reversed(letters))
+
+
+def downsample_for_inset(canvas, x_data, y_data, full_resolution=False):
+    """
+    拡大図の点列を本体と同じく LTTB で間引く(注釈は描き直しのたびに作り直すので、大きなデータで重くなる)。
+    拡大図は種類に関わらず線で描くので、散布図を除く本体の条件は当てはまらない。X が昇順のときだけ間引く。
+    """
+    if full_resolution or len(x_data) <= LTTB_DOWNSAMPLE_THRESHOLD:
+        return x_data, y_data
+    if not np.all(np.diff(x_data) >= 0):
+        return x_data, y_data
+    indices = calculate_lttb_downsample(x_data, y_data, LTTB_DOWNSAMPLE_TARGET_POINTS)
+    return x_data[indices], y_data[indices]
+
+
+def annotation_render_key(canvas, axis_index, settings, datasets, full_resolution):
+    """
+    注釈の描き直しを省くかどうかのキー。描いた結果に影響するものを全部入れる:
+    ダークモード(色が変わる)、統計値ラベルの計算後の文字列、拡大図が描くデータセットの色・線幅・透明度・表示。
+    拡大図のデータそのものは入れない。これを使う update_appearance_only はデータが変わっていない前提の経路
+    (データが変わる操作は cla() する別の経路を通り、そこでは使い回さない)。
+    """
+    annotations = axis_setting(settings, 'annotations')
+    parts = [bool(canvas.dark_mode), bool(full_resolution), len(annotations)]
+    if not annotations:
+        return json.dumps(parts, default=str)
+
+    datasets_by_id = {ds.dataset_id: ds for ds in (datasets or ())}
+    for ann in annotations:
+        parts.append(json.dumps(ann, sort_keys=True, default=str))
+        ann_type = ann.get('type')
+        if ann_type == 'stat':
+            dataset = datasets_by_id.get(ann.get('dataset_id'))
+            parts.append(_compute_stat_label_text(dataset, ann.get('stat')))
+        elif ann_type == 'inset':
+            for target_ds in (datasets or ()):
+                if target_ds.subplot_target != axis_index or not target_ds.visible:
+                    continue
+                parts.append((target_ds.dataset_id, target_ds.color,
+                              target_ds.linewidth, target_ds.alpha))
+    return json.dumps(parts, default=str)
+
+
+def draw_annotations(canvas, ax, axis_index, settings, datasets=None, full_resolution=False,
+                      allow_reuse=False):
+    """
+    軸の注釈(テキスト・矢印・領域ハイライト・統計値ラベル・拡大図)を、前回の分を消してから描く。
+
+    allow_reuse=True なら、内容が前回と同じとき描き直しを省く(拡大図はデータを描き直すので重い)。
+    使ってよいのは update_appearance_only() だけ。ほかの経路は前回の artist が既に消えている
+    (fig.clf() / ax.cla() / 新しい軸)ので、使い回すと注釈が消える。既定は False。
+    datasets は統計値ラベルと拡大図が使う(省略すると「データセットなし」)。
+    """
+    render_key = canvas._annotation_render_key(axis_index, settings, datasets, full_resolution)
+    if allow_reuse and canvas._annotation_render_keys.get(axis_index, _NO_KEY) == render_key:
+        return
+
+    for artist in canvas._annotation_artists.get(axis_index, []):
+        try:
+            artist.remove()
+        except (ValueError, NotImplementedError):
+            pass
+
+    datasets_by_id = {ds.dataset_id: ds for ds in (datasets or ())}
+
+    new_artists = []
+    for ann in axis_setting(settings, 'annotations'):
+        ann_type = ann.get('type')
+        text = ann.get('text', '')
+        try:
+            if ann_type == 'arrow':
+                color = canvas._effective_text_color(ann.get('color', '#000000'))
+                arrowstyle = _ARROW_STYLE_MAP.get(ann.get('arrow_style', 'single'), '->')
+                curvature = ann.get('arrow_curvature', 0.0)
+                arrow_props = dict(arrowstyle=arrowstyle, color=color)
+                if curvature:
+                    arrow_props['connectionstyle'] = f'arc3,rad={curvature}'
+                artist = ax.annotate(
+                    text, xy=ann['xy'], xytext=ann['xytext'],
+                    arrowprops=arrow_props,
+                    color=color, fontsize=9, family=families_for_text(text, JP_CAPABLE_FONT_FAMILIES)
+                )
+            elif ann_type in ('vspan', 'hspan'):
+                # 利用者が選んだ色をそのまま使う(ダークモードの読み替えはしない)
+                lo, hi = ann.get('range', (0, 0))
+                color = ann.get('color', REGION_HIGHLIGHT_DEFAULT_COLOR)
+                alpha = ann.get('alpha', REGION_HIGHLIGHT_DEFAULT_ALPHA)
+                if ann_type == 'vspan':
+                    artist = ax.axvspan(lo, hi, color=color, alpha=alpha, zorder=0.5)
+                else:
+                    artist = ax.axhspan(lo, hi, color=color, alpha=alpha, zorder=0.5)
+            elif ann_type == 'inset':
+                # 拡大図は、種類やグラデーションは再現せず、範囲内の点を線で結ぶだけの概観
+                x0, y0 = _INSET_CORNER_ORIGINS.get(ann.get('corner', '右上'), (0.55, 0.55))
+                size = ann.get('size', 0.4)
+                x_min, x_max = ann.get('zoom_x_range', (0, 1))
+                color = canvas._effective_text_color(ann.get('color', '#000000'))
+                inset_ax = ax.inset_axes((x0, y0, size, size))
+                for target_ds in (datasets or ()):
+                    if target_ds.subplot_target != axis_index or not target_ds.visible:
+                        continue
+                    tx = np.asarray(target_ds.x_data, dtype=float)
+                    ty = np.asarray(target_ds.y_data, dtype=float)
+                    in_range = (tx >= x_min) & (tx <= x_max)
+                    if in_range.any():
+                        inset_x, inset_y = canvas._downsample_for_inset(
+                            tx[in_range], ty[in_range], full_resolution=full_resolution
+                        )
+                        inset_ax.plot(inset_x, inset_y, color=target_ds.color,
+                                      linewidth=target_ds.linewidth, alpha=target_ds.alpha)
+                inset_ax.set_xlim(x_min, x_max)
+                inset_ax.tick_params(labelsize=7)
+                pp, p1, p2 = mark_inset(ax, inset_ax, loc1=ann.get('loc1', 2), loc2=ann.get('loc2', 4),
+                                        fc="none", ec=color)
+                new_artists.extend([inset_ax, pp, p1, p2])
+                artist = None
+            elif ann_type == 'stat':
+                # 軸に対する位置なので、拡大・移動しても同じ場所に留まる
+                color = canvas._effective_text_color(ann.get('color', '#000000'))
+                xy = ann.get('xy', (0.05, 0.95))
+                dataset = datasets_by_id.get(ann.get('dataset_id'))
+                label_text = _compute_stat_label_text(dataset, ann.get('stat'))
+                artist = ax.text(
+                    xy[0], xy[1], label_text, transform=ax.transAxes,
+                    color=color, fontsize=9, family=families_for_text(label_text, JP_CAPABLE_FONT_FAMILIES),
+                    va='top', ha='left', zorder=10,
+                )
+            else:
+                color = canvas._effective_text_color(ann.get('color', '#000000'))
+                xy = ann.get('xy', (0, 0))
+                artist = ax.text(xy[0], xy[1], text, color=color, fontsize=9,
+                                 family=families_for_text(text, JP_CAPABLE_FONT_FAMILIES))
+            if artist is not None:
+                new_artists.append(artist)
+        except Exception:
+            logger.exception("注釈の描画に失敗しました: %s", ann)
+    canvas._annotation_artists[axis_index] = new_artists
+    # 使い回さない経路でもキーは更新する(直後の update_appearance_only が無駄に描き直さないように)
+    canvas._annotation_render_keys[axis_index] = render_key