---

Python NumPy dstack徹底解説：深淵なるスタッキングの世界へ

1. はじめに

科学計算、データ分析、機械学習といった分野でPythonを使用する際、NumPyライブラリは不可欠なツールです。NumPyは、多次元配列を効率的に扱うための強力な機能を提供します。配列の生成、操作、演算など、さまざまなタスクをNumPyで行いますが、その中でも特に重要な操作の一つに「配列の結合（スタッキング）」があります。複数のNumPy配列を特定の規則に基づいて一つの大きな配列に結合することで、データを整理したり、特定のアルゴリズムに適した形に整えたりすることができます。

NumPyには配列をスタックするためのいくつかの関数が用意されています。代表的なものとして、vstack (縦方向、行方向のスタック)、hstack (横方向、列方向のスタック)、stack (新しい軸に沿ったスタック) などがありますが、本記事で焦点を当てるのは dstack 関数です。

dstack は “depth stack” の略であり、複数の配列を「深さ方向」、つまり3番目の軸（インデックス2）に沿ってスタックする関数です。これは特に、画像処理でRGBチャンネルを結合したり、複数のセンサーデータや特徴量をまとめて一つの3次元以上の配列として扱いたい場合などに非常に有用です。

しかし、dstackの挙動は、入力配列の次元によって少し特殊な側面を持っています。特に1次元配列や2次元配列を入力とした場合の形状変換は、他のスタック関数と比較しても独特です。このため、dstackを効果的に使いこなすためには、その基本的な使い方だけでなく、内部でどのように配列が処理され、スタックされるのか、そして他の関数とどのように異なるのかを深く理解する必要があります。

本記事では、NumPyのdstack関数について、その定義、基本的な使い方、詳細な仕組み、多様な応用例、そして他のスタック関数（vstack, hstack, stack）との比較を通じて、徹底的に解説します。この記事を読むことで、あなたはdstackを自信を持って使いこなし、あなたのNumPy配列操作スキルをさらに向上させることができるでしょう。

この記事は、NumPyの基本的な概念（配列、形状、次元、軸など）をある程度理解している読者を対象としていますが、必要に応じてこれらの基本概念も復習しながら進めます。さあ、dstackの深淵なる世界へ一緒に踏み込んでいきましょう。

2. NumPy配列の基礎知識

dstack関数を理解するためには、NumPy配列の基本、特に「次元」「形状」「軸」といった概念をしっかりと把握しておくことが重要です。

2.1. NumPy配列 (ndarray) とは

NumPyの核となるのは、ndarrayと呼ばれる多次元配列オブジェクトです。これはPythonのリストに似ていますが、より効率的な数値計算のために設計されています。すべての要素が同じデータ型である必要があり、固定サイズです。

2.2. 次元 (Dimension)

配列の次元は、配列が持つ「方向」の数を指します。
* 0次元配列（スカラー）: 単一の値。形状は ()。
* 1次元配列（ベクトル）: 一方向の並び。形状は (N,)。
* 2次元配列（行列）: 行と列の並び。形状は (M, N)。
* 3次元配列: 例えば、行、列、深さを持つ。形状は (P, M, N)。
* …そして、さらに高次元の配列も可能です。

dstackは特に、3次元以上の配列を扱う際や、入力配列から3次元以上の配列を生成する際に重要になります。

2.3. 形状 (Shape)

配列の形状は、各次元に沿った要素の数をタプルで示したものです。例えば、3行4列の2次元配列の形状は (3, 4) です。10個の要素を持つ1次元配列の形状は (10,) です。形状は配列の構造を完全に定義します。

2.4. 軸 (Axis)

配列の軸は、特定の次元を指し示すためのインデックスです。NumPyでは、軸のインデックスは0から始まります。
* 1次元配列 [a, b, c] の場合、軸0に沿って要素が並んでいます。形状は (3,)。
* 2次元配列 [[a, b], [c, d]] の場合、軸0は「行」方向、軸1は「列」方向に対応します。形状は (2, 2)。
* 3次元配列 [[[a,b],[c,d]], [[e,f],[g,h]]] の場合、軸0、軸1、軸2の3つの軸があります。形状は (2, 2, 2)。

多くのNumPy関数（スタック関数、集約関数など）は、操作を行う「軸」を指定できます。dstack関数は、デフォルトで「深さ方向」、つまり新しい軸を生成し、そこに沿ってスタックを行います。この新しい軸は、元の配列の次元数によって配置される位置が異なります。

2.5. スタッキングとは

スタッキング（Stacking）とは、複数のNumPy配列を連結して一つの大きな配列を作成する操作です。連結の方法によって、vstack, hstack, dstack, stackなどの関数が使い分けられます。これらの関数は、連結する配列の形状が特定の規則に従っている必要があります。

dstackは、入力配列を変換し、新しい軸（デフォルトでは3番目の軸、インデックス2）を生成してそこに沿って結合する特殊なスタッキングです。この「変換」の挙動がdstackの理解の鍵となります。

3. dstack関数とは何か

NumPyの dstack 関数は、複数のNumPy配列を「深さ方向」にスタックするための関数です。より正確には、入力として与えられた配列のシーケンス（タプルやリスト）を取り、それらを結合して次元を一つ増やした新しい配列を返します。この新しい次元は、結合された配列の各要素が元のどの配列に由来するかを示すような役割を果たします。

dstack の目的は、形状が (..., M, N) であるような複数の配列を、形状が (..., M, N, k) （kは入力配列の数）であるような一つの配列に結合することです。ここで ... は任意の数の先行する次元を表します。つまり、最後の2つの次元 (M, N) はそのまま保持され、その「奥」にもう一つの次元が追加されるイメージです。

ただし、dstackには特別なルールがあります。それは、1次元配列と2次元配列を入力とした場合の挙動です。

