get_sample_info
Retrieve sample metadata and demographics from the GTEx Portal for genomic analysis, optionally filtered by tissue type or dataset version.
Instructions
Get GTEx sample metadata and demographics
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| datasetId | No | GTEx dataset ID (default: gtex_v8) | gtex_v8 |
| tissueSiteDetailId | No | Tissue site detail ID (optional, for tissue-specific samples) |
Implementation Reference
- The getSamples method implements the core logic for the 'get_sample_info' tool. It calls the GTExApiClient.getSamples API with parameters mapped from tool arguments, handles errors, and formats detailed sample metadata (subject info, tissue details, quality metrics) or summary statistics for large result sets.async getSamples(args: any) { const result = await this.apiClient.getSamples({ datasetId: args.datasetId || 'gtex_v8', sampleId: args.sampleIds, tissueSampleId: args.tissueSampleIds, subjectId: args.subjectIds, ageBracket: args.ageBrackets, sex: args.sex, pathCategory: args.pathCategories, tissueSiteDetailId: args.tissueIds, page: args.page || 0, itemsPerPage: args.itemsPerPage || 100 }); if (result.error) { return { content: [{ type: "text", text: `Error retrieving sample information: ${result.error}` }], isError: true }; } const samples = result.data || []; if (samples.length === 0) { return { content: [{ type: "text", text: "No samples found matching the specified criteria." }] }; } let output = `**Sample Information (${samples.length} samples)**\n`; output += `Dataset: ${samples[0]?.datasetId}\n\n`; if (samples.length <= 20) { // Detailed view for small result sets samples.forEach((sample, index) => { output += `### Sample ${index + 1}: ${sample.sampleId}\n`; output += `**Subject Information:**\n`; output += ` • Subject ID: ${sample.subjectId}\n`; output += ` • Age bracket: ${sample.ageBracket}\n`; output += ` • Sex: ${sample.sex}\n`; output += ` • Hardy Scale: ${sample.hardyScale}\n`; output += `\n**Sample Details:**\n`; output += ` • Tissue sample ID: ${sample.tissueSampleId}\n`; output += ` • Tissue: ${sample.tissueSiteDetail} (${sample.tissueSiteDetailId})\n`; if (sample.aliquotId) { output += ` • Aliquot ID: ${sample.aliquotId}\n`; } output += ` • Data type: ${sample.dataType}\n`; if (sample.ischemicTime !== undefined) { output += `\n**Sample Quality:**\n`; output += ` • Ischemic time: ${sample.ischemicTime} min (${sample.ischemicTimeGroup})\n`; if (sample.rin !== undefined) { output += ` • RIN: ${sample.rin}\n`; } if (sample.autolysisScore) { output += ` • Autolysis score: ${sample.autolysisScore}\n`; } } if (sample.pathologyNotes) { output += `\n**Pathology Notes:** ${sample.pathologyNotes}\n`; } output += '\n'; }); } else { // Summary view for large result sets const tissueGroups: { [key: string]: any[] } = {}; samples.forEach(sample => { if (!tissueGroups[sample.tissueSiteDetailId]) { tissueGroups[sample.tissueSiteDetailId] = []; } tissueGroups[sample.tissueSiteDetailId].push(sample); }); output += `**Sample Summary by Tissue:**\n`; Object.entries(tissueGroups).forEach(([tissueId, tissueSamples]) => { const tissueDisplayName = this.getTissueDisplayName(tissueId); const maleCount = tissueSamples.filter(s => s.sex === 'male').length; const femaleCount = tissueSamples.filter(s => s.sex === 'female').length; const avgAge = this.calculateAverageAge(tissueSamples); output += ` **${tissueDisplayName}** (${tissueSamples.length} samples)\n`; output += ` • Male: ${maleCount}, Female: ${femaleCount}\n`; if (avgAge) { output += ` • Average age: ${avgAge}\n`; } }); } if (result.paging_info && result.paging_info.totalNumberOfItems > samples.length) { output += `\n**Note:** Showing ${samples.length} of ${result.paging_info.totalNumberOfItems} total results.\n`; } return { content: [{ type: "text", text: output.trim() }] }; }
- src/index.ts:462-478 (schema)Input schema for the get_sample_info tool, defining optional tissueSiteDetailId and datasetId parameters with descriptions and defaults.name: "get_sample_info", description: "Get GTEx sample metadata and demographics", inputSchema: { type: "object", properties: { tissueSiteDetailId: { type: "string", description: "Tissue site detail ID (optional, for tissue-specific samples)" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } } } },
- src/index.ts:739-744 (registration)Tool dispatch/registration in the CallToolRequestHandler that maps 'get_sample_info' calls to referenceHandlers.getSamples with argument transformation.if (name === "get_sample_info") { return await referenceHandlers.getSamples({ tissueIds: args?.tissueSiteDetailId ? [args.tissueSiteDetailId] : undefined, datasetId: args?.datasetId }); }