データ品質フィールドについて：data_incomplete と null_percentage

この記事では、Butlr が API レスポンスで data_incomplete と null_percentage の 2 つのフィールドを使ってデータの使用可否を示す仕組みについて説明します。

これらのインジケーターにより、次の 2 つを区別できます。

• 有効な在室値（0 を含む）

• データ収集が不完全だった区間

これにより、ダッシュボード、分析システム、インテグレーションがセンサーデータを正しく解釈できます。

これらのフィールドが重要な理由

時間枠によっては、システムが 1 台以上のセンサーから不完全なデータを受信することがあります。

追加のインジケーターがないと、次のケースを区別するのが難しくなります。

• 実際に無人のスペース（occupancy = 0）

• 無人と表示されている（occupancy = 0）が、データが不完全なため使用すべきでないスペース

• 在室ありと表示されている（occupancy = 0）が、データが不完全なため使用すべきでないスペース

これに対応するため、Butlr API は、返された値が完全なデータに基づいているかどうかを判断するためのデータ品質インジケーターを提供しています。

データ品質フィールド

data_incomplete

時間枠のデータが完全かどうかを示すブール型のフィールドです。

data_incomplete = true の場合でも、利用可能な入力から値が計算されることはありますが、その区間は長期的な分析やレポートには使用しないでください。

null_percentage（0～1）

null_percentage は診断用のフィールドで、0.30 をしきい値として解釈します。

• ≤ 0.30：データは引き続き使用可能とみなされ、必ずしも品質が低いことを示すものではありません

• > 0.30：データ品質は不十分とみなされ、通常は信頼できるデータとして扱うべきではありません

null_percentage は診断用のフィールドです。Butlr では、データを使用するかどうかの判断に data_incomplete を主な指標として用いることを推奨しています。

結果の解釈方法

ユースケース 1：在室 0 とデータなしの見分け方

• シナリオ
  • 在室値が 0 で、それが実際の値なのかデータの欠落なのかを判断する必要がある場合。
• 検証ルール
  • data_incomplete = false の場合 → 有効な在室 0 です。
  • data_incomplete = true の場合 → 値を信頼しないでください。
  • null_percentage だけに頼らないでください。
• 期待される結果
  • 「無人のスペース」と「データ未報告」を明確に区別できます。
  • 運用ワークフローでの誤報が減ります。

ユースケース 2：グラフで使用する前のデータ検証

• シナリオ
  • ダッシュボードのグラフを作成する際に、データの信頼性を確保したい場合。
• 推奨される方法
  • 15 分の粒度でクエリします。
  • data_incomplete = true の場合：
    • その 15 分間の区間を除外します。
  • 検証後、必要に応じて時間単位または日単位に集計します。
• 期待される結果
  • 短時間の品質低下も 15 分の解像度で確認できます。
  • 集計グラフ（時間単位・日単位）には、検証済みの区間のみが反映されます。
  • data_incomplete = false で在室が 0 の場合は、有効な 0 として信頼できます。

{
  "window": {
    "every": "15m",
    "function": "max",
    "timezone": "America/New_York"
  },
  "filter": {
    "start": "2026-02-01T05:00:00Z",
    "stop": "2026-02-13T05:00:00Z",
    "null_on_incomplete": true,
    "spaces": { "eq": ["space_XXXXXXXXX"] },
    "measurements": ["traffic_floor_occupancy"],
    "value": { "gte": 0 }
  }
}

ユースケース 3：長期間のデータ可用性（例：過去 6 か月）

• シナリオ
  • 長期間（例：6 か月）にわたってデータの信頼性を評価する必要がある場合。
• 推奨される方法
  1. データを 1 日単位でクエリします。
  2. UTC の日付境界を使用します。
  3. 15 分～1 日の粒度を維持します。
  4. data_incomplete = true の区間を除外します。
  5. 既知のスリープモード中またはオフラインの時間帯を除外します。
  6. 検証後に集計します。
• 期待される結果
  • 局所的な品質低下が、集計によって隠れることなく保持されます。
  • SLA 指標に、実際に品質が低下した区間が反映されます。
  • 月単位のサマリーは、検証済みのデータのみから作成されます。

import requests
from datetime import datetime, timedelta, timezone
import pandas as pd

API_URL = "<https://api.butlr.io/api/v3/reporting>"
API_TOKEN = "YOUR_API_TOKEN"

SPACE_ID = "space_....."

START_DATE = datetime(2025, 8, 1, tzinfo=timezone.utc)
END_DATE   = datetime(2026, 2, 1, tzinfo=timezone.utc)

SLEEP_START_UTC = 0   # Example: exclude 00:00–05:00 UTC
SLEEP_END_UTC   = 5

def query_day(day_start):
    day_end = day_start + timedelta(days=1)

    payload = {
        "window": {
            "every": "15m",
            "function": "max",
            "timezone": "UTC"
        },
        "filter": {
            "start": day_start.isoformat(),
            "stop": day_end.isoformat(),
            "null_on_incomplete": True,
            "spaces": { "eq": [SPACE_ID] },
            "measurements": ["traffic_floor_occupancy"],
            "value": { "gte": 0 }
        }
    }

    headers = {
        "Authorization": f"Bearer {API_TOKEN}",
        "Content-Type": "application/json"
    }

    response = requests.post(API_URL, json=payload, headers=headers)
    response.raise_for_status()
    return response.json()

all_records = []
current = START_DATE

while current < END_DATE:
    data = query_day(current)
    all_records.extend(data)
    current += timedelta(days=1)

# Convert to DataFrame
df = pd.DataFrame(all_records)

# --- Validation Step ---

# Convert time to datetime
df["time"] = pd.to_datetime(df["time"], utc=True)

# 1️⃣ Exclude incomplete intervals
df_valid = df[df["data_incomplete"] == False]

# 2️⃣ Exclude sleep-mode hours (example: 00:00–05:00 UTC)
df_valid = df_valid[
    ~df_valid["time"].dt.hour.between(SLEEP_START_UTC, SLEEP_END_UTC - 1)
]

# --- SLA Calculation Example ---

total_intervals = len(df)
valid_intervals = len(df_valid)
incomplete_intervals = len(df[df["data_incomplete"] == True])

sla_percentage = (valid_intervals / total_intervals) * 100

print(f"Total intervals: {total_intervals}")
print(f"Incomplete intervals: {incomplete_intervals}")
print(f"SLA Availability: {sla_percentage:.2f}%")

# --- Monthly Summary (after validation) ---

df_valid["month"] = df_valid["time"].dt.to_period("M")

monthly_summary = df_valid.groupby("month").agg({
    "value": "mean"
})

print(monthly_summary)

推奨される使い方

Butlr API から返されたデータを処理する際は、次の推奨評価順序に従ってください。

1. data_incomplete を確認します。

   1. data_incomplete = true の場合は、その区間を分析から除外します。

   2. data_incomplete = false の場合は、値を使用可能として扱います。

2. null_percentage は補助的な診断情報としてのみ使用します。

   1. このフィールドはデータ品質のデバッグ用です。

これが、信頼性の高いグラフ、サマリー、インテグレーションを構築するための推奨パターンです。

API の動作と制約

サポートされるクエリ時間枠

この機能は、15 分以上の間隔での利用を想定しています。

15 分未満の粒度でリクエストしても結果が返ることはありますが、その結果は分析上意味のあるものとはみなされません。Webhook の配信間隔も最小 15 分です。

スリープモード時の動作

スケジュールされたスリープ期間中は、次のようになります。

• データが収集されない場合があります。

• null_percentage と data_incomplete の値は、クエリの時間枠によって変わる場合があります。

長期的な可用性を分析する場合、Butlr は既知のスリープ期間を評価対象の時間枠から除外することを推奨しています。

長期間のオフライン

Hive またはセンサーが連続して 2 週間を超えてオフラインになっている場合、データ集計で使用される一部の内部計算パスから除外されることがあります。

この場合、次のようになります。

• そのデバイスが null_percentage の計算に含まれなくなる場合があります。

• その区間で data_incomplete がトリガーされなくなる場合があります。

• その結果、デバイスで以前に長期間の障害があった場合でも、null_percentage が 0% と表示されることがあります。

このため、null_percentage が「クリーン」な値であっても、長期間の障害がなかったことが常に保証されるわけではありません（特に、障害が 2 週間のしきい値を超えていた場合）。

プレースホルダーセンサー

スペースの設定に未使用のプレースホルダーセンサーが含まれている場合、次のような影響があります。

• それらのセンサーがオフラインとして表示されることがあります。

• その結果、null_percentage の値が実際より高くなったり、data_incomplete がトリガーされたりすることがあります。

推奨される対応：
データ品質の指標を正確に保つため、未使用のプレースホルダーセンサーを設定から削除してください。

仮想的にミラーリングまたはクローンされたセンサー

まれに、センサーが設定上で「クローン」または「ミラーリング」されている場合があります。

この場合、次のようになります。

• クローンまたはミラーリングされたエントリーがオフラインとして表示されることがあります。

• 物理デバイス自体は正常に動作している場合があります。

この状況が null_percentage や data_incomplete に悪影響を与えることはありません。

この機能の適用範囲

これらのデータ品質インジケーターは、次のデータに適用されます。

• プレゼンスセンサーの在室データ

• トラフィックセンサーの IN/OUT 計測値

ただし、トラフィックセンサーから生成されるフロア単位の在室推定値には適用されません。こちらは別のキャリブレーションプロセスに従います。

分析のベストプラクティス

最も信頼性の高いレポートを作成するには、次のようにします。

1. 15 分の粒度でデータをクエリします。

2. data_incomplete = true の区間を除外します。

3. 残りの検証済みの区間を、時間単位、日単位、またはそれ以上の期間のサマリーに集計します。

これにより、データ品質の短い欠落を把握しつつ、長期的なレポートを使用可能な区間に基づいて作成できます。