Merge pull request #17 from ImagingDataCommons/idc-index-0.12.2

Update to idc-index 0.12.2 (idc-index-data 24.1.0)

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/).
 
+## [1.6.1] - 2026-05-08
+
+### Added
+
+- `series_init_idc_version` and `series_revised_idc_version` columns in primary `index` table (idc-index-data 24.1.0): expose the IDC version when each series was first added and last revised, enabling version-aware filtering
+- `version_metadata_index` table: maps each IDC version number to its release timestamp; requires `client.fetch_index("version_metadata_index")`
+- Tests for new index columns and `version_metadata_index` (61 total, up from 55)
+
+### Changed
+
+- Updated to idc-index 0.12.2 (idc-index-data 24.1.0); IDC data version remains v24
+- `analysis_results_index` column renames (idc-index-data 24.1.0): `Updated` → `updated`, `Description` → `description`
+
 ## [1.6.0] - 2026-05-07
 
 ### Added

SKILL.md

@@ -3,9 +3,9 @@ name: imaging-data-commons
 description: Query and download public cancer imaging data from NCI Imaging Data Commons using idc-index. Invoke for any question about IDC collections, cancer imaging datasets, DICOM data access, radiology (CT, MR, PET) or pathology AI training sets, metadata queries, visualization, or license checks — even when the user doesn't explicitly mention "IDC". No authentication required.
 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.6.0
+    version: 1.6.1
     skill-author: Andrey Fedorov, @fedorov
-    idc-index: "0.12.1"
+    idc-index: "0.12.2"
     idc-data-version: "v24"
     repository: https://github.com/ImagingDataCommons/idc-claude-skill
 ---
@@ -27,7 +27,7 @@ Use the `idc-index` Python package to query and download public cancer imaging d
 ```python
 import idc_index
 
-REQUIRED_VERSION = "0.12.1"  # Must match metadata.idc-index in this file
+REQUIRED_VERSION = "0.12.2"  # Must match metadata.idc-index in this file
 installed = idc_index.__version__
 
 if installed < REQUIRED_VERSION:
@@ -143,6 +143,7 @@ The `idc-index` package provides multiple metadata index tables, accessible via
 | `contrast_index` | 1 row = 1 series with contrast info | fetch_index() | Contrast agent metadata: agent name, ingredient, administration route (CT, MR, PT, XA, RF) |
 | `volume_geometry_index` | 1 row = 1 CT/MR/PT series | fetch_index() | 3D volume geometry validation for single-frame CT, MR, and PT series; boolean checks for orientation, spacing, dimensions, and slice positions; composite `regularly_spaced_3d_volume` flag |
 | `rtstruct_index` | 1 row = 1 RTSTRUCT series | fetch_index() | RT Structure Set metadata: total ROI count, ROI names, generation algorithms, interpreted types, and the referenced image series UID |
+| `version_metadata_index` | 1 row = 1 IDC release version | fetch_index() | IDC version release timestamps; join on `idc_version` to correlate series with their release date |
 
 **Auto** = loaded automatically when `IDCClient()` is instantiated
 **fetch_index()** = requires `client.fetch_index("table_name")` to load
@@ -167,7 +168,7 @@ The `idc-index` package provides multiple metadata index tables, accessible via
 | `SeriesInstanceUID` | index, volume_geometry_index | Link series to its 3D geometry validation result (join index.SeriesInstanceUID = volume_geometry_index.SeriesInstanceUID) |
 | `SeriesInstanceUID` / `referenced_SeriesInstanceUID` | index, rtstruct_index | Join RTSTRUCT series to its metadata (index.SeriesInstanceUID = rtstruct_index.SeriesInstanceUID); use rtstruct_index.referenced_SeriesInstanceUID to find the source image series |
 
-**Note:** `Subjects`, `Updated`, and `Description` appear in multiple tables but have different meanings (counts vs identifiers, different update contexts).
+**Note:** `subjects`, `updated`, and `description` appear in multiple tables but have different meanings (counts vs identifiers, different update contexts).
 
 For detailed join examples, schema discovery patterns, key columns reference, and DataFrame access, see `references/index_tables_guide.md`.
 
@@ -243,7 +244,7 @@ print(client.get_idc_version())  # Should return "v24"
 ```
 If you see an older version, upgrade with: `pip install --upgrade idc-index`
 
