@brainpilot/skills 0.0.6 → 0.0.7

package/skills/16_Animal_Behavior/ethoclaw-trajectory-velocity-heatmap-generate/reference_data/reference_2d.csv

@@ -0,0 +1,101 @@
+nose_x,nose_y,nose_confidence,back_x,back_y,back_confidence,tail_x,tail_y,tail_confidence
+475.19022,108.41098,0.97418493,452.82947,83.8712,0.48843163,440.92596,60.840816,0.014156458
+475.96747,106.043686,0.977368,452.07486,83.35011,0.32172602,440.52692,60.321404,0.023331426
+475.9436,104.0922,0.95961916,451.5134,82.44809,0.12809052,438.39813,60.378574,0.022728235
+476.5516,101.46619,0.9527784,449.18625,80.479454,0.13255136,437.36713,58.613197,0.048248637
+475.8122,97.53424,0.9633512,448.715,79.59667,0.09865817,436.0404,58.518726,0.030002944
+477.19226,92.58784,0.97487473,448.5418,79.498184,0.061244663,432.8206,58.903667,0.035898533
+475.4471,89.65908,0.23926876,449.19867,79.764404,0.06674655,432.00882,58.235233,0.041348696
+474.89267,86.11696,0.47965217,449.14856,78.79237,0.14172536,431.76782,58.098022,0.04468035
+475.81052,83.515915,0.7251396,448.94492,78.26098,0.14395516,431.6078,57.766907,0.029120898
+477.00906,81.68745,0.3982678,450.1728,78.62082,0.098565176,430.8751,58.004257,0.049617562
+478.28668,77.757515,0.2960763,450.65967,78.348045,0.055771455,430.17957,58.002514,0.105040275
+478.43027,75.234924,0.5760072,451.05902,78.6149,0.020200796,429.76953,59.06678,0.11681607
+477.81113,73.42118,0.5526418,451.23944,77.75386,0.040210053,429.10855,59.828175,0.36768687
+477.20575,72.72647,0.23583315,451.73837,76.932205,0.0151637485,428.56604,59.696182,0.30882075
+478.26083,72.456276,0.10802835,452.29608,76.65421,0.012873299,428.70264,59.3634,0.27397633
+428.9237,64.97222,0.08534209,452.57104,75.78511,0.0060122153,428.6798,59.477497,0.29528347
+428.81577,65.49353,0.15389323,452.98068,75.29305,0.002499816,428.51532,60.227802,0.27094534
+483.0385,70.21974,0.15120375,453.44012,74.62088,0.0024384116,428.5032,60.135273,0.3158878
+429.1478,65.54042,0.1002913,453.13464,74.2387,0.0015184148,428.73825,60.51488,0.3211375
+429.46326,65.36337,0.052627034,452.1668,69.58755,0.0036536132,428.812,60.035492,0.46613395
+429.39114,65.55221,0.07463741,452.22314,69.4596,0.0031227532,428.79355,60.240623,0.4143251
+429.56277,65.37942,0.05925322,451.88196,69.38171,0.00299257,428.46292,60.013813,0.39717472
+429.53595,65.61803,0.06936282,452.76355,69.60437,0.0038697054,428.64987,60.194157,0.3848
+429.69672,65.776505,0.06246201,458.10858,69.50576,0.0045912173,428.65005,60.26518,0.4409084
+483.26978,65.028465,0.15279293,452.95712,69.58249,0.0076134456,428.29648,60.390465,0.5032113
+483.99158,62.34483,0.2602438,458.20325,69.30007,0.009826792,428.44754,60.824818,0.5019335
+482.98288,61.029884,0.18575935,457.7434,69.021454,0.015260913,428.3536,60.53927,0.48933157
+483.18,58.96129,0.28232524,457.9416,68.61969,0.01855121,428.45532,60.47257,0.61480916
+482.248,57.970062,0.14941862,457.90106,68.64875,0.011531551,428.86597,60.88859,0.6058602
+482.15262,57.243977,0.09091685,457.99033,68.29213,0.010296796,428.832,61.051346,0.66437036
+482.21332,55.13769,0.06395929,458.19547,67.830185,0.019791752,429.00574,61.03566,0.75376755
+482.17334,54.715195,0.09333275,457.98495,67.42056,0.02786627,429.24033,61.250557,0.7702554
+482.41943,54.085865,0.1428192,458.03607,66.74514,0.03851001,429.43637,61.01059,0.8324066
+482.76627,53.51361,0.27744597,457.86893,66.10332,0.051902797,429.60233,60.94935,0.88025624
+482.59744,52.66356,0.30038524,458.10184,65.86685,0.04923729,429.87433,60.82519,0.8736636
+482.54276,52.040592,0.23129715,459.03345,63.442455,0.083021805,430.83548,60.5543,0.8204793
+482.34216,52.100437,0.3498157,458.76337,62.789597,0.1699896,432.19604,61.543816,0.508585
+482.43643,51.388615,0.31710148,458.37048,63.074078,0.068616286,432.1274,62.492676,0.4865205
+482.94928,49.806484,0.29563445,458.3772,62.419365,0.100758135,431.76288,62.330696,0.54924566
+484.10876,47.230446,0.63732904,458.73312,61.375698,0.42538193,432.07236,61.919518,0.5184152
+484.00076,46.543293,0.7260198,458.4415,61.165863,0.80617714,431.93674,62.251236,0.39229998
+483.4959,46.267815,0.7400175,458.30362,60.91133,0.7859283,432.46927,62.87769,0.29088646
+482.82138,47.409725,0.33860043,457.53607,60.375214,0.7863781,432.47824,63.00264,0.21963216
+479.83945,47.635616,0.28650776,457.11084,60.409218,0.7415505,432.23538,62.76469,0.33192453
+479.04437,47.103504,0.367384,456.94736,60.053917,0.66081357,431.6346,62.533787,0.46377325
+478.5038,46.580276,0.57288724,456.87582,59.99891,0.60552746,431.5096,62.93097,0.41092953
+476.4693,45.545464,0.7198797,456.7139,59.844822,0.40035453,431.31992,62.701935,0.4298933
+475.0532,44.064537,0.7204908,453.34073,59.117725,0.53503996,431.1139,62.359947,0.6175124
+469.68213,42.64747,0.46564254,452.9286,59.168186,0.6038627,431.1573,62.627117,0.5333248
+469.38837,41.532978,0.4487599,453.07214,58.9391,0.6488823,430.8039,62.680874,0.6340045
+469.62073,40.89138,0.31737277,452.65765,57.942112,0.683082,430.86203,62.88522,0.51941824
+469.22266,41.128643,0.30629447,452.14435,58.082436,0.7630493,430.59653,63.04912,0.54187006
+468.31903,38.76789,0.43456078,452.55283,57.34493,0.7429347,431.32846,63.334915,0.3408875
+468.4213,37.809376,0.4577458,451.9682,56.83949,0.75418866,430.7434,64.13222,0.3261971
+467.51538,37.666195,0.5653502,451.16446,56.82583,0.6302297,430.48282,64.04944,0.17465137
+466.65988,36.50628,0.61504436,451.20886,56.25506,0.5557539,430.27908,64.210106,0.10238222
+465.5955,36.076225,0.53754383,451.83905,56.053,0.45687675,431.7848,68.326126,0.033657942
+462.65607,36.581203,0.5355755,451.93747,54.328995,0.53796774,431.67374,68.70468,0.15803406
+462.22427,36.333683,0.6599198,451.39783,56.028362,0.62568897,430.6076,69.329666,0.36983305
+460.88824,35.594975,0.81448835,451.01758,55.7829,0.60703444,430.3216,69.55594,0.5155534
+459.42957,34.985806,0.7906708,451.5709,53.787735,0.4822854,430.01617,69.885605,0.76526356
+458.5865,34.803276,0.85184824,451.02625,53.6984,0.49024966,430.18634,70.29848,0.64626306
+457.82428,34.36119,0.8235948,450.52103,53.442123,0.5518548,429.7276,70.12557,0.7188167
+457.9267,34.612534,0.7680719,450.04593,53.015614,0.52258235,429.25314,70.2875,0.7669633
+457.65442,33.84248,0.75301266,449.91977,52.62924,0.5036106,429.2836,70.244194,0.81333417
+456.19458,29.939999,0.73246455,449.5976,51.84486,0.46144152,430.47238,71.28205,0.69256055
+453.7165,28.821825,0.77715933,449.39575,51.641685,0.5464043,430.4364,71.671036,0.7715367
+452.66003,28.099947,0.953882,449.53012,51.011158,0.39557797,430.99557,72.12316,0.67706597
+450.32538,28.037716,0.9192612,449.8995,50.78756,0.3503521,431.30316,72.22595,0.67770016
+450.1087,27.870989,0.894967,449.63754,50.771378,0.2872086,431.51248,72.703476,0.63415223
+451.0601,27.824474,0.94048035,449.45264,50.69797,0.30145282,431.82507,72.76508,0.57980585
+451.36267,27.230774,0.95762783,449.41702,50.397503,0.28309053,432.01416,72.73747,0.60496956
+451.22125,25.733862,0.9410667,449.67697,50.33525,0.3778461,432.32968,72.479324,0.47284836
+452.4408,22.620169,0.8652197,449.69595,50.324062,0.33349735,432.69962,72.61114,0.25099555
+452.59766,20.805674,0.89577013,449.74713,49.96258,0.30555755,432.98145,72.6306,0.0897828
+453.73013,17.738146,0.82926816,447.5794,48.904346,0.24059598,433.2309,72.48654,0.042403568
+455.17593,16.110397,0.54065204,447.57693,48.298992,0.18979661,435.1374,70.17715,0.026642296
+456.51913,14.290302,0.67301893,450.5511,47.090717,0.22624439,434.8925,69.713684,0.044014648
+457.71545,13.588767,0.68447375,450.52054,46.182716,0.21309857,434.35843,69.6884,0.046630066
+459.02747,13.8669615,0.89123917,450.1306,45.832996,0.4844229,432.30518,71.14157,0.05422834
+460.52682,14.251099,0.7855431,450.80515,45.387314,0.3270457,432.0324,71.1387,0.07196752
+461.23972,14.245913,0.69130164,450.41443,45.260418,0.41451007,431.6567,71.12655,0.21798684
+460.5387,16.930105,0.6575714,450.56412,45.35634,0.6483859,431.3135,71.13163,0.34458005
+460.26016,17.50916,0.8029109,450.5231,46.160744,0.7791846,431.54977,71.13665,0.34299734
+460.23965,18.397465,0.8703991,450.93323,46.32791,0.87556064,430.87762,71.224335,0.3263267
+460.46844,19.057467,0.8473045,450.9986,46.21194,0.89116555,430.80753,71.09605,0.28094956
+461.367,20.838001,0.28883928,450.78036,46.64988,0.8151598,430.79556,70.99249,0.3824023
+461.04675,24.810747,0.34329742,450.02783,46.965733,0.7544698,430.17868,69.76707,0.62859887
+462.10077,25.853115,0.26938504,450.33768,47.12716,0.7423133,430.04428,69.73064,0.77208865
+462.68234,26.428125,0.25117677,450.18292,46.93383,0.8040483,430.07886,69.641716,0.7725009
+463.68512,27.124378,0.19901426,450.16696,46.707375,0.82411397,430.01138,69.49438,0.7696716
+467.26263,28.167276,0.20903409,450.3857,46.793427,0.8540617,429.9169,69.34043,0.71282244
+467.45746,28.458931,0.25088128,450.8757,47.394215,0.78518736,430.20087,69.26028,0.65115976
+467.22015,27.93804,0.27814582,451.23834,47.105648,0.8373768,430.19778,69.21618,0.6501194
+466.3904,27.698723,0.18894985,451.15683,47.126724,0.7913548,430.78458,69.15909,0.60931724
+466.19763,27.95717,0.21227437,450.9813,46.87953,0.839437,430.74506,69.06585,0.6121624
+466.93335,27.48888,0.318299,450.7709,46.832752,0.8483097,430.768,68.68003,0.6648284
+467.41125,27.174343,0.3175771,451.29102,46.288765,0.9077181,430.79,68.65356,0.6228951
+467.7633,27.35007,0.36879963,451.41772,46.352516,0.91477853,430.9584,68.10584,0.5783075
+468.2507,27.676323,0.31984952,451.5842,46.04663,0.9283726,431.0345,67.68998,0.5779432