• 1次元配列 (N,): dstackはまずこの配列を (1, N) の形状に変換し、さらに (1, N, 1) の形状に変換します。そして、このように変換された複数の (1, N, 1) 配列を3番目の軸（インデックス2）に沿ってスタックし、結果として (1, N, k) の形状を持つ配列を生成します（kは入力された1次元配列の数）。
• 2次元配列 (M, N): dstackはまずこの配列を (M, N, 1) の形状に変換します。そして、このように変換された複数の (M, N, 1) 配列を3番目の軸（インデックス2）に沿ってスタックし、結果として (M, N, k) の形状を持つ配列を生成します（kは入力された2次元配列の数）。
• 3次元以上の配列 (..., M, N): 3次元以上の配列の場合、dstackはこれらの配列の最後の次元の直後、つまり新しい軸を生成し、そこに沿ってスタックします。形状は (..., M, N, k) となります。この場合、形状の変換は行われません（最後の次元のサイズが1になるような変換は行われない）。

重要なポイント:
* dstackは必ず新しい次元を生成します。
* この新しい次元は、元の配列の最後の次元の「次」に位置します。
* 1次元配列と2次元配列は、スタック前に特殊な形状変換を受けます。

この特殊な形状変換が、dstackが他のスタック関数と異なる点であり、その挙動を理解する上で最も重要な部分です。

4. dstackの基本的な使い方

dstack関数は numpy.dstack(tup) の形式で使用します。引数 tup は、スタックしたいNumPy配列を含むタプルまたはリストである必要があります。

import numpy as np を前提とします。

4.1. 1次元配列のスタック

複数の1次元配列を入力としてdstackを使用してみましょう。

“`python
import numpy as np

1次元配列の定義

a = np.array([1, 2, 3])
b = np.array([4, 5, 6])
c = np.array([7, 8, 9])

print(“元の配列 a:”, a, “, shape:”, a.shape)
print(“元の配列 b:”, b, “, shape:”, b.shape)
print(“元の配列 c:”, c, “, shape:”, c.shape)

dstackでスタック

result = np.dstack((a, b, c))

print(“\ndstackの結果:\n”, result)
print(“dstackの結果の形状:”, result.shape)
“`

出力:

“`
元の配列 a: [1 2 3] , shape: (3,)
元の配列 b: [4 5 6] , shape: (3,)
元の配列 c: [7 8 9] , shape: (3,)

dstackの結果:
[[[1 4 7]
[2 5 8]
[3 6 9]]]
dstackの結果の形状: (1, 3, 3)
“`

解説:

1. 入力は3つの1次元配列 a, b, c です。それぞれの形状は (3,) です。
2. dstackはこれらの配列を処理します。まず、各1次元配列 (3,) は (1, 3) に変換され、さらに (1, 3, 1) に変換されます。つまり、a は [[[1]], [[2]], [[3]]] のような形状 (1, 3, 1) の配列として扱われます（概念的な変換です）。
3. 変換された3つの (1, 3, 1) 配列（概念的に arr_a_converted, arr_b_converted, arr_c_converted とします）は、3番目の軸（インデックス2）に沿ってスタックされます。
   • arr_a_converted: [[[1]], [[2]], [[3]]]
   • arr_b_converted: [[[4]], [[5]], [[6]]]
   • arr_c_converted: [[[7]], [[8]], [[9]]]
4. これらを軸2でスタックすると、結果の形状は (1, 3, 3) となります。
   • 結果の [0, 0, :] は [1, 4, 7] となります（arr_a_converted[0, 0, 0], arr_b_converted[0, 0, 0], arr_c_converted[0, 0, 0] を並べたもの）。
   • 結果の [0, 1, :] は [2, 5, 8] となります。
   • 結果の [0, 2, :] は [3, 6, 9] となります。

結果の配列 [[[1 4 7] [2 5 8] [3 6 9]]] は、形状 (1, 3, 3) を持っています。これは、元の3つの1次元配列の各要素が、結果配列の最も内側の配列（軸2に沿った配列）として並んでいることを意味します。

注意: 1次元配列を入力する場合、すべての配列の要素数（形状 (N,) の N）が一致している必要があります。一致しない場合はエラーが発生します。

“`python
import numpy as np

a = np.array([1, 2]) # 要素数2
b = np.array([4, 5, 6]) # 要素数3

try:
result = np.dstack((a, b))
print(result)
except ValueError as e:
print(“エラーが発生しました:”, e)
“`

出力:

エラーが発生しました: all the input arrays must have the same shape

これは期待通りの挙動です。変換後の形状 (1, N, 1) の N が一致しないためスタックできません。

4.2. 2次元配列のスタック

次に、複数の2次元配列を入力としてdstackを使用してみましょう。

“`python
import numpy as np

2次元配列の定義

a = np.array([[1, 2], [3, 4]])
b = np.array([[5, 6], [7, 8]])
c = np.array([[9, 10], [11, 12]])

print(“元の配列 a:\n”, a, “\nshape:”, a.shape)
print(“元の配列 b:\n”, b, “\nshape:”, b.shape)
print(“元の配列 c:\n”, c, “\nshape:”, c.shape)

dstackでスタック

result = np.dstack((a, b, c))

print(“\ndstackの結果:\n”, result)
print(“dstackの結果の形状:”, result.shape)
“`

出力:

“`
元の配列 a:
[[1 2]
[3 4]]
shape: (2, 2)
元の配列 b:
[[5 6]
[7 8]]
shape: (2, 2)
元の配列 c:
[[ 9 10]
[11 12]]
shape: (2, 2)

dstackの結果:
[[[ 1 5 9]
[ 2 6 10]]

[[ 3 7 11]
[ 4 8 12]]]
dstackの結果の形状: (2, 2, 3)
“`

解説:

1. 入力は3つの2次元配列 a, b, c です。それぞれの形状は (2, 2) です。
2. dstackはこれらの配列を処理します。まず、各2次元配列 (M, N) は (M, N, 1) に変換されます。この例では、a は [[[1], [2]], [[3], [4]]] のような形状 (2, 2, 1) の配列として扱われます（これも概念的な変換です）。
3. 変換された3つの (2, 2, 1) 配列（概念的に arr_a_converted, arr_b_converted, arr_c_converted とします）は、3番目の軸（インデックス2）に沿ってスタックされます。
   • arr_a_converted の shape は (2, 2, 1)
   • arr_b_converted の shape は (2, 2, 1)
   • arr_c_converted の shape は (2, 2, 1)
