# Physical activity measures

## 應用情境
- 美國標準化運動紀錄建構指引:FHIR Physical Activity(PA) IG 指引中包含運動紀錄 (**Physical activity measures**) 規格
- 可記錄進行哪種運動(Activity performed)、運動進行時間(Activity duration)、運動過程平均及最大心律、估算消耗的卡路里等資訊
- 在 FHIR US PA IG 中，這些紀錄屬於 [measurement profile](https://build.fhir.org/ig/HL7/physical-activity/measures.html)...
- 這可用 FHIR observation 紀錄，以記錄個別量； 運動距離、時間、最大心律等，分別以不同 FHIR observation 紀錄測註 A

## 註 A
1. 目前 US PA measures 公告內容，主要是針對心肺功能提升，規範其運動方式及量測數據規格。但運動種類及器材繁多，如肌力訓練、復健等領域，因其運動形式、配合的器材眾多，可產生許多深具參考價值的量測，但目前在 US FHIR PA 當中並無規範，可延伸 US PA measures 紀錄
2. 若一次觀察若包含多個數值，可用一個 FHIR observation 紀錄，於 [observation.component 當中紀錄多個同時量測的數值](https://hackmd.io/xcA3Jw2oT5qThxFV8YZ9JQ?view#Record-mutiple-value)
3. 運動過程紀錄之連續性波形或影片，與本文件格式不一，需另外訂立。

## PA measure observation JSON 範例及主要的欄位
- 若已有公告規範，可基於公告規範整理範例，並延伸應用。若無可自行定義(也可與 AI 協作產生)，在由專家審核後公告
- 本情境屬於上述方式 1,已有公告規範
### 方式 1: [參考已公告的範例](https://build.fhir.org/ig/HL7/physical-activity/Observation-ExampleActivityCalories.json.html)
- 這個 JSON 檔案是一個遵循 FHIR (Fast Healthcare Interoperability Resources) 標準的 Observation 資源範例，記錄了一位病患的活動卡路里消耗數據。

{
  "resourceType" : "Observation",
  "status" : "final",
  "category" : [{
    "coding" : [{
      "system" : "http://terminology.hl7.org/CodeSystem/observation-category",
      "code" : "activity"
    }]
  },
  {
    "coding" : [{
      "system" : "http://hl7.org/fhir/us/physical-activity/CodeSystem/pa-temporary-codes",
      "code" : "PhysicalActivity"
    }]
  }],
  "code" : {
    "coding" : [{
      "system" : "http://loinc.org",
      "code" : "55424-6",
      "display" : "Calories burned in unspecified time Pedometer"
    }]
  },
  "subject" : {
    "reference" : "http://example.org/Patient/1",
    "display" : "Example Patient"
  },
  "effectiveDateTime" : "2022-06-08",
  "performer" : [{
    "reference" : "http://example.org/Patient/1",
    "display" : "Example Patient"
  }],
  "valueQuantity" : {
    "value" : 738,
    "unit" : "kilocalories",
    "system" : "http://unitsofmeasure.org",
    "code" : "kcal"
  }
}

## 主要欄位說明
- 可上傳上述範例，由 chatGPT 或 deepSeek 產生欄位說明文件，應會有類似的說明。如下:
### 基本資訊
- **resourceType**: "Observation" - 表示這是一個觀察類型的資源
- **id**: "ExampleActivityCalories" - 此資源的唯一識別碼
- **status**: "final" - 表示此觀察結果是最終版本

### 分類資訊 (category)
此觀察被歸類為：
1. "activity" - 來自 HL7 的觀察類別代碼系統
2. "PhysicalActivity" - 來自臨時物理活動代碼系統

### 觀察項目 (code)
- 使用 LOINC 代碼系統
- 代碼: "55424-6"
- 顯示名稱: "Calories burned in unspecified time Pedometer" (計步器測量的未指定時間內燃燒的卡路里)

### 相關人員
- **subject**: 觀察對象，指向一位範例病患 (http://example.org/Patient/1)
- **performer**: 觀察執行者，同樣是這位病患本人

### 時間資訊
- **effectiveDateTime**: "2022-06-08" - 觀察結果的有效日期

### 觀察值 (valueQuantity)
- **value**: 738 - 數值
- **unit**: "kilocalories" - 單位(千卡)
- **system**: "http://unitsofmeasure.org" - 使用 UCUM 單位系統
- **code**: "kcal" - 單位代碼

### chatGPT 回應的總結
這個 JSON 檔案完整記錄了一位病患在 2022年6月8日 通過計步器測量到的卡路里消耗數據(738千卡)，並提供了相關的元數據以便於系統間的數據交換和理解。它遵循了醫療資訊交換的 FHIR 標準，使用了標準化的代碼系統(如 LOINC 和 UCUM)來確保數據的一致性和可互操作性。
### [方式2 完全由 AI 產生的結果](https://hackmd.io/rplnGnZ0Qq6WKhqNTqXQdw?view)
- 當已有公告規範， AI 產生結果可能與 公告有差異，不建議如此做

## 欄位及編碼 (規格)
- 固定的欄位及編碼
- 產生實體 JSON需填寫的欄位
-- 必須及可能參考的 resources
-- 特定種類的紀錄 (如 observation code, condition code...)
-- 紀錄的資料或數值編碼(如 observation 可能包含數值及單位)

## FHIR resources 可變欄位分析說明
- 上述 JSON 範例，有多個欄位可在輸入介面(或 JSON 資料產生程式) 設定，以針對特定人員、特定項目的數據。 如上範例， 55424-6: 計步器測量的未指定時間內燃燒的卡路里，可調整成最大心跳，以支援多樣化的運動數據記錄需求
- 可向 AI 提問整理出可調整欄位:
-- 請基於上述範例，分析那些欄位資料可在程式中調整，以針對特定人員，設定其各式運動紀錄，如消耗的卡路里、運動期間最大心跳等

### DeepSeek 回應結果
根據提供的FHIR Observation資源範例，以下是可在程式中調整以針對特定人員設定運動紀錄的關鍵欄位，以及如何擴展來支援不同運動指標：

---

### **1. 受試者識別 (Subject)**
- **調整欄位**：`subject.reference`
- **用途**：綁定特定患者
- **範例調整**：

  "subject": {
    "reference": "Patient/12345",  // 改成實際患者ID
    "display": "張小明"
  }

---

### **2. 運動指標類型 (Code)**
- **調整欄位**：`code.coding` 中的 `code` 和 `display`
- **用途**：定義記錄的運動指標類型（需配合LOINC或其他標準碼）
- **擴展範例**：
- **卡路里消耗**（沿用範例）：

    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "55424-6",
        "display": "Calories burned"
      }]
    }