package/skills/16_Animal_Behavior/ethoclaw-trajectory-velocity-heatmap-generate/reference_data/reference_data_readme.md

@@ -0,0 +1,126 @@
+# 📖 Reference Data Guide: Animal Behavior Trajectory Data (.h5 & .csv)
+
+This document explains how to process 2D animal behavior trajectory tracking data using Python. The data is available in both original HDF5 (`.h5`) format and converted standard table (`.csv`) format.
+
+---
+
+## 1. Data Structure and Physical Meaning
+
+Whether from the original `.h5` file or the converted `.csv` file, the core data representation is the same. This is a typical combination of **Time-series** and **Spatial coordinates** data.
+
+### 1.1 What does each "Row" represent?
+
+- **Physical Meaning**: **1 Row = 1 Frame**.
+- **Explanation**: Each row of data represents one frame in the video. If your video recording frame rate is 30 fps (30 frames per second), then 30 consecutive rows of data represent 1 second of animal behavior trajectory in the real world. The increasing row number represents the passage of time.
+
+### 1.2 What does each "Column" represent?
+
+Column data is organized by "Body Part", with each part occupying **3 columns**.
+Taking `nose` as an example:
+
+1.  `nose_x`: The **X-axis pixel coordinate** of the nose in the current frame of the video (typically with the top-left corner of the frame as the origin 0,0, and rightward as the positive X direction).
+2.  `nose_y`: The **Y-axis pixel coordinate** of the nose in the current frame of the video (downward as the positive Y direction).
+3.  `nose_confidence` (or likelihood): The **confidence/probability value** of the algorithm model's detection of the nose position in the current frame. The value range is `0.0 ~ 1.0`.
+    - `1.0` means the model is 100% confident that the nose is at this (X, Y) coordinate.
+    - If the value is very low (e.g., `< 0.6`), it usually means the nose is occluded in this frame, or the image is blurry causing inaccurate model recognition. In this case, the (X, Y) coordinate is **unreliable**.
+
+---
+
+## 2. Reading and Using CSV Files (⭐ Recommended: Simplest and Most Efficient)
+
+The converted `.csv` file already contains intuitive headers, making it most convenient to process using the `pandas` library.
+
+### 2.1 Basic Reading Code
+
+```python
+import pandas as pd
+
+# 1. Read CSV file
+csv_path = "control 506.csv"
+df = pd.DataFrame()
+try:
+    df = pd.read_csv(csv_path)
+    print("✅ CSV data loaded successfully!")
+except FileNotFoundError:
+    print("❌ File not found, please check the path.")
+
+# 2. View data overview
+print(f"Data contains {df.shape[0]} frames and {df.shape[1]} columns of information.")
+print("\nFirst 5 rows preview:")
+print(df.head())
+```
+
+### 2.2 Data Analysis Tips: How to Clean and Extract Data?
+
+In actual analysis, we cannot directly trust all coordinates. We must use the `confidence` column to filter out "dirty data" with inaccurate recognition.
+
+```python
+# Assume we want to study the movement trajectory of the mouse nose
+
+# 1. Extract complete nose data
+nose_data = df[['nose_x', 'nose_y', 'nose_confidence']]
+
+# 2. [Core Technique] Filter low confidence data
+# Set a threshold, e.g., 0.8. Treat coordinates with confidence < 0.8 as invalid (NaN)
+threshold = 0.8
+valid_nose_data = df.copy() # Copy data to avoid modifying original table
+
+# Replace x and y coordinates that don't meet the condition with missing value NaN (Not a Number)
+valid_nose_data.loc[valid_nose_data['nose_confidence'] < threshold, ['nose_x', 'nose_y']] = None
+
+# 3. Extract filtered clean coordinates for plotting or calculating velocity
+clean_x = valid_nose_data['nose_x']
+clean_y = valid_nose_data['nose_y']
+
+print(f"After filtering, {clean_x.isna().sum()} frames of nose data were excluded due to low confidence.")
+```
+
+---
+
+## 3. Reading Original HDF5 (.h5) Files
+
+If you don't want to generate intermediate CSV files and prefer to read directly from the source using code, you can use `h5py`.
+
+### 3.1 HDF5 Internal Structure
+
+According to our data's HDFView structure, you need to focus on two internal paths:
+
+- `/2Dskeleton/BodyParts`: A one-dimensional byte array storing body part names (e.g., `[b'nose', b'back', b'tail']`).
+- `/2Dskeleton/data2D`: A two-dimensional pure numeric matrix storing coordinates and confidence values.
+
+### 3.2 Basic Reading Code
+
+```python
+import h5py
+import numpy as np
+import pandas as pd
+
+h5_path = "control 506.h5"
+
+with h5py.File(h5_path, 'r') as f:
+    # 1. Parse body part names (and decode utf-8)
+    raw_body_parts = f['/2Dskeleton/BodyParts'][:]
+    body_parts = [part.decode('utf-8') if isinstance(part, bytes) else str(part) for part in raw_body_parts]
+
+    # 2. Read pure numeric matrix
+    data2d = f['/2Dskeleton/data2D'][:]
+
+    # 3. Dynamically reconstruct into DataFrame in memory for easy subsequent processing
+    column_names = []
+    for part in body_parts:
+        column_names.extend([f"{part}_x", f"{part}_y", f"{part}_confidence"])
+
+    df_from_h5 = pd.DataFrame(data2d, columns=column_names)
+
+print("\n✅ Data parsed directly from HDF5:")
+print(df_from_h5.head())
+```
+
+## 4. Advanced Application Scenarios
+
+Once you successfully extract clean `X` and `Y` coordinates, you can use them for the following animal behavior analyses:
+
+1.  **Plot Trajectory Heatmap**: Use `matplotlib` or `seaborn` to plot `(back_x, back_y)` as a 2D histogram to observe which area the mouse prefers to stay in.
+2.  **Calculate Total Movement Distance**: Calculate the **Euclidean distance** between coordinate points in each frame and the previous frame ($d = \sqrt{(x_2 - x_1)^2 + (y_2 - y_1)^2}$), then sum the distances of all frames.
+3.  **Calculate Instantaneous Velocity**: Use the distance between adjacent frames divided by the time difference between adjacent frames ($t = 1 / frame rate$).
+4.  **Identify Body Posture**: By calculating the distance between `nose` and `tail` points, you can determine whether the mouse is in a stretched or curled state.