xlsx

XLSX の作成、編集、分析

タスク	方法
数式や書式を使って作成または編集する	openpyxl — 以下の注意点を参照してください
大量のデータを取り込む、または出力する	pandas（read_excel、to_excel）
シートを手早く確認する	markitdown file.xlsx — シートごとに ## SheetName を出力します。.xlsm も読み取れます。セルの座標は表示されないため、これをもとに編集箇所を決めないでください
モデルを（数式と値の両方を）読み取る	load_workbook を 2 回実行します — 以下の注意点を参照してください

openpyxl、pandas、markitdown はインストール済みです — 先に pip install を実行せず、スクリプトを作成して直接インポートしてください。インポートに失敗した場合、または markitdown コマンドが見つからない場合に限り、不足しているパッケージを pip install でインストールしてください。

以下のスクリプトのパスは、このスキルのディレクトリからの相対パスです。

すべての出力に関する要件

• ユーザーから別の指定がない限り、全体をプロフェッショナルなフォント（Arial、Times New Roman）にしてください。
• 数式エラーはゼロにしてください。 recalc.py が errors_found を報告する場合は、決して納品しないでください。エラーが作業開始前から存在していたと思われる場合は、元のファイルを data_only=True で読み込み、そのセルを確認して証明してください。自分が追加したエラーも、引き継いだエラーも同じように見えます。
• 計算結果をハードコードせず、必ず数式を使ってください。 Python で計算した合計値ではなく、sheet['B10'] = '=SUM(B2:B9)' のように記述してください。入力が変わったときにシートを再計算できるようにする必要があります。
• ユーザーの仕様に厳密に従ってください。 タブ名、列見出し、指定された数式は正確に一致させてください。どれほど洗練されていても、別のものを計算するように再設計した場合は要件を満たしません。
• 前提とハードコードした数値はすべて、読み手に見える場所に記載してください。 セルのコメント、または表の末尾に隣接するセルに記載します。実在する出典がある場合は明記してください（Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]）。数値がユーザーから提供された場合は、その旨を明記してください。
• **あなたが作成する、入力用のブックには、**編集するセルを示す簡潔な凡例と、期待される書式が分かる現実的な値を入力したサンプル行を 1 行追加してください。編集を依頼されたファイルに、このような行を追加してはいけません。
• 既存のファイルを編集する場合は、既存の規則に厳密に合わせてください。 既存の規則はここに記載されたすべてのガイドラインに優先します。まず指定された入力セルを見つけてください — フォント色、塗りつぶし、または網かけの違いで示されています。そこにのみ入力し、既存の数式には一切手を加えないでください。

再計算（ファイルに数式が含まれている場合は必須）

openpyxl は数式をキャッシュ値なしの文字列として書き込みます。再計算するまでは、キャッシュ値を読み取るもの（pandas、load_workbook(data_only=True)、ほとんどのプレビューアー）では、すべての数式セルが None として読み込まれます。

python scripts/recalc.py output.xlsx [timeout_seconds]   # default 30

LibreOffice がすべての数式を計算し、ファイルを上書きして、次の内容を含む JSON を返します。 status（success | errors_found）、total_formulas、total_errors、およびエラー種別ごとに最大 100 個のセルを示す error_summary（省略した数は locations_truncated に示されます。リストの長さではなく total_errors を基準にしてください）。表示された問題を修正して、もう一度実行してください。status の代わりに error キーを含む JSON が返された場合は、何も再計算されていません。この場合に限り終了コードがゼロ以外になります。errors_found の場合は終了コードが 0 になるため、正常終了したからといって、ワークブックに問題がないと判断しないでください。

再計算が成功していることは、数式が計算できることを示すだけで、正しいことを示すわけではありません。 範囲の指定が 1 つずれていたり、誤った行を参照していたりすると、エラーのないファイルができても、値は間違っています。グリッド全体を作る前に、数式を 2～3 個入力して、期待どおりの値が取得されるか確認してください。

別のファイルにリンクしているワークブックは、openpyxl で再保存してから再計算すると、そのリンクが失われます。このような数式は ='[1]Returns Analysis'!$B$2 の形式で、[1] はシートではなく、外部参照リスト内の、ディスク上にある別のファイルを指すインデックスです。そのファイルは通常ここにはないため、セルのキャッシュ値だけがデータを保持しています。openpyxl は保存時にその値を削除します。その後、LibreOffice は参照先を実際に解決しようとしますが、失敗して #NAME? を書き込み、すべてのリンクを削除します。recalc.py はその状態では実行を拒否します。保存して上書きする前に、元のファイルから該当セルの値をコピーしてください（--force を指定すると上書きできますが、データの消失を受け入れる必要があります）。

