14 KiB

Raw Blame History Unescape Escape

AGENTS.md

プロジェクト概要

Data Science for Beginnersは、Microsoft Azure Cloud Advocatesによって作成された包括的な10週間、20レッスンのカリキュラムです。このリポジトリは、プロジェクトベースのレッスンを通じて、Jupyterノートブック、インタラクティブなクイズ、実践的な課題を含む基礎的なデータサイエンスの概念を教える学習リソースです。

主要技術:

Jupyterノートブック: Python 3を使用した主要な学習媒体
Pythonライブラリ: pandas、numpy、matplotlibを使用したデータ分析と可視化
Vue.js 2: クイズアプリケーション（quiz-appフォルダー）
Docsify: オフラインアクセス用のドキュメントサイト生成ツール
Node.js/npm: JavaScriptコンポーネントのパッケージ管理
Markdown: すべてのレッスン内容とドキュメント

アーキテクチャ:

多言語対応の教育リポジトリで広範な翻訳を提供
レッスンモジュール（1-Introductionから6-Data-Science-In-Wildまで）に構造化
各レッスンにはREADME、ノートブック、課題、クイズが含まれる
独立したVue.jsクイズアプリケーションでレッスン前後の評価を実施
GitHub CodespacesとVS Code開発コンテナをサポート

セットアップコマンド

リポジトリセットアップ

# Clone the repository (if not already cloned)
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners

Python環境セットアップ

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install common data science libraries (no requirements.txt exists)
pip install jupyter pandas numpy matplotlib seaborn scikit-learn

クイズアプリケーションセットアップ

# Navigate to quiz app
cd quiz-app

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint and fix files
npm run lint

Docsifyドキュメントサーバー

# Install Docsify globally
npm install -g docsify-cli

# Serve documentation locally
docsify serve

# Documentation will be available at localhost:3000

可視化プロジェクトセットアップ

meaningful-visualizations（レッスン13）のような可視化プロジェクトの場合:

# Navigate to starter or solution folder
cd 3-Data-Visualization/13-meaningful-visualizations/starter

# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Lint files
npm run lint

開発ワークフロー

Jupyterノートブックの操作

リポジトリのルートでJupyterを開始: jupyter notebook
希望するレッスンフォルダーに移動
.ipynbファイルを開いて演習を進める
ノートブックは説明とコードセルを含む自己完結型
ほとんどのノートブックはpandas、numpy、matplotlibを使用 - これらがインストールされていることを確認

レッスン構成

各レッスンには通常以下が含まれます:

README.md - 理論と例を含む主要なレッスン内容
notebook.ipynb - 実践的なJupyterノートブック演習
assignment.ipynbまたはassignment.md - 練習課題
solution/フォルダー - 解答ノートブックとコード
images/フォルダー - 補助的な視覚資料

クイズアプリケーション開発

Vue.js 2アプリケーションで開発中にホットリロードを使用
クイズはquiz-app/src/assets/translations/に保存
各言語には独自の翻訳フォルダー（en、fr、esなど）がある
クイズ番号は0から始まり、39まで（合計40クイズ）

翻訳の追加

翻訳はリポジトリルートのtranslations/フォルダーに配置
各言語は英語の構造を完全にミラーリング
GitHub Actionsによる自動翻訳（co-op-translator.yml）

テスト手順

クイズアプリケーションテスト

cd quiz-app

# Run lint checks
npm run lint

# Test build process
npm run build

# Manual testing: Start dev server and verify quiz functionality
npm run serve

ノートブックテスト

ノートブックには自動テストフレームワークが存在しない
手動検証: すべてのセルを順番に実行してエラーがないことを確認
データファイルがアクセス可能で出力が正しく生成されることを確認
可視化が正しくレンダリングされることを確認

ドキュメントテスト

# Verify Docsify renders correctly
docsify serve

# Check for broken links manually by navigating through content
# Verify all lesson links work in the rendered documentation

コード品質チェック

# Vue.js projects (quiz-app and visualization projects)
cd quiz-app  # or visualization project folder
npm run lint

# Python notebooks - manual verification recommended
# Ensure imports work and cells execute without errors

コードスタイルガイドライン

Python（Jupyterノートブック）

PythonコードのPEP 8スタイルガイドラインに従う
分析するデータを説明する明確な変数名を使用
コードセルの前に説明を含むMarkdownセルを追加
コードセルは単一の概念または操作に集中させる
データ操作にはpandas、可視化にはmatplotlibを使用

一般的なインポートパターン:

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

JavaScript/Vue.js

Vue.js 2のスタイルガイドとベストプラクティスに従う
ESLint設定はquiz-app/package.jsonに記載
Vueの単一ファイルコンポーネント（.vueファイル）を使用
コンポーネントベースのアーキテクチャを維持
コミット前にnpm run lintを実行

Markdownドキュメント

明確な見出し階層（# ## ###など）を使用
言語指定付きのコードブロックを含める
画像には代替テキストを追加
関連するレッスンやリソースへのリンクを追加
読みやすさのために行の長さを適切に保つ

ファイル構成

レッスン内容は番号付きフォルダー（01-defining-data-scienceなど）に配置
解答は専用のsolution/サブフォルダーに配置
翻訳は英語の構造をミラーリングしてtranslations/フォルダーに配置
データファイルはdata/またはレッスン専用フォルダーに保存

ビルドとデプロイ

クイズアプリケーションのデプロイ

cd quiz-app

