npm - @brainpilot/skills - Versions diffs - 0.0.6 → 0.0.8 - Mend

@brainpilot/skills 0.0.6 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (285) hide show

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/report_template_en.html ADDED Viewed

@@ -0,0 +1,112 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>{{ report_title }}</title>
+  <style>
+    :root {
+      --page-width: 1100px;
+      --border: #d7dee7;
+      --ink: #1f1f1f;
+      --muted: #56697d;
+      --panel: #f5f8fb;
+      --accent: #1b4f72;
+    }
+    body {
+      font-family: "Noto Serif", Georgia, serif;
+      line-height: 1.7;
+      color: var(--ink);
+      margin: 0;
+      background: #eef3f7;
+    }
+    .page {
+      max-width: var(--page-width);
+      margin: 32px auto;
+      background: #ffffff;
+      padding: 40px 48px 56px;
+      box-shadow: 0 16px 40px rgba(22, 37, 56, 0.08);
+    }
+    h1, h2, h3 {
+      color: var(--accent);
+      line-height: 1.3;
+    }
+    h1 {
+      font-size: 28px;
+      margin: 0 0 20px;
+    }
+    h2 {
+      font-size: 22px;
+      margin: 36px 0 14px;
+      padding-bottom: 6px;
+      border-bottom: 1px solid var(--border);
+    }
+    h3 {
+      font-size: 18px;
+      margin: 24px 0 10px;
+    }
+    p {
+      margin: 10px 0;
+    }
+    ul {
+      margin: 10px 0 14px 20px;
+      padding: 0;
+    }
+    li {
+      margin: 6px 0;
+    }
+    .meta {
+      padding: 14px 18px;
+      background: var(--panel);
+      border-left: 4px solid #5c89b0;
+      margin-bottom: 28px;
+    }
+    figure {
+      margin: 20px auto 28px;
+      padding: 14px;
+      border: 1px solid var(--border);
+      background: #fafcfe;
+      max-width: 980px;
+    }
+    img {
+      display: block;
+      width: auto;
+      max-width: min(100%, 960px);
+      max-height: 560px;
+      height: auto;
+      margin: 0 auto;
+      object-fit: contain;
+    }
+    figcaption {
+      margin-top: 10px;
+      text-align: center;
+      color: var(--muted);
+      font-size: 14px;
+    }
+    code {
+      background: #eef3f7;
+      padding: 1px 5px;
+      border-radius: 4px;
+      font-size: 0.95em;
+    }
+    a {
+      color: #18507a;
+      text-decoration: none;
+    }
+    a:hover {
+      text-decoration: underline;
+    }
+  </style>
+</head>
+<body>
+  <div class="page">
+    <h1>{{ report_title }}</h1>
+    <div class="meta">
+      <div><strong>Project Path:</strong> {{ project_path }}</div>
+      <div><strong>Report Mode:</strong> {{ report_mode }}</div>
+      <div><strong>Report Goal:</strong> {{ report_goal }}</div>
+    </div>
+    {{ body_html }}
+  </div>
+</body>
+</html>

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/report_template_en.md ADDED Viewed

