Metadata-Version: 2.4
Name: graphica-plot
Version: 2.0.0
Summary: PySide6 + matplotlib によるデータプロット・解析デスクトップアプリケーション
Author: STsuruga
License-Expression: MIT
Project-URL: Homepage, https://github.com/STsuruga/Graphica
Project-URL: Changelog, https://github.com/STsuruga/Graphica/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/STsuruga/Graphica/issues
Keywords: plotting,matplotlib,PySide6,data-visualization,curve-fitting
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: Microsoft :: Windows
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Environment :: X11 Applications :: Qt
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_LICENSES.md
Requires-Dist: PySide6<6.12,>=6.9
Requires-Dist: matplotlib<3.12,>=3.10
Requires-Dist: numpy<3,>=2.0
Requires-Dist: pandas<3,>=2.2
Requires-Dist: scipy<2,>=1.13
Requires-Dist: openpyxl<4,>=3.1
Requires-Dist: xlrd<3,>=2.0
Provides-Extra: dev
Requires-Dist: pytest==9.1.1; extra == "dev"
Requires-Dist: ruff==0.16.8; extra == "dev"
Requires-Dist: mypy==2.3.1; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller==6.16.0; extra == "build"
Dynamic: license-file

# Graphica

**日本語** | [English](https://github.com/STsuruga/Graphica/blob/master/README.en.md)

**CSV / Excel の測定データから、論文や報告書に載せられるグラフを作るデスクトップアプリです。**
曲線フィット、ピーク検出、ベースライン補正などの解析もアプリの中で完結します(Windows / macOS、無料・オープンソース)。

A desktop app for turning CSV/Excel measurement data into publication-quality plots, with curve fitting, peak detection and baseline correction built in (Windows / macOS, free and open source). The interface is in Japanese, with an English option for the main menus and dialogs.

[![Release](https://img.shields.io/github/v/release/STsuruga/Graphica)](https://github.com/STsuruga/Graphica/releases/latest)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/STsuruga/Graphica/blob/master/LICENSE)
[![Coverage report](https://img.shields.io/badge/coverage-report-brightgreen.svg)](https://stsuruga.github.io/Graphica/coverage/)

![Graphica のメイン画面](https://github.com/STsuruga/Graphica/raw/master/Graphica_project/docs/images/main_window.png)

- **ダウンロード**: [最新版(Releases)](https://github.com/STsuruga/Graphica/releases/latest) から、Windows / macOS の zip を入手できます(インストール不要)。
- **使い方**: [Wiki](https://github.com/STsuruga/Graphica/wiki) に、最初のグラフを作るチュートリアルから解析機能まで、画面写真付きでまとめています。
- **不具合の報告・要望**: [Issues](https://github.com/STsuruga/Graphica/issues/new/choose) / 開発に参加する方は [CONTRIBUTING.md](https://github.com/STsuruga/Graphica/blob/master/CONTRIBUTING.md)

---

# 取扱説明書

## 1. 概要

Graphica は、CSV/Excel などのファイルからデータを読み込み、グラフを作成・編集・エクスポートするためのソフトウェアです。複数のデータセットの同時表示、サブプロット、曲線フィット、ピーク検出、ベースライン補正、データ編集など、科学技術分野でのデータ可視化に役立つ多くの機能を備えています。

**操作方法の詳しい説明(画面写真付き)は [Wiki](https://github.com/STsuruga/Graphica/wiki) にまとめています。** この README は機能の概要と、入手・開発の手順を扱います。

バージョン番号は、ヘルプメニューの「Graphica について...」で確認できます。

---

## 2. 基本的な使い方

### 2.1 ファイルの読み込み

1.  **ファイル ▸ データファイルを開く**、または画面下部のボタン列にある **「データ追加」** を押します。ファイルをウィンドウへドラッグ&ドロップしても読み込めます(複数ファイル可)。
2.  読み込めるファイルは次のとおりです。
    * **CSV / テキスト** (`.csv` / `.txt`): 文字コード(UTF-8 / Shift_JIS など)と区切り文字(カンマ / タブ / セミコロン / 空白)を自動で判定します。
    * **Excel** (`.xlsx` / `.xls`): 複数のシートがある場合は、読み込むシートを選べます(複数シートの一括読み込みも可)。
3.  列の選択ダイアログでデータのプレビューを確認し、X軸・Y軸に使う列を選びます。自動判定が合わない場合は、ここで文字コード・区切り文字・ヘッダー行を変更できます。
4.  読み込んだデータは「データセットリスト」に追加され、グラフが描画されます。大きなファイルでも画面が固まらないよう、読み込みはバックグラウンドで行われます。

このほか、**ファイル ▸ クリップボードから貼り付け** や **ファイル ▸ フォルダから一括インポート** でも読み込めます。

### 2.2 画面構成

* **中央上**: グラフ。上部のツールバーの左側が拡大/移動/保存などの標準ボタン、右側がデータカーソル・注釈・範囲選択などのマウスモードです。グラフの下には全体を見渡すミニマップ(レンジスライダー)があります。
* **中央下**: データセットの検索欄とデータセットリスト(目のアイコンで表示/非表示)、選択中データの要約(件数・平均・SD)、その下にデータ追加・削除・複製・データ編集・曲線フィット・ピーク検出などのボタン列があります。
* **右側**: 「プロパティ」ドック。上半分の「データセットのプロパティ」で選択中のデータセットの見た目を、下半分の「プロットのプロパティ」でグラフ全体(軸・ラベル・凡例など)を設定します。

### 2.3 データセットの操作

* **削除**: データセットリストで項目を選び、「データ削除」ボタンを押します(`Ctrl+Z` で元に戻せます)。フォルダを削除すると中身もまとめて削除されます。
* **複製**: 「プロット複製」ボタンで、同じデータを持つコピーを追加します。同じファイルの別の列を並べて描くときに便利です。
* **複数選択**: `Ctrl`/`Shift` を押しながらクリックすると複数選択でき、色・線種などの変更をまとめて適用できます。
* **並べ替え**: リスト上でドラッグ&ドロップすると描画順(前面/背面)が変わります。
* **右クリックメニュー**(メニューバーの **データセット** と同じ内容): データ処理(規格化・平滑化・ベースライン補正・積分など)、解析・注釈、エクスポート、別のタブへのコピー/移動などを実行できます。

### 2.4 フォルダによるグループ分け

* 「新しいフォルダ」ボタン、またはリストの右クリック ▸ 「新しいフォルダ」でフォルダを作成します。
* データセットやフォルダをドラッグ&ドロップでフォルダの中へ移動できます(入れ子にも対応)。
* フォルダはリスト上の整理のためのもので、グラフには影響しません。

---

## 3. グラフ全体の外観(プロットのプロパティ)

右側の「プロパティ」ドック下半分の「プロットのプロパティ」で、「編集対象のプロット」で選んだサブプロットの外観を設定します。

### 3.1 X軸 / Y軸 タブ

* **範囲**: 最小値・最大値を指定します。「自動スケール」にチェックを入れるとデータに合わせて自動調整されます。`1e-5` のような指数表記でも入力できます。
* **表示**: 「対数表示」でログスケールに、「軸を反転」で軸の向きを逆にします。
* **目盛**: 主目盛は「自動」または「固定間隔」、補助目盛は表示の有無と間隔を指定します。目盛り表記(指数表記の方式)、小数桁数、目盛/目盛の数値の表示も軸ごとに設定できます。
* **第2Y軸**(Y軸タブの下): 右側の第2Y軸にも、範囲(自動スケール・最小値・最大値)・対数表示・反転・主目盛と補助目盛を設定できます。
  既定はデータに合わせた自動です。第2Y軸を使うデータセットは、プロパティの「第2Y軸 (右側) を使用」で選びます。
* **単位変換の第2X軸**(X軸タブ): X軸の単位(nm / eV / cm⁻¹ / Hz)を指定すると、上部に別の単位の軸を追加できます。

### 3.2 ラベル/書式 タブ

* **ラベル**: タイトル・X軸/Y軸/第2Y軸ラベルを入力します。「Aa」ボタンで太字・斜体・上付き/下付き・記号の入力を補助するダイアログが開きます。`$\alpha$` のような mathtext 記法も使えます(ヘルプ ▸ mathtext リファレンス)。
* **目盛**: 目盛数値と軸ラベルのフォント・色、目盛の向き(主/補助)、太さ、長さを設定します。
    * **目盛の長さ**: 主目盛と補助目盛の線の長さを pt で指定します(既定は主目盛 3.5pt)。補助目盛を「自動」にすると、主目盛の長さの約0.57倍(matplotlib の既定と同じ比率)になり、主目盛を変えるだけで補助目盛もつられて伸び縮みします。長さは物理サイズ(pt)なので、大きいサイズでエクスポートすると文字や線と同じくグラフに対しては相対的に小さくなります。
* **凡例**: 表示/非表示、位置、フォント、文字色、並び順を設定します。凡例は**マウスでドラッグして移動でき、移動した位置は保存されます**(「凡例の位置」を選び直すと、その位置に戻ります)。
* **グリッド**: 主グリッド/補助グリッドの表示と、X軸/Y軸・主/補助ごとの線種・太さ・透明度を設定します。
* **外枠・カラーバー**: 枠線の太さと色、2Dマップ用のカラーバーを設定します。

### 3.3 レイアウト(サブプロット)

「プロットのプロパティ」上部で行数・列数を指定するとサブプロットを並べられます。自由配置レイアウトにすると、ツールバーの「レイアウト編集」でサブプロットをドラッグして配置できます。**表示 ▸ パネルラベルを自動表示** で (a)(b)(c) を付けられます。

### 3.4 ダークモード

**表示 ▸ ダークモード** で、アプリ全体とグラフの配色がダークテーマに切り替わります。エクスポートする画像にもこの配色が反映される点に注意してください。

---

## 4. データセットの個別設定(データセットのプロパティ)

右側の「プロパティ」ドック上半分で、データセットリストで選択中のデータセットを設定します。7つの区分(データ列 / 基本スタイル / グラデーション / ウォーターフォール / 2Dマップ・値による配色 / 表示の追加要素 / 配置・情報)に分かれており、見出しをクリックして開閉できます。複数選択している場合は、変更した項目だけが選択中の全データセットに適用されます。

* **データ列**: X軸/Y軸の列、X/Y誤差列(エラーバー)、欠損値の扱い。
* **基本スタイル**: 凡例名、種別(`Line` / `Scatter` / `Line+Scatter` / `Area` / `Bar` / `Step` / `Density Scatter` / `Z-Color Scatter`)、色、線の種類と太さ、マーカー、透明度、平滑化。
    * **色**: 色見本を押すとメニューが開き、名前を付けて登録した色から選んだり、色を登録したりできます(「その他の色...」で自由に選択)。
* **グラデーション / ウォーターフォール**: 線や塗りのグラデーション、複数のトレースを少しずつずらして重ねる表示。
* **2Dマップ・値による配色**: ヒートマップ/等高線表示、カラーマップ、値域。
* **表示の追加要素**: データ点ラベル、誤差の表示形式(エラーバー/誤差バンド)。データ点ラベルは、点数が環境設定の上限(既定 1,000件)を超えると表示されません(描画が非常に重くなるため)。その場合はチェックボックスの下に理由が表示されます。
* **配置・情報**: 第2Y軸(右側)の使用、描画先のサブプロット、フィット結果の情報。

これらの変更は **編集 ▸ 元に戻す / やり直し** (`Ctrl+Z` / `Ctrl+Y`) で取り消せます。

---

## 5. 高度な機能

### 5.1 データ編集(「データ表示/編集」ボタン)

データを表形式で表示・編集するウィンドウが開きます。セルの直接編集(空にすると `NaN`)、行・列の追加/削除、列名の変更、**列の計算**(`A + B * 2` や `log(A)` のような式、移動平均・差分・正規化などのプリセット。**ヘルプ ▸ 列計算機能 リファレンス**)、CSV への保存ができます。セル編集や行列操作は `Ctrl+Z` / `Ctrl+Y` で元に戻せます。

### 5.2 曲線フィット(「曲線フィット」ボタン)

線形・多項式・指数・ガウシアンなどのモデル、またはユーザー定義の式でフィットします。パラメータの初期値・固定・範囲を指定でき、結果(パラメータ、R² など)は別ウィンドウに表示され、コピーや CSV 保存ができます。フィット曲線は破線のデータセットとして追加されます。重なったピークの分離には「多峰フィット」ボタンとツールバーの「ピーク配置」モードを使います。

### 5.3 ピーク検出(「ピーク検出」ボタン)

上に凸/下に凸、最小高さ・最小距離・突出度を指定してピーク(谷)を検出し、位置にマーカーのデータセットを追加します。検出結果の一覧はコピーや CSV 保存ができます。

### 5.4 データ処理・解析

データセットの右クリックメニュー(または **データセット** メニュー)から、規格化、Savitzky-Golay フィルタ、ベースライン補正、区間積分/累積積分、リサンプリング、外れ値検出、ヒストグラム/KDE などを実行できます。多くの処理は元のデータを残したまま、結果を新しいデータセットとして追加します。統計量(件数・平均・SD など)は、ツールバーの「統計情報」ボタンやリスト下の要約で確認できます。標準偏差はすべて標本標準偏差(n−1 で割る)で計算します。

### 5.5 データカーソル(ツールバーの「データカーソル」)

グラフ上部のツールバー右側にある「データカーソル」を押して有効にすると、マウス位置の座標がステータスバーに表示され、線や点をクリックするとその点の (X, Y) が吹き出しで表示されます。もう一度押すと無効になります。

### 5.6 プラグイン

プラグインで、読み込み/書き出し形式、データ処理・解析、曲線フィットの関数、パネルなどを追加できます。

* **インストール**: **編集 ▸ 環境設定** の「プラグイン」タブで「プラグインをインストール...」を押し、プラグインの zip ファイルを選びます。プラグインはユーザーごとのフォルダ(Windows では `%LOCALAPPDATA%\Graphica\plugins`)に展開されます。インストール後は Graphica を再起動してください。
* **管理**: 同じタブで、読み込まれているプラグインの一覧・有効/無効の切り替え・エラー内容の確認ができます。
* **トラブル時**: `--safe-mode` を付けて起動すると、プラグインを読み込まずに起動します(7.2 参照)。
* **プラグイン開発**: 作り方は [`Graphica_project/docs/plugin_development.md`](https://github.com/STsuruga/Graphica/blob/master/Graphica_project/docs/plugin_development.md) を参照してください。

---

## 6. ファイル操作(メニューバー)

### 6.1 ファイル メニュー

* **データファイルを開く / クリップボードから貼り付け / フォルダから一括インポート**: データの読み込み(2.1 参照)。
* **プロジェクトを開く** (`Ctrl+O`): `.gra` プロジェクトファイル(以前の拡張子 `.graphica` も可)を読み込み、データ・フォルダ構成・グラフ設定を復元します。プロジェクトファイルをウィンドウへドラッグ&ドロップしても開けます(開くのは 1 つだけで、一緒に落としたデータファイルはそのプロジェクトに加わります)。
* **上書き保存** (`Ctrl+S`) / **名前を付けて保存** (`Ctrl+Shift+S`): 現在の状態を `.gra` ファイルに保存します。
* **保存していない変更の確認**: 保存していない変更があるときに、タブを閉じる・Graphica を終了する・別のプロジェクトを開く操作をすると、「保存 / 保存しない / キャンセル」を尋ねます。
* **最近使ったファイル / スタートアップ画面**: 直近のファイルをすばやく開き直せます。
* **書式テンプレートを保存 / 適用**: グラフの外観設定だけ(データは含まない)を `.graphica-style` ファイルとして保存・適用します。
* **エクスポート** サブメニュー:
    * **名前を付けてエクスポート**: 画像(PNG)・PDF・SVG として保存します。サイズや解像度、背景の透過、SVG の文字のパス化などを指定できます。PDF にはフォントを TrueType として埋め込みます(Illustrator などで文字を編集できます)。
    * **グラフをコピー / 印刷 / バッチエクスポート / Pythonスクリプトとしてエクスポート / LaTeX/Word用キャプションを生成 / 実験レポートを生成 (HTML/PDF)**
* **オートセーブ**: 自動保存の間隔(分、0で無効)を設定します。自動保存は既定でユーザーごとのフォルダ(Windows では `%LOCALAPPDATA%\Graphica`)に保存され、保存先は環境設定で変更できます。**自動バックアップ履歴から復元** で過去の世代に戻せます。
* **設定・スタイルをエクスポート / インポート**: 環境設定やパレットなどを別の PC へ持ち運べます。

### 6.2 編集 メニュー

* **元に戻す / やり直し** (`Ctrl+Z` / `Ctrl+Y`)
* **環境設定**: ダークモード、オートセーブ、言語、データ点ラベルの表示上限、プラグインなど。
* **コマンドパレット** (`Ctrl+Shift+P`): メニュー項目を名前で検索して実行します。

### 6.3 表示 メニュー

* **プロパティパネル / エクスポートプレビュー / 残差プロット / 処理履歴**: 各パネルの表示/非表示。
* **ミニマップ(レンジスライダー) / キャンバスを別ウィンドウに切り離す / パネルラベルを自動表示 / 色覚シミュレーションプレビュー**
* **ドックレイアウト**: 現在のパネル配置の保存・読み込み・既定へのリセット。
* **クイックアクセスツールバー / ダークモード**

### 6.4 ヘルプ メニュー

* **mathtext リファレンス / 列計算機能 リファレンス / キーボードショートカット一覧**
* **診断情報をエクスポート**: 不具合報告用に、環境・設定・ログをまとめて書き出します。
* **アップデートを確認 / Graphica について**(バージョンとライセンス)

---

## 7. 入手とインストール

### 7.1 ビルド済みの実行ファイルを使う

[Releases](https://github.com/STsuruga/Graphica/releases) から、お使いのOSの
ファイルをダウンロードしてください。インストール作業は不要です。

* **Windows**: インストーラー(`Graphica-<版>-setup.exe`)で入れるか、zip を展開して中の `Graphica.exe` を実行します。
  インストーラーは管理者権限なしで入れられ、`.gra` と `.graphica` のファイルをダブルクリックで開けるようにします
  (アンインストールで元に戻ります)。zip から使う場合は、**編集 ▸ 環境設定** の「ファイルの関連付け」で同じ登録ができます。
* **ファイルを開いて起動**: プロジェクトファイルをダブルクリックすると Graphica が開きます。Graphica がすでに起動していれば、
  そのウィンドウの新しいタブで開きます。macOS では Finder から開くか、`Graphica.app` にドロップしてください。
* **macOS**: zip を展開し、`Graphica.app` を「アプリケーション」へ移動します。
  **署名していないため、初回は右クリック(またはControlキーを押しながらクリック)して
  「開く」を選んでください。** ダブルクリックだけでは Gatekeeper に阻まれます。
  なお配布している `.app` は Apple Silicon (arm64) 向けです。

### 7.2 pip で入れる

Python 3.10 以降があれば、PyPI からインストールできます。依存するライブラリも一緒に入ります
(ほかのソフトとぶつかりにくいよう、仮想環境に入れることをおすすめします)。

```
pip install graphica-plot
graphica
```

`graphica` はコンソール(黒い画面)を開かずに起動します。ログを画面で見たいときは `python -m graphica` で起動してください。
更新は同じコマンドに `--upgrade` を付けて、アンインストールは `pip uninstall graphica-plot` です。
PyPI の `graphica`(名前が同じ別のソフト)とは同じ環境に入れられません。

リリース前の最新版は GitHub から入れられます:
`pip install "git+https://github.com/STsuruga/Graphica.git#subdirectory=Graphica_project"`

### 7.3 ソースから実行する

Python 3.11 以降が必要です(`requirements.txt` は動作を確認した版に固定しています)。

```
git clone https://github.com/STsuruga/Graphica.git
cd Graphica/Graphica_project
pip install -r requirements.txt
python main.py
```

`python main.py --safe-mode`(配布版では `Graphica.exe --safe-mode`)で起動すると、**プラグインを読み込まずに**起動します。プラグインが原因で起動しない・動作がおかしいときの切り分けに使います。パネルの配置が崩れたときは、**表示 ▸ ドックレイアウト ▸ 既定のレイアウトにリセット** を使ってください(`--safe-mode` ではパネルの配置は元に戻りません)。

---

## 8. 開発者向け: 自動テストの実行

`tests/` ディレクトリに pytest ベースの自動テスト(約2,900件)を用意しています。
`core/` のデータ処理・曲線フィット・Undo/Redo・プロジェクトの保存/読込から、
GUI の配線や描画まで対象です。

```
pip install -r requirements.txt   # pytest を含む依存パッケージをインストール
bash scripts/run_tests_chunked.sh # フルスイート (Graphica_project ディレクトリで実行、約18分)
```

**フルスイートを `pytest` 一発で実行しないでください。** GUIテストが1プロセスに
Qt/matplotlib のリソースを溜め込むため、進むほど遅くなります。また
`tests/test_export_preview_panel.py` は全件パスした後の終了処理でクラッシュする
既知の問題があり、1プロセスにまとめるとそれ以降のテストが失われます。
上記のスクリプトはファイル単位でプロセスを分けて実行し、この2点を回避します。

個別のファイルやテストだけなら、そのまま pytest を使って問題ありません。

```
pytest tests/test_dataset.py
pytest tests/test_dataset.py::test_name -v
pytest tests/test_dataset.py -k waterfall
```

カバレッジを測る場合:

```
bash scripts/run_coverage.sh       # htmlcov/index.html と docs/COVERAGE.md・COVERAGE_DETAILS.md を生成
```

最新のカバレッジレポートは **https://stsuruga.github.io/Graphica/coverage/** で公開しています(master への push ごとに CI が自動更新)。

---

## 9. ライセンス

Graphica 本体は **MIT License** です(`LICENSE` を参照)。

配布している実行ファイルには、Qt/PySide6 をはじめとする第三者のライブラリが
同梱されています。**Qt/PySide6 は LGPL v3** です。同梱物の一覧と、再配布する
場合に必要な条件は `THIRD_PARTY_LICENSES.md` にまとめてあります。

---
