Aspose.Cells for Python via Java でのスパークライン

Aspose.Cells はワークシートセル内のスパークラインの作成をサポートしています。スパークラインは 1 つのセル内に収まるミニチュアチャートであり、データの傾向をすばやく視覚的に表現します。Aspose.Cells は折れ線、縦棒、勝敗のスパークラインをサポートしており、それぞれを色、線の太さ、高値/安値ポイント、マーカーなどに関してカスタマイズできます。

はじめに

スパークラインはセル内に収まる小さなチャートであり、完全なグラフが占めるスペースを取らずにデータの行や列の隣にすばやく傾向を表示したい場合に便利です。Excel は 3 種類のスパークライン (折れ線、縦棒、勝敗) をサポートしています。Aspose.Cells は Aspose.Cells.Charts 名前空間にある SparklineGroup および SparklineGroupCollection API を通じてこの機能を提供します。 Aspose.Cells では、追加するすべてのスパークラインが worksheet.getSparklineGroups().add(...) を通じて作成され、これは SparklineGroup オブジェクトを返します。そのオブジェクトを使用して、スパークラインのタイプ、データ範囲、配置先セル、および線の色、線の太さ、マーカー、高値/安値ポイントインジケーターなどの視覚的なプロパティを設定できます。 この記事では、Aspose.Cells がサポートする 3 種類のスパークラインタイプ (折れ線、縦棒、勝敗) それぞれについて説明し、追加方法、色のカスタマイズ、結果として得られるワークブックの保存方法を示します。

折れ線スパークライン

折れ線スパークラインは、系列のデータポイントを通って連続した線を描画するため、時間の経過に伴う傾向を示すための最も自然な選択肢です。Aspose.Cells では、add メソッドに SparklineType.LINE を渡すことで折れ線スパークラインが作成されます。

1. 新しい Workbook を作成し、最初のワークシートにアクセスします。
2. 視覚化する値を使用して、ソースデータの行 (たとえば、1 行目、A 列から E 列) にデータを入力します。
3. スパークラインが描画される配置先セルを示す CellArea を構築します。
4. worksheet.getSparklineGroups().add(SparklineType.LINE, "A1:E1", false, dest) を呼び出します。3 番目の引数である false は、データ範囲が縦 (列) ではなく横 (行) であることを Aspose.Cells に伝えます。
5. 必要に応じて、返された SparklineGroup をカスタマイズします。折れ線スパークラインの場合、group.getLine().getColor() (これは Aspose.Cells.Drawing の CellsColor を必要とします) を使用して線の色を設定したり、線の太さを調整したり、高値/安値ポイントのマーカーを切り替えたりできます。
6. ワークブックを保存します。 次の例では、ワークブックを作成し、セル A1 から E1 に値 5、-3、8、-2、6 を書き込み、それらの値をトレースする折れ線スパークラインをセル F1 に追加します。また、線の色を赤にカスタマイズし、高値および安値ポイントのマーカーを有効化します。

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook, CellArea, CellsColor, SparklineType
from java.awt import Color
# Step 1: Create a Workbook and get the first worksheet
workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)
# Step 2: Populate sample data in row 1 (A1:E1)
worksheet.getCells().get("A1").putValue(5)
worksheet.getCells().get("B1").putValue(-3)
worksheet.getCells().get("C1").putValue(8)
worksheet.getCells().get("D1").putValue(-2)
worksheet.getCells().get("E1").putValue(6)
# Step 3: Add a Line sparkline group at F1
lineArea = CellArea()
lineArea.setStartColumn(5)
lineArea.setEndColumn(5)
lineArea.setStartRow(0)
lineArea.setEndRow(0)
lineIdx = worksheet.getSparklineGroups().add(SparklineType.LINE, "A1:E1", False, lineArea)
lineGroup = worksheet.getSparklineGroups().get(lineIdx)
# Customize the line sparkline color via CellsColor
lineColor = workbook.createCellsColor()
lineColor.setColor(Color.BLUE)
lineGroup.setSeriesColor(lineColor)
# Step 4: Add a Column sparkline group at F2
columnArea = CellArea()
columnArea.setStartColumn(5)
columnArea.setEndColumn(5)
columnArea.setStartRow(1)
columnArea.setEndRow(1)
columnIdx = worksheet.getSparklineGroups().add(SparklineType.COLUMN, "A1:E1", False, columnArea)
columnGroup = worksheet.getSparklineGroups().get(columnIdx)
# Customize the column sparkline series color
columnColor = workbook.createCellsColor()
columnColor.setColor(Color.GREEN)
columnGroup.setSeriesColor(columnColor)
# Step 5: Add a Win/Loss (Stacked) sparkline group at F3
stackedArea = CellArea()
stackedArea.setStartColumn(5)
stackedArea.setEndColumn(5)
stackedArea.setStartRow(2)
stackedArea.setEndRow(2)
stackedIdx = worksheet.getSparklineGroups().add(SparklineType.STACKED, "A1:E1", False, stackedArea)
stackedGroup = worksheet.getSparklineGroups().get(stackedIdx)
# Customize the win/loss sparkline series color
stackedColor = workbook.createCellsColor()
stackedColor.setColor(Color(255, 140, 0))  # DarkOrange
stackedGroup.setSeriesColor(stackedColor)
# Step 6: Save the workbook
workbook.save("output_all.xlsx")
jpype.shutdownJVM()

