Update Readme

.gitignore

@@ -170,6 +170,7 @@ cython_debug/
 /data/**
 !/data/**/
 !/data/**/.gitkeep
+!/data/**/README.md
 
 .bash_history
 

README.md

@@ -17,16 +17,6 @@
     - [主要ディレクトリの説明](#主要ディレクトリの説明)
       - [`work/`](#work)
       - [`data/`](#data)
-    - [`work/` ディレクトリ](#work-ディレクトリ)
-      - [`example/`](#example)
-      - [`experiments/`](#experiments)
-      - [`src/`](#src)
-      - [`tests/`](#tests)
-    - [`data/` ディレクトリ](#data-ディレクトリ)
-      - [`models/`](#models)
-      - [`preprocessed/`](#preprocessed)
-      - [`raw/`](#raw)
-      - [`results/`](#results)
   - [VSCode上での作業(Dev container)](#vscode上での作業dev-container)
     - [前提条件](#前提条件-1)
     - [🔧 セットアップ手順](#-セットアップ手順)
@@ -104,8 +94,11 @@ Poetryを使用してパッケージを管理します。
   ```bash
   poetry remove [パッケージ名]
   ```
-
-> 📝 パッケージの追加や削除を行った後は、必ず変更をコミットしてください。
+- **lock fileの更新**:
+  ```bash
+  poetry lock
+  ```
+> 📝 パッケージの追加や削除を行った後は必ずlock fileを更新して、poetry.lockとpyproject.tomlの差分をコミットしてください
 
 ## 🔄 開発の手順
 
@@ -203,70 +196,7 @@ root/
 - **raw/**: 元データ（提供されたExcelファイルなど）
 - **results/**: 各タスクの出力結果
 
-
-
-### `work/` ディレクトリ
-
-`work/` ディレクトリは、プロジェクトの主要なコードベースを含みます。各サブディレクトリの詳細は以下の通りです：
-
-#### `example/`
-- **目的**: デモンストレーションやサンプルコードの保管
-- **内容**:
-  - クリーンで理解しやすいコード例
-  - Hugging Face Spacesのデモスクリプト
-  - クライアントへの提示用コードサンプル
-
-#### `experiments/`
-- **目的**: 実験的なコードや一時的なスクリプトの保管
-- **内容**:
-  - 新しいアルゴリズムの試験実装
-  - パラメータチューニングスクリプト
-  - プロジェクト固有のプロンプトやコンフィグ
-
-#### `src/`
-- **目的**: 再利用可能な共通コンポーネントの保管
-- **内容**:
-  - プロジェクト間で共有できる基本クラス
-  - ユーティリティ関数
-  - データ処理パイプライン
-
-#### `tests/`
-- **目的**: 単体テストとその関連ファイルの保管
-- **内容**:
-  - 各モジュールの単体テスト
-
-### `data/` ディレクトリ
-
-`data/` ディレクトリは、プロジェクトで使用する様々なデータを保管します。
-#### `models/`
-- **目的**: 学習済みモデルの保存
-- **内容**:
-  - PyTorchモデル（.pthファイル）
-  - TensorFlowモデル（.h5ファイル）
-  - その他の機械学習モデル
-
-#### `preprocessed/`
-- **目的**: 前処理済みデータの保存
-- **内容**:
-  - クリーニング済みCSVファイル
-  - トークン化されたテキストファイル
-  - 正規化された数値データ
-
-#### `raw/`
-- **目的**: 元データの保管
-- **内容**:
-  - クライアントから提供された元のExcelファイル
-  - ウェブスクレイピングで取得した生データ
-  - 未処理のログファイル
-
-#### `results/`
-- **目的**: 分析結果や出力データの保存
-- **内容**:
-  - モデルの予測結果
-  - 統計分析のレポート
-  - 生成されたグラフや図表
-
-> ⚠️ 注意: `data/`ディレクトリの内容はGitで管理されません。重要なデータは別途バックアップを取ってください。
+> ⚠️ 注意: `data/`ディレクトリの内容はGitで管理されません。dataディレクトリからdata.zipファイルに圧縮しgoogledriveにて保管してください。
 
 
 ## VSCode上での作業(Dev container)

data/README.md

@@ -0,0 +1,93 @@
+# 📊 data ディレクトリ概要
+
+`data/` ディレクトリは、プロジェクトの心臓部とも言える重要なデータを管理します。各サブディレクトリは特定の目的を持ち、プロジェクトのデータフローを効率化します。
+
+---
+
+### 📂 ディレクトリ構造
+
+```
+data/
+├── models/
+├── preprocessed/
+├── raw/
+└── results/
+```
+
+---
+
+## 📁 詳細説明
+
+### 🧠 `models/`
+
+**目的**: 学習済みモデルの保存と版管理
+
+| 内容     | 説明                   |
+| -------- | ---------------------- |
+| 📄 `.pth` | PyTorchモデル          |
+| 📄 `.pd`  | TensorFlowモデル       |
+| 📄 その他 | scikit-learnモデルなど |
+
+➡️ **使用例**:
+```python
+model = torch.load('data/models/bert_classifier_v2.1.pth')
+```
+
+---
+
+### 🔧 `preprocessed/`
+
+**目的**: 前処理済みデータの保存と再利用
+
+| 内容                  | 説明                       |
+| --------------------- | -------------------------- |
+| 📊 クリーニング済みCSV | 整形されたデータセット     |
+| 📝 トークン化テキスト  | NLP用処理済みテキスト      |
+| 📈 正規化データ        | スケーリング済み数値データ |
+
+➡️ **使用例**:
+```python
+df = pd.read_csv('data/preprocessed/customer_data_2024Q1.csv')
+```
+
+---
+
+### 📦 `raw/`
+
+**目的**: 元データの保管
+
+| 内容                   | 説明                   |
+| ---------------------- | ---------------------- |
+| 📑 Excelファイル        | クライアント提供データ |
+| 🌐 スクレイピングデータ | Web収集の生データ      |
+| 📜 ログファイル         | システムログなど       |
+
+⚠️ **注意**: このディレクトリは読み取り専用として扱い、データの整合性を保護すること。
+
+---
+
+### 📊 `results/`
+
+**目的**: 分析結果や出力データの保存と共有
+
+| 内容           | 説明                 |
+| -------------- | -------------------- |
+| 📉 予測結果     | モデルのアウトプット |
+| 📃 分析レポート | 統計解析のサマリー   |
+| 🖼️ グラフ・図表 | 可視化結果           |
+
+➡️ **使用例**:
+```python
+plt.savefig('data/results/sales_forecast_2024Q2.png', dpi=300)
+```
+
+---
+### 🚨 注意事項
+
+1. **🔒 管理方法**: 
+   - `data/` は基本的にGit管理外。
+   - dataディレクトリからdata.zipファイルに圧縮しgoogledriveにて保管してください。
+   - 大容量ファイルはGit LFSの使用を検討。
+---
+> 💡 **Tip**: このディレクトリ構造を効果的に活用することで、データ管理の効率性が向上し、プロジェクトの再現性と品質が確保されます。
+

work/README.md

@@ -0,0 +1,90 @@
+# 🚀 プロジェクト構造
+
+## 📁 ディレクトリ構成例
+
+```
+work/
+├── example/
+├── experiments/
+│   ├── task_1/
+│   ├── task_2/
+│   └── ...
+├── src/
+│   ├── components/
+│   ├── utils/
+│   └── pipelines/
+└── tests/
+```
+
+## 📂 ディレクトリ詳細
+
+### 🎯 `example/`
+
+**目的**: デモンストレーションとサンプルコードの提供
+
+| 内容                                                                            | 特徴                                                           |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| • Hugging Face Spacesのデモスクリプト<br>• クライアント共有用の整形されたコード | • クリーンで再利用可能なコード<br>• 明確なドキュメンテーション |
+
+---
+
+### 🧪 `experiments/`
+
+**目的**: 
+- 実験的コードの開発
+- PoCの主要作業場所
+
+**使用方法**:
+1. タスク単位でディレクトリを作成
+2. 各タスクディレクトリ内で実験的コードを記述
+3. クライアント共有前にコードをリファクタリングし、`example/`に移動
+
+**構造例**:
+```
+experiments/
+├── task_1/
+├── task_2/
+└── ...
+```
+
+---
+
+### 🛠 `src/`
+
+**目的**: 
+- プロジェクト非依存の主要コンポーネントとユーティリティクラスの保管
+- 他プロジェクトでの再利用を可能にする
+
+> 💡 **ヒント**: プロジェクト終了時に、全体のコードをリファクタリングし、再利用可能な部分を`src/`に移動させましょう。
+
+**構造例**:
+```
+src/
+├── utils/
+├── components/
+├── pipelines/
+└── ...
+```
+
+---
+
+### 🧪 `tests/`
+
+**目的**: プロジェクトの品質保証
+
+**構造**:
+- `unit/`: 単体テスト
+  - `src/`の各モジュールに対応
+  - 命名規則: `test_*.py`
+  - 例: `src/utils/data_loader.py` → `tests/utils/test_data_loader.py`
+
+**テストの実行方法**:
+
+| コマンド                                      | 説明                           |
+| --------------------------------------------- | ------------------------------ |
+| `pytest tests/unit`                           | 全ての単体テストを実行         |
+| `pytest tests/unit/utils/test_data_loader.py` | 特定のモジュールのテストを実行 |
+| `pytest tests/unit -v`                        | 詳細なテスト結果を表示         |
+
+> ⚠️ **注意**: テスト実行前に、必要な依存関係がインストールされていることを確認してください。
+