Merge pull request #7 from ImagingDataCommons/add-clinical-reference

Add references for clinical data and DICOM private tags

Author: fedorov

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to the IDC Claude Skill are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [1.2.0] - 2026-02-04
+
+### Added
+
+- Clinical data reference guide for navigating tabular data accompanying images
+- Detailed patterns for mapping coded values (option_code to option_description)
+- Examples for joining clinical data with imaging data via dicom_patient_id
+- Expanded BigQuery guide with comprehensive clinical data coverage (metadata tables, cross-collection queries)
+- Private DICOM elements documentation in BigQuery guide covering vendor-specific tags (e.g., diffusion b-values)
+- Query patterns for discovering, accessing, and filtering by private tags in the OtherElements column
+
 ## [1.1.0] - 2026-02-02
 
 ### Added

README.md

@@ -39,8 +39,7 @@ This skill is included in the [K-Dense-AI/claude-scientific-skills](https://gith
 
 This skill follows [Semantic Versioning](https://semver.org/).
 
-- **Current Version:** 1.0.0
-- **Requires:** idc-index >= 0.11.7
+- **Requires:** [idc-index](https://github.com/ImagingDataCommons/idc-index)
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and [Releases](https://github.com/ImagingDataCommons/idc-claude-skill/releases) for downloads.
 
@@ -50,7 +49,7 @@ This skill was created and is maintained by [Andrey Fedorov (@fedorov)](https://
 
 For comprehensive documentation about the skill's capabilities, see [SKILL.md](SKILL.md).
 
-Development of this skill as part of Imaging Data Commons development has been funded in whole or in part with Federal funds from the National Cancer Institute, National Institutes of Health, under Task Order No. HHSN26110071 under Contract No. HHSN261201500003l. 
+Development of this skill as part of Imaging Data Commons development has been funded in whole or in part with Federal funds from the National Cancer Institute, National Institutes of Health, under Task Order No. HHSN26110071 under Contract No. HHSN261201500003I. 
 
 If you use this skill in your research, please acknowledge IDC by citing the following publication:
 

SKILL.md

@@ -3,7 +3,7 @@ name: imaging-data-commons
 description: Query and download public cancer imaging data from NCI Imaging Data Commons using idc-index. Use for accessing large-scale radiology (CT, MR, PET) and pathology datasets for AI training or research. No authentication required. Query by metadata, visualize in browser, check licenses.
 license: This skill is provided under the MIT License. IDC data itself has individual licensing (mostly CC-BY, some CC-NC) that must be respected when using the data.
 metadata:
-    version: 1.1.0
+    version: 1.2.0
     skill-author: Andrey Fedorov, @fedorov
     idc-index: "0.11.7"
     repository: https://github.com/ImagingDataCommons/idc-claude-skill
@@ -255,6 +255,8 @@ tables = client.sql_query("SELECT DISTINCT table_name, column_label FROM clinica
 clinical_df = client.get_clinical_table("table_name")
 ```
 
+See `references/clinical_data_guide.md` for detailed workflows including value mapping patterns and joining clinical data with imaging.
+
 ## Data Access Options
 
 | Method | Auth Required | Best For |
@@ -693,14 +695,15 @@ for i in range(0, len(results), batch_size):
 
 ### 7. Advanced Queries with BigQuery
 
-For queries requiring full DICOM metadata, complex JOINs, or clinical data tables, use Google BigQuery. Requires GCP account with billing enabled.
+For queries requiring full DICOM metadata, complex JOINs, clinical data tables, or private DICOM elements, use Google BigQuery. Requires GCP account with billing enabled.
 
 **Quick reference:**
 - Dataset: `bigquery-public-data.idc_current.*`
 - Main table: `dicom_all` (combined metadata)
 - Full metadata: `dicom_metadata` (all DICOM tags)
+- Private elements: `OtherElements` column (vendor-specific tags like diffusion b-values)
 
-See `references/bigquery_guide.md` for setup, table schemas, query patterns, and cost optimization.
+See `references/bigquery_guide.md` for setup, table schemas, query patterns, private element access, and cost optimization.
 
 ### 8. Tool Selection Guide
 
@@ -1121,6 +1124,8 @@ client.sql_query("""
 """)
 ```
 
+See `references/clinical_data_guide.md` for complete patterns including value mapping and patient cohort selection.
+
 ## Related Skills
 
 The following skills complement IDC workflows for downstream analysis and visualization:
@@ -1154,6 +1159,7 @@ columns = [(c['name'], c['type'], c.get('description', '')) for c in schema['col
 
 ### Reference Documentation
 
+- **clinical_data_guide.md** - Clinical/tabular data navigation, value mapping, and joining with imaging data
 - **cloud_storage_guide.md** - Direct cloud bucket access (S3/GCS), file organization, CRDC UUIDs, versioning, and reproducibility
 - **cli_guide.md** - Complete idc-index command-line interface reference (`idc download`, `idc download-from-manifest`, `idc download-from-selection`)
 - **bigquery_guide.md** - Advanced BigQuery usage guide for complex metadata queries