4. これらを軸2でスタックすると、結果の形状は (2, 2, 3) となります。
   • 結果の [0, 0, :] は [1, 5, 9] となります（arr_a_converted[0, 0, 0], arr_b_converted[0, 0, 0], arr_c_converted[0, 0, 0] を並べたもの）。
   • 結果の [0, 1, :] は [2, 6, 10] となります。
   • 結果の [1, 0, :] は [3, 7, 11] となります。
   • 結果の [1, 1, :] は [4, 8, 12] となります。

結果の配列は形状 (2, 2, 3) を持ち、これは元の2つの次元 (2, 2) が保持され、その深さ方向（軸2）に元の配列が結合されたことを示します。この構造は、例えば2×2の画像のR, G, Bチャンネルデータ（各チャンネルが2×2の配列）を結合して2x2x3の配列にする場合などに類似しています。

注意: 2次元配列を入力する場合、すべての配列の形状 (M, N) が一致している必要があります。一致しない場合はエラーが発生します。

4.3. 3次元以上の配列のスタック

最後に、3次元配列を入力としてdstackを使用してみましょう。

“`python
import numpy as np

3次元配列の定義

shape (2, 2, 2)

a = np.arange(8).reshape(2, 2, 2)
b = np.arange(8, 16).reshape(2, 2, 2)

print(“元の配列 a:\n”, a, “\nshape:”, a.shape)
print(“元の配列 b:\n”, b, “\nshape:”, b.shape)

dstackでスタック

result = np.dstack((a, b))

print(“\ndstackの結果:\n”, result)
print(“dstackの結果の形状:”, result.shape)
“`

出力:

“`
元の配列 a:
[[[0 1]
[2 3]]

[[4 5]
[6 7]]]
shape: (2, 2, 2)
元の配列 b:
[[[ 8 9]
[10 11]]

[[12 13]
[14 15]]]
shape: (2, 2, 2)

dstackの結果:
[[[ 0 1 8 9]
[ 2 3 10 11]]

[[ 4 5 12 13]
[ 6 7 14 15]]]
dstackの結果の形状: (2, 2, 4)
“`

解説:

1. 入力は2つの3次元配列 a, b です。それぞれの形状は (2, 2, 2) です。
2. 3次元以上の配列の場合、dstackは入力配列の形状を変換しません。つまり、aは形状 (2, 2, 2) のまま、bも形状 (2, 2, 2) のまま扱われます。
3. これらの配列は、3番目の軸（インデックス2）に沿ってスタックされます。
4. 結果の形状は (2, 2, 2 + 2)、つまり (2, 2, 4) となります。これは、元の配列の最後の軸のサイズが合計された結果です。

dstackは3次元以上の配列に対しては、指定された軸（インデックス2）に沿って concatenate を実行しているかのように見えます。しかし、これはあくまで3次元以上の配列の場合の挙動であり、1次元・2次元の入力に対する挙動は異なります。

注意: 3次元以上の配列を入力する場合、すべての配列の、最後の次元を除く形状 (..., M, N) が一致している必要があります。最後の次元のサイズは異なっていても構いませんが、スタック後のその軸のサイズは、入力配列それぞれの最後の軸のサイズの合計となります。

例えば、形状 (2, 3, 4) と (2, 3, 5) の3次元配列をdstackすると、結果は (2, 3, 4+5) = (2, 3, 9) の形状になります。

“`python
import numpy as np

a = np.zeros((2, 3, 4))
b = np.ones((2, 3, 5))

result = np.dstack((a, b))
print(“dstackの結果の形状:”, result.shape)

出力: dstackの結果の形状: (2, 3, 9)

“`

5. dstackの詳細な仕組み

dstackがどのように配列をスタックするかをより深く理解するために、特に1次元および2次元配列がどのように変換されるかに注目しましょう。

NumPyの内部では、dstack(tup) は、与えられたタプル tup の各配列 arr に対して、その次元数に応じて以下のような処理を行った後、最後に軸2に沿って結合（concatenate）を行っていると考えられます。

1. 入力配列 arr を取り出す。
2. 配列 arr の次元数を確認する。
   • 次元数 1 (形状 (N,)) の場合:
     • まず、形状を (1, N) に変換します。これは np.atleast_2d(arr) に相当します。
     • 次に、形状を (1, N, 1) に変換します。これは変換後の配列に対して np.expand_dims(arr_2d, axis=2) に相当します。
     • 例: [1, 2, 3] ((3,)) -> [[1, 2, 3]] ((1, 3)) -> [[[1], [2], [3]]] ((1, 3, 1))
   • 次元数 2 (形状 (M, N)) の場合:
     • 形状を (M, N, 1) に変換します。これは np.expand_dims(arr, axis=2) に相当します。
     • 例: [[1, 2], [3, 4]] ((2, 2)) -> [[[1], [2]], [[3], [4]]] ((2, 2, 1))
   • 次元数 3以上 (形状 (..., M, N)) の場合:
     • 形状変換は行いません。配列はそのままの形状 (..., M, N) で扱われます。
3. すべての変換済み配列を集める。 入力タプル tup に含まれるすべての配列に対してステップ2を行います。
4. 変換済み配列を軸2に沿って連結する。 np.concatenate(list_of_converted_arrays, axis=2) を実行します。

この仕組みから、以下の制約と挙動が説明できます。

• 入力配列の次元数は少なくとも1である必要がある。 0次元配列（スカラー）は dstack に渡せません。これは、変換後の形状が常に少なくとも3次元になることから直感的に理解できます。
• 1次元配列を入力する場合、すべての配列の要素数が一致する必要がある。 変換後の形状は (1, N, 1) となるため、N が一致しないと concatenate を軸2で行うことができません。
• 2次元配列を入力する場合、すべての配列の形状 (M, N) が一致する必要がある。 変換後の形状は (M, N, 1) となるため、M と N が一致しないと concatenate を軸2で行うことができません。
• 3次元以上の配列を入力する場合、最後の次元を除く形状 (..., M, N) が一致する必要がある。 変換は行われず、そのままの形状 (..., M, N) の配列を軸2で結合するため、軸2より前の次元のサイズ (...) と、軸2自身のサイズ M と N が一致している必要があります。最後の次元のサイズだけは異なっていても構いません（それが結合される軸だからです）。