検証に耐える数式を選ぶ

LibreOffice が実装している関数は Excel より少なく、評価できない関数は、納品するファイルにリテラルの #NAME? として埋め込まれます。

• Excel 2007 世代の関数を優先してください — SUMIFS、INDEX、MATCH、IFERROR、SUMPRODUCT は接頭辞なしで使用できます。
• 2007 年以降に追加された 6 つの関数は _xlfn. 接頭辞を付ければ使えます。openpyxl は数式を XML にそのまま書き込み、Excel は 2007 年以降の関数名に接頭辞を付けて保存するためです（Excel の UI ではこの接頭辞は非表示です）。対象は _xlfn.TEXTJOIN、_xlfn.CONCAT、_xlfn.IFS、_xlfn.SWITCH、_xlfn.MAXIFS、_xlfn.MINIFS です。接頭辞なしで記述すると、いずれも #NAME? になります。
• XLOOKUP、XMATCH、SORT、FILTER、UNIQUE、SEQUENCE は絶対に使用しないでください。 ランタイムの LibreOffice は、どのような接頭辞を付けてもこれらを評価できません。新しいビルドでは評価できますが、これらは配列をスピルする関数であり、openpyxl が書き込んだファイルにはスピルのメタデータがありません。そのため、範囲の左上のセルにしか値が入りません。そして、切り詰められた結果に対して recalc.py は total_errors: 0 を報告します。検索には INDEX／MATCH を使い、セルを書き込む前に Python で並べ替え、フィルター処理、重複の削除を行ってください。
• LibreOffice が解析できなかった数式は、小文字に変換されて書き戻されます。#NAME? と並んでいる場合は、問題をすばやく見分ける手掛かりになります。

openpyxl で注意すべき点

• モデルの読み込みには 2 回の読み込みが必要です。 data_only=True では数式がなくなり、キャッシュ値だけが取得されます。デフォルトでは、数式文字列は取得できますが値はありません。1 回の読み込みで両方を取得することはできません。
• data_only=True で読み込んだブックを保存すると、データが失われます。 このブックには数式が残っていないため、保存すると数式がすべてリテラルに置き換わり、元には戻せません。
• openpyxl で書き込んだ直後のファイルを data_only=True で読み込むと、すべての値が None になります。 まず recalc.py を実行してください。（計算結果が "" の数式も、読み込むと None になります。）
• 結合セルには左上のアンカーセルだけを書き込んでください。 範囲内のほかのセルは MergedCell であり、.value は読み取り専用です。
• load_workbook に keep_vba=True を渡さないと、.xlsm のマクロは失われます。
• シート名にスペースが含まれる場合は、別シートを参照する数式でシート名を引用符で囲む必要があります。 ='Assumptions Inputs'!$B$5 のように記述してください。引用符で囲まないと、#VALUE! になります。

財務モデル

ユーザーから別の指定がある場合、または既存のファイルですでに異なる方法が使われている場合を除きます。

色： ハードコードされた入力値とシナリオの調整項目には青文字（0,0,255）を使用します · 数式には黒を使用します · 別のシートへのリンクには緑（0,128,0）を使用します · 別のファイルへのリンクには赤（255,0,0）を使用します · 重要な前提条件とユーザーが入力するセルには黄色の塗りつぶし（255,255,0）を使用します。

数値： 通貨は $#,##0 とし、単位をヘッダーに記載します（Revenue ($mm)） · ゼロはパーセンテージを含め - と表示します（$#,##0;($#,##0);-） · 負の値は括弧で囲みます · パーセンテージは 0.0% とし、小数として保存します（0.15 は 15.0% と表示されます。15 を保存すると 1500.0% と表示されます） · 評価倍率は 0.0x とします · 年はテキストとして扱います（"2024" とし、2,024 にはしません）。

構成： すべての前提条件をそれぞれ個別のラベル付きセルに置き、使用する数式から参照します（=B5*(1+$B$6) とし、=B5*1.05 にはしません） · すべての予測期間で数式を統一します。行の途中のセルだけが編集されているのは、最もよくあるサイレントエラーです · ゼロになる可能性がある分母は保護します。

依存関係

openpyxl、pandas、markitdown（pip 経由でインストール済み。インポートに失敗するか、コマンドが見つからない場合に限りインストールしてください） · LibreOffice（soffice。サンドボックス環境では scripts/office/soffice.py により自動設定されます）