【Streamlit】st.column_config.DatetimeColumnの基本と使い方

こんにちは、JS2IIUです。StreamlitのDataFrame表示で日時を自在に表示するcolumn_config.DatetimeColumnを紹介します。日時の表示もDataFrameで時系列のデータを扱う際には欠かせないですね。今回もよろしくお願いします。

はじめに
st.column_config.DatetimeColumnとは
1. 主な用途
パラメータの説明
実際の使用例
1. 例：イベント管理の日時列
応用例：特定の日時範囲でフィルタリング
注意点
まとめ

はじめに

データフレーム内で日付や時間を扱いたい場合、Streamlitのst.column_config.DatetimeColumnを利用することで、日時情報を直感的かつ便利に操作できます。このクラスを使えば、データフレームに日時形式の列を追加し、カスタマイズ可能なインターフェースを提供できます。本記事では、DatetimeColumnの基本的な使い方や実例を交えて詳しく解説します。

st.column_config.DatetimeColumnとは

st.column_config.DatetimeColumnは、データフレームの列を日時データとしてフォーマットし、ユーザーにわかりやすく表示するためのクラスです。これにより、日付と時間がフォーマットされた状態で表示されるだけでなく、ユーザーにとって直感的に使いやすいインターフェースを提供します。

主な用途

日時データの表示：イベントやタスクの開始・終了時刻を管理。
日時データの操作：特定の範囲でフィルタリングや処理が可能。
フォーマットの統一：カスタムフォーマットで日時を表示。

パラメータの説明

以下は、DatetimeColumnの各パラメータとその用途です。

label（デフォルト: None）
列の名前を指定します。データフレームの列ヘッダーとして表示されます。
width（デフォルト: None）
列の幅を指定します。px単位でカスタマイズ可能で、デフォルトでは自動調整されます。
help（デフォルト: None）
列に関する説明文を指定します。ツールチップとして表示され、列の使い方を補足します。
disabled（デフォルト: None）
列を編集不可にするかを指定します。Trueの場合、ユーザーは編集できません。
required（デフォルト: None）
列の値が必須かどうかを指定します。Trueの場合、列の値を空にすることはできません。
default（デフォルト: None）
新しい行が追加された際に使用される初期値を指定します。
format（デフォルト: None）
日時データの表示形式を指定します。指定方法はMoment.jsのフォーマットに従います。こちらを参照して下さい。Pythonのstrftime形式ではないことに注意が必要です。
min_value（デフォルト: None）
入力可能な日時の最小値を指定します。datetime型で指定する必要があります。
max_value（デフォルト: None）
入力可能な日時の最大値を指定します。datetime型で指定する必要があります。
step（デフォルト: None）
日時の増減ステップを指定します（例: 15分単位など）。
timezone（デフォルト: None）
日時データのタイムゾーンを指定します。指定しない場合はシステムのデフォルトタイムゾーンが使用されます。

Moment.js | Docs

実際の使用例

以下は、DatetimeColumnを使ったシンプルな例です。

例：イベント管理の日時列

from datetime import datetime
import streamlit as st
import pandas as pd
from streamlit.column_config import DatetimeColumn

# データフレームを作成
data = {
    "Event": ["Event A", "Event B", "Event C"],
    "Start Time": ["2024-11-20 14:00:00", "2024-11-21 10:00:00", "2024-11-22 16:30:00"]
}
df = pd.DataFrame(data)

# 日時列のデータ型を変換
df["Start Time"] = pd.to_datetime(df["Start Time"])

# DatetimeColumnで列をカスタマイズ
column_config = {
    "Start Time": DatetimeColumn(
        label="開始時刻",
        help="イベントの開始日時",
        format="MMM Do, YYYY hh:mm:ss A",  # カスタムフォーマット
        min_value=datetime(2024, 11, 20, 0, 0, 0),
        max_value=datetime(2024, 11, 30, 0, 0, 0),
        step=60  # 1分単位で選択可能
    )
}

# カスタム列設定でデータフレームを表示
st.data_editor(df, column_config=column_config)

こちらの動画では、min_value, max_valueで指定した範囲内で日時選択した場合と、範囲外を選択しようとしたときの操作を行なっています。

1. ライブラリのインポート

from datetime import datetime
import streamlit as st
import pandas as pd
from streamlit.column_config import DatetimeColumn

datetime: Pythonの標準ライブラリで、日時を操作するために使用します。
streamlit: インタラクティブなウェブアプリを簡単に作成するためのPythonライブラリです。
pandas: データ解析やデータフレーム操作のためのライブラリです。
streamlit.column_config.DatetimeColumn: st.data_editorで使用する列の設定をカスタマイズするためのクラスです。ここでは日時型の列の表示や操作を細かく制御できます。

2. データフレームの作成

data = {
    "Event": ["Event A", "Event B", "Event C"],
    "Start Time": ["2024-11-20 14:00:00", "2024-11-21 10:00:00", "2024-11-22 16:30:00"]
}
df = pd.DataFrame(data)

data: イベント名と開始時刻を持つ辞書型データ。
pd.DataFrame: 辞書型データをPandasのデータフレームに変換します。

結果として、以下のようなデータフレームが作成されます：

Event	Start Time
Event A	2024-11-20 14:00:00
Event B	2024-11-21 10:00:00
Event C	2024-11-22 16:30:00

3. 日時列のデータ型を変換

df["Start Time"] = pd.to_datetime(df["Start Time"])

pd.to_datetime: Start Time列の文字列データをPandasのdatetime型に変換します。
この変換により、日時データとしての操作（例: ソート、フィルタリング）が可能になります。

4. DatetimeColumnで列のカスタマイズ

column_config = {
    "Start Time": DatetimeColumn(
        label="開始時刻",
        help="イベントの開始日時",
        format="MMM Do, YYYY hh:mm:ss A",  # カスタムフォーマット
        min_value=datetime(2024, 11, 20, 0, 0, 0),
        max_value=datetime(2024, 11, 30, 0, 0, 0),
        step=60
    )
}

label: 列名をカスタマイズ。デフォルトのStart Timeを「開始時刻」に変更。
help: 列のヘルプテキスト。ユーザーが列名の上にマウスオーバーすると表示されます。
format: 日時の表示フォーマットを指定。
- "MMM Do, YYYY hh:mm:ss A"の例:
  - Nov 20th, 2024 02:00:00 PM（11月20日午後2時）。
min_value: 列の最小日時を指定。
- datetime(2024, 11, 20, 0, 0, 0)は2024年11月20日午前0時。
max_value: 列の最大日時を指定。
- datetime(2024, 11, 30, 0, 0, 0)は2024年11月30日午前0時。
step: 選択可能な間隔（単位: 秒）。
- ここでは60秒（1分単位）を指定。

5. st.data_editorでデータフレームを表示

st.data_editor(df, column_config=column_config)

st.data_editor:
- Streamlitでインタラクティブなデータ編集UIを提供する機能。
- ユーザーはデータフレームのデータを編集可能。
column_config:
- 列のカスタマイズ設定を適用。Start Time列が指定されたフォーマットと制約に基づいて表示されます。

プログラムの動作

データフレームの表示:

データフレームがst.data_editorを通じてアプリ画面に表示されます。
Start Time列はDatetimeColumn設定に従い、指定したフォーマットで表示されます。

インタラクティブ操作:

ユーザーはStart Time列で日時を編集できます。
編集可能な範囲（2024年11月20日～30日）外の日時や1分単位でない日時は設定により制限されます。

ヘルプ表示:

マウスオーバーで「イベントの開始日時」のヘルプテキストが表示されます。

ポイント

ユーザーインターフェースの向上:
- DatetimeColumnのカスタマイズにより、ユーザー体験を向上させることができます。
データ制御:
- 入力範囲やフォーマットを制御することで、データの一貫性を保つことが可能です。

応用例：特定の日時範囲でフィルタリング

以下のコードでは、特定の日時範囲に基づいてイベントを抽出します。

# フィルタリング用の日時範囲を定義
start_date = pd.Timestamp("2024-11-21 00:00:00")
end_date = pd.Timestamp("2024-11-22 23:59:59")

# 指定した範囲内のイベントを抽出
filtered_events = df[(df["Start Time"] >= start_date) & (df["Start Time"] <= end_date)]

# フィルタリング結果を表示
st.write("指定された期間のイベント:", filtered_events)

注意点

日時データの型
DatetimeColumnを使用する場合、対象列のデータ型はdatetime64[ns]である必要があります。pd.to_datetimeで事前に変換しましょう。
フォーマット指定
formatオプションに無効なフォーマットを指定するとエラーになります。Pythonの日時フォーマット（strftime形式）ではなく、Moment.jsのフォーマットに従って正確に記述してください。
タイムゾーン
タイムゾーンを指定しない場合、システムのデフォルトが使用されるため、アプリケーションの要件に応じて設定しましょう。

Moment.js | Docs

まとめ

st.column_config.DatetimeColumnは、データフレームで日時データを操作するのに非常に便利なツールです。日時フォーマットをカスタマイズしたり、特定の範囲でデータをフィルタリングしたりする際に役立ちます。
次回は、日付情報に特化したst.column_config.DateColumnについて解説します。どうぞお楽しみに！

公式ドキュメントはこちら：st.column_config.DatetimeColumn

月	火	水	木	金	土	日
				1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30