仕組みを図解的に理解する (概念)

図は表示できませんが、イメージとして捉えてみましょう。

1次元配列 (N,) のスタック:

“`
[1, 2, 3] (3,)
[4, 5, 6] (3,)
[7, 8, 9] (3,)

↓ 変換（概念的に）

[[[1]], [[2]], [[3]]] (1, 3, 1)
[[[4]], [[5]], [[6]]] (1, 3, 1)
[[[7]], [[8]], [[9]]] (1, 3, 1)

↓ 軸2で concatenate

[[[1, 4, 7], <– 元の [1], [4], [7] が軸2方向に並ぶ
[2, 5, 8], <– 元の [2], [5], [8] が軸2方向に並ぶ
[3, 6, 9]]] <– 元の [3], [6], [9] が軸2方向に並ぶ
(1, 3, 3)
“`

2次元配列 (M, N) のスタック:

“`
[[1, 2], (2, 2)
[3, 4]]

[[5, 6], (2, 2)
[7, 8]]

[[ 9, 10], (2, 2)
[11, 12]]

↓ 変換（概念的に）

[[[1], [2]], (2, 2, 1)
[[3], [4]]]

[[[5], [6]], (2, 2, 1)
[[7], [8]]]

[[[ 9], [10]], (2, 2, 1)
[[11], [12]]]

↓ 軸2で concatenate

[[[ 1, 5, 9], <– 元の [1], [5], [9] が軸2方向に並ぶ
[ 2, 6, 10]], <– 元の [2], [6], [10] が軸2方向に並ぶ

[[ 3, 7, 11], <– 元の [3], [7], [11] が軸2方向に並ぶ
[ 4, 8, 12]]] <– 元の [4], [8], [12] が軸2方向に並ぶ
(2, 2, 3)
“`

3次元配列 (P, M, N) のスタック:

“`
[[[0, 1], (2, 2, 2)
[2, 3]],

[[4, 5],
[6, 7]]]

[[[ 8, 9], (2, 2, 2)
[10, 11]],

[[12, 13],
[14, 15]]]

↓ 変換なし

[[[0, 1], (2, 2, 2)
[2, 3]],
[[4, 5],
[6, 7]]]

[[[ 8, 9], (2, 2, 2)
[10, 11]],
[[12, 13],
[14, 15]]]

↓ 軸2で concatenate

[[[ 0, 1, 8, 9], <– 元の [0, 1], [8, 9] が軸2方向に並ぶ
[ 2, 3, 10, 11]], <– 元の [2, 3], [10, 11] が軸2方向に並ぶ

[[ 4, 5, 12, 13], <– 元の [4, 5], [12, 13] が軸2方向に並ぶ
[ 6, 7, 14, 15]]] <– 元の [6, 7], [14, 15] が軸2方向に並ぶ
(2, 2, 4)
“`

このように、dstackは入力配列の次元数によって異なる前処理を施してから、最後に軸2で連結するという一貫した操作を行っています。

6. dstackの応用例

dstackは、特に以下のようなシナリオで非常に役立ちます。

6.1. 画像処理：RGBチャンネルの結合

カラー画像は通常、R（赤）、G（緑）、B（青）の3つのチャンネルに分けられたデータの集まりとして扱われます。各チャンネルは、例えば高さx幅の2次元配列で表現されます。dstackを使用すると、これらの個別のチャンネル配列を一つの高さx幅x3の3次元配列に簡単に結合できます。これは、多くの画像処理ライブラリや機械学習フレームワークがカラー画像を扱う標準的な形式です。

“`python
import numpy as np

import matplotlib.pyplot as plt # 画像表示ライブラリを使う場合

例として、小さな3×4ピクセルの画像データを作成

Rチャンネル (3×4)

r_channel = np.array([[255, 0, 0, 255],
[ 0, 128, 128, 0],
[255, 0, 0, 255]], dtype=np.uint8)

Gチャンネル (3×4)

g_channel = np.array([[ 0, 255, 0, 0],
[128, 255, 128, 128],
[ 0, 255, 0, 0]], dtype=np.uint8)

Bチャンネル (3×4)

b_channel = np.array([[ 0, 0, 255, 0],
[128, 128, 255, 255],
[ 0, 0, 255, 0]], dtype=np.uint8)

print(“Rチャンネル shape:”, r_channel.shape)
print(“Gチャンネル shape:”, g_channel.shape)
print(“Bチャンネル shape:”, b_channel.shape)

dstackでRGBチャンネルを結合

各チャンネル (3, 4) が (3, 4, 1) に変換され、軸2でスタックされる

rgb_image = np.dstack((r_channel, g_channel, b_channel))

print(“\n結合されたRGB画像データの形状:”, rgb_image.shape)
print(“結合されたRGB画像データ (最初の行):\n”, rgb_image[0, :, :])

結果は形状 (高さ, 幅, チャンネル数) となる

この形状は、多くの画像処理ライブラリ（OpenCV, PILなど）や

ディープラーニングフレームワーク（TensorFlow, PyTorchなど）が

標準とするカラー画像の形式 (H, W, C) に対応している。

画像を表示する場合は matplotlib を使う (ここではコードのみ)

plt.imshow(rgb_image)

plt.axis(‘off’) # 軸を表示しない

plt.show()

“`

この例では、3つの2次元配列（R, G, Bチャンネル）が dstack によって形状 (3, 4, 3) の1つの3次元配列に結合されています。これは、高さ3ピクセル、幅4ピクセル、チャンネル数3のカラー画像を表現する一般的な方法です。

6.2. 時系列データやセンサーデータの結合

複数のセンサーから同時に取得した時系列データや、同一の対象に対する複数の特徴量ベクトルを組み合わせたい場合にもdstackが有効です。

例えば、3つの異なるセンサーがそれぞれ100時点のデータを持つとします。各センサーのデータは1次元配列 (100,) で表現できます。これらをdstackで結合すると、形状 (1, 100, 3) の3次元配列が得られます。これは「1つの観測、100のタイムステップ、3つのセンサー」といった構造を表すのに使えます。

