project-sharing

プロジェクトの共有と出力の準備

共同作業者、査読者、リポジトリと共有するために、プロジェクトの出力を準備する際の専門的なガイダンスです。作業ディレクトリを維持しながら、共有レベルに応じて整理されたパッケージを作成します。

このディレクトリ内の関連ファイル：

• notebook-streamlining.md - 共有に向けたノートブックの整理と abridge オプション
• quality-assurance.md - QA 手順、ベストプラクティス、チェックリスト、依存関係の管理
• common-scenarios.md - 共有シナリオ（共同作業者、論文、アーカイブ、リポジトリ）とスクリプトの例
• cleanup-and-deprecation.md - クリーンアップ時のミスの修正と、冗長なノートブックの非推奨化

このスキルを使用する場面

• 解析結果を共同作業者と共有する
• 論文の補足資料を準備する
• 再現可能な研究パッケージを作成する
• 完了したプロジェクトをアーカイブする
• 他の研究者に引き継ぐ
• データリポジトリに提出する

基本原則

1. コピー上で作業する - 作業ディレクトリは絶対に変更しないでください
2. 適切なレベルを選ぶ - 対象者のニーズに合わせて共有の詳細度を選びます
3. すべてを文書化する - わかりやすいガイドとメタデータを含めます
4. 共有前に整理する - デバッグコードを削除し、出力をクリアし、必要に応じて匿名化します
5. 再現可能にする - 依存関係と手順を含めます
6. 重要：共有フォルダーを作成した後の作業は、すべてメインのプロジェクトディレクトリで行い、共有フォルダーでは行わないでください - 共有フォルダーは読み取り専用のスナップショットです

---

3 つの共有レベル

レベル 1：概要のみ

目的： プレゼンテーション、レポート、概要レベルのレビューのための簡易共有

含めるもの：

• 最終ノートブックの PDF エクスポート
• 最終データ／結果（CSV、Excel、図表） - 任意
• 簡潔な README

使用する場面：

• 技術者以外の関係者と結果を共有する
• プレゼンテーションや講演
• 再現が不要な簡易レビュー
• 容量や時間に制約がある場合

構成：

shared-summary/
├── README.md                          # Brief overview
├── analysis-YYYY-MM-DD.pdf           # Notebook as PDF
└── results/
    ├── figures/
    │   ├── fig1-main-result.png
    │   └── fig2-comparison.png
    └── tables/
        └── summary-statistics.csv

---

レベル 2：再現可能

目的： 処理済みデータから他の人が解析を再現できるようにする

含めるもの：

• 解析ノートブック（.ipynb） - 整理済み
• 図表作成用スクリプト
• 処理済み／解析可能なデータ
• 要件ファイル（requirements.txt または environment.yml）
• 手順を記載した詳細な README

使用する場面：

• 共同研究者と共有する
• 査読／論文の補足資料
• 教育やチュートリアル
• 標準的な共同作業のニーズ

構成：

標準的なプロジェクト構成については、folder-organization スキルを参照してください。再現可能なパッケージには、以下を含めます。

• 処理済みデータ（data/processed/ 内）
• 出力をクリアした整理済みノートブック（notebooks/ 内）
• スクリプト（scripts/ 内）
• 環境仕様（environment.yml または requirements.txt）
• ドキュメント（README.md、MANIFEST.md）

shared-reproducible/
├── README.md                          # Setup and reproduction instructions
├── MANIFEST.md                        # File descriptions
├── environment.yml                    # Conda environment OR requirements.txt
├── notebooks/                         # Cleaned notebooks
├── scripts/                           # Standalone scripts
└── data/
    └── processed/                     # Analysis-ready data

---

レベル 3：完全な追跡可能性

目的： 生データからすべての処理手順に至るまで、完全な透明性を確保する

含めるもの：

• 開始時のデータ／生データ
• すべての処理スクリプトとノートブック
• すべての中間ファイル
• 最終結果
• 完全なドキュメント
• 依存関係の完全な仕様

使用する場面：

• 将来の参照用にアーカイブする
• 規制への準拠
• 高い再現性が求められる場合（臨床、政策）
• データリポジトリへの提出（Zenodo、Dryad など）
• プロジェクト全体の引き継ぎ

構成：