- **最大心率**：

    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "89269-0",
        "display": "Maximum heart rate during exercise"
      }]
    }

- **運動持續時間**：

    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "54899-0",
        "display": "Exercise duration"
      }]
    }

---

### **3. 數值與單位 (ValueQuantity)**
- **調整欄位**：`valueQuantity` 下的 `value`、`unit`、`code`
- **用途**：記錄運動數據的實際值和單位
- **擴展範例**：
- **卡路里**：

    "valueQuantity": {
      "value": 500,
      "unit": "kilocalories",
      "system": "http://unitsofmeasure.org",
      "code": "kcal"
    }

- **最大心率**：

    "valueQuantity": {
      "value": 165,
      "unit": "beats per minute",
      "system": "http://unitsofmeasure.org",
      "code": "/min"
    }

- **運動距離**：

    "valueQuantity": {
      "value": 5.2,
      "unit": "kilometers",
      "system": "http://unitsofmeasure.org",
      "code": "km"
    }

---

### **4. 時間範圍 (EffectiveDateTime)**
- **調整欄位**：`effectiveDateTime` 或改用 `effectivePeriod`
- **用途**：記錄運動時間或區間
- **擴展範例**：
- **單次運動時間點**：

    "effectiveDateTime": "2023-05-15T15:30:00+08:00"

