calculate_expression_correlation

Instructions

Implementation Reference

• src/handlers/expression-handlers.ts:751-853 (handler)

  Main handler function that fetches median gene expression data for multiple genes and computes pairwise Pearson correlations across common tissues, returning formatted correlation results.

  async calculateExpressionCorrelation(args: any) {
    if (!args.geneIds || !Array.isArray(args.geneIds) || args.geneIds.length < 2) {
      throw new Error('geneIds parameter is required and must contain at least 2 gene IDs for correlation analysis');
    }
  
    if (args.geneIds.length > 10) {
      return {
        content: [{
          type: "text",
          text: "Maximum 10 genes can be processed for correlation analysis."
        }]
      };
    }
  
    // Get median expression for all genes
    const result = await this.apiClient.getMedianGeneExpression(
      args.geneIds,
      args.datasetId || 'gtex_v8'
    );
  
    if (result.error) {
      return {
        content: [{
          type: "text",
          text: `Error calculating expression correlation: ${result.error}`
        }],
        isError: true
      };
    }
  
    const expressions = result.data || [];
    if (expressions.length === 0) {
      return {
        content: [{
          type: "text",
          text: "No expression data found for correlation analysis."
        }]
      };
    }
  
    // Organize by gene and tissue
    const geneData: { [gene: string]: { [tissue: string]: number } } = {};
    const geneNames: { [gene: string]: string } = {};
    
    expressions.forEach(expr => {
      const geneKey = expr.gencodeId;
      geneNames[geneKey] = expr.geneSymbol;
      if (!geneData[geneKey]) {
        geneData[geneKey] = {};
      }
      geneData[geneKey][expr.tissueSiteDetailId] = expr.median;
    });
  
    // Find common tissues
    const genes = Object.keys(geneData);
    const commonTissues = Object.keys(geneData[genes[0]] || {});
    
    // Calculate pairwise correlations
    let output = `**Gene Expression Correlation Analysis**\n`;
    output += `Genes: ${genes.length}\n`;
    output += `Common tissues: ${commonTissues.length}\n`;
    output += `Dataset: ${expressions[0]?.datasetId}\n\n`;
  
    if (commonTissues.length < 5) {
      output += `⚠️ **Warning**: Only ${commonTissues.length} common tissues found. Correlation analysis requires more data points for reliability.\n\n`;
    }
  
    output += `**Pairwise Correlations:**\n`;
    
    for (let i = 0; i < genes.length; i++) {
      for (let j = i + 1; j < genes.length; j++) {
        const gene1 = genes[i];
        const gene2 = genes[j];
        
        // Calculate Pearson correlation
        const values1 = commonTissues.map(t => geneData[gene1][t]).filter(v => v !== undefined);
        const values2 = commonTissues.map(t => geneData[gene2][t]).filter(v => v !== undefined);
        
        if (values1.length !== values2.length || values1.length < 3) {
          output += `• **${geneNames[gene1]}** vs **${geneNames[gene2]}**: Insufficient data\n`;
          continue;
        }
        
        const correlation = this.calculatePearsonCorrelation(values1, values2);
        const strength = Math.abs(correlation) > 0.7 ? "Strong" : 
                        Math.abs(correlation) > 0.4 ? "Moderate" : "Weak";
        
        output += `• **${geneNames[gene1]}** vs **${geneNames[gene2]}**: r = ${correlation.toFixed(3)} (${strength})\n`;
      }
    }
  
    output += `\n**Analysis Notes:**\n`;
    output += `- Correlations calculated using median expression across tissues\n`;
    output += `- |r| > 0.7: Strong correlation, |r| > 0.4: Moderate correlation\n`;
    output += `- Based on ${commonTissues.length} tissue samples\n`;
  
    return {
      content: [{
        type: "text",
        text: output
      }]
    };
  }

• src/index.ts:175-190 (schema)

  Input schema defining the parameters for the calculate_expression_correlation tool: array of GENCODE gene IDs (required) and optional datasetId.

  inputSchema: {
    type: "object",
    properties: {
      gencodeIds: {
        type: "array", 
        items: { type: "string" },
        description: "Array of GENCODE gene IDs to compare"
      },
      datasetId: {
        type: "string",
        description: "GTEx dataset ID (default: gtex_v8)",
        default: "gtex_v8"
      }
    },
    required: ["gencodeIds"]
  }

• src/index.ts:172-191 (registration)

  Tool registration in the listTools response, including name, description, and input schema.

  {
    name: "calculate_expression_correlation",
    description: "Calculate expression correlation between genes across tissues",
    inputSchema: {
      type: "object",
      properties: {
        gencodeIds: {
          type: "array", 
          items: { type: "string" },
          description: "Array of GENCODE gene IDs to compare"
        },
        datasetId: {
          type: "string",
          description: "GTEx dataset ID (default: gtex_v8)",
          default: "gtex_v8"
        }
      },
      required: ["gencodeIds"]
    }
  },

• src/index.ts:657-662 (registration)

  Dispatch logic in CallToolRequest handler that routes calls to the expressionHandlers.calculateExpressionCorrelation method.

  if (name === "calculate_expression_correlation") {
    return await expressionHandlers.calculateExpressionCorrelation({
      geneIds: args?.gencodeIds || [],
      datasetId: args?.datasetId
    });
  }

• src/handlers/expression-handlers.ts:987-1001 (helper)

  Private helper method that computes the Pearson correlation coefficient between two arrays of expression values.

  private calculatePearsonCorrelation(x: number[], y: number[]): number {
    const n = x.length;
    if (n !== y.length || n === 0) return 0;
    
    const sumX = x.reduce((sum, val) => sum + val, 0);
    const sumY = y.reduce((sum, val) => sum + val, 0);
    const sumXY = x.reduce((sum, val, i) => sum + val * y[i], 0);
    const sumX2 = x.reduce((sum, val) => sum + val * val, 0);
    const sumY2 = y.reduce((sum, val) => sum + val * val, 0);
    
    const numerator = n * sumXY - sumX * sumY;
    const denominator = Math.sqrt((n * sumX2 - sumX * sumX) * (n * sumY2 - sumY * sumY));
    
    return denominator === 0 ? 0 : numerator / denominator;
  }