building_block.assert_dtypes

データ型による引数のアサーション

概要

　R言語の checkmate パッケージの関数群をオマージュした、引数に代入された値が想定されたデータ型ではないときにエラーを出力する関数です。

assert_character(
    arg: Any, 
    arg_name: Optional[str] = None,
    len_arg: Optional[int] = None,
    len_min: int = 1,
    len_max: Optional[int] = None,
    any_missing: bool = False,
    all_missing: bool = False,
    nullable: bool = False,
    scalar_only: bool = False
    )

assert_logical(
    arg: Any, 
    arg_name: Optional[str] = None,
    len_arg: Optional[int] = None,
    len_min: int = 1,
    len_max: Optional[int] = None,
    any_missing: bool = False,
    all_missing: bool = False,
    nullable: bool = False,
    scalar_only: bool = False
    )

assert_numeric(
    arg: Any,
    arg_name: Optional[str] = None,
    lower = -float('inf'), 
    upper = float('inf'), 
    inclusive: Literal["both", "neither", "left", "right"] = "both",
    len_arg: Optional[int] = None,
    len_min: int = 1,
    len_max: Optional[int] = None,
    any_missing: bool = False,
    all_missing: bool = False,
    nullable: bool = False,
    scalar_only: bool = False
    )

assert_integer(
    arg: Any,
    arg_name: Optional[str] = None,
    lower = -float('inf'), 
    upper = float('inf'), 
    inclusive: Literal["both", "neither", "left", "right"] = "both",
    len_arg: Optional[int] = None,
    len_min: int = 1,
    len_max: Optional[int] = None,
    any_missing: bool = False,
    all_missing: bool = False,
    nullable: bool = False,
    scalar_only: bool = False
    )

assert_count(
    arg: Any,
    arg_name: Optional[str] = None,
    lower = 0, 
    upper = float('inf'), 
    inclusive: Literal["both", "neither", "left", "right"] = "both",
    len_arg: Optional[int] = None,
    len_min: int = 1,
    len_max: Optional[int] = None,
    any_missing: bool = False,
    all_missing: bool = False,
    nullable: bool = False,
    scalar_only: bool = False
    )

assert_float(
    arg: Any,
    arg_name: Optional[str] = None,
    lower = -float('inf'), 
    upper = float('inf'), 
    inclusive: Literal["both", "neither", "left", "right"] = "both",
    len_arg: Optional[int] = None,
    len_min: int = 1,
    len_max: Optional[int] = None,
    any_missing: bool = False,
    all_missing: bool = False,
    nullable: bool = False,
    scalar_only: bool = False
    )

　それぞれの関数は第一引数 arg に代入された array-like オブジェクトの要素が、次の型ではない場合にエラーを出力します。

• assert_character()：str
• assert_numeric()：int or float
• assert_integer()：int
• assert_count()：int
• assert_float()：float

引数 Argument

• arg（必須）array-like
  　適正かどうかを判断したい引数。検証対象となる引数。スカラー値、または array-like オブジェクト（例：list、NumPy 配列、pandas Series）を指定できます。
• arg_name：str
  　エラーメッセージに表示する引数の名前。None の場合、可能であれば arg に渡された変数名が自動的に推定されます。なお、この機能は varname.argname()関数を使って実装されています。
• lower, upper：int or float
  　arg に代入されたオブジェクトの要素が取るべき値の最大値と最小値。
• inclusive：str
  　値の範囲チェックにおいて、境界値を含めるかどうかを表す文字列。
  'both', 'neither', 'left', 'right' から選択できます。
  
  • 'both'：lower <= x <= upper
  • 'neither'：lower < x < upper
  • 'left'：lower <= x < upper
  • 'right'：lower < x <= upper
• len_arg: int 引数の要素数を表す自然数：要素数をこの値と正確に一致させたい場合に指定します。len_arg を指定した場合、引数はちょうどこの個数の要素をもつ必要があります。
  　引数の長さは、None や np.nan などの欠測値を含む要素数をもとに判定されます。例えば引数の要素が arg = [1, None, 3] のとき、len_arg = 3なら正常として判定され、len_arg = 2 ならエラーが出されます。
• len_min, len_max:: int
  許容される最小の要素数と最大の要素数。len_max = None の場合、上限は設けられません。
• any_missing:bool
  True の場合、欠測値（例：None、NaN、pd.NA など）が引数 arg の一部に含まれていても許容されます。
• all_missing: bool
  True の場合、すべての要素が欠測値であることを許容します。
• nullable: bool
  True の場合、引数そのものが None であることを許容します。この機能は、None を初期値とする Optional な引数のアサーションを行う際に使用することを想定しています。
• scalar_only: bool
  True の場合、スカラー値のみを許容します。この場合、1要素であっても、list や配列などの array-like オブジェクトは受け付けません。

返り値 Value

引数 arg に代入されたオブジェクトの全ての要素が、アサーションの条件を満たしていれば何も返さず、そうでなければエラーメッセージを出力します。

使用例 Examples

from py4stats import building_block as build
x = [1, 2, 3]
y = ['A', 'B', 'C']

build.assert_character(x, arg_name = 'x')
#> TypeError: Argument `x` must be of type 'str'.

build.assert_character(y, arg_name = 'y')

build.assert_numeric(x, arg_name = 'x')

build.assert_numeric(y, arg_name = 'y')
#> TypeError: Argument `y` must be of type 'int' or 'float' with value(s) -inf <= x <= inf.

z = [0.1, 0.3, 0.6]
build.assert_numeric(z, arg_name = 'z', lower = 0, upper = 1)

z.extend([2, 3])
build.assert_numeric(z, arg_name = 'z', lower = 0, upper = 1)
#> ValueError: Argument `x` must have value 0 <= x <= 2.
#>             element '3' of `x` not sutisfy the condtion.

z = 1
build.assert_numeric(
    z, arg_name = 'z', 
    lower = 0, upper = 1, 
    inclusive = 'left'
    )
#> ValueError: Argument `z` must have value 0 <= x < 1.

また、これらの関数では、 len_arg, len_min および len_max を使うことで引数の要素数に関するアサーションを実施できます。

build.assert_numeric(x, arg_name = 'x', len_arg = 1)
#> ValueError: Argument `x` must have length 1, but has length 3.

build.assert_numeric(x, arg_name = 'x', len_min = 4)
#> ValueError: Argument `x` must have length 4 <= n <= inf, but has length 3.

build.assert_numeric(x, arg_name = 'x', len_max = 2)
#> ValueError: Argument `x` must have length 1 <= n <= 2, but has length 3.

欠測値を含む引数に関する処理として、初期設定では引数の要素に欠測値が含まれるとエラーを出力しますが、any_missing = True を指定した場合、欠測値を除外した上でアサーションを実施します。

l = [1, 2, None]
build.assert_numeric(l, arg_name = 'l')
#> ValueError: Argument `l` contains missing values (element 2).

build.assert_numeric(l, arg_name = 'l', any_missing = True)

l = [None, None]
build.assert_numeric(l, arg_name = 'l', any_missing = True)
#> ValueError: Argument `arg` contains only missing values.

build.assert_numeric(l, arg_name = 'l', all_missing = True)

また、引数に None が指定されると初期設定ではエラーを出力しますが、nullable = True で None を許容することができ、None ます。nullable = True かつ arg に None が代入された場合、引数の型や値に関するアサーションは省略されます。

build.assert_numeric(None, arg_name = 'x')
#> ValueError: Argument `x` contains only missing values.

build.assert_numeric(None, arg_name = 'x', nullable = True)

参照

　データ型の判定にはこちらの関数を使用しています。

---

Return to Function reference.