フィルタ式

フィルタ式は、データセットの行を条件で絞り込む式です。MIDAS は、次の場所で同じ構文と同じ評価の規則でフィルタ式を読みます。Data Table タブ と Filtered Data タブ のフィルタ入力欄、Graph Builder の layer のフィルタ、Agent API の datasets.filter()・datasets.selectRows()・datasets.excludeRows() です。

このページの例は、Auto MPG データセットの列を使っています。列の意味は サンプルデータセット を参照してください。

式の構成

フィルタ式は、model_year >= 80 のような条件を AND・OR・NOT と括弧で組み合わせて書きます。条件の対象には、列のほかに stat の関数 も書けます。AND や LIKE などの演算子は、大文字でも小文字でも書けます。

列名は "model year" のようにダブルクォートで囲んで書きます。英字で始まり、英字・数字・アンダースコアだけからなる列名は、クォートなしでも書けます。ただし、and・like・null などフィルタ式の予約語と同じ列名は、ダブルクォートで囲みます。

値はデータ型ごとに次の形で書きます。string と enum の値は 'usa' のようにシングルクォートで囲みます。値にシングルクォートを含めるには、'O''Brien' のようにシングルクォートを 2 つ重ねます。int64 と float64 の値は 80・-1.5・1e3 のようにクォートなしで書きます。boolean の値は、クォートなしで true または false と書きます。date と datetime の値は '2024-01-31' または '2024/01/31' の形で書きます。時刻を付けるときは '2024-01-31T09:00:00' の形で書きます。タイムゾーンは '2024-01-31T09:00:00+09:00' のように末尾に付けます。

条件

書ける条件は次の表のとおりです。

条件例意味
= != > < >= <=model_year >= 80値の比較
LIKE / ILIKE / NOT LIKE / NOT ILIKEname LIKE 'ford%'パターン照合
IS NULL / IS NOT NULLhorsepower IS NULL欠損値の判定
IN / NOT INorigin IN ('europe', 'japan')候補のいずれかに一致
BETWEEN / NOT BETWEENmodel_year BETWEEN 70 AND 75両端を含む範囲の判定
NOT (条件)NOT (origin = 'usa' AND model_year = 70)条件の否定

LIKE のパターンでは、% が 0 文字以上の任意の文字列に、_ が任意の 1 文字に一致します。% と _ をその文字として照合するには、バックスラッシュを前に置きます。ILIKE は大文字小文字を区別せずに照合します。LIKE と ILIKE は string と enum の列だけに使えます。パターンは 'ford%' のように文字列で書きます。

比較の規則

MIDAS は、式に書いた値を列のデータ型に変換してから列の値と比較します。たとえば int64 の列 model_year に対する model_year = '70' は数値の 70 との比較になり、model_year = 70 と同じ結果です。string の列を数値として比較するには、Convert Column Types タブ で先にデータ型を変換します。

MIDAS は date と datetime の値を UTC で比較します。タイムゾーンを省略した時刻は UTC の時刻として扱います。date 列の値を時刻付きの値と比較するときは、date の値を UTC のその日の 0 時として扱います。

値の大小の順序は、データ型ごとに決まっています。enum の列は、値を enum 定義の順序 で比較します。たとえば enum 定義が Low・Medium・High の順の列では、level > 'Medium' は High の行に一致します。string の値は UTF-16 の符号単位の順で比較するので、ASCII の英字では大文字が小文字より前になります。boolean の値は false を true より小さい値として比較します。

欠損値

欠損値は、どの値とも等しくなく、大小の順序を持たず、どのパターンにも一致しません。そのため、比較する列の値が欠損の行は、=・>・<・>=・<=・LIKE・ILIKE・IN・BETWEEN のどの条件にも一致しません。

否定の条件は、否定する前の条件に一致しない行すべてに一致します1。!=・NOT IN・NOT BETWEEN・NOT LIKE・NOT ILIKE・NOT (条件) は、否定する前の条件が欠損の行に一致しないため、どれも欠損の行に一致します。たとえば horsepower != 100 は、horsepower が欠損の行にも一致します。否定の条件から欠損の行を外すには、AND horsepower IS NOT NULL を加えます。

