xlsx

XLSX の作成、編集、分析

タスク	アプローチ
数式/書式を含む 作成 または 編集	openpyxl — 以下の注意点を参照
大量データ の入出力	pandas (read_excel, to_excel)
シートの クイック確認	markitdown file.xlsx — シートごとに ## シート名 を出力。.xlsm も読み取り可能。セル座標は出力されないため、編集の計画には使用不可
モデル（数式 と 値）の 読み取り	2回の load_workbook パス — 以下の注意点を参照

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

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

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

• プロフェッショナルなフォント (Arial、Times New Roman) を全体に使用する。ただし、ユーザーが別途指定した場合はその限りではない。
• 数式エラーゼロ。recalc.py が errors_found を報告している状態では絶対に成果物を提供しないでください。エラーが元から存在したと思われる場合、それを証明してください：data_only=True で元のファイルをロードし、該当セルを確認してください。あなたが導入したエラーは、受け継いだエラーと見た目がまったく同じです。
• 数式を使用し、ハードコードされた結果は絶対に使用しない。 sheet['B10'] = '=SUM(B2:B9)' のように記述し、Python で計算した合計値は記述しないでください。シートは入力が変更されたときに再計算される必要があります。
• ユーザーの仕様に文字通り従う。 タブ名、列見出し、ユーザーが指定した数式をそのまま使用します。異なる計算を行う再設計は、どんなに洗練されていても失敗とみなされます。
• すべての仮定とハードコードされた数値について、 読者が確認できる場所（セルコメント、表の末尾の隣接セルなど）に文書化します。実在する情報源がある場合はそれを引用してください（出典：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]   # デフォルトは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年以降の名前を保存するためです（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 は読み取り専用です。
• .xlsm は、load_workbook に keep_vba=True を渡さないとマクロが失われます。
• スペースを含むシート名は、 シート間参照で引用符で囲む必要があります：='Assumptions Inputs'!$B$5。引用符で囲まないと、#VALUE! と評価されます。

財務モデル

ユーザーが別途指定した場合、または既存ファイルがすでに別のことを行っている場合を除きます。

色： ハードコードされた入力とシナリオレバーには青いテキスト (0,0,255) · 数式には黒 · 別のシートへのリンクには緑 (0,128,0) · 別のファイルへのリンクには赤 (255,0,0) · 主要な仮定とユーザーが入力するセルには黄色の塗りつぶし (255,255,0)。

数値： 通貨 $#,##0、ヘッダーで単位を指定（収益 ($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 を介して自動設定)