@brainpilot/skills 0.0.6 → 0.0.8

package/skills/14_Writing/paper-writing/scripts/section_phrasebank.py

@@ -0,0 +1,246 @@
+"""
+Academic section phrase bank and move orders for manuscript writing.
+
+Derived from nature-skills/nature-polishing (MIT License, Copyright 2026 Yuan Yizhe).
+Source: https://github.com/Yuan1z0825/nature-skills
+"""
+
+SECTION_MOVES = {
+    "introduction": {
+        "questions": [
+            "Why does the topic matter?",
+            "What is already known?",
+            "What is still missing or contested?",
+            "What does the present study ask or do?",
+        ],
+        "move_order": [
+            "establish importance",
+            "summarize what is known",
+            "identify a gap, limitation, or controversy",
+            "state the study aim",
+            "indicate value or approach",
+        ],
+        "useful_phrases": [
+            "Recent years have seen increasing interest in ...",
+            "X is a central issue in ...",
+            "Previous studies have shown that ...",
+            "However, the mechanisms underlying ... remain poorly understood.",
+            "Few studies have examined ...",
+            "Here, we investigate whether ...",
+            "This work provides ...",
+        ],
+        "avoid": [
+            "long historical throat-clearing",
+            "detailed results",
+            "inflated novelty claims before the gap is defined",
+        ],
+    },
+    "literature_review": {
+        "questions": [
+            "What lines of work define the field?",
+            "What has been established?",
+            "Where do findings diverge or remain incomplete?",
+            "Which gap matters for the present paper?",
+        ],
+        "move_order": [
+            "describe the scope of existing work",
+            "identify dominant approaches",
+            "state what has been established",
+            "note disagreements or contradictions",
+            "isolate the missing piece",
+        ],
+        "useful_phrases": [
+            "A substantial body of work has focused on ...",
+            "Most studies have relied on ...",
+            "Previous work has established that ...",
+            "Findings have been mixed regarding ...",
+            "By contrast, little attention has been paid to ...",
+            "No study has yet examined ...",
+        ],
+        "avoid": [
+            "citation-by-citation summary",
+            "treating all prior work as uniformly weak",
+        ],
+    },
+    "methods": {
+        "questions": [
+            "Could another group reproduce the work from this description?",
+        ],
+        "move_order": [
+            "design or cohort",
+            "materials or data source",
+            "procedure",
+            "outcome measures",
+            "analysis and statistics",
+            "ethics when relevant",
+        ],
+        "useful_phrases": [
+            "A cross-sectional study was undertaken to ...",
+            "Samples were collected from ...",
+            "X was quantified using ...",
+            "We used ... to assess ...",
+            "Differences were analysed using ...",
+            "All analyses were performed in ...",
+        ],
+        "avoid": [
+            "under standard conditions",
+            "using routine methods",
+            "data were analysed statistically",
+        ],
+    },
+    "results": {
+        "questions": [
+            "What was observed, under which condition, and with what evidence?",
+        ],
+        "move_order": [
+            "orient the reader to the figure, table, or experiment",
+            "state the main observation",
+            "add quantitative detail",
+            "note expected or unexpected patterns",
+            "compare with prior work only if it clarifies the result",
+        ],
+        "useful_phrases": [
+            "Figure 1 shows ...",
+            "As shown in Table 1, ...",
+            "The most notable finding was that ...",
+            "Contrary to expectations, ...",
+            "No significant difference was observed in ...",
+            "These results are consistent with ...",
+            "In contrast to earlier reports, ...",
+        ],
+        "avoid": [
+            "discussion-length mechanism explanations",
+            "repeating every visual detail from the figure",
+        ],
+    },
+    "discussion": {
+        "questions": [
+            "What do the main findings mean?",
+            "How do they relate to earlier work?",
+            "Which explanations are plausible?",
+            "What limitations constrain interpretation?",
+            "What follows from the findings, and what does not?",
+        ],
+        "move_order": [
+            "restate the main finding",
+            "explain plausible reasons",
+            "compare with earlier work",
+            "note limitations",
+            "state implications",
+            "point to future work if needed",
+        ],
+        "useful_phrases": [
+            "Taken together, these findings suggest that ...",
+            "A possible explanation is that ...",
+            "This discrepancy may reflect ...",
+            "These results should be interpreted with caution because ...",
+            "An implication of this is that ...",
+            "Further work is needed to determine whether ...",
+        ],
+        "avoid": [
+            "repeating the Results section in new words",
+            "claiming mechanism when only association was shown",
+        ],
+    },
+    "conclusion": {
+        "questions": [
+            "What was the central contribution?",
+            "Which finding matters most?",
+            "What implication follows, with what boundary?",
+        ],
+        "move_order": [
+            "return to the aim",
+            "summarize the decisive finding",
+            "state contribution or significance",
+            "give a boundary or forward look",
+        ],
+        "useful_phrases": [
+            "This study set out to ...",
+            "The present findings indicate that ...",
+            "These results extend our understanding of ...",
+            "Notwithstanding these limitations, ...",
+            "Further studies are required to ...",
+        ],
+        "avoid": [
+            "introducing new experiments",
+            "ending on vague praise of the work",
+        ],
+    },
+    "abstract": {
+        "questions": [
+            "What problem or gap is being addressed?",
+            "What was done?",
+            "What was found?",
+            "Why should the reader care?",
+        ],
+        "move_order": [
+            "broad context",
+            "concrete gap",
+            "approach",
+            "key result with numbers if available",
+            "implication",
+        ],
+        "useful_phrases": [
+            "X remains challenging because ...",
+            "Here, we ...",
+            "Using ... , we found that ...",
+            "We show that ...",
+            "These findings suggest ...",
+        ],
+        "avoid": [],
+    },
+    "title": {
+        "questions": [
+            "Which few words make the paper searchable, accurate, and interesting without overclaiming?",
+        ],
+        "target_properties": ["searchable", "specific", "restrained", "defensible"],
+        "useful_patterns": [
+            "[Core entity] in/through/by [mechanism or context]",
+            "[Process] shapes [outcome] in [system]",
+            "[Signature/pattern/framework] of [phenomenon]",
+        ],
+        "avoid": [
+            "A study of ...",
+            "vague hooks",
+            "unverified 'first'",
+            "stacked jargon",
+        ],
+    },
+}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Evidence Strength Verbs
+# ─────────────────────────────────────────────────────────────────────────────
+
+EVIDENCE_VERBS = {
+    "strong": [
+        "demonstrate", "establish", "confirm", "show", "reveal",
+    ],
+    "moderate": [
+        "suggest", "indicate", "support", "point to",
+    ],
+    "speculative": [
+        "may reflect", "could imply", "is consistent with", "appears to",
+    ],
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Transition Families
+# ─────────────────────────────────────────────────────────────────────────────
+
+TRANSITIONS = {
+    "contrast": [
+        "However,", "By contrast,", "In contrast,", "Nevertheless,",
+        "On the other hand,", "Conversely,",
+    ],
+    "addition": [
+        "Moreover,", "Furthermore,", "In addition,", "Additionally,",
+    ],
+    "consequence": [
+        "Therefore,", "Consequently,", "As a result,", "Thus,",
+    ],
+    "qualification": [
+        "Notwithstanding,", "Although,", "Despite this,", "While",
+    ],
+}

package/skills/16_Animal_Behavior/deeplabcut/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: deeplabcut
+description: "Toolbox for markerless animal pose estimation with DeepLabCut. Covers single/multi-animal tracking, SuperAnimal pretrained models, 2D/3D pose estimation, keypoint labeling GUI, model training/evaluation, video analysis, and behavioral quantification. Use when the user needs animal pose estimation, behavior tracking, keypoint detection in videos, or mentions DeepLabCut/DLC/SuperAnimal."
+version: "1.0.0"
+authors:
+  - "Claude (AI-assisted)"
+review_status: "ai-generated"
+source: "https://github.com/DeepLabCut/DeepLabCut"
+---
+
+# DeepLabCut — Markerless Animal Pose Estimation
+
+## Purpose
+
+DeepLabCut is a Python toolbox for state-of-the-art markerless pose estimation of animals. It uses deep learning to track body parts from videos without physical markers. The library is animal-agnostic, supports both single and multi-animal scenarios, and includes the SuperAnimal family of pretrained models for out-of-the-box inference.
+
+## When to Use This Skill
+
+Activate when the user:
+- Wants to track animal body parts from video
+- Asks about pose estimation, keypoint detection, or behavioral tracking
+- Mentions DeepLabCut, DLC, SuperAnimal, or markerless tracking
+- Needs to analyze animal movement/kinematics
+- Asks about multi-animal tracking or 3D pose reconstruction
+- Wants to use pretrained animal pose models
+
+## Quick Decision Tree
+
+```
+What does the user need?
+├── No labeled data, just want to track animals → SuperAnimal (video_inference_superanimal)
+├── Single animal, have labeled data → Standard single-animal pipeline
+├── Multiple animals interacting → maDLC (multi-animal pipeline)
+├── 3D pose reconstruction → 3D pipeline (calibrate_cameras + triangulate)
+└── Just post-process results → filterpredictions, analyzeskeleton
+```
+
+## Reference Files (Progressive Disclosure)
+
+| Topic | File | When to Read |
+|-------|------|--------------|
+| Standard Pipeline | `references/standard-pipeline.md` | Full workflow: create project → train → analyze |
+| SuperAnimal & ModelZoo | `references/modelzoo.md` | Pretrained models, zero-shot inference |
+| Multi-Animal (maDLC) | `references/maDLC.md` | Tracking multiple interacting animals |
+| 3D Pose Estimation | `references/3d-pose.md` | Triangulation from multiple camera views |
+| Video & Data Utilities | `references/utilities.md` | Video cropping, format conversion, data export |
+
+## Installation
+
+```bash
+# Minimal (headless, no GUI):
+pip install deeplabcut
+
+# With GUI (label_frames, refine_labels, SkeletonBuilder):
+pip install "deeplabcut[gui]"
+
+# PyTorch must be installed separately:
+pip install torch torchvision
+# Or for GPU (check pytorch.org for your CUDA version):
+conda install pytorch cudatoolkit=11.3 -c pytorch
+```
+
+Verify: `python -c "import deeplabcut; print(deeplabcut.__version__)"`
+
+## Standard Pipeline Overview
+
+```python
+import deeplabcut as dlc
+
+# 1. Create project
+config_path = dlc.create_new_project(
+    "ProjectName", "ExperimenterName", ["/path/to/video.mp4"],
+    working_directory="/path/to/projects"
+)
+
+# 2. Extract frames for labeling
+dlc.extract_frames(config_path, mode="automatic", algo="kmeans", crop=True)
+
+# 3. USER labels frames manually in GUI
+# dlc.label_frames(config_path)  # launches the labeling GUI
+
+# 4. Create training dataset from labeled frames
+dlc.create_training_dataset(config_path, net_type="resnet_50")
+
+# 5. Train the network
+dlc.train_network(config_path, maxiters=100000, saveiters=5000)
+
+# 6. Evaluate
+dlc.evaluate_network(config_path, plotting=True)
+
+# 7. Analyze videos (predict poses)
+dlc.analyze_videos(config_path, ["/path/to/video.mp4"], videotype=".mp4")
+
+# 8. Create labeled videos (overlay predictions)
+dlc.create_labeled_video(config_path, ["/path/to/video.mp4"])
+
+# 9. Export results to CSV
+dlc.analyze_videos_converth5_to_csv("/path/to/videoDLC_resnet50_ProjectNameJul9")
+```
+
+## Key API Reference
+
+### Project Management
+
+| Function | Description |
+|----------|-------------|
+| `create_new_project(project, experimenter, videos, working_directory)` | Start a new single-animal project |
+| `create_new_project_3d(project, experimenter, num_cameras, working_directory)` | Start a new 3D project |
+| `create_pretrained_project(path, task, videos, SUPERANIMAL_NAME, model_name, detector_name)` | Create project from SuperAnimal pretrained model |
+| `add_new_videos(config_path, videos)` | Add videos to existing project |
+
+### Training & Evaluation
+
+| Function | Description |
+|----------|-------------|
+| `create_training_dataset(config_path, net_type, augmenter_type)` | Prepare training data; `net_type`: `resnet_50`, `resnet_101`, `mobilenet_v2_1.0`, `efficientnet-b0` |
+| `train_network(config_path, maxiters, saveiters)` | Train; key params: `maxiters=100000`, `saveiters=5000` |
+| `evaluate_network(config_path, plotting=True)` | Evaluate on test set, produce metrics |
+
+### Video Analysis
+
+| Function | Description |
+|----------|-------------|
+| `analyze_videos(config_path, videos, videotype, save_as_csv)` | Predict poses for all frames in videos |
+| `create_labeled_video(config_path, videos, videotype, filtered)` | Overlay predicted keypoints on video |
+| `video_inference_superanimal(videos, superanimal_name, ...)` | Zero-shot inference with pretrained SuperAnimal models |
+
+### Post-Processing
+
+| Function | Description |
+|----------|-------------|
+| `filterpredictions(config_path, video, ...)` | Smooth predictions (ARIMA, median filtering) |
+| `analyzeskeleton(config_path, video, ...)` | Compute bone lengths, joint angles from predictions |
+| `plot_trajectories(config_path, video, ...)` | Plot body part trajectories over time |
+
+### SuperAnimal Pretrained Models
+
+Available models for zero-shot inference:
+
+| Model | Species | Body Parts |
+|-------|---------|------------|
+| `superanimal_topviewmouse` | Top-view mouse (various strains) | 21 keypoints |
+| `superanimal_quadruped` | Quadrupeds (dog, horse, sheep, etc.) | 39 keypoints |
+| `superanimal_face` | Primate/human faces | 54 keypoints |
+| `superanimal_full` | Full body animals (topview mouse + quadruped) | Combined |
+
+## Common Pitfalls
+
+1. **Wrong PyTorch version**: Always install PyTorch BEFORE deeplabcut. Check [pytorch.org](https://pytorch.org) for the correct CUDA version.
+2. **GPU out of memory**: Reduce batch size (default 8 → 4 or 2) in `pose_cfg.yaml`.
+3. **Missing GUI dependencies**: `label_frames` requires `pip install "deeplabcut[gui]"`. On headless servers, use X11 forwarding or label locally.
+4. **Video codec issues**: If `create_labeled_video` fails, try converting to `.mp4` (H.264) or `.avi` first.
+5. **maDLC detector**: Multi-animal mode requires a detection model (`fasterrcnn_resnet50_fpn_v2` is the default). Single-animal can work with heatmap regression alone.
+6. **SuperAnimal scale**: Adjust `scale_list` parameter for SuperAnimal — try `[200, 300, 400]` first; smaller animals may need higher values.

package/skills/16_Animal_Behavior/deeplabcut/references/3d-pose.md

@@ -0,0 +1,89 @@
+# 3D Pose Estimation Reference
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Camera Setup & Calibration](#camera-setup-calibration)
+3. [3D Triangulation](#3d-triangulation)
+4. [Creating 3D Labeled Videos](#creating-3d-labeled-videos)
+
+## Overview
+
+DeepLabCut 3D reconstructs 3D poses from 2+ calibrated camera views. The workflow:
+
+```
+Multiple cameras → Calibrate → Analyze each view (2D) → Triangulate → 3D poses
+```
+
+## Camera Setup & Calibration
+
+```python
+import deeplabcut as dlc
+
+# Create 3D project
+config_path = dlc.create_new_project_3d(
+    "3D_Project",
+    "ExperimenterName",
+    num_cameras=2,               # number of camera views
+    working_directory="/path/to/projects",
+)
+```
+
+Calibration requires a checkerboard visible in all cameras simultaneously:
+
+```python
+# Calibrate cameras
+dlc.calibrate_cameras(
+    config_path,
+    cbrow=8,            # checkerboard rows (inner corners)
+    cbcol=6,            # checkerboard cols (inner corners)
+    calibrate=False,    # True to run calibration
+    alpha=0,            # 0 = crop to valid region; 1 = keep all pixels
+)
+
+# Verify calibration quality
+dlc.check_undistortion(
+    config_path,
+    cbrow=8,
+    cbcol=6,
+)
+```
+
+## 3D Triangulation
+
+Each camera view is analyzed independently, then triangulated:
+
+```python
+# Step 1: Analyze each camera's video separately
+for cam_config in camera_configs:
+    dlc.analyze_videos(cam_config, [f"camera{i}_video.mp4"])
+    dlc.filterpredictions(cam_config, [f"camera{i}_video.mp4"])
+
+# Step 2: Triangulate 2D→3D
+dlc.triangulate(
+    config_path,
+    video_path="/path/to/videos/",
+    filterpredictions=True,
+    videotype=".mp4",
+)
+```
+
+## Creating 3D Labeled Videos
+
+```python
+dlc.create_labeled_video_3d(
+    config_path,
+    path="/path/to/videos/",
+    start=0,            # start frame
+    end=1000,           # end frame
+    videotype=".mp4",
+)
+```
+
+## Calibration Tips
+
+- Use a printed checkerboard with known square size (in mm)
+- Film the checkerboard moving through all areas where the animal moves
+- Record at least 30-50 synchronized frames of the checkerboard from each camera
+- `pick_corners`: if `True`, manually click corners on one frame; `False` for automatic detection
+- Sync cameras with a flash/LED or use hardware triggers
+- Higher resolution cameras give better 3D accuracy

package/skills/16_Animal_Behavior/deeplabcut/references/maDLC.md

@@ -0,0 +1,123 @@
+# Multi-Animal Pose Estimation (maDLC) Reference
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Creating a maDLC Project](#creating-a-madlc-project)
+3. [Training maDLC](#training-madlc)
+4. [Video Analysis for maDLC](#video-analysis-for-madlc)
+5. [Tracking & Tracklets](#tracking-tracklets)
+
+## Overview
+
+Multi-animal DeepLabCut supports tracking multiple interacting animals simultaneously. It uses a two-step approach:
+1. **Detection**: Find all animals in each frame (Faster R-CNN)
+2. **Pose estimation**: Estimate keypoints for each detected animal
+
+Then **tracking** links detections across frames to form persistent animal identities.
+
+## Creating a maDLC Project
+
+```python
+import deeplabcut as dlc
+
+config_path = dlc.create_new_project(
+    "MultiMouseProject",
+    "ExperimenterName",
+    ["/path/to/video.mp4"],
+    working_directory="/path/to/projects",
+    multianimal=True,        # KEY: enables maDLC mode
+)
+```
+
+In `config.yaml`, the `individuals` field lists the animals to track:
+
+```yaml
+individuals:
+- mouse1
+- mouse2
+- mouse3
+```
+
+The skeleton defines connections both within and optionally between animals.
+
+## Training maDLC
+
+maDLC uses two networks: a detector and a pose model.
+
+```python
+# Create training dataset (trains both detector + pose model)
+dlc.create_multianimaltraining_dataset(
+    config_path,
+    net_type="dlcrnet_ms5",      # good for multi-animal
+    detector_type="fasterrcnn_resnet50_fpn_v2",
+    num_shuffles=1,
+)
+
+# Train
+dlc.train_network(
+    config_path,
+    maxiters=100000,
+    saveiters=5000,
+)
+```
+
+**Key differences from single-animal:**
+- Labels include animal identity (which mouse is which)
+- Detector network runs first to find all animals
+- `numframes2pick` is per-animal; label ~20 frames per individual
+- Labeling is more time-consuming; use the GUI's animal switching feature
+
+## Video Analysis for maDLC
+
+```python
+# Analyze
+dlc.analyze_videos(
+    config_path,
+    ["/path/to/video.mp4"],
+    videotype=".mp4",
+    auto_track=True,      # track animals across frames
+    track_method="box",   # "box" (IoU) or "skeleton" (pose similarity)
+)
+
+# Create labeled video
+dlc.create_labeled_video(
+    config_path,
+    ["/path/to/video.mp4"],
+    filtered=True,
+    videotype=".mp4",
+)
+```
+
+## Tracking & Tracklets
+
+After analysis, refine tracking:
+
+```python
+# Convert detections to tracklets
+dlc.convert_detections2tracklets(
+    config_path,
+    ["/path/to/video.mp4"],
+    videotype=".mp4",
+    track_method="box",
+)
+
+# Manually refine tracklets in GUI
+# dlc.refine_tracklets(config_path, ["/path/to/video.mp4"])
+
+# Stitch corrected tracklets into final predictions
+dlc.stitch_tracklets(
+    config_path,
+    ["/path/to/video.mp4"],
+    videotype=".mp4",
+)
+```
+
+## Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| Animals not detected | Lower detection threshold in `inference_cfg.yaml` |
+| ID swaps | Use `track_method="skeleton"` for more robust tracking |
+| Animals too similar | Add distinguishing features (ear tags, fur marks) or use re-identification |
+| Detection too slow | Use `fasterrcnn_mobilenet_v3_large_fpn` as detector |
+| Missing keypoints on occluded animals | Increase `numframes2pick`, add more labeled frames with occlusions |