標準的なプロジェクト構成については、folder-organization スキルを参照してください。完全な追跡可能性を備えたパッケージには、完全なデータ階層を含めます。

shared-complete/
├── README.md                          # Complete project guide
├── MANIFEST.md                        # Comprehensive file listing
├── environment.yml
├── data/
│   ├── raw/                          # Original, unmodified data
│   ├── intermediate/                 # Processing steps
│   └── processed/                    # Final analysis-ready
├── scripts/                           # All processing scripts
├── notebooks/                         # All notebooks (exploratory + final)
├── results/                           # All outputs
│   ├── figures/
│   ├── tables/
│   └── supplementary/
└── documentation/                     # Complete documentation
    ├── methods.md
    ├── changelog.md
    └── data-dictionary.md

---

準備のワークフロー

ステップ 1：ユーザーに共有レベルを尋ねる

レベルを判断するための質問：

Which sharing level do you need?

1. Summary Only - PDF + final results (quick sharing)
2. Reproducible - Notebooks + scripts + data (standard sharing)
3. Full Traceability - Everything from raw data (archival/compliance)

Additional questions:
- Who is the audience? (colleagues, reviewers, public)
- Are there size constraints?
- Any sensitive data to handle?
- Timeline for sharing?

Step 2: 含めるファイルを特定する

レベル 1 - 概要：

• 主な解析ノートブック
• 主要な図（出版物に掲載できる品質）
• 要約テーブル／統計量

レベル 2 - 再現可能：

• すべての解析ノートブック（探索的なものを除く）
• 図の生成スクリプト
• 処理済み／クリーンアップ済みデータ
• 環境仕様
• ユーティリティ関数／モジュール

レベル 3 - 完全版：

• 生データ（大きすぎる場合はリンク）
• すべての処理スクリプト
• すべてのノートブック（探索的なものを含む）
• すべての中間ファイル
• 完全なドキュメント

Step 3: 共有ディレクトリを作成する

# Create dated directory
SHARE_DIR="shared-$(date +%Y%m%d)-[level]"
mkdir -p "$SHARE_DIR"

Step 4: ファイルをコピーして整理する

ノートブック（.ipynb）の場合：

import nbformat
from nbconvert.preprocessors import ClearOutputPreprocessor

def clean_notebook(input_path, output_path):
    """Clean notebook: clear outputs, remove debug cells."""
    with open(input_path, 'r') as f:
        nb = nbformat.read(f, as_version=4)

    clear_output = ClearOutputPreprocessor()
    nb, _ = clear_output.preprocess(nb, {})

    nb.cells = [cell for cell in nb.cells
                if 'debug' not in cell.metadata.get('tags', [])
                and 'remove' not in cell.metadata.get('tags', [])]

    with open(output_path, 'w') as f:
        nbformat.write(nb, f)

データファイルの場合： 小さなファイルはそのままコピーし、大きなファイルは圧縮します。機密情報が含まれていないか確認してください。

スクリプトの場合： デバッグコードを削除し、不足している場合は docstring を追加し、パスが相対パスになっていることを確認します。

ノートブックの簡素化と abridge オプションについては、notebook-streamlining.md を参照してください。

Step 4.5: ファイルパスを確認して修正する

問題：ファイルパスが壊れているノートブックやスクリプトは、共有先で失敗します。

パスの完全な検証手順、自動チェック用スクリプト、修正パターンについては、folder-organization スキルを参照してください。

共有時に動作しない	共有時に動作する
/Users/yourname/project/data.csv	data/data.csv
C:\Users\yourname\project\fig.png	figures/fig.png
/absolute/path/to/results/	results/

すぐに使える確認コマンド：

# Check for absolute paths in notebooks
grep -l "/Users/" *.ipynb
grep -l "C:\\\\" *.ipynb

Step 5: ドキュメントを生成する

README.md テンプレート

# Project: [Project Name]

**Date:** YYYY-MM-DD
**Author:** [Your Name]
**Sharing Level:** [Summary/Reproducible/Full]

## Overview
Brief description of the project and analysis.

## Contents
See MANIFEST.md for detailed file descriptions.

## Requirements
[For Reproducible/Full levels]
- Python 3.X
- See environment.yml for dependencies