# Build production version
npm run build

# Output is in dist/ folder
# Deploy dist/ folder to static hosting (Azure Static Web Apps, Netlify, etc.)

Azure Static Web Appsのデプロイ

クイズアプリはAzure Static Web Appsにデプロイ可能:

Azure Static Web Appリソースを作成
GitHubリポジトリに接続
ビルド設定を構成:
- アプリの場所: quiz-app
- 出力の場所: dist
GitHub Actionsワークフローがプッシュ時に自動デプロイ

ドキュメントサイト

# Build PDF from Docsify (optional)
npm run convert

# Docsify documentation is served directly from markdown files
# No build step required for deployment
# Deploy repository to static hosting with Docsify

GitHub Codespaces

リポジトリには開発コンテナ構成が含まれる
CodespacesはPythonとNode.js環境を自動的にセットアップ
GitHub UIを介してリポジトリをCodespaceで開く
すべての依存関係が自動的にインストールされる

プルリクエストガイドライン

提出前

# For Vue.js changes in quiz-app
cd quiz-app
npm run lint
npm run build

# Test changes locally
npm run serve

PRタイトル形式

明確で説明的なタイトルを使用
フォーマット: [コンポーネント] 簡単な説明
例:
- [Lesson 7] Pythonノートブックのインポートエラーを修正
- [Quiz App] ドイツ語翻訳を追加
- [Docs] 新しい前提条件をREADMEに更新

必須チェック

すべてのコードがエラーなく実行されることを確認
ノートブックが完全に実行されることを確認
Vue.jsアプリが正常にビルドされることを確認
ドキュメントリンクが機能することを確認
クイズアプリケーションを変更した場合はテスト
翻訳が一貫した構造を維持していることを確認

貢献ガイドライン

既存のコードスタイルとパターンに従う
複雑なロジックには説明コメントを追加
関連するドキュメントを更新
適用可能な場合は異なるレッスンモジュールで変更をテスト
CONTRIBUTING.mdファイルを確認

追加の注意事項

使用される一般的なライブラリ

pandas: データ操作と分析
numpy: 数値計算
matplotlib: データの可視化とプロット
seaborn: 統計データの可視化（一部のレッスン）
scikit-learn: 機械学習（高度なレッスン）

データファイルの操作

データファイルはdata/フォルダーまたはレッスン専用ディレクトリに配置
ほとんどのノートブックはデータファイルを相対パスで期待
CSVファイルが主なデータ形式
一部のレッスンでは非リレーショナルデータ例としてJSONを使用

多言語対応

GitHub Actionsによる40以上の言語翻訳
翻訳ワークフローは.github/workflows/co-op-translator.ymlに記載
翻訳はtranslations/フォルダーに言語コード付きで配置
クイズ翻訳はquiz-app/src/assets/translations/に保存

開発環境オプション

ローカル開発: Python、Jupyter、Node.jsをローカルにインストール
GitHub Codespaces: クラウドベースの即時開発環境
VS Code開発コンテナ: ローカルコンテナベースの開発
Binder: クラウドでノートブックを起動（設定されている場合）

レッスン内容ガイドライン

各レッスンは独立しているが、前の概念を基に構築
レッスン前のクイズで事前知識をテスト
レッスン後のクイズで学習を強化
課題で実践的な練習を提供
スケッチノートで視覚的な要約を提供

よくある問題のトラブルシューティング

Jupyterカーネルの問題:

# Ensure correct kernel is installed
python -m ipykernel install --user --name=datascience

npmインストールの失敗:

# Clear npm cache and retry
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

ノートブックのインポートエラー:

必要なライブラリがすべてインストールされていることを確認
Pythonバージョンの互換性を確認（Python 3.7以上推奨）
仮想環境が有効化されていることを確認

Docsifyが読み込まれない:

リポジトリルートから提供していることを確認
index.htmlが存在することを確認
適切なネットワークアクセス（ポート3000）を確認

パフォーマンスに関する注意事項

大規模なデータセットはノートブックで読み込むのに時間がかかる場合がある
複雑なプロットの可視化レンダリングが遅くなる可能性がある
Vue.js開発サーバーはホットリロードを有効にして迅速な反復を可能に
本番ビルドは最適化され、縮小される

セキュリティに関する注意事項

機密データや資格情報をコミットしない
クラウドレッスンでのAPIキーは環境変数を使用
Azure関連のレッスンではAzureアカウント資格情報が必要な場合がある
セキュリティパッチのために依存関係を最新に保つ

翻訳への貢献

GitHub Actionsによる自動翻訳管理
翻訳の正確性向上のための手動修正歓迎
既存の翻訳フォルダー構造に従う
クイズリンクに言語パラメータを追加: ?loc=fr
翻訳されたレッスンが正しくレンダリングされることをテスト

プロジェクトの維持管理

コンテンツを最新に保つための定期的な更新
コミュニティの貢献を歓迎
GitHubで問題を追跡
カリキュラム管理者によるPRレビュー
毎月のコンテンツレビューと更新

免責事項:
この文書は、AI翻訳サービス Co-op Translator を使用して翻訳されています。正確性を追求しておりますが、自動翻訳には誤りや不正確な部分が含まれる可能性があります。元の言語で記載された文書を正式な情報源としてお考えください。重要な情報については、専門の人間による翻訳を推奨します。この翻訳の使用に起因する誤解や誤解釈について、当方は一切の責任を負いません。

14 KiB Raw Blame History Unescape Escape