縦棒スパークライン

縦棒スパークラインは、各データポイントを縦棒としてレンダリングします。これにより、値が意味を持つデータ (たとえば、月次売上数値や件数) によく適しています。Aspose.Cells では、add メソッドに SparklineType.COLUMN を渡すことで縦棒スパークラインを作成します。 手順は折れ線スパークラインの例と同じです。

1. 新しい Workbook を作成し、最初のワークシートにアクセスします。
2. 配置先セルを示す CellArea を構築します。
3. worksheet.getSparklineGroups().add(SparklineType.COLUMN, "A1:E1", false, dest) を呼び出します。
4. 必要に応じて、結果として得られる SparklineGroup をカスタマイズします。たとえば、group.getType() を設定してタイプを確認したり、棒の色を調整したりします。
5. 折れ線スパークラインの例を上書きしないように、別の出力ファイルにワークブックを保存します。 以下の例では、A1:E1 に値 5、-3、8、-2、6 を書き込み、F1 に縦棒スパークラインを描画します。負の値は下向きの棒として、正の値は上向きの棒として描画されるため、一目で正と負の寄与を識別できます。

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook, Worksheet, CellArea, SparklineType
# ステップ 1: Workbook を作成し、最初のワークシートを取得します
workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)
# ステップ 2: サンプル値を A1:E1 に書き込みます
values = [5, -3, 8, -2, 6]
for i in range(len(values)):
    worksheet.getCells().get(0, i).putValue(values[i])
# ステップ 3: F1 (列インデックス 5、行インデックス 0) を指す CellArea を作成します
dest = CellArea()
dest.setStartColumn(5)
dest.setEndColumn(5)
dest.setStartRow(0)
dest.setEndRow(0)
# ステップ 4: コピー先のセルに Column スパークラインを追加します
idx = worksheet.getSparklineGroups().add(
    SparklineType.Column, "A1:E1", False, dest)
group = worksheet.getSparklineGroups().get(idx)
# ステップ 5: group.Type を読み取ってスパークラインのタイプを確認します
print("Sparkline Type added: " + str(group.getType()))
# ステップ 6: ワークブックを保存します
workbook.save("output_column.xlsx")
print("Workbook saved as output_column.xlsx")
jpype.shutdownJVM()

勝敗スパークライン

勝敗スパークラインは、縦棒スパークラインの特殊なバリエーションであり、2 つの結果のみを表示するように設計されています。正の値は「上向き」の棒 (勝ち) として、ゼロまたは負の値は「下向き」の棒 (負け) として描画されます。勝敗スパークラインは、勝ちと負けのシーケンス、合否結果、または時間にわたる任意の二項結果の可視化に一般的に使用されます。 Aspose.Cells では、add メソッドに SparklineType.STACKED を渡すことで勝敗スパークラインが作成されます (名前にもかかわらず、SparklineType.STACKED は勝敗レンダリングを要求するために使用される列挙値です)。

1. 新しい Workbook を作成し、最初のワークシートにアクセスします。
2. ソース範囲にデータを入力します。勝敗スパークラインではすべての値が勝ちか負けのいずれかとして扱われるため、値の大きさは重要ではなく、符号のみが重要です。正の値は上向きの棒になり、非正の値は下向きの棒になります。
3. 配置先セルを示す CellArea を構築します。
4. worksheet.getSparklineGroups().add(SparklineType.STACKED, "A1:E1", false, dest) を呼び出します。
5. 必要に応じて、返された SparklineGroup をカスタマイズします。たとえば、勝ち棒と負け棒のアクセント色を設定します。
6. 3 つの例すべてがディスク上に共存できるように、ワークブックを別のファイル名で保存します。

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook, Worksheet, CellArea, SparklineType, CellsColor, Color
# Step 1: Create a Workbook and get the first worksheet
workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)
worksheet.setName("WinLoss")
# Step 2: Populate sample data in row 1: A1=5, B1=-3, C1=8, D1=-2, E1=6
worksheet.getCells().get("A1").putValue(5)
worksheet.getCells().get("B1").putValue(-3)
worksheet.getCells().get("C1").putValue(8)
worksheet.getCells().get("D1").putValue(-2)
worksheet.getCells().get("E1").putValue(6)
# Step 3: Build a CellArea pointing to F1 (column 5, row 0)
dest = CellArea()
dest.setStartColumn(5)   # F
dest.setEndColumn(5)
dest.setStartRow(0)      # row 1
dest.setEndRow(0)
# Step 4: Add a Win/Loss sparkline (SparklineType.Stacked)
groupIndex = worksheet.getSparklineGroups().add(
    SparklineType.Stacked,
    "A1:E1",
    False,
    dest)