-**Tested with:** idc-index 0.12.1 (IDC data version v24)
+**Tested with:** idc-index 0.12.2 (IDC data version v24)
 
 **Optional (for data analysis):**
 ```bash
@@ -366,6 +367,7 @@ results = client.sql_query("""
 - Clinical: PatientAge, PatientSex, StudyDate
 - Descriptions: StudyDescription, SeriesDescription
 - Licensing: license_short_name
+- Versioning: series_init_idc_version (IDC version when series was first added), series_revised_idc_version (IDC version when series was last revised)
 
 **Note:** Cancer type is in `collections_index.cancer_types`, not in the primary `index` table.
 

references/index_tables_guide.md

@@ -1,6 +1,6 @@
 # Index Tables Guide for IDC
 
-**Tested with:** idc-index 0.12.1 (IDC data version v24)
+**Tested with:** idc-index 0.12.2 (IDC data version v24)
 
 This guide covers the structure and access patterns for IDC index tables: programmatic schema discovery, DataFrame access, and join column references. For the overview of available tables and their purposes, see the "Index Tables" section in the main SKILL.md.
 

tests/requirements-test.txt

@@ -1,4 +1,4 @@
-idc-index==0.12.1
+idc-index==0.12.2
 pandas
 pytest
 pytest-timeout

tests/test_snippets.py

@@ -42,6 +42,7 @@ def client_with_all_indices(client):
         "contrast_index",
         "volume_geometry_index",
         "rtstruct_index",
+        "version_metadata_index",
     ]:
         client.fetch_index(table)
     return client
@@ -55,14 +56,50 @@ class TestVersionAndSetup:
     """SKILL.md: version check and IDC data version."""
 
     def test_package_version_meets_requirement(self):
-        required = "0.12.1"
+        required = "0.12.2"
         assert idc_index.__version__ >= required, (
             f"idc-index {idc_index.__version__} < required {required}"
         )
 
     def test_idc_data_version_is_v24(self, client):
         assert client.get_idc_version() == "v24"
 
+    def test_series_version_columns_present(self, client):
+        cols = client.index.columns.tolist()
+        assert "series_init_idc_version" in cols
+        assert "series_revised_idc_version" in cols
+
+    def test_version_metadata_index_available(self, client):
+        assert "version_metadata_index" in client.indices_overview
+        assert client.indices_overview["version_metadata_index"]["installed"]
+
+    def test_version_metadata_index_query(self, client_with_all_indices):
+        df = client_with_all_indices.sql_query(
+            "SELECT idc_version, version_timestamp FROM version_metadata_index ORDER BY idc_version"
+        )
+        assert len(df) > 0
+        assert "idc_version" in df.columns
+        assert "version_timestamp" in df.columns
+
+    def test_series_version_columns_query(self, client):
+        df = client.sql_query("""
+            SELECT SeriesInstanceUID, series_init_idc_version, series_revised_idc_version
+            FROM index
+            WHERE series_init_idc_version IS NOT NULL
+            LIMIT 10
+        """)
+        assert len(df) > 0
+
+    def test_join_index_with_version_metadata(self, client_with_all_indices):
+        df = client_with_all_indices.sql_query("""
+            SELECT i.SeriesInstanceUID, i.series_init_idc_version, v.version_timestamp
+            FROM index i
+            JOIN version_metadata_index v ON i.series_init_idc_version = v.idc_version
+            LIMIT 5
+        """)
+        assert len(df) > 0
+        assert "version_timestamp" in df.columns
+
 
 # ===========================================================================
 # SKILL.md – Overall statistics
@@ -124,6 +161,13 @@ def test_analysis_results_index(self, client_with_all_indices):
         """)
         assert len(df) > 0
 
+    def test_analysis_results_index_column_names(self, client_with_all_indices):
+        cols = client_with_all_indices.analysis_results_index.columns.tolist()
+        for expected in ("updated", "description"):
+            assert expected in cols, f"Expected lowercase column '{expected}' in analysis_results_index"
+        assert "Updated" not in cols
+        assert "Description" not in cols
+
 
 # ===========================================================================
 # SKILL.md – SQL queries