もし、各時点のデータが複数の特徴量を持つ場合（例えば、センサー1が温度と湿度の2つのデータを持つ場合）、センサーデータは2次元配列 (100, 2) となるでしょう。複数のセンサー（例えば3つ）から得られた (100, 2) のデータをdstackで結合すると、形状 (100, 2, 3) の3次元配列が得られます。これは「100のタイムステップ、各タイムステップで2つの特徴量、3つのセンサー」といった構造を表すのに使えます。

“`python
import numpy as np

例: 2つのセンサーから得た時系列データ

センサー1: 温度 (100時点)

temp_data = np.linspace(10, 30, 100) # 100個のデータポイント

センサー2: 湿度 (100時点)

humidity_data = np.linspace(40, 60, 100) # 100個のデータポイント

print(“温度データ shape:”, temp_data.shape)
print(“湿度データ shape:”, humidity_data.shape)

dstackでデータを結合

1次元配列 (100,) が (1, 100, 1) に変換され、軸2でスタックされる

sensor_data_stacked = np.dstack((temp_data, humidity_data))

print(“\ndstackで結合されたデータ shape:”, sensor_data_stacked.shape)
print(“結合されたデータの例 (最初のタイムステップ):\n”, sensor_data_stacked[:, 0, :]) # 結果の0番目の軸はサイズ1

結果の shape は (1, 100, 2) となる

軸0: 観測数 (この場合は1)

軸1: タイムステップ数 (100)

軸2: センサー数 (2)

例2: 各時点が複数の特徴量を持つ場合

センサーA: 温度と気圧 (100時点, 各時点2特徴量)

sensor_a_data = np.random.rand(100, 2)

センサーB: 湿度と風速 (100時点, 各時点2特徴量)

sensor_b_data = np.random.rand(100, 2)

print(“\nセンサーAデータ shape:”, sensor_a_data.shape)
print(“センサーBデータ shape:”, sensor_b_data.shape)

dstackでデータを結合

2次元配列 (100, 2) が (100, 2, 1) に変換され、軸2でスタックされる

combined_sensor_features = np.dstack((sensor_a_data, sensor_b_data))

print(“\ndstackで結合された特徴量 shape:”, combined_sensor_features.shape)
print(“結合された特徴量の例 (最初のタイムステップ):\n”, combined_sensor_features[0, :, :])

結果の shape は (100, 2, 2) となる

軸0: タイムステップ数 (100)

軸1: 各時点の特徴量数 (2)

軸2: センサーの種類数 (2)

“`

これらの例に示すように、dstackはデータの種類や発生源を区別する新しい軸を追加することで、複雑な多次元データを構造化するのに役立ちます。

6.3. 3Dデータの構築

複数の2D平面（スライス）から3Dボリュームデータを構築する際にもdstackが考えられます。例えば、医療用画像（MRIやCTスキャン）は複数の2Dスライスとして取得されることがありますが、これらを積み重ねて3Dボリュームデータとして解析することがよくあります。

ただし、dstackで2Dスライス (H, W) をスタックすると、結果は (H, W, N_slices) となります。これは最も一般的な3Dボリュームデータの表現形式の一つです。

“`python
import numpy as np

例: 3つの2Dスライス (各 10×10)

slice1 = np.random.rand(10, 10)
slice2 = np.random.rand(10, 10)
slice3 = np.random.rand(10, 10)

print(“スライス1 shape:”, slice1.shape)

dstackでスライスを結合

2次元配列 (10, 10) が (10, 10, 1) に変換され、軸2でスタックされる

volume_data = np.dstack((slice1, slice2, slice3))

print(“\n結合されたボリュームデータ shape:”, volume_data.shape)

結果の shape は (10, 10, 3) となる

軸0: 高さ

軸1: 幅

軸2: スライス番号 (深さ)

“`

この結果は、例えば10x10x3ピクセルの小さな3Dボリュームデータとして解釈できます。軸2がボリュームの「深さ」や「スライスのインデックス」に対応します。

6.4. 機械学習における特徴量エンジニアリング

複数の異なる方法で抽出された特徴量ベクトルを組み合わせて、よりリッチな特徴量表現を作成したい場合にもdstackが使えます。

例えば、あるデータサンプルに対して、手法Aで形状 (N,) の特徴量ベクトル、手法Bで形状 (N,) の特徴量ベクトルが得られたとします。これらをdstackで結合すると、形状 (1, N, 2) の配列が得られます。もし多くのサンプルがあり、各サンプルに対してこれらの特徴量が得られている場合、サンプルのバッチを扱う際には異なるスタック方法が適切かもしれません（例えば、バッチ内の各サンプルに対して個別にdstackを行い、その後バッチ軸でvstackするなど）。

dstackは、複数の単一の特徴量ベクトルを1つの「深い」特徴量ベクトルにまとめる、あるいは複数の特徴量マップ（2D）を1つの「深い」特徴量ボリューム（3D）にまとめる、といった用途に適しています。

これらの応用例からわかるように、dstackは特に「最後の次元の次に新しい次元を追加し、その次元に沿って要素を並べる」という操作が必要な場合に強力なツールとなります。これは、複数の種類のデータをまとめて一つの共通の構造で表現したい場合にしばしば発生します。

7. dstackと他のスタック関数の比較

NumPyにはdstack以外にも配列をスタックする関数があります。vstack, hstack, stackです。それぞれの関数がどのように配列をスタックするかを理解すると、dstackの特性がより明確になります。

これらの関数はすべて np.______((arr1, arr2, ...)) の形式で、配列のシーケンスを入力として受け取ります。

7.1. vstack (vertical stack / row_stack)

vstackは、配列を「縦方向」（行方向）、つまり軸0に沿ってスタックします。

• 1次元配列 (N,): まず (1, N) の形状に変換され、その後軸0でスタックされます。結果の形状は (k, N) となります（kは入力配列の数）。
• 2次元以上の配列 (..., M, N): 最後の次元を除く形状 (..., M) が一致している必要があり、軸0に沿ってスタックされます。結果の形状は (sum_of_M, N) となります（厳密には (..., sum_of_M, N) となります）。