group = worksheet.getSparklineGroups().get(groupIndex)
# Step 5: Customize the sparkline group
# Enable high-point and low-point markers
group.setShowHighPoint(True)
group.setShowLowPoint(True)
group.setShowNegativePoints(True)
# Set the high-point color to green
highColor = workbook.createCellsColor()
highColor.setColor(Color.GREEN)
group.setHighPointColor(highColor)
# Set the low-point color to red
lowColor = workbook.createCellsColor()
lowColor.setColor(Color.RED)
group.setLowPointColor(lowColor)
# Set the negative-point color to orange
negColor = workbook.createCellsColor()
negColor.setColor(Color.ORANGE)
group.setNegativePointsColor(negColor)
# Set the default series color (used for positive bars)
seriesColor = workbook.createCellsColor()
seriesColor.setColor(Color.STEELBLUE)
group.setSeriesColor(seriesColor)
# Step 6: Save the workbook
workbook.save("output_winloss.xlsx")
print("Workbook saved successfully: output_winloss.xlsx")
jpype.shutdownJVM()

3 種類のスパークラインタイプの組み合わせ

以下の組み合わせ例では、単一のワークブックを作成し、1 行目に値 5、-3、8、-2、6 を入力し、セル F1、F2、F3 に 3 つのスパークライングループを追加します (各タイプの 1 つずつ)。これにより、結果として得られるファイルが 3 種類のスパークラインスタイルを一度に示します。

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook, CellArea, SparklineType
from java.awt import Color
# Step 1: Create a Workbook and get the first worksheet
workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)
cells = worksheet.getCells()
# Step 2: Write sample values 5, -3, 8, -2, 6 into cells A1:E1
cells.get("A1").putValue(5)
cells.get("B1").putValue(-3)
cells.get("C1").putValue(8)
cells.get("D1").putValue(-2)
cells.get("E1").putValue(6)
# Step 3: Build a CellArea pointing to destination cell F1
dest = CellArea()
dest.setStartColumn(5)  # column F (0-indexed)
dest.setEndColumn(5)
dest.setStartRow(0)     # row 1 (0-indexed)
dest.setEndRow(0)
# Step 4: Add a Line sparkline from A1:E1 into F1
# SparklineGroups.add returns the index of the newly added group
index = worksheet.getSparklineGroups().add(SparklineType.Line, "A1:E1", False, dest)
group = worksheet.getSparklineGroups().get(index)
# Step 5: Create a red CellsColor and assign it to the sparkline line color
red = workbook.createCellsColor()
red.setColor(Color.RED)
group.setSeriesColor(red)
# Step 6: Enable high-point and low-point markers
group.setShowHighPoint(True)
group.setShowLowPoint(True)
# Step 7: Save the workbook
workbook.save("output_line.xlsx")
jpype.shutdownJVM()

スパークラインの外観のカスタマイズ

SparklineGroup が作成されて worksheet.getSparklineGroups() に追加されたら、ワークブックを保存する前にその視覚的なプロパティのいくつかを読み取ったり変更したりできます。最も一般的にカスタマイズされるプロパティは次のとおりです。

• group.getType() — SparklineType (LINE、COLUMN、または STACKED)。これはグループが追加される際に設定されますが、読み戻して確認できます。
• group.getLine().getColor() — 線の色。workbook.createCellsColor() を介して作成された CellsColor として表されます。これは折れ線スパークラインの線の色を設定するために使用するプロパティです。
• group.getLine().getWeight() — ポイント単位の線の太さ。値を大きくすると線が太くなります。
• 高値/安値ポイントマーカー — 最高および最低のデータポイントに小さなマーカーをオンにするフラグ。極端な値を強調するのに役立ちます。
• 最初/最後/負のポイントマーカー — 最初、最後、および負のデータポイントのマーカーを切り替えるフラグ。 色を変更するには、常に CellsColor インスタンスを作成し、関連するプロパティに割り当てます。java.awt.Color をスパークラインの色プロパティに直接割り当てないでください。これらは Aspose.Cells.Drawing の CellsColor 型を必要とします。add メソッド自体は完全に型指定された SparklineGroup オブジェクトを返すため、戻り値に対してプロパティ割り当てをチェーンしたり、ローカル変数に保存して保存前にカスタマイズしたりできます。