@@ -0,0 +1,21 @@
+# {{ report_title }}
+{{ project_summary_section }}
+{{ overview_section }}
+{{ sample_check_section }}
+{{ raw_trajectory_section }}
+{{ heatmap_section }}
+{{ radar_section }}
+{{ stats_section }}
+{{ cluster_section }}
+{{ single_subject_section }}
+{{ integrated_interpretation_section }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/cluster-section.md ADDED Viewed

@@ -0,0 +1,5 @@
+## Clustering Results
+{{ cluster_body }}
+{{ cluster_gallery }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/heatmap-section.md ADDED Viewed

@@ -0,0 +1,5 @@
+## Heatmap and Trajectory Results
+{{ heatmap_body }}
+{{ heatmap_gallery }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/integrated-interpretation.md ADDED Viewed

@@ -0,0 +1,3 @@
+## Integrated Interpretation
+{{ integrated_interpretation_body }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/overview.md ADDED Viewed

@@ -0,0 +1,3 @@
+## Project Overview
+{{ overview_body }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/project-summary.md ADDED Viewed

@@ -0,0 +1,3 @@
+## Project Overview and Materials
+{{ project_summary_body }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/radar-section.md ADDED Viewed

@@ -0,0 +1,5 @@
+## Radar Plot Results
+{{ radar_body }}
+{{ radar_gallery }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/raw-trajectory.md ADDED Viewed

@@ -0,0 +1,3 @@
+## Raw Trajectory Summary
+{{ raw_trajectory_body }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/sample-check.md ADDED Viewed

@@ -0,0 +1,3 @@
+## Sample and Group Verification
+{{ sample_check_body }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/single-subject-section.md ADDED Viewed

@@ -0,0 +1,3 @@
+## Single-Subject Results Overview
+{{ single_subject_body }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/assets/section_templates/stats-section.md ADDED Viewed

@@ -0,0 +1,5 @@
+## Statistical Summary Plot Results
+{{ stats_body }}
+{{ stats_gallery }}

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/experiment-types/epm.md ADDED Viewed

@@ -0,0 +1,52 @@
+# EPM
+`EPM` stands for Elevated Plus Maze.
+## What It Primarily Evaluates
+- Open-arm exploration
+- Closed-arm preference
+- Time in center and transitions between arms
+- In some projects, also looks at the balance between exploration and avoidance combined with total activity
+## Common Experimental Procedure
+- Apparatus usually consists of two open arms and two closed arms
+- Animal starts exploring from the center
+- Record time in and entries to open arms, closed arms, and center within fixed duration
+## Common Readouts
+- Time in open arms
+- Open arm entries
+- Time in closed arms
+- Time in center
+- Total arm entries
+- Total distance
+## How to Write When Only Raw Skeleton Data Exists
+- First look at where trajectories are mainly concentrated, rather than saying "only have materials, cannot summarize"
+- If device orientation is not clearly labeled, prioritize writing distribution in "longitudinal axis / transverse axis / center", do not force naming open arms and closed arms
+- If grouping prefixes like `control`, `model` are already obvious, can directly compare which group has larger lateral spread, which group is more concentrated near center or axis
+- Can directly write "larger / more concentrated activity range", "more / fewer center transitions", "more biased toward certain axis activity"
+## How to Summarize in Reports
+- When formal area indicators exist, first summarize whether open-arm exploration increases or decreases, then see if total entries or total distance change synchronously
+- When only raw trajectories exist, first summarize which type of area activities are mainly concentrated in, then write whether activity range contracts or expands
+- In multi-sample projects, if differences between `control` and `model` are already intuitive, can directly write which group is more dispersed, which is more concentrated
+- Single-sample projects can directly summarize trajectory features like "mainly active near center and certain axis", "limited lateral spread"
+## Recommended Summary Style
+- "Trajectories mainly concentrated on the longitudinal axis passing through center, with relatively limited lateral spread."
+- "`control` group has larger lateral activity range, `model` group trajectories more concentrated near center and axis areas."
+- "Overall sample has larger activity range, with frequent transitions between center and arm sections."
+- "If combined with formal area statistics, open-arm exploration is reduced, overall more biased toward closed areas."
+## Do Not Overstep
+- Do not directly write reduced open-arm exploration as clinical anxiety diagnosis
+- Do not ignore motor ability confounds from decreased total entries or total activity
+- Only have axis distribution, no device mapping: do not force longitudinal and transverse axes as confirmed open/closed arms

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/experiment-types/fst.md ADDED Viewed

@@ -0,0 +1,37 @@
+# FST
+`FST` stands for Forced Swim Test.
+## What It Primarily Evaluates
+- Behavioral responses to inescapable water environment stress
+- Commonly used for antidepressant-like efficacy screening
+## Common Experimental Procedure
+- Place the animal in a water tank or cylindrical container from which it cannot escape
+- Record swimming, struggling, and immobility within a fixed duration
+- Some protocols include pre-test and test session
+## Common Readouts
+- Immobility time
+- Latency to immobility
+- Swimming time
+- Climbing / struggling time
+## How to Summarize in Reports
+- Directly summarize the main change direction of immobility time, swimming time, or struggling time
+- If behavioral typing is clear, can directly write "increased passive coping / increased active coping"
+- Single-sample projects can directly summarize the main coping style
+## Recommended Summary Style
+- "Increased immobility time, showing more obvious passive coping."
+- "More swimming and struggling time, overall showing more active stress coping."
+## Do Not Overstep
+- Do not write FST alone as sufficient evidence for "enhanced/reduced depression-like behavior"
+- Do not ignore protocol differences, such as whether there is a pre-test

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/experiment-types/nor.md ADDED Viewed

@@ -0,0 +1,39 @@
+# NOR
+`NOR` stands for Novel Object Recognition.
+## What It Primarily Evaluates
+- Recognition memory
+- Novelty preference
+## Common Experimental Procedure
+Usually includes two core phases:
+1. Familiarization / training phase: Animal is exposed to two identical or equivalent objects
+2. Test phase: Replace one of the objects with a novel object and record exploration preference
+## Common Readouts
+- Novel object exploration time
+- Familiar object exploration time
+- Discrimination index
+- Preference index
+- Total object exploration time
+## How to Summarize in Reports
+- First summarize whether preference for novel object increases, decreases, or is not obvious
+- If discrimination index or preference index exists, directly write the direction
+- Single-sample projects can directly summarize as "prefers novel object / prefers familiar object / preference not obvious"
+## Recommended Summary Style
+- "Longer exploration time for novel object, showing obvious novelty preference."
+- "Decreased novelty preference, with decreasing discrimination index."
+## Do Not Overstep
+- Do not write NOR alone as "comprehensive learning memory impairment/recovery"
+- Do not ignore object attraction differences and side bias

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/experiment-types/oft.md ADDED Viewed

@@ -0,0 +1,43 @@
+# OFT
+`OFT` stands for Open Field Test.
+## What It Primarily Evaluates
+- Spontaneous locomotor activity
+- Novelty-driven exploration
+- Partial indicators of anxiety-like behavior, such as center avoidance or thigmotaxis
+## Common Experimental Procedure
+- Place the animal in an open field (square or circular arena)
+- Record movement trajectory and behavior within a fixed duration
+- Often divide the arena into center zone and periphery
+## Common Readouts
+- Total distance traveled
+- Average velocity
+- Time in center
+- Center entries
+- Thigmotaxis (wall-hugging behavior)
+- Rearing
+- Immobility
+## How to Summarize in Reports
+- First summarize whether activity increases, decreases, or remains stable
+- Then summarize whether center exploration and periphery preference change
+- If total distance and center exploration direction are consistent, can directly write conclusions like "decreased activity accompanied by reduced center exploration"
+- Single-sample projects can directly summarize as "high/low activity", "more/less center exploration", "obvious/not obvious thigmotaxis"
+## Recommended Summary Style
+- "Decreased locomotor activity, accompanied by reduced center exploration."
+- "Test animals stay more in the periphery, showing obvious thigmotaxis."
+- "Increased center entries suggests enhanced center exploration in the open field."
+## Do Not Overstep
+- Do not directly write changes in center time as changes in anxiety level while completely ignoring activity level
+- Do not write OFT alone as depression-like conclusions

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/experiment-types/tcst.md ADDED Viewed

@@ -0,0 +1,45 @@
+# TCST
+`TCST` in this skill refers to Three-Chamber Social Test (Three-Chamber Sociability and Social Novelty Test).
+## What It Primarily Evaluates
+- Sociability
+- Social novelty preference
+- In some designs, can also reflect social recognition
+## Common Experimental Procedure
+Typical procedure is divided into 2 to 3 phases:
+1. Habituation phase: Subject mouse freely explores the three-chamber apparatus
+2. Sociability phase: Stranger mouse placed on one side, empty cup/cage on the other side
+3. Social novelty phase: Familiar mouse on one side, novel stranger on the other side
+## Common Readouts
+- Time in each chamber
+- Time near stimulus cup/cage
+- Sniffing time
+- Entries to each chamber
+- Social preference index
+- Social novelty index
+## How to Summarize in Reports
+- If data comes from "stranger vs empty cup" phase, prioritize summarizing whether sociability increases or decreases
+- If data comes from "familiar vs novel stranger" phase, prioritize summarizing whether social novelty preference exists
+- If only chamber time is available, can directly summarize spatial preference and social cue preference direction
+- Single-sample projects can directly write "this sample mainly stayed on which side, approached which type of stimulus more"
+## Recommended Summary Style
+- "In the sociability phase, the subject mouse spent more time in the chamber containing the stranger mouse, suggesting strong sociability."
+- "In the social novelty phase, the subject mouse approached the novel stranger more, showing social novelty preference."
+- "Current single-sample results show that this sample mainly stayed in... area and approached... stimulus more."
+## Do Not Overstep
+- Do not directly write chamber time differences as "impaired social memory" unless the design and indicators sufficiently support it
+- Do not automatically interpret low-activity samples as social avoidance
+- Do not write single TCST results as complete autism-like behavioral conclusions

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/experiment-types/tst.md ADDED Viewed

@@ -0,0 +1,36 @@
+# TST
+`TST` stands for Tail Suspension Test.
+## What It Primarily Evaluates
+- Behavioral responses to inescapable stress
+- Commonly used for antidepressant-like efficacy screening
+## Common Experimental Procedure
+- Mice are suspended by fixing their tails
+- Record struggling and immobility within a fixed duration
+- Common duration is 6 minutes
+## Common Readouts
+- Immobility time
+- Latency to immobility
+- Mobility / struggling time
+## How to Summarize in Reports
+- Directly summarize whether immobility time increases or decreases
+- If latency or struggling time exists, also directly write the direction of active coping or passive coping
+- Single-sample projects can summarize as "mainly immobile" or "more struggling"
+## Recommended Summary Style
+- "Increased immobility time suggests enhanced passive coping."
+- "Decreased immobility time, with increased struggling time, indicates more active stress coping."
+## Do Not Overstep
+- Do not directly write TST results as "having depression" or "higher depression level"
+- Do not ignore the effects of motor ability or sedative effects on immobility

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/input-types.md ADDED Viewed

@@ -0,0 +1,59 @@
+# Input Types
+Read this file when determining "what materials are available in the project path for generating reports".
+## Common Input Types
+### Raw or Semi-Raw Data
+- `.h5`: Common for skeleton, trajectory, keypoints, or intermediate results.
+- `.csv` / `.xlsx`: Common for behavioral summary tables, event tables, significance test results.
+- `txt` / `yaml` / `json`: Common for parameter orders, group name descriptions, configuration files.
+These files are typically used to determine:
+- Whether there is single-sample or multi-sample data.
+- Whether group labels exist.
+- Whether there are quantifiable tables that can support figure interpretation.
+### Image or Document Results
+- Heatmaps, trajectory plots: spatial distribution, activity paths, velocity distributions.
+- Radar plots: multi-parameter profiles, group mean comparisons, single-sample overviews.
+- Violin plots / box plots: parameter distributions and inter-group differences.
+- Cluster plots / clustermap: sample or parameter pattern structures.
+These files are typically used for:
+- Generating figure captions.
+- Organizing result sections.
+- Deciding which figures go into the main text and which are suitable for appendices.
+## Priority Questions When Scanning Within Path
+1. Are there file names or table columns that can identify samples.
+2. Are there group labels, but do not automatically interpret label meanings.
+3. Are there statistical result tables like `stats_overall.csv`, `stats_pairwise.csv`.
+4. Are there figures representing overall patterns, such as group means radar, clustermap.
+5. Are there same-directory description texts, experimental notes, or background information supplemented by the user in conversation.
+## Handling Principles When Materials Are Incomplete
+- Only figures, no tables: Can do figure organization and conservative descriptions, do not make strong statistical interpretations.
+- Have tables, no figures: Can generate text-based result summaries, but image display is limited.
+- Have multiple figure types but no background: First do material inventory and ask the user questions.
+- Only single sample: Prioritize switching to `single-subject` mode.
+## Minimum Judgment Items to Output to Upper Flow
+At least judge and organize these boolean or summary fields:
+- `has_skeleton_data`
+- `has_behavior_summary`
+- `has_stats_tables`
+- `has_heatmaps`
+- `has_radar`
+- `has_cluster_figure`
+- `sample_count_detected`
+- `group_labels_detected`
+- `metadata_files_found`

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/interpretation-guardrails.md ADDED Viewed

@@ -0,0 +1,45 @@
+# Interpretation Guardrails
+Read this file when generating result interpretation and summary text.
+## General Principles
+- First give the most direct result conclusions, then add a sentence about which figures or tables they are based on.
+- Prioritize summarizing "the most obvious characteristics of current data", do not give up normal summarization just because background is incomplete.
+- Separate "observed facts" from "interpretations based on experimental paradigm", but do not repeat limitation statements in every paragraph.
+- If key limitations truly exist, concentrate them in one section briefly, do not repeatedly write disclaimers throughout.
+## Allowed Conclusion Types to Write Directly
+- Main activity areas, preference directions, entry patterns, residence patterns of single samples
+- High/low differences already clearly presented between multiple groups in images or statistical tables
+- Simple summaries based on trajectory axis distribution, activity range, and path length when only raw skeleton data exists
+- Readout conclusions directly corresponding to experimental paradigm, e.g., increased open-arm exploration, decreased center exploration, enhanced novel object preference
+## Not Allowed to Overstep Situations
+- When only ambiguous abbreviation labels exist, do not explain inter-group relationships
+- When no statistical tables exist, do not write "significantly increased / significantly decreased"
+- Cluster plot showing separation does not equal statistical significant difference
+- Heatmap showing activity distribution does not equal mechanistic conclusions
+- Single-sample results should not be written as group-level patterns
+- Obvious file name prefixes like `control`, `model`, `sham`, `vehicle` can be used as candidate groupings first; other abbreviations should not be directly interpreted as biological groupings
+## Recommended Expression Style
+- "Results show..."
+- "Images and statistical results together indicate..."
+- "This sample mainly exhibits..."
+- "Under this experimental paradigm, this typically corresponds to..."
+- "If looking only at evidence within the current project path, the most obvious characteristic is..."
+## Conclusion Levels
+Prioritize output with the following strength:
+1. Direct result summary
+2. Comparisons with statistical support
+3. Interpretations combined with experimental paradigm
+4. Mechanistic conclusions
+Default should cover levels 1 to 3. Only enter level 4 when user explicitly allows and evidence is sufficient.

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/references/metadata-schema.md ADDED Viewed

@@ -0,0 +1,57 @@
+# Metadata Schema
+Read this file when determining "what information must be confirmed with the user".
+## Key Metadata
+The following information, if cannot be confirmed from the project directory, file names, figure titles, or user conversation, should first be asked to the user:
+- `project_name`: Project name or report title
+- `report_goal`: Report purpose, e.g., result organization, internal reporting, manuscript draft
+- `experiment_type`: Experimental paradigm or task type
+- `has_groups`: Whether groupings exist
+- `group_mapping`: What each group label represents
+- `control_group`: If there is a control group, which group is the control
+- `allow_interpretive_conclusion`: Whether interpretive conclusions are allowed
+## Recommended Supplementary Information
+- `species`
+- `sample_definition`: Whether one record corresponds to individual, session, trial, or other unit
+- `preferred_language`
+- `priority_figures`
+- `main_result_dirs`
+- `notes`
+## Where This Information Comes From
+There are only three sources of metadata:
+- Existing description texts, result files, and figure titles within the project directory
+- Information that can be directly inferred from file names, directory names, and sample naming conventions
+- Experimental background and writing requirements supplemented by the user in conversation
+## Questioning Rules
+- Missing `project_path`: Ask for the path first, do not do other work
+- When group names are obvious labels like `control`, `model`, `sham`, `vehicle`, they can be used as candidate groupings first
+- When group names are opaque abbreviations like `Y`, `con`, `k`, ask for group meaning first
+- Need to write formal inter-group comparisons but no `control_group`: Ask for control group first
+- User requests interpretive conclusions but `allow_interpretive_conclusion` is unclear: Ask if allowed
+## What Can Be Written When Unconfirmed
+Even if metadata is incomplete, the following are allowed to be output first:
+- Project and material overview
+- Sample and candidate grouping verification
+- Raw trajectory summary
+- Direct summary of image and statistical results
+Do not avoid obvious data characteristics just because of a small amount of missing background; only when key information is truly missing, do not hard-interpret opaque abbreviations as formal experimental group definitions.
+## Relationship with Manifest
+- `build_report_manifest.py` will aggregate unconfirmed items into `facts.unconfirmed_items`
+- When agents fill in `project_summary_body`, `overview_body`, `sample_check_body`, they can briefly mention key points that still need confirmation
+- All body text is directly filled back into `manifest.json`, no additional configuration or section files are created