harmmean

R2026b

調和平均

構文

m = harmmean(X)

m = harmmean(X,"all")

m = harmmean(X,dim)

m = harmmean(X,vecdim)

m = harmmean(___,nanflag)

説明

m = harmmean(X) は、X の調和平均を返します。m で返される調和平均は、X のデータのタイプによって異なります。

m = harmmean(X,"all") は、X のすべての要素の調和平均を返します。

m = harmmean(X,dim) は、X の作用次元 dim に沿った調和平均を返します。

m = harmmean(X,vecdim) は、ベクトル vecdim で指定された次元における調和平均を返します。vecdim の各要素は、入力配列 X の次元を表します。出力 m の指定された作用次元における長さは 1 です。他の次元の長さは、X と m で同じになります。

m = harmmean(___,nanflag) は、前の構文におけるいずれかの入力引数の組み合わせを使用して、NaN 値を計算から除外するかどうかを指定します。

例

調和平均と算術平均の比較

結果の再現性を得るため、乱数シードを設定します。

rng(0,"twister")

5 行 4 列の指数乱数の行列を作成します。

X = exprnd(1,5,4)

X = 5×4

    0.2049    2.3275    1.8476    1.9527
    0.0989    1.2783    0.0298    0.8633
    2.0637    0.6035    0.0438    0.0880
    0.0906    0.0434    0.7228    0.2329
    0.4583    0.0357    0.2228    0.0414

X の列の調和平均と算術平均を計算します。

harmonic = harmmean(X)

harmonic = 1×4

    0.1743    0.0928    0.0797    0.1205

arithmetic = mean(X)

arithmetic = 1×4

    0.5833    0.8577    0.5734    0.6357

X のすべての列で、算術平均が調和平均より大きくなっています。

すべての値の調和平均

配列のすべての値の調和平均を求めます。

3 x 5 x 2 の配列 X を作成します。

X = reshape(1:30,[3 5 2])

X = 
X(:,:,1) =

     1     4     7    10    13
     2     5     8    11    14
     3     6     9    12    15


X(:,:,2) =

    16    19    22    25    28
    17    20    23    26    29
    18    21    24    27    30

X のすべての要素の調和平均を求めます。

m = harmmean(X,"all")

m = 
7.5094

指定した次元に沿った調和平均

多次元配列に対して、複数の異なる作用次元および次元のベクトルに沿って調和平均を求めます。

3 x 5 x 2 の配列 X を作成します。

X = reshape(1:30,[3 5 2])

X = 
X(:,:,1) =

     1     4     7    10    13
     2     5     8    11    14
     3     6     9    12    15


X(:,:,2) =

    16    19    22    25    28
    17    20    23    26    29
    18    21    24    27    30

既定の次元に沿って X の調和平均を求めます。

hmean1 = harmmean(X)

hmean1 = 
hmean1(:,:,1) =

    1.6364    4.8649    7.9162   10.9392   13.9523


hmean1(:,:,2) =

   16.9607   19.9666   22.9710   25.9743   28.9770

既定では、harmmean は、サイズが 1 ではない X の最初の次元に沿って作用します。このケースでは、この次元は X の 1 番目の次元です。したがって、hmean1 は 1×5×2 の配列です。

2 番目の次元に沿って X の調和平均を求めます。

hmean2 = harmmean(X,2)

hmean2 = 
hmean2(:,:,1) =

    3.1852
    5.0641
    6.5693


hmean2(:,:,2) =

   21.1595
   22.1979
   23.2329

hmean2 は 3×1×2 の配列です。

3 番目の次元に沿って X の調和平均を求めます。

hmean3 = harmmean(X,3)

hmean3 = 3×5

    1.8824    6.6087   10.6207   14.2857   17.7561
    3.5789    8.0000   11.8710   15.4595   18.8837
    5.1429    9.3333   13.0909   16.6154   20.0000

hmean3 は 3 行 5 列の配列です。

入力引数 vecdim を使用して 1 番目の次元と 2 番目の次元を指定することにより、X の各ページの調和平均を求めます。

mpage = harmmean(X,[1 2])

mpage = 
mpage(:,:,1) =

    4.5205


mpage(:,:,2) =

   22.1645

たとえば、mpage(1,1,2) は X(:,:,2) の要素の調和平均です。

2 番目の次元と 3 番目の次元を指定して、X(i,:,:) の各スライスの要素の調和平均を求めます。

mrow = harmmean(X,[2 3])

mrow = 3×1

    5.5369
    8.2469
   10.2425

たとえば、mrow(3) は X(3,:,:) の要素の調和平均であり、harmmean(X(3,:,:),"all") を指定することと同じです。