## Setup
\`\`\`bash
conda env create -f environment.yml
conda activate project-name
\`\`\`

## Reproduction Steps
[For Reproducible/Full levels]
1. [Description of first step]

## Data Sources
[For Full level]
- Dataset A: [Source, download date, version]

## Contact
[Your email or preferred contact]

## License
[If applicable - e.g., CC BY 4.0, MIT]

MANIFEST.md テンプレート

# File Manifest
Generated: YYYY-MM-DD

## File Descriptions

### Notebooks
- \`notebooks/01-data-processing.ipynb\` - Initial data loading and cleaning
- \`notebooks/02-analysis.ipynb\` - Main statistical analysis

### Data
- \`data/processed/cleaned_data.csv\` - Quality-controlled dataset (N=XXX samples)

### Scripts
- \`scripts/generate_figures.py\` - Automated figure generation

### Results
- \`results/figures/fig1-main.png\` - Main result showing [description]

Step 6: 機密データを扱う

確認する項目： 個人を特定できる情報（PII）、アクセス認証情報、専有データ、機関による制限、患者／被験者の識別情報。

対処方法：

1. 匿名化する - 識別情報を削除またはハッシュ化します
2. 除外する - 機密ファイルを含めないようにします
3. 集計する - 要約統計量のみを共有します
4. 制限事項を記載する - 何を除外したか、その理由を記載します

Step 7: パッケージ化して圧縮する

# For smaller packages (<100MB)
zip -r shared-YYYYMMDD.zip shared-YYYYMMDD/

# For larger packages
tar -czf shared-YYYYMMDD.tar.gz shared-YYYYMMDD/

Step 8: 作業ディレクトリに戻る

重要：共有用パッケージを作成した後は、必ずメインのプロジェクトディレクトリで作業してください。

共有フォルダーは配布専用のスナップショットです。今後の開発、解析、変更はすべて、元の作業ディレクトリで行ってください。

cd /path/to/main/project  # Return to working directory
pwd                        # Verify location
# Continue work here, NOT in shared-YYYYMMDD/

---

他のスキルとの連携

次のスキルと相性がよいです：

• folder-organization - 共有前にソースプロジェクトを適切に整理します
• jupyter-notebook-analysis - 共有可能なノートブックを作成します
• managing-environments - 依存関係を適切にドキュメント化します

このスキルを使う前に：

1. 作業ディレクトリを整理する（folder-organization）
2. 解析を完成させる（jupyter-notebook-analysis）
3. 環境をドキュメント化する（managing-environments）

このスキルを使った後に：

1. クリーンな環境でパッケージをテストする
2. 適切な方法（メール、リポジトリ、クラウドストレージ）で共有する
3. 参照用にアーカイブしたコピーを保管する

品質保証の手順とチェックリストについては、quality-assurance.md を参照してください。 一般的な共有シナリオとスクリプト例については、common-scenarios.md を参照してください。 クリーンアップのミスやノートブックの非推奨化への対処については、cleanup-and-deprecation.md を参照してください。

---

まとめ

プロジェクトを共有する際の主な原則：

1. 適切なレベルを選ぶ - 共有の範囲を対象者のニーズに合わせます
2. 移動せず、コピーする - 作業ディレクトリを保持します
3. 徹底的に整理する - デバッグコードを削除し、出力をクリアします
4. すべてをドキュメント化する - 最低限、README と MANIFEST を用意します
5. 機密性を確認する - 必要に応じて匿名化するか、除外します
6. 共有前にテストする - クリーンな環境で実行します
7. 適切にパッケージ化する - 圧縮し、内容をドキュメント化します
8. メインディレクトリで作業する - 共有用パッケージの作成後は、今後の作業をすべて共有フォルダーではなく、元のプロジェクトディレクトリで行います

忘れないでください： 優れた共有の習慣は、共同作業者にも未来の自分にも役立ちます！

---

Claude への重要な注意事項

共有パッケージを作成した後は、必ず以下を守ってください。

1. 必ずメインプロジェクトディレクトリに戻ってください
2. shared-*/ ディレクトリ内では作業しないでください - これらは読み取り専用のスナップショットです
3. 今後の編集、分析、開発はすべて元の作業ディレクトリで行ってください
4. 共有フォルダーは配布専用であり、開発作業には使用しないでください

ユーザーからファイルの変更を求められた場合は、必ず現在のディレクトリを確認し、共有パッケージ内ではなくメインプロジェクトの場所で作業していることを確かめてください。