jp-stopword-filter 0.2.2

A lightweight Python library designed to filter stopwords for Japanese text.

English

jp-stopword-filter

jp-stopword-filter は、カスタマイズ可能なルールに基づいて日本語のストップワードをフィルタリングするための軽量なPythonライブラリです。自然言語処理（NLP）タスクのために日本語テキストを効率的に前処理する方法を提供し、一般的なストップワード削除技術とユーザー定義のカスタマイズをサポートします。

特徴

• プリロードされたストップワード: SlothLibからの日本語ストップワードリストを含みます。
• カスタマイズ可能なルール:
  • 文字数に基づいてトークンを削除。
  • 日本語形式の日付（例: 2024年11月）をフィルタリング。
  • 数字、記号、スペース、絵文字を除外。
• カスタムワードリスト: 独自のストップワードをフィルタに追加可能。
• カスタムフィルタ: custom_filter関数を使用して独自のフィルタリングロジックを定義可能。
• 柔軟な利用: 初期化時に必要なルールのみを有効または無効にできます。

インストール

PyPI経由でインストール：

pip install jp-stopword-filter

注意：配布名は jp-stopword-filter ですが、インポート名は ja_stopword_filter です：

from ja_stopword_filter import JaStopwordFilter

開発

このプロジェクトは環境構築・依存管理・ビルド・公開のすべてに uv を使用します。

git clone https://github.com/BrambleXu/jp-stopword-filter.git
cd jp-stopword-filter

uv sync          # .venv を作成し、ランタイム + 開発依存をインストール
uv run pytest    # テストを実行
make lint        # ruff + codespell

ビルドと公開：

uv build         # sdist + wheel を dist/ に生成
uv publish       # PyPI へアップロード（または Release ワークフローの trusted publishing に任せる）

使用方法

基本的な使い方（文字列トークンのみ）

この例では、文字列として表現されたトークンをフィルタリングします。追加のフィルタリングのためにカスタムワードリストを提供しています。

from ja_stopword_filter import JaStopwordFilter

# トークンリストの定義
tokens = ["２０２４年１１月", "こんにちは", "１２３", "！", "😊", "スペース", "短い", "custom"]

# カスタムワードリスト
custom_wordlist = ["custom", "スペース"]

# フィルタの初期化
filter = JaStopwordFilter(
    convert_full_to_half=True,  # 全角文字を半角文字に変換
    use_slothlib=True,         # SlothLibのストップワードを使用
    filter_length=1,           # 長さが1以下のトークンをフィルタリング
    use_date=True,             # 日付形式のトークンを削除
    use_numbers=True,          # 数字のトークンを削除
    use_symbols=True,          # 記号を含むトークンを削除
    use_spaces=True,           # 空白のみのトークンを削除
    use_emojis=True,           # 絵文字を含むトークンを削除
    custom_wordlist=custom_wordlist  # カスタムストップワードを追加
)

# トークンをフィルタリング
filtered_tokens = filter.remove(tokens)
print(filtered_tokens)  # 出力: ['こんにちは', '短い']

高度な使い方（Tokenクラスとcustom_filterの使用）

この例では、Tokenクラスとcustom_filter関数を使用してカスタムフィルタリングロジックを定義する方法を示します。また、Tokenクラスを拡張してカスタム属性を追加し、それに応じたcustom_filter関数を設計することもできます。

基本的なTokenクラスの例

from ja_stopword_filter import JaStopwordFilter, Token

# Tokenオブジェクトのリストを定義
tokens = [
    Token("２０２４年１１月", "名詞"),
    Token("こんにちは", "動詞"),
    Token("１２３", "名詞"),
    Token("短い", "形容詞"),
    Token("custom", "名詞"),
]

# カスタムフィルタ関数を定義
def custom_filter(token: Token) -> bool:
    # 品詞（pos）が"名詞"の場合、トークンを削除
    return token.pos == "名詞"

# フィルタを初期化
filter = JaStopwordFilter(
    convert_full_to_half=True,  # 全角文字を半角文字に変換
    custom_filter=custom_filter,  # カスタムフィルタリングロジックを適用
    use_numbers=True,            # 数字のトークンを削除
    use_emojis=True,             # 絵文字を含むトークンを削除
)

# トークンをフィルタリング
filtered_tokens = filter.remove(tokens)
filtered_surfaces = [t.surface for t in filtered_tokens]
print(filtered_surfaces)  # 出力: ['こんにちは', '短い']

拡張されたTokenクラスの例

Tokenクラスを拡張して、frequency、is_special、contextなどの追加属性を含めることができます。これらの属性を使用して、より複雑なフィルタリングロジックを設計できます。

from ja_stopword_filter import JaStopwordFilter, Token

# Tokenクラスを拡張し、カスタム属性を追加
class ExtendedToken(Token):
    def __init__(self, surface: str, pos: str, frequency: int, is_special: bool) -> None:
        super().__init__(surface, pos)
        self.frequency = frequency  # トークンの頻度
        self.is_special = is_special  # 特殊フラグ

# ExtendedTokenオブジェクトのリストを定義
tokens = [
    ExtendedToken("２０２４年１１月", "名詞", 10, False),
    ExtendedToken("こんにちは", "動詞", 5, True),
    ExtendedToken("１２３", "名詞", 2, False),
    ExtendedToken("短い", "形容詞", 15, False),
    ExtendedToken("custom", "名詞", 3, True),
]

# カスタムフィルタ関数を定義
def custom_filter(token: ExtendedToken) -> bool:
    # 品詞が"名詞"または頻度が5未満のトークンを削除
    return token.pos == "名詞" or token.frequency < 5

# フィルタを初期化
filter = JaStopwordFilter(
    custom_filter=custom_filter,  # カスタムフィルタリングロジックを適用
    use_numbers=True,            # 数字のトークンを削除
    use_symbols=True,            # 記号を含むトークンを削除
)

# トークンをフィルタリング
filtered_tokens = filter.remove(tokens)
filtered_surfaces = [t.surface for t in filtered_tokens]
print(filtered_surfaces)  # 出力: ['こんにちは', '短い']

パラメータ

JaStopwordFilterは以下のパラメータをサポートしています：

パラメータ	型	デフォルト	説明
convert_full_to_half	bool	True	全角文字を半角文字に変換します。
use_slothlib	bool	True	SlothLibのストップワードリストを使用します。
filter_length	int	0	指定した文字数以下のトークンを削除します。
use_date	bool	False	日本語の日付形式に一致するトークンを削除します。
use_numbers	bool	False	数字のトークンを削除します。
use_symbols	bool	False	記号を含むトークンを削除します。
use_spaces	bool	False	空白のみのトークンを削除します。
use_emojis	bool	False	絵文字を含むトークンを削除します。
custom_wordlist	list[str]	None	カスタムストップワードを追加します。
custom_filter	Callable[[Token], bool]	None	Tokenオブジェクト用のカスタムフィルタ関数を適用します。

フィルタリングルール

プリロードされたストップワード

デフォルトでは、JaStopwordFilter はSlothLibのストップワードを使用します。これは、日本語の一般的なストップワードを網羅したリストです。

さらに、ユーザーはcustom_wordlistパラメーターを通じて独自のカスタムワードリストを提供することもできます。これにより、特定の分野やタスクに合わせてストップワードのフィルタリングプロセスをさらにカスタマイズできます。

例: カスタムワードリストを追加する

from ja_stopword_filter import JaStopwordFilter

# カスタムワードリストを定義
custom_wordlist = ["example", "特定単語", "custom_stopword"]

# カスタムワードリストを使用してフィルタを初期化
filter = JaStopwordFilter(
    use_slothlib=True,           # SlothLibのストップワードを含む
    custom_wordlist=custom_wordlist  # ユーザー定義のストップワードを追加
)

# トークンのリストを定義
tokens = ["こんにちは", "特定単語", "example", "custom_stopword", "一般単語"]

# トークンをフィルタリング
filtered_tokens = filter.remove(tokens)
print(filtered_tokens)  # 出力: ['こんにちは', '一般単語']

主なポイント:

• SlothLibストップワード: use_slothlib=True（デフォルト設定）で自動的に含まれる。
• カスタムワードリスト: custom_wordlistパラメーターを使用して独自のストップワードを追加可能。
• ストップワードの統合: SlothLibのリストとカスタムワードリストがシームレスに連携し、ニーズに合わせた包括的なストップワードの除去を実現。

この機能により、特定の言語、分野、またはプロジェクトに応じた柔軟なフィルタリングプロセスを可能にします。

ルールの説明

1. 長さによるフィルタリング: 指定された値以下の長さのトークンを除去します。
2. 日付フィルタリング: 以下のような日本語の日付パターンを一致させて除去します。
   • YYYY年MM月
   • MM月DD日
   • YYYY年MM月DD日
3. 数値フィルタリング: 123や2024のような数値のトークンを除去します。
4. 記号フィルタリング: 句読点や特殊文字を除去します。
5. スペースフィルタリング: 空白またはスペースのみのトークンを除去します。
6. 絵文字フィルタリング: 絵文字を含むトークンを検出して除去します。
7. カスタムフィルタ: ユーザー定義のルールに基づいてトークンをフィルタリングするロジックを適用します。

コントリビューション

バグを見つけた場合や新機能のリクエストがある場合は、Issueを作成するか、Pull Requestを送信してください！