NaN を除外した調和平均

ベクトルを作成し、NaN 値を除外して調和平均を計算します。

X = 1:10;
X(3) = nan; % Replace the third element of x with a NaN value
n = harmmean(X,"omitnan")

n = 
3.4674

"omitnan" を指定しない場合、harmmean(x) は NaN を返します。

入力引数

X — 入力データ

数値ベクトル | 数値行列 | 多次元数値配列

入力データ。数値ベクトル、数値行列、または多次元数値配列として指定します。

• X がベクトルである場合、harmmean(X) は X 内の要素の調和平均です。

• X が行列である場合、harmmean(X) は X の各列の調和平均が格納されている行ベクトルです。

• X が多次元配列である場合、harmmean は X の大きさが 1 でない最初の次元に作用します。

X が行列または配列である場合に作用次元を指定するには、入力引数 dim を使用します。

データ型: single | double

dim — 次元

正の整数スカラー

作用する対象となる次元。正の整数スカラーを指定します。値を指定しなかった場合、サイズが 1 ではない X の最初の配列次元が既定値になります。

2 次元配列 X について考えます。

• dim が 1 に等しい場合、harmmean(X,1) は X の各列の調和平均が格納されている行ベクトルを返します。

• dim が 2 に等しい場合、harmmean(X,2) は X の各行の調和平均が格納されている列ベクトルを返します。

dim が ndims(X) より大きい場合、または size(X,dim) が 1 である場合、harmmean は X を返します。

データ型: single | double

vecdim — 次元のベクトル

正の整数ベクトル

次元のベクトル。正の整数ベクトルを指定します。vecdim の各要素は、入力配列 X の次元を表します。出力 m の指定された作用次元における長さは 1 です。他の次元の長さは、X と m で同じになります。

たとえば、X が 2×3×3 の配列である場合、harmmean(X,[1 2]) は 1×1×3 の配列を返します。出力の各要素は、X の対応するページにおける要素の調和平均です。

データ型: single | double

nanflag — NaN の条件

"includenan" (既定値) | "omitnan"

NaN 条件。"includenan" または "omitnan" として指定します。この引数の値が "includenan" の場合、関数は調和平均を計算するときに NaN 値を含め、NaN を返します。値が "omitnan" の場合、関数は入力データに含まれている NaN 値を無視します。

データ型: char | string

出力引数

m — 調和平均

数値スカラー | 数値ベクトル | 数値行列 | 多次元配列

調和平均。数値スカラー、数値ベクトル、数値行列、または多次元数値配列として返されます。harmmean で 0 を含む配列の調和平均を計算した場合、返される値は 0 になります。

詳細

調和平均

標本 X の調和平均は次のようになります。

$$m=\frac{n}{{\displaystyle \sum _{i=1}^n\frac{1}{x_i}}}$$

ここで、n は X 内の値の個数です。

調和平均は、平均株価収益率や平均投資収益率など、一連の比率やレート値の平均を計算する場合に使用します。

拡張機能

tall 配列

メモリの許容量を超えるような多数の行を含む配列を計算します。

harmmean 関数は、tall 配列を完全にサポートします。詳細については、tall 配列を参照してください。

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意および制限:

• 入力引数 "all"、vecdim および nanflag はサポートされません。

• 入力引数 dim はコンパイル時の定数でなければなりません。

• 入力引数 dim を指定しなかった場合、生成されるコードでは作用次元が異なる可能性があります。この結果、ランタイム エラーが発生する可能性があります。詳細は、既定の次元の選択に関する MATLAB との非互換性 (MATLAB Coder)を参照してください。

コード生成の詳細については、統計と機械学習の関数のコード生成の紹介およびMATLAB Coder を使用したコード生成の概要 (MATLAB Coder)を参照してください。

GPU コード生成

GPU Coder™ を使用して NVIDIA® GPU のための CUDA® コードを生成します。

使用上の注意および制限については、「C/C++ コード生成」セクションを参照してください。GPU コード生成にも同様の、使用上の注意および制限が適用されます。

スレッドベースの環境

MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

harmmean 関数は、スレッドベースの環境を完全にサポートします。詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

GPU 配列

Parallel Computing Toolbox™ を使用してグラフィックス処理装置 (GPU) 上で実行することにより、コードを高速化します。

この関数は、GPU 配列を完全にサポートします。詳細については、GPU での MATLAB 関数の実行 (Parallel Computing Toolbox)を参照してください。

バージョン履歴

R2006a より前に導入

R2024a: gpuArray 入力の指定

harmmean は gpuArray 入力を完全にサポートします。

参考

mean | median | geomean | trimmean