欠損かどうかを判定する条件は IS NULL と IS NOT NULL だけです。NULL は値として書けません。

stat の関数

stat の関数は、Graph Builder の stat が計算する値を行ごとに返します。stat は行を集めて集計結果を作ります。ヒストグラムの 1 本のビンや、1 つの群の平均値のような、stat が作る 1 つの集計結果を、このページでは要素と呼びます。stat の関数は、各行に、その行が入った要素の値を返します。たとえば summary(mpg, fun: mean, by: [origin]) は、各行に、その行と origin の値が同じ行での mpg の平均値を返します。

関数は、フィルタを適用するデータセットのすべての行で集計します。同じ式の中で AND でつないだほかの条件は集計に使う行を絞らず、行を絞るのは where だけです。

関数は、列を書ける場所のどこにでも書けます。比較の左辺にも右辺にも書け、IS NULL・IN・BETWEEN の対象にも書けます。

関数の書き方

関数は name(列, ..., by: [列, ...], key: value, ..., where: 条件) の形で書きます。位置引数は、関数が入力に使う列です。by は群を分ける列の並びで、関数は by の列の値の組ごとに群を作ります。関数は、by の列の欠損値も 1 つの値として扱い、群を作ります。where は関数が計算に使う行の条件で、フィルタ式と同じ構文で書きます。列名は、条件の対象の列名と同じ規則で書きます。関数名は大文字と小文字を区別せず、次に ( が続くときだけ関数として読むので、count という名前の列は count > 3 のように書けます。

名前付き引数の値は、数値、シングルクォートの文字列、true・false、角括弧で囲んだ列名の並びのいずれかで書きます。クォートなしの識別子は文字列として読むので、fun: mean は fun: 'mean' と同じ意味です。

名前付き引数の多くは、同じ名前の stat のパラメータ と同じ意味と値の範囲を持ちます。この対応から外れるのは、output・within・timeZone・fun・p・k・closedEnd の 7 つと、日時の列に関わる 2 つの例外です。output は、関数が返す値の種類を選ぶ名前付き引数です。timebin の interval は、閲覧者のローカル時刻ではなく timeZone の現地時刻で区間を区切ります。bin に date か datetime の列を渡したときの binwidth・boundary・center の単位は、時刻を 1970-01-01T00:00:00Z からのミリ秒で表した値です。

関数が返す値

関数は、値を計算できない行で欠損値を返します。where に合わない行と、位置引数の列の値が欠損の行は、どの要素にも入らないので欠損値になります。stat が値を計算できない群の行も欠損値になります。summary の fun: sd は、行が 1 つしかない群の行で欠損値を返します。density は、bandwidth を省いたときに自動の帯域幅が 0 になる群の行で欠損値を返します。行が 1 つの群、値がすべて同じ群、中央 50% の値が同じ群がこれに当たります。roc は、ラベルが 0 から 1 の範囲の外にある行と、ラベルが 1 種類しかない群の行で欠損値を返します。survival は、時間が負の行かイベントが 0・1 以外の行が 1 行でもあると、すべての行で欠損値を返します。関数の値が欠損の行は、列の値が欠損の行と同じ規則で比較の条件に一致しません。

関数の値の型は、timebin の center・start・end が datetime、boxplot の outlier が boolean、それ以外が float64 です。関数の値は、同じ型の列と同じ規則で比較します。bin に date か datetime の列を渡したときの center・start・end は、引数と同じミリ秒の単位の float64 の値です。

関数の一覧

書ける関数は次の表のとおりです。表の output 欄は選べる値を示し、先頭の値が既定です。

関数位置引数output名前付き引数返す値
count数える列valueなし数える列の値と by の列の値がその行と同じ行の数
summary数値の列valuefun(必須)、p、k群の fun の集計値
bin数値・date・datetime の列center、value、start、endbins、binwidth、boundary、center、yScale、closedEnd行が入るビンの中央・高さ・下端・上端
timebindate・datetime の列center、value、start、endinterval、yScale、timeZone(datetime の列で必須)行が入る時間の区間の中央・高さ・始点・終点
boxplot数値の列value、outliercoefひげの内側の行では群の中央値、ひげの外側の行では行の値。outlier はひげの外側かどうか
density数値の列valuebandwidth、yScale行の値での群のカーネル密度推定値
smoothx の列(数値・date・datetime)、y の列(数値)value、lower、uppermethod、span、level、interval行の x での平滑化曲線の値と、その区間の下端・上端
survival時間の列、イベントの列(どちらも数値)value、lower、upperconfLevel行の時間での Kaplan-Meier 推定値と、各時点ごとの信頼区間の下端・上端
rocスコアの列、ラベルの列(どちらも数値)tpr、fprなし行のスコアをしきい値とする ROC 曲線の点の真陽性率・偽陽性率
ecdf数値の列valueなし行の値での群の経験累積分布関数の値
qq数値の列theoreticalなし群の中での行のプロット位置に対応する標準正規分布の分位点
cumsum内側の関数valuenormalize、within内側の関数の値を要素の順に累積した和
sort内側の関数rank、valueby(1 列)、order、limitby の列のカテゴリを内側の関数の値の合計で並べたときの順位(rank)か、limit で残した要素の内側の関数の値(value)
transform内側の関数valuemultiply、add内側の関数の値 × multiply + add
stack内側の関数top、bottomwithin内側の関数の値を積み上げたときの、行が入った要素の区間の上端・下端
fill内側の関数top、bottomwithinstack と同じ積み上げで、積み上げの合計を 1 にしたときの上端・下端

summary の fun には、次の表の値のどれかを書きます。表の SD は分母を n−1 とする標本標準偏差、SE は標準誤差 SD / √n です。

fun集計値
mean平均
sum合計
median中央値
min最小値
max最大値
sdSD
var分母を n−1 とする標本分散
lower_se、upper_se平均 − SE、平均 + SE
lower_sd、upper_sd平均 − SD、平均 + SD
quantilep 分位数。Statistics タブの分位点 と同じ線形補間で求めます
mean_plus_k_sd、mean_minus_k_sd平均 + k × SD、平均 − k × SD

p は quantile の確率で、0 から 1 の値です。省くと 0.5 です。k は mean_plus_k_sd と mean_minus_k_sd の SD の倍率で、省くと 1 です。

bin と timebin のビンの区切りは、by によらず、関数が計算に使うすべての行の範囲から決まります。by は、各ビンの行数を群ごとに分けます。bin と timebin は、各ビンに下端以上、上端未満の値の行を入れます。bin で binwidth を省くとビンの数が bins に固定され、最後のビンは上端以上の値の行も入れます。boundary や center で区切りをずらしたときに出る、最後のビンの上端を超える値の行も、最後のビンに入ります。binwidth を書くと、bin は最大値の行を入れるまでビンを足すので、最大値がビンの端にあるときは、その端から始まるビンを作ります。

bin の closedEnd は、closedEnd 以上の値の行を入れるビンを決めます。closedEnd は binwidth と併せて書きます。bin は、closedEnd 以上の値の行を、値が closedEnd − binwidth / 2 の行と同じビンに入れます。closedEnd がビンの端なら、これらの行は closedEnd で終わるビンに入ります。Select mode で binwidth を省いたヒストグラムを囲むと、MIDAS は最後のビンの上端を closedEnd に記録します。値がすべて整数の列を描いた Histogram と、Integer Bins が効いた Bin stat のレイヤーでは、MIDAS は整数の binwidth を記録し、closedEnd を記録しません。

timebin は、date の列では暦の日付で区間を区切ります。datetime の列では timeZone に書いた IANA のタイムゾーン('Asia/Tokyo' など)の現地時刻で区間を区切るので、datetime の列には timeZone が必須です。

datetime の列の timebin では、夏時間の終了などで現地時刻が戻る時点も区間の区切りになります。現地時刻が 1 時から 0 時に戻るタイムゾーン(Atlantic/Azores など)では、その日の 1day の区間が、時刻が戻る時点の前後で 2 つに分かれます。

boxplot は、第 1 四分位数 − coef × IQR より小さい行と、第 3 四分位数 + coef × IQR より大きい行を、ひげの外側の行とします。IQR は四分位範囲で、第 3 四分位数 − 第 1 四分位数です。四分位数は Statistics タブの分位点 と同じ線形補間で求めます。coef の既定は 1.5 です。

density は、群の範囲を 100 点で等分した位置で求めた密度曲線を、行の値で線形補間した値を返します。bandwidth を省くと、帯域幅は Silverman の経験則 で決まります。群の範囲が帯域幅に比べて広いと、100 点の間隔が帯域幅より広くなり、線形補間した値と行の値での推定値の差が大きくなります。

smooth は、群の平滑化曲線を行の x で線形補間した値を返します。lower・upper は interval の区間の端で、interval を省くと予測区間です。

survival の区間は、Greenwood の公式 による分散から log 尺度で作った、各時点での信頼区間です。曲線全体を同時に覆う信頼帯ではありません。

roc は、スコアが行のスコア以上の行を陽性と判定したときの真陽性率と偽陽性率を返します。ラベルが 0 から 1 の割合のときは、各行をラベルの値の重みで陽性に、1 − ラベルの値の重みで陰性に数えます。

qq は、同じ値の行にも、データの順に別々のプロット位置を割り当てます。

要素を変換する関数

cumsum・sort・transform・stack・fill は、位置引数に内側の関数を 1 つ書き、内側の関数が作った要素の値を変換します。変換する値は内側の関数の output の値です。ビンの位置と outlier は量ではないので、内側の bin と timebin には output: value を書き、boxplot の outlier は内側にできません。

sort を内側にすると、外側の関数は順位ではなく、sort の内側の値を並べ替えた順で変換します。

within と sort の by には、内側の関数の要素を分ける列から選んだ列を書きます。要素を分ける列は、count では数える列と by の列、それ以外の関数では by の列です。この 5 つの関数のうち、自身の by を書けるのは sort だけで、sort の by には順位を付ける列を 1 つ書きます。

cumsum は、内側の関数の値を要素の順に、within の列の値の組ごとに累積します。要素の順は内側の関数の出力の順で、count・summary・boxplot では群がデータに最初に現れた順、bin・timebin ではビンの順、sort では並べた順です。値の順で累積するには、sort を内側に書きます。within を省くと、すべての要素を通して累積します。値が欠損の要素は累積から外します。normalize: true のとき、cumsum は累積した和を、合計を 100 とするパーセントで返します。合計が 0 の組では、累積した和をそのまま返します。

sort は、by の列のカテゴリに、内側の関数の値の合計の順で 1 から順位を付けます。order を省くと、合計が大きい順に順位を付けます。合計が同じカテゴリには、データに最初に現れた順で別々の順位を付けます。どの要素の値も計算できないカテゴリの行と、limit で外れたカテゴリの行には欠損値を返します。

stack と fill は、within の列の値の組ごとに、要素を分ける列のうち within に無い列の値ごとの要素を順に積み上げます。内側の関数がビンを作るときは、ビンごとに積み上げます。within を省くと、count では数える列、bin と timebin ではビンが既定になります。fill は、合計が 0 の組の行に欠損値を返します。

関数を使った条件の例

次の表は、関数を使った条件の例です。最後の例は、日時の列 ts を持つデータセットの例です。

式一致する行
summary(mpg, fun: mean, by: [origin, cylinders], where: model_year >= 80) BETWEEN 25 AND 35model_year が 80 以上の行だけで求めた、その行の origin と cylinders の組の mpg の平均値が 25 以上 35 以下になる行。model_year が 80 未満の行は一致しません
mpg > summary(mpg, fun: mean, by: [origin])mpg が、その行の origin の群の mpg の平均値より大きい行
boxplot(horsepower, by: [cylinders], output: outlier) = truecylinders の群の箱ひげ図で、ひげの外側にある行
sort(count(origin), by: [origin]) <= 2行数が多い順で上位 2 位以内の origin の行
timebin(ts, interval: '1month', timeZone: 'Asia/Tokyo', output: start) = '2024-04-01T00:00:00+09:00'日時の列 ts が東京の現地時刻で 2024 年 4 月に入る行

See also

脚注

  1. SQL Query Editor タブ の WHERE 句はこの規則に従いません。WHERE horsepower != 100 は、horsepower が欠損の行に一致しません。 ↩