- **長時間運動區間**：

    "effectivePeriod": {
      "start": "2023-05-15T09:00:00+08:00",
      "end": "2023-05-15T10:30:00+08:00"
    }

---

### **5. 執行者 (Performer)**
- **調整欄位**：`performer`
- **用途**：標記數據提供者（如患者本人或設備）
- **範例調整**：

  "performer": [{
    "reference": "Device/fitbit-123",  // 若數據來自穿戴設備
    "display": "Fitbit Charge 5"
  }]

---

### **6. 運動類別 (Category)**
- **調整欄位**：`category.coding`
- **用途**：進一步分類運動類型（可擴展自定義CodeSystem）
- **擴展範例**：

  "category": [{
    "coding": [{
      "system": "http://example.org/custom-codes",
      "code": "running",
      "display": "跑步"
    }]
  }]

---

### **7. 擴展其他運動相關欄位**
FHIR允許透過擴展（Extension）加入自定義數據，例如：
- **運動強度**：

  "extension": [{
    "url": "http://example.org/extensions/exercise-intensity",
    "valueCode": "high"
  }]

- **運動地點**：

  "extension": [{
    "url": "http://example.org/extensions/location",
    "valueString": "健身房"
  }]

---

### **完整調整後的範例（記錄最大心率）**

{
  "resourceType": "Observation",
  "status": "final",
  "category": [{
    "coding": [{
      "system": "http://hl7.org/fhir/us/physical-activity/CodeSystem/pa-temporary-codes",
      "code": "PhysicalActivity"
    }]
  }],
  "code": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "89269-0",
      "display": "Maximum heart rate during exercise"
    }]
  },
  "subject": {
    "reference": "Patient/12345",
    "display": "張小明"
  },
  "effectiveDateTime": "2023-05-15T15:30:00+08:00",
  "performer": [{
    "reference": "Device/fitbit-123",
    "display": "Fitbit Charge 5"
  }],
  "valueQuantity": {
    "value": 165,
    "unit": "beats per minute",
    "system": "http://unitsofmeasure.org",
    "code": "/min"
  },
  "extension": [{
    "url": "http://example.org/extensions/exercise-intensity",
    "valueCode": "high"
  }]
}

---

### **程式設計建議**
1. **動態欄位映射**：
建立一個對照表，將運動類型（如跑步、游泳）映射到對應的LOINC codes和單位。
2. **驗證單位系統**：
確保單位符合UCUM標準（如心率單位為`/min`）。
3. **時間處理**：
若需精確記錄，改用`effectivePeriod`取代`effectiveDateTime`。

透過靈活調整上述欄位，即可支援多樣化的運動數據記錄需求。

## 產生程式
- 可向 AI 提問:
-- 無提供相關資訊 : 請提供產生 FHIR JSON 運動紀錄之 HTML 及 JS 網頁程式
-- 基於 JSON 範例: 請基於上述 JSON 範例,產生 FHIR 運動紀錄之 HTML 及 JS 網頁程式
-- [基於嚴謹的對照表(如 CSV)](https://hackmd.io/ZTfUQO-OQLKArMpuk5D-gw?view)，利於:
--- 資料產生及調閱端程式都基於對照表，確保互通性
--- 利於支援多國語言
--- [利於擴充(需再整理)](https://hackmd.io/QQhiZYZHSRqkNvc-OSNPHw)

### 使用設定檔以增強程式可擴展性
- 可將程式及設定檔分離，以利增強程式可擴展性。如向 chatGPT 提問: 使用者下載程式後，可透過設定檔改變其功能及介面，請列舉其優點
-- [chatGPT result](https://chatgpt.com/share/c5023b36-b4fa-4d95-a8f8-6d8519cd4fb4)

## [data provider 及 consumer](https://hackmd.io/8Gty-6YEQ-abrj5o0otmvw?view_)
- 資料產生端 data provider 及資料使用端 data consumer 形成成對之資料處理模塊
-- 透過 FHIR server 互通資料
-- 基於明確的規格， 互通的資料可在 provider 及 consumer 兩端程式恰當處理

## 常用之 search API