“`python
import numpy as np

a = np.array([1, 2, 3])
b = np.array([4, 5, 6])
print(“1D vstack:”)
result_vstack_1d = np.vstack((a, b))
print(result_vstack_1d, “, shape:”, result_vstack_1d.shape)

1D vstack:

[[1 2 3]

[4 5 6]] , shape: (2, 3)

a = np.array([[1, 2], [3, 4]])
b = np.array([[5, 6], [7, 8]])
print(“\n2D vstack:”)
result_vstack_2d = np.vstack((a, b))
print(result_vstack_2d, “\nshape:”, result_vstack_2d.shape)

2D vstack:

[[1 2]

[3 4]

[5 6]

[7 8]]

shape: (4, 2)

“`

vstackは、入力配列の行数（または1Dの場合は1行）を合計するようにスタックします。

7.2. hstack (horizontal stack / column_stack)

hstackは、配列を「横方向」（列方向）、つまり軸1に沿ってスタックします。

• 1次元配列 (N,): 形状変換なしでそのままスタックされます。結果の形状は (k*N,) となります。これは np.concatenate と同じ挙動です。np.column_stack は1次元配列を (N, 1) に変換してから hstack します。
• 2次元以上の配列 (..., M, N): 最初の次元を除く形状 (M, ...) が一致している必要があり、軸1に沿ってスタックされます。結果の形状は (M, sum_of_N, ...) となります。

“`python
import numpy as np

a = np.array([1, 2, 3])
b = np.array([4, 5, 6])
print(“1D hstack:”)
result_hstack_1d = np.hstack((a, b))
print(result_hstack_1d, “, shape:”, result_hstack_1d.shape)

1D hstack:

[1 2 3 4 5 6] , shape: (6,)

a = np.array([[1, 2], [3, 4]])
b = np.array([[5, 6], [7, 8]])
print(“\n2D hstack:”)
result_hstack_2d = np.hstack((a, b))
print(result_hstack_2d, “\nshape:”, result_hstack_2d.shape)

2D hstack:

[[1 2 5 6]

[3 4 7 8]]

shape: (2, 4)

column_stackとの比較 (1D入力の場合)

print(“\n1D column_stack:”)
result_column_stack_1d = np.column_stack((a[0], b[0])) # a[0] = [1, 2], b[0] = [5, 6]
print(result_column_stack_1d, “\nshape:”, result_column_stack_1d.shape)

1D column_stack:

[[1 5]

[2 6]]

shape: (2, 2)

“`

hstackは、入力配列の列数（または1Dの場合は要素数）を合計するようにスタックします。np.column_stack は hstack の特殊なケースで、1次元入力に対して (N, 1) への変換を行います。

7.3. stack

stack関数は最も汎用的なスタック関数です。指定したaxisに沿って、新しい次元を生成してスタックします。

• すべての入力配列は同じ形状である必要がある。
• 指定した axis の位置に新しい次元が挿入され、その次元に沿って入力配列が並べられます。
• 結果の形状は、元の形状の axis の位置に、入力配列の数 k が挿入されたものとなります。例えば、入力形状が (M, N) で axis=0 なら結果は (k, M, N)、axis=1 なら (M, k, N)、axis=2 なら (M, N, k) となります。

“`python
import numpy as np

a = np.array([1, 2, 3])
b = np.array([4, 5, 6])

stackは同じ形状が必要なので、まず1Dを2Dに変換

a_2d = a.reshape(1, -1) # [[1, 2, 3]], shape (1, 3)
b_2d = b.reshape(1, -1) # [[4, 5, 6]], shape (1, 3)

print(“Stack axis=0:”)
result_stack_0 = np.stack((a_2d, b_2d), axis=0)
print(result_stack_0, “\nshape:”, result_stack_0.shape)

Stack axis=0:

[[[1 2 3]]

[[4 5 6]]]

shape: (2, 1, 3) # 元の shape (1, 3) の axis=0 に 2 が挿入された

print(“\nStack axis=1:”)
result_stack_1 = np.stack((a_2d, b_2d), axis=1)
print(result_stack_1, “\nshape:”, result_stack_1.shape)

Stack axis=1:

[[[1 2 3]

[4 5 6]]]

shape: (1, 2, 3) # 元の shape (1, 3) の axis=1 に 2 が挿入された

print(“\nStack axis=2:”)
result_stack_2 = np.stack((a_2d, b_2d), axis=2)
print(result_stack_2, “\nshape:”, result_stack_2.shape)

Stack axis=2:

[[[1 4]

[2 5]

[3 6]]]

shape: (1, 3, 2) # 元の shape (1, 3) の axis=2 に 2 が挿入された

a = np.array([[1, 2], [3, 4]]) # shape (2, 2)
b = np.array([[5, 6], [7, 8]]) # shape (2, 2)

print(“\nStack axis=0 (2D input):”)
result_stack_0_2d = np.stack((a, b), axis=0)
print(result_stack_0_2d, “\nshape:”, result_stack_0_2d.shape)

Stack axis=0 (2D input):

[[[1 2]

[3 4]]

[[5 6]

[7 8]]]

shape: (2, 2, 2) # 元の shape (2, 2) の axis=0 に 2 が挿入された

print(“\nStack axis=1 (2D input):”)
result_stack_1_2d = np.stack((a, b), axis=1)
print(result_stack_1_2d, “\nshape:”, result_stack_1_2d.shape)

Stack axis=1 (2D input):

[[[1 2]

[5 6]]

[[3 4]

[7 8]]]

shape: (2, 2, 2) # 元の shape (2, 2) の axis=1 に 2 が挿入された

print(“\nStack axis=2 (2D input):”)
result_stack_2_2d = np.stack((a, b), axis=2)
print(result_stack_2_2d, “\nshape:”, result_stack_2_2d.shape)

Stack axis=2 (2D input):

[[[1 5]

[2 6]]

[[3 7]

[4 8]]]

shape: (2, 2, 2) # 元の shape (2, 2) の axis=2 に 2 が挿入された

“`

7.4. dstackとstackの比較

ここが重要な点です。dstackは「深さ方向」にスタックすると説明され、これは3番目の軸（インデックス2）に沿って結合するように見えます。しかし、前述の「詳細な仕組み」セクションで見たように、dstackは1次元、2次元の入力に対して特別な形状変換を行います。

• dstack(tup) は、1次元配列 (N,) を (1, N, 1) に、2次元配列 (M, N) を (M, N, 1) に変換してから軸2で結合します。結果の形状は1次元入力に対して (1, N, k)、2次元入力に対して (M, N, k) となります。
• stack(tup, axis=2) は、すべての入力配列が同じ形状である必要があり、その形状 (..., M, N) の配列に対して、新しい軸2を生成して結合します。結果の形状は (..., M, N, k) となります。

つまり、dstackは stack(tup, axis=2) の単純なエイリアスではありません。特に1次元・2次元入力に対する挙動が異なります。

例で比較します。

“`python
import numpy as np

1次元配列を入力

a = np.array([1, 2, 3])
b = np.array([4, 5, 6])

dstackの場合

dstack_result_1d = np.dstack((a, b))
print(“dstack (1D input):\n”, dstack_result_1d, “\nshape:”, dstack_result_1d.shape)

dstack (1D input):

[[[1 4]

[2 5]

[3 6]]]

shape: (1, 3, 2)

stack(axis=2)の場合 – 直接1D配列は受け付けない

stackは入力配列が同じ形状である必要があり、かつスタックする軸はその配列の既存の軸より大きいインデックスである必要がある

1D配列 (3,) に axis=2 でスタックしようとするとエラー

try:
stack_result_1d_axis2 = np.stack((a, b), axis=2)
print(stack_result_1d_axis2)
except ValueError as e:
print(“\nstack(axis=2, 1D input) エラー:”, e)

stack(axis=2, 1D input) エラー: axis 2 is out of bounds for array of dimension 1

stackを使うためには、まず入力配列の次元を増やす必要がある

例えば、hstackと同じ結果を得るには stack(axis=0) か concatenate

vstackと同じ結果を得るには stack(axis=0) 後に transpose か reshape

dstackと同じ結果を得るにはどうするか？

dstackの変換 (3,) -> (1, 3, 1) に相当する操作を各配列に行い、その後 stack(axis=2) する

a_conv = np.expand_dims(np.atleast_2d(a), axis=2) # (3,) -> (1, 3) -> (1, 3, 1)
b_conv = np.expand_dims(np.atleast_2d(b), axis=2) # (3,) -> (1, 3) -> (1, 3, 1)
stack_equivalent_1d = np.stack((a_conv, b_conv), axis=2) # (1, 3, 1) を axis=2 でスタック
print(“\nstack equivalent of dstack (1D input):\n”, stack_equivalent_1d, “\nshape:”, stack_equivalent_1d.shape)

stack equivalent of dstack (1D input):

[[[1 4]

[2 5]

[3 6]]]

shape: (1, 3, 2)

この結果は dstack(a, b) と一致する。

2次元配列を入力

a_2d = np.array([[1, 2], [3, 4]]) # shape (2, 2)
b_2d = np.array([[5, 6], [7, 8]]) # shape (2, 2)

dstackの場合

dstack_result_2d = np.dstack((a_2d, b_2d))
print(“\ndstack (2D input):\n”, dstack_result_2d, “\nshape:”, dstack_result_2d.shape)

dstack (2D input):

[[[1 5]

[2 6]]

[[3 7]

[4 8]]]

shape: (2, 2, 2)

stack(axis=2)の場合

stack_result_2d_axis2 = np.stack((a_2d, b_2d), axis=2)
print(“\nstack(axis=2, 2D input):\n”, stack_result_2d_axis2, “\nshape:”, stack_result_2d_axis2.shape)

stack(axis=2, 2D input):

[[[1 5]

[2 6]]

[[3 7]

[4 8]]]

shape: (2, 2, 2)

この結果は dstack(a_2d, b_2d) と一致する。

“`

この比較から、dstackは
* 1次元配列に対しては (N,) -> (1, N, 1) と変換してから stack(axis=2) を行う。
* 2次元配列に対しては (M, N) -> (M, N, 1) と変換してから stack(axis=2) を行う。
* 3次元以上の配列に対しては、変換なしで stack(axis=2) と同じ結果が得られる。

という特殊な振る舞いをしていることがわかります。したがって、dstackは stack(axis=2) の単なる別名ではなく、特に低次元配列に対する使いやすさを考慮した関数と言えます。2次元配列を「深さ方向」に結合して3次元配列にしたいという、画像処理などの一般的なタスクにおいて直感的に使いやすくなっています。

7.5. まとめ：スタック関数の選び方

• vstack: 配列を行方向に重ねたい場合。同じ列数である必要がある（1Dは1列に変換）。
• hstack: 配列を列方向に並べたい場合。同じ行数である必要がある（1Dはそのまま連結）。
• dstack: 配列を深さ方向（3番目の軸）に重ねたい場合。特に画像チャンネルの結合や、複数の2次元データを3次元データとして扱いたい場合に便利。1D/2D入力に対する特別な変換に注意。
• stack: 指定した任意の軸に沿って新しい次元を作成してスタックしたい場合。すべての入力配列は同じ形状である必要がある。最も柔軟だが、入力配列の準備が必要な場合がある。

状況に応じて適切なスタック関数を選択することが重要です。dstackは特定のユースケース（特に2次元配列を3次元に変換して深さ方向で結合）に特化しており、その挙動を理解していれば非常に効率的に利用できます。

8. dstack使用時の注意点

dstackを効果的かつ安全に使用するために、以下の点に注意してください。

8.1. 入力配列の形状に関する制約

前述の通り、dstackは入力配列の形状に対して特定の制約を課します。

• すべての入力配列は少なくとも1次元である必要がある。 スカラー値は直接スタックできません。
• 1次元配列を入力する場合、すべての配列の要素数が一致する必要がある。 ((N,) の N がすべて同じであること)
• 2次元配列を入力する場合、すべての配列の形状 (M, N) が一致する必要がある。
• 3次元以上の配列を入力する場合、最後の次元を除く形状 (..., M, N) が一致する必要がある。 最後の次元のサイズは異なっていても構いません。

これらの制約を満たさない場合、ValueError が発生します。関数を使用する前に、入力配列の形状を確認する習慣をつけましょう。array.shape プロパティで確認できます。

8.2. メモリ使用量

dstackは入力されたすべての配列の要素を結合して新しい配列を作成します。結果として生成される配列のサイズは、元の配列の要素数の合計になります。したがって、非常に大きな配列を多数スタックする場合、大量のメモリを消費する可能性があることに注意してください。システムメモリを超過すると、プログラムがクラッシュする可能性があります。

メモリ効率が重要な場合は、データ全体を一度にメモリにロードするのではなく、ジェネレーターやイテレーターを使ってデータをチャンクごとに処理したり、Daskのような遅延評価を行うライブラリを検討したりする必要があるかもしれません。

8.3. データ型 (dtype)

dstackは、入力配列のデータ型を考慮して、結果の配列のデータ型を決定します。通常、NumPyは結合される配列の中で最も優先順位の高い（より多くの値を表現できる）データ型に合わせてキャストを行います。例えば、整数型と浮動小数点型の配列をスタックすると、結果の配列は浮動小数点型になります。

明示的に特定のデータ型にしたい場合は、スタック前に入力配列のデータ型を揃えるか、スタック後に result.astype(desired_dtype) を使用することを検討してください。データ型の不一致による予期せぬキャストは、計算精度に影響を与える可能性があります。

8.4. 入力形式はタプルまたはリスト

dstackの引数 tup は、スタックしたいNumPy配列を要素とするタプルまたはリストである必要があります。個々の配列をカンマ区切りで羅列してはいけません。

“`python
import numpy as np

a = np.array([1, 2])
b = np.array([3, 4])

正しい使い方

result_tuple = np.dstack((a, b))
result_list = np.dstack([a, b])

誤った使い方 (SyntaxError になるか、意図しない結果になる)

result_wrong = np.dstack(a, b) # これは引数が2つ渡されたと解釈されるためエラー

“`

9. 上級者向けトピック

9.1. ビューとコピー

NumPyの操作には、元の配列のデータメモリを共有する「ビュー」を返すものと、新しいメモリ領域にデータを複製する「コピー」を返すものがあります。dstack関数は、入力配列を結合して新しい形状の配列を作成するため、通常は新しい配列（コピー）を作成します。つまり、dstackの結果を変更しても、元の入力配列は変更されません。同様に、元の入力配列を変更しても、一度作成されたdstackの結果は変更されません。

“`python
import numpy as np

a = np.array([1, 2])
b = np.array([3, 4])

result = np.dstack((a, b))

print(“Original a:”, a)
print(“Result before modification:\n”, result)

結果配列の一部を変更する

result[0, 0, 0] = 99

print(“\nResult after modification:\n”, result)
print(“Original a after modification:”, a) # aは変更されない
“`

出力:

“`
Original a: [1 2]
Result before modification:
[[[1 3]
[2 4]]]

Result after modification:
[[[99 3]
[ 2 4]]]

Original a after modification: [1 2]
“`

この挙動は、ほとんどの場合で期待されるものであり、意図しない副作用を防ぎます。

10. まとめ

本記事では、Python NumPyライブラリの dstack 関数について、その基本的な使い方から詳細な仕組み、多様な応用例、そして他のスタック関数との比較まで、徹底的に解説しました。

dstack は、複数の配列を「深さ方向」、すなわち3番目の軸（インデックス2）に沿って結合するための関数です。その最大の特徴は、1次元配列 (N,) を (1, N, 1) に、2次元配列 (M, N) を (M, N, 1) に自動的に変換してから軸2で連結するという特殊な前処理を行う点です。この挙動により、特に2次元配列（画像チャンネルなど）を自然な形で3次元配列に結合するタスクに適しています。3次元以上の配列に対しては、最後の次元を除く形状が一致していれば、変換なしで軸2に沿って結合します。

私たちは以下の点を深く掘り下げました：

• NumPy配列の基本概念（次元、形状、軸）の重要性。
• dstackの定義と、それが「深さ方向」のスタックをどのように実現するか。
• 1次元、2次元、3次元以上の各配列を入力とした場合のdstackの具体的な使用方法と結果の形状。
• dstackが内部でどのように配列を変換し、結合しているかの詳細な仕組み。
• 画像処理におけるRGBチャンネルの結合、時系列/センサーデータの結合、3Dデータの構築など、dstackの具体的な応用例。
• vstack、hstack、stackといった他のNumPyスタック関数との挙動や用途の違い。特に、dstackが stack(axis=2) とは異なる（特に低次元入力に対する変換がある）ことを確認しました。
• dstackを使用する際の注意点、特に形状に関する制約、メモリ使用量、データ型について。

dstackはNumPyの強力な機能の一つであり、多次元データを扱う上で非常に有用なツールです。その特殊な挙動を理解することで、あなたはより複雑な配列操作を自信を持って行うことができるようになります。画像処理、データ分析、数値シミュレーションなど、さまざまな分野でNumPy配列を駆使する際に、ぜひdstackをあなたのツールキットに加えてください。

NumPyにはまだまだ多くの強力な関数があります。本記事が、あなたがNumPyの他の関数についても深く学び、Pythonを使った数値計算のスキルをさらに向上させる一助となれば幸いです。

11. 参考文献/リソース

• NumPy 公式ドキュメント: numpy.dstack – https://numpy.org/doc/stable/reference/generated/numpy.dstack.html
• NumPy 公式ドキュメント: numpy.vstack – https://numpy.org/doc/stable/reference/generated/numpy.vstack.html
• NumPy 公式ドキュメント: numpy.hstack – https://numpy.org/doc/stable/reference/generated/numpy.hstack.html
• NumPy 公式ドキュメント: numpy.stack – https://numpy.org/doc/stable/reference/generated/numpy.stack.html
• NumPy 公式ドキュメント: Array manipulation routines – https://numpy.org/doc/stable/reference/routines.array-manipulation.html

これらの公式ドキュメントは、各関数の詳細な情報、パラメータ、さらなる例を提供しています。必要に応じて参照することをお勧めします。

---