readability-scorer

可読性スコアラー

業界標準の数式を使用して、テキストの可読性を分析します。推定学年レベル、複雑さの指標、明瞭さを向上させるための提案を取得できます。

クイックスタート

from scripts.readability_scorer import ReadabilityScorer

# Score text
scorer = ReadabilityScorer()
scores = scorer.analyze("Your text to analyze goes here.")
print(f"Grade Level: {scores['grade_level']}")
print(f"Flesch Reading Ease: {scores['flesch_reading_ease']}")

特徴

• 複数の数式：Flesch-Kincaid、Gunning Fog、SMOG、Coleman-Liau、ARI
• 学年レベル：米国の学年レベルを推定
• 読みやすさ：0～100の読みやすさスコア
• テキスト統計：単語数、文数、音節数、複雑な単語数
• 一括分析：複数のドキュメントを処理
• 比較：テキスト間の可読性を比較

API リファレンス

初期化

scorer = ReadabilityScorer()

分析

scores = scorer.analyze(text)
# Returns:
# {
#     'flesch_reading_ease': 65.2,
#     'flesch_kincaid_grade': 8.1,
#     'gunning_fog': 10.2,
#     'smog_index': 9.5,
#     'coleman_liau': 9.8,
#     'ari': 8.4,
#     'grade_level': 8.5,  # Average
#     'reading_time_minutes': 2.3,
#     'stats': {
#         'words': 250,
#         'sentences': 15,
#         'syllables': 380,
#         'complex_words': 25,
#         'avg_words_per_sentence': 16.7,
#         'avg_syllables_per_word': 1.52
#     }
# }

個別スコア

# Get specific scores
fre = scorer.flesch_reading_ease(text)
fkg = scorer.flesch_kincaid_grade(text)
fog = scorer.gunning_fog(text)
smog = scorer.smog_index(text)

一括分析

texts = [text1, text2, text3]
results = scorer.analyze_batch(texts)

# From files
results = scorer.analyze_files(["doc1.txt", "doc2.txt"])

比較

# Compare two texts
comparison = scorer.compare(text1, text2)
print(f"Text 1 grade: {comparison['text1']['grade_level']}")
print(f"Text 2 grade: {comparison['text2']['grade_level']}")

CLI の使い方

# Analyze text
python readability_scorer.py --text "Your text here"

# Analyze file
python readability_scorer.py --input document.txt

# Compare files
python readability_scorer.py --compare doc1.txt doc2.txt

# Batch analyze directory
python readability_scorer.py --input-dir ./docs --output report.csv

# Specific formula only
python readability_scorer.py --input doc.txt --formula flesch

CLI 引数

引数	説明	デフォルト
--text	分析するテキスト	-
--input	入力ファイル	-
--input-dir	ファイルのディレクトリ	-
--output	出力ファイル（json/csv）	-
--compare	2つのファイルを比較	-
--formula	特定の数式	all

スコアの解釈

Flesch の読みやすさ

スコア	難易度	学年レベル
90-100	非常に簡単	小学5年生
80-89	簡単	小学6年生
70-79	比較的簡単	中学1年生
60-69	標準	中学2～3年生
50-59	比較的難しい	高校1～3年生
30-49	難しい	大学
0-29	非常に難しい	大学卒業レベル

学年レベルの尺度

学年	対象
1-5	小学校
6-8	中学校
9-12	高校
13-16	大学
17+	大学院レベル

例

ブログ記事を分析する

scorer = ReadabilityScorer()

blog_post = """
Writing clear content is essential for engaging readers.
Short sentences help. Simple words work best.
Your audience will thank you for making things easy to understand.
"""

scores = scorer.analyze(blog_post)
print(f"Flesch Reading Ease: {scores['flesch_reading_ease']:.1f}")
print(f"Grade Level: {scores['grade_level']:.1f}")
print(f"Reading Time: {scores['reading_time_minutes']:.1f} minutes")

if scores['grade_level'] > 8:
    print("Consider simplifying for a wider audience.")

ドキュメントのバージョンを比較する

scorer = ReadabilityScorer()

original = open("original.txt").read()
simplified = open("simplified.txt").read()

comparison = scorer.compare(original, simplified)

print("Original:")
print(f"  Grade Level: {comparison['text1']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text1']['flesch_reading_ease']:.1f}")

print("\nSimplified:")
print(f"  Grade Level: {comparison['text2']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text2']['flesch_reading_ease']:.1f}")

improvement = comparison['text1']['grade_level'] - comparison['text2']['grade_level']
print(f"\nImprovement: {improvement:.1f} grade levels easier")

ドキュメントを一括分析する

scorer = ReadabilityScorer()
import os

results = []
for filename in os.listdir("./docs"):
    if filename.endswith(".md"):
        text = open(f"./docs/{filename}").read()
        scores = scorer.analyze(text)
        results.append({
            'file': filename,
            'grade': scores['grade_level'],
            'ease': scores['flesch_reading_ease']
        })

# Sort by difficulty
results.sort(key=lambda x: x['grade'], reverse=True)

print("Documents by Difficulty:")
for r in results:
    print(f"  {r['file']}: Grade {r['grade']:.1f}")

依存関係

nltk>=3.8.0

制限事項

• 英語のみ対応
• 数式は散文向けに設計されているため、リストやコードなどでは適切に機能しない場合があります
• 音節数は推定値のため、多少の誤差が生じる場合があります
• 理解度は評価せず、表面的な複雑さのみを評価します