bear-hackathon-ecology/README.md

TypeScript library providing ecological data and lifecycle information for Japanese Black Bears

# Bear Hackathon Ecology

日本のツキノワグマ（*Ursus thibetanus japonicus*）の生態データと生活サイクル情報を提供するTypeScriptライブラリです。月別危険度、遭遇リスク、詳細な行動サイクルデータを含み、アウトドア活動の安全計画に役立ちます。

## インストール

```bash
npm install bear-hackathon-ecology
```

## 使用方法

```typescript
import { bearEcology } from 'bear-hackathon-ecology';

// 10月の危険度データを取得
const october = bearEcology.getMonthData(10);
console.log(`危険度: ${october?.dangerous_level}/5`);

// 詳細なサイクル情報を取得
const cycle = bearEcology.getCycleData('autumn_feeding');
console.log(`食物: ${cycle?.foods.join(', ')}`);
```

## API リファレンス

### メソッド

- `getMonthData(month: number): MonthlyData | undefined`
  - 指定月の危険度データを取得（1-12月）

- `getCycleData(cycleId: string): CycleData | undefined`  
  - IDによる詳細サイクル情報を取得

- `getAllMonthlyData(): MonthlyData[]`
  - 全月の危険度データを取得

- `getAllCycles(): CycleData[]`
  - 全ライフサイクルデータを取得

### 型定義

```typescript
interface MonthlyData {
  month: number;
  dangerous_level: number;    // 1-5スケール
  chance_of_encounter: number; // 1-5スケール  
  current_cycle: string;
}

interface CycleData {
  id: string;
  title: string;
  start_month: number;
  end_month: number;
  description: string;
  activity: string;
  characteristics: string[];
  foods: string[];
  location: string[];
  caution: string[];
}
```

## クマの生活サイクル

- **hibernation** - 冬眠期（12-2月）
- **hibernation_ending** - 冬眠明け期（3月）  
- **spring_active** - 春期活動期（4月）
- **dispersal** - 分散期（5月）
- **mating** - 繁殖期（6-7月）
- **summer_foraging** - 夏期採餌期（8月）
- **autumn_feeding** - 秋期飽食期・最危険期（9-10月）
- **pre_hibernation** - 冬眠準備期（11月）

## 危険度レベル

- **レベル1-2**: 低リスク（冬眠期間）
- **レベル3**: 中リスク  
- **レベル4**: 高リスク（活動期）
- **レベル5**: 最高リスク（10月ピーク）

## 使用例

```typescript
// 年間危険パターンを表示
const allMonths = bearEcology.getAllMonthlyData();
allMonths.forEach(month => {
  const risk = month.dangerous_level >= 4 ? '高リスク' : '低リスク';
  console.log(`${month.month}月: ${risk}`);
});

// 現在月のサイクル詳細を取得
const monthData = bearEcology.getMonthData(10);
if (monthData) {
  const cycle = bearEcology.getCycleData(monthData.current_cycle);
  console.log(`注意事項: ${cycle?.caution.join(', ')}`);
}
```

## ⚠️ 重要な安全に関する注意事項

### データの限界
1. **地域差**: データは全国平均を表し、地域の状況は異なる場合があります
2. **個体差**: クマの行動は個体により異なり、予測困難です
3. **気候変動**: 地球温暖化により従来のパターンが変化している可能性があります
4. **年変動**: ドングリの凶作などの要因により年ごとに大きな変動があります

### 安全に関する免責事項
- **このデータは参考情報のみであり、絶対的な安全を保証するものではありません**
- **アウトドア活動前には必ず最新の地域情報を確認してください**
- **地方自治体の警報やアラートを優先してください**
- **専門ガイドや地元専門家にご相談ください**

## ライセンス

MIT License。このデータセットは教育、研究、安全計画目的での利用を想定しています。

## キーワード

- bear
- ecology
- wildlife
- safety
- japan
- typescript
- outdoor
- hiking
- danger-assessment
- ツキノワグマ
- 野生動物
- 安全対策
- 登山
- ハイキング