出力に関する要件
すべてのExcelファイル
プロフェッショナルなフォント
- 特にユーザーから指示がない限り、すべての成果物で一貫性のあるプロフェッショナルなフォント(例: Arial, Times New Roman)を使用する
ゼロ 数式エラー
- すべてのExcelモデルは、数式エラー(#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)がゼロの状態で納品すること
既存テンプレートの保持(テンプレート更新時)
- ファイルを変更する際は、既存の書式、スタイル、慣例を正確に調査し、それに合わせること
- 確立されたパターンを持つファイルに標準化された書式を押し付けてはいけない
- 既存のテンプレートの慣例が、これらのガイドラインよりも常に優先される
財務モデル
色分け標準
ユーザーまたは既存のテンプレートによって別途指示がない限り
業界標準の色に関する慣例
- 青色テキスト(RGB: 0,0,255): ハードコードされた入力値、およびユーザーがシナリオ用に変更する数値
- 黒色テキスト(RGB: 0,0,0): すべての数式と計算
- 緑色テキスト(RGB: 0,128,0): 同じワークブック内の他のワークシートからデータを参照するリンク
- 赤色テキスト(RGB: 255,0,0): 他のファイルへの外部リンク
- 黄色の背景(RGB: 255,255,0): 注意が必要な重要な仮定、または更新が必要なセル
数値書式標準
必須の書式ルール
- 年: 文字列として書式設定(例: "2024"、"2,024"としない)
- 通貨: $#,##0 形式を使用。ヘッダーで単位を常に指定すること(「Revenue ($mm)」)
- ゼロ: パーセンテージを含め、すべてのゼロを "-" と表示する数値書式を使用(例: "$#,##0;($#,##0);-")
- パーセンテージ: デフォルトで 0.0% 形式(小数点以下1桁)
- 倍数: バリュエーション倍率(EV/EBITDA, P/E)は 0.0x 形式
- 負の数: 括弧を使用 (123)、マイナス記号 -123 は使用しない
数式構築ルール
仮定の配置
- すべての仮定(成長率、マージン、倍率など)は、別の仮定セルに配置する
- 数式内ではハードコードされた値ではなくセル参照を使用する
- 例: =B51.05 ではなく =B5(1+$B$6) を使用
数式エラー防止
- すべてのセル参照が正しいことを確認する
- 範囲のオフバイワンエラーをチェックする
- すべての予測期間にわたって数式が一貫していることを確認する
- エッジケース(ゼロ値、負の数)でテストする
- 意図しない循環参照がないことを確認する
ハードコード値のドキュメント要件
- セルにコメントを付けるか、セルの隣(テーブル末尾の場合)に記述する。形式: 「出典: [システム/文書], [日付], [具体的な参照], [該当する場合はURL]」
- 例:
- 「出典: 有価証券報告書、2024年度、45ページ、収益注記、[EDGAR URL]」
- 「出典: 四半期報告書、2025年第2四半期、別紙99.1、[EDGAR URL]」
- 「出典: Bloomberg Terminal、2025/8/15、AAPL US Equity」
- 「出典: FactSet、2025/8/20、コンセンサス予想画面」
XLSXの作成、編集、分析
概要
ユーザーから .xlsx ファイルの作成、編集、または内容の分析を依頼される場合があります。タスクごとに利用可能なツールとワークフローが異なります。
重要な要件
数式再計算にはLibreOfficeが必要: LibreOfficeがインストールされていることを前提とし、scripts/recalc.py スクリプトを使用して数式値を再計算できます。このスクリプトは初回実行時にLibreOfficeを自動設定します。これには、Unixソケットが制限されたサンドボックス環境も含まれます(scripts/office/soffice.py で処理)。
データの読み取りと分析
pandasを使用したデータ分析
データ分析、可視化、および基本的な操作には、強力なデータ操作機能を提供する pandas を使用します。
import pandas as pd
# Excelを読み込む
df = pd.read_excel('file.xlsx') # デフォルト: 最初のシート
all_sheets = pd.read_excel('file.xlsx', sheet_name=None) # すべてのシートを辞書として
# 分析
df.head() # データのプレビュー
df.info() # 列情報
df.describe() # 統計情報
# Excelに書き出す
df.to_excel('output.xlsx', index=False)
Excelファイルのワークフロー
重要: 数式を使用し、ハードコード値は使用しない
Pythonで値を計算してハードコードするのではなく、常にExcelの数式を使用してください。 これにより、スプレッドシートが動的で更新可能な状態を維持できます。
❌ 誤り - 計算値のハードコード
# 悪い例: Pythonで計算し、結果をハードコード
sheet['B10'] = 5000 # ハードコード
# 悪い例: 成長率をPythonで計算
sheet['C5'] = 0.15 # ハードコード
# 悪い例: Pythonで平均を計算
sheet['D20'] = 42.5 # ハードコード
✅ 正しい - Excel数式の使用
# 良い例: Excelに合計を計算させる
sheet['B10'] = '=SUM(B2:B9)'
# 良い例: 成長率をExcel数式として
sheet['C5'] = '=(C4-C2)/C2'
# 良い例: Excel関数で平均
sheet['D20'] = '=AVERAGE(D2:D19)'
これは、合計、パーセンテージ、比率、差など、すべての計算に適用されます。スプレッドシートは、元データが変更されたときに再計算できる必要があります。
一般的なワークフロー
- ツールの選択: データにはpandas、数式/書式設定にはopenpyxl
- 作成/読み込み: 新しいワークブックを作成するか、既存のファイルを読み込む
- 変更: データ、数式、書式設定の追加/編集
- 保存: ファイルに書き出す
- 数式の再計算(数式を使用する場合は必須):
scripts/recalc.pyスクリプトを使用するpython scripts/recalc.py output.xlsx - エラーの確認と修正:
- スクリプトはエラーの詳細を含むJSONを返す
statusがerrors_foundの場合、error_summaryでエラーの種類と場所を確認する- 特定されたエラーを修正し、再度再計算する
- 修正すべき一般的なエラー:
#REF!: 無効なセル参照#DIV/0!: ゼロによる除算#VALUE!: 数式内の間違ったデータ型#NAME?: 認識されない数式名
新しいExcelファイルの作成
# 数式と書式設定には openpyxl を使用
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment
wb = Workbook()
sheet = wb.active
# データを追加
sheet['A1'] = 'Hello'
sheet['B1'] = 'World'
sheet.append(['Row', 'of', 'data'])
# 数式を追加
sheet['B2'] = '=SUM(A1:A10)'
# 書式設定
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')
# 列幅
sheet.column_dimensions['A'].width = 20
wb.save('output.xlsx')
既存のExcelファイルの編集
# openpyxl を使用して数式と書式設定を保持
from openpyxl import load_workbook
# 既存ファイルを読み込む
wb = load_workbook('existing.xlsx')
sheet = wb.active # または wb['SheetName'] で特定のシート
# 複数シートの操作
for sheet_name in wb.sheetnames:
sheet = wb[sheet_name]
print(f"シート: {sheet_name}")
# セルを変更
sheet['A1'] = 'New Value'
sheet.insert_rows(2) # 2行目に行を挿入
sheet.delete_cols(3) # 3列目を削除
# 新しいシートを追加
new_sheet = wb.create_sheet('NewSheet')
new_sheet['A1'] = 'Data'
wb.save('modified.xlsx')
数式の再計算
openpyxl で作成または変更されたExcelファイルには、数式が文字列として含まれていますが、計算された値は含まれていません。提供されている scripts/recalc.py スクリプトを使用して数式を再計算します。
python scripts/recalc.py <excel_file> [timeout_seconds]
例:
python scripts/recalc.py output.xlsx 30
このスクリプトは:
- 初回実行時にLibreOfficeマクロを自動設定する
- すべてのシートのすべての数式を再計算する
- Excelエラー(#REF!, #DIV/0! など)がないかすべてのセルをスキャンする
- エラーの場所と件数の詳細を含むJSONを返す
- LinuxとmacOSの両方で動作する
数式検証チェックリスト
数式が正しく動作することを確認するためのクイックチェック:
必須の検証
- 2~3個のサンプル参照をテストする: 完全なモデルを構築する前に、正しい値を取得していることを確認する
- 列マッピング: Excelの列が正しいことを確認する(例: 列64はBLであり、BKではない)
- 行オフセット: Excelの行は1から始まることを覚えておく(DataFrameの行5はExcelの行6)
よくある落とし穴
- NaN処理:
pd.notna()でnull値をチェックする - 右端の列: データはしばしば50列以降にある
- 複数の一致: 最初の出現だけでなく、すべての出現を検索する
- ゼロ除算: 数式で
/を使用する前に分母を確認する(#DIV/0!) - 間違った参照: すべてのセル参照が意図したセルを指していることを確認する(#REF!)
- シート間参照: シートをリンクするには正しい形式(Sheet1!A1)を使用する
数式テスト戦略
- 小さく始める: 広範囲に適用する前に、2~3個のセルで数式をテストする
- 依存関係を確認する: 数式で参照されているすべてのセルが存在することを確認する
- エッジケースをテストする: ゼロ、負の数、非常に大きな値を含める
scripts/recalc.py の出力の解釈
スクリプトはエラーの詳細を含むJSONを返します:
{
"status": "success", // または "errors_found"
"total_errors": 0, // エラーの総数
"total_formulas": 42, // ファイル内の数式の数
"error_summary": { // エラーが見つかった場合のみ存在
"#REF!": {
"count": 2,
"locations": ["Sheet1!B5", "Sheet1!C10"]
}
}
}
ベストプラクティス
ライブラリの選択
- pandas: データ分析、一括操作、単純なデータエクスポートに最適
- openpyxl: 複雑な書式設定、数式、Excel固有の機能に最適
openpyxl の操作
- セルインデックスは1から始まる(row=1, column=1 はセルA1を指す)
- 計算値を読み取るには
data_only=Trueを使用:load_workbook('file.xlsx', data_only=True) - 警告:
data_only=Trueで開いて保存すると、数式が値に置き換えられ、完全に失われる - 大きなファイルの場合: 読み取りには
read_only=True、書き込みにはwrite_only=Trueを使用する - 数式は保持されるが評価されない - 値を更新するには scripts/recalc.py を使用する
pandas の操作
- データ型を指定して推論の問題を回避:
pd.read_excel('file.xlsx', dtype={'id': str}) - 大きなファイルの場合、特定の列を読み取る:
pd.read_excel('file.xlsx', usecols=['A', 'C', 'E']) - 日付を適切に処理する:
pd.read_excel('file.xlsx', parse_dates=['date_column'])
コードスタイルガイドライン
重要: Excel操作用のPythonコードを生成する場合:
- 不要なコメントなしで、最小限かつ簡潔なPythonコードを記述する
- 冗長な変数名や不要な操作を避ける
- 不要なprint文を避ける
Excelファイル自体について:
- 複雑な数式や重要な仮定を含むセルにコメントを追加する
- ハードコードされた値のデータソースを文書化する
- 主要な計算やモデルのセクションに関する注釈を含める