> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Mapping Quality

> Analyze OMOP mapping quality between two vocabularies to assess reliability and trustworthiness of cross-vocabulary translations for production use.

This endpoint provides analysis of mapping quality between a specific vocabulary pair, essential for understanding the reliability of cross-vocabulary translations, identifying high-confidence mappings, and assessing the trustworthiness of mapping relationships for clinical and operational use.

## Path Parameters

<ParamField path="source_vocabulary" type="string" required>
  The source vocabulary identifier

  <br />

  **Example:** `SNOMED`, `ICD10CM`, `RxNorm`
</ParamField>

<ParamField path="target_vocabulary" type="string" required>
  The target vocabulary identifier

  <br />

  **Example:** `ICD10CM`, `HCPCS`, `NDC`
</ParamField>

## Query Parameters

<ParamField query="vocab_release" type="string" optional>
  Specific vocabulary release version to query

  <br />

  **Example:** `2025.1`
</ParamField>

## Response

<ResponseField name="quality_overview" type="object">
  High-level summary of mapping quality

  <Expandable title="Quality Overview Object">
    <ResponseField name="total_mappings_analyzed" type="integer">
      Total number of mappings included in analysis
    </ResponseField>

    <ResponseField name="mappings_with_quality_data" type="integer">
      Mappings that have quality metadata
    </ResponseField>

    <ResponseField name="overall_average_confidence" type="number">
      Overall average confidence score across all mappings
    </ResponseField>

    <ResponseField name="overall_quality_rating" type="string">
      Overall quality assessment

      <br />

      **Values:** `excellent`, `good`, `moderate`, `poor`
    </ResponseField>

    <ResponseField name="high_quality_percentage" type="number">
      Percentage of mappings with confidence > 0.8 (0-100%)
    </ResponseField>

    <ResponseField name="validated_percentage" type="number">
      Percentage of officially validated mappings (0-100%)
    </ResponseField>

    <ResponseField name="disputed_percentage" type="number">
      Percentage of disputed or problematic mappings
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="quality_by_vocabulary_pair" type="object">
  Quality metrics for each vocabulary pair

  <Expandable title="Vocabulary Pair Quality Object">
    <ResponseField name="[source_vocabulary_id]" type="object">
      Quality metrics for each source vocabulary

      <Expandable title="Source Vocabulary Quality Object">
        <ResponseField name="vocabulary_name" type="string">
          Human-readable vocabulary name
        </ResponseField>

        <ResponseField name="target_vocabularies" type="object">
          Quality metrics by target vocabulary

          <Expandable title="Target Vocabulary Quality Object">
            <ResponseField name="[target_vocabulary_id]" type="object">
              Quality metrics for this vocabulary pair

              <Expandable title="Pair Quality Metrics Object">
                <ResponseField name="target_vocabulary_name" type="string">
                  Target vocabulary name
                </ResponseField>

                <ResponseField name="total_mappings" type="integer">
                  Number of mappings between these vocabularies
                </ResponseField>

                <ResponseField name="average_confidence" type="number">
                  Average confidence score for this pair
                </ResponseField>

                <ResponseField name="median_confidence" type="number">
                  Median confidence score
                </ResponseField>

                <ResponseField name="confidence_std_dev" type="number">
                  Standard deviation of confidence scores
                </ResponseField>

                <ResponseField name="equivalence_distribution" type="object">
                  Distribution of equivalence types
                </ResponseField>

                <ResponseField name="validation_rate" type="number">
                  Rate of validated mappings (0.0-1.0 fraction)
                </ResponseField>

                <ResponseField name="quality_rating" type="string">
                  Quality rating for this vocabulary pair
                </ResponseField>

                <ResponseField name="primary_use_cases" type="array">
                  Main use cases for these mappings
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="overall_outgoing_quality" type="number">
          Average quality of outgoing mappings
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="quality_by_domain" type="object">
  Quality analysis by medical domain

  <Expandable title="Domain Quality Object">
    <ResponseField name="[domain_id]" type="object">
      Quality metrics for each domain

      <Expandable title="Individual Domain Quality Object">
        <ResponseField name="domain_name" type="string">
          Human-readable domain name
        </ResponseField>

        <ResponseField name="total_mappings" type="integer">
          Number of mappings in this domain
        </ResponseField>

        <ResponseField name="average_confidence" type="number">
          Average confidence score for domain
        </ResponseField>

        <ResponseField name="quality_distribution" type="object">
          Distribution of quality levels

          <Expandable title="Quality Distribution Object">
            <ResponseField name="excellent" type="integer">
              Mappings with confidence score of 0.9 or higher
            </ResponseField>

            <ResponseField name="good" type="integer">
              Mappings with confidence score between 0.7 and 0.9
            </ResponseField>

            <ResponseField name="moderate" type="integer">
              Mappings with confidence score between 0.5 and 0.7
            </ResponseField>

            <ResponseField name="poor" type="integer">
              Mappings with confidence score below 0.5
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="most_reliable_vocabulary_pairs" type="array">
          Vocabulary pairs with highest quality in this domain
        </ResponseField>

        <ResponseField name="least_reliable_vocabulary_pairs" type="array">
          Vocabulary pairs with lowest quality in this domain
        </ResponseField>

        <ResponseField name="quality_challenges" type="array">
          Common quality issues in this domain
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="quality_metrics" type="object">
  Detailed quality metrics and distributions

  <Expandable title="Quality Metrics Object">
    <ResponseField name="confidence_score_distribution" type="object">
      Distribution of confidence scores

      <Expandable title="Confidence Distribution Object">
        <ResponseField name="histogram_bins" type="array">
          Confidence score ranges and counts
        </ResponseField>

        <ResponseField name="percentiles" type="object">
          Key percentile values
        </ResponseField>

        <ResponseField name="skewness" type="number">
          Skewness of confidence distribution
        </ResponseField>

        <ResponseField name="kurtosis" type="number">
          Kurtosis of confidence distribution
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="semantic_similarity_analysis" type="object">
      Analysis of semantic similarity scores

      <Expandable title="Semantic Similarity Analysis Object">
        <ResponseField name="average_similarity" type="number">
          Average semantic similarity score
        </ResponseField>

        <ResponseField name="similarity_confidence_correlation" type="number">
          Correlation between similarity and confidence
        </ResponseField>

        <ResponseField name="low_similarity_high_confidence" type="integer">
          Mappings with low similarity but high confidence
        </ResponseField>

        <ResponseField name="high_similarity_low_confidence" type="integer">
          Mappings with high similarity but low confidence
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="mapping_source_analysis" type="object">
      Quality breakdown by mapping source

      <Expandable title="Mapping Source Analysis Object">
        <ResponseField name="official_mappings" type="object">
          Quality metrics for official mappings
        </ResponseField>

        <ResponseField name="community_mappings" type="object">
          Quality metrics for community mappings
        </ResponseField>

        <ResponseField name="algorithmic_mappings" type="object">
          Quality metrics for algorithmic mappings
        </ResponseField>

        <ResponseField name="manual_mappings" type="object">
          Quality metrics for manually created mappings
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="validation_impact_analysis" type="object">
      Impact of validation on quality perception

      <Expandable title="Validation Impact Object">
        <ResponseField name="validated_vs_unvalidated" type="object">
          Quality comparison between validated and unvalidated
        </ResponseField>

        <ResponseField name="validation_accuracy" type="number">
          Accuracy of validation process
        </ResponseField>

        <ResponseField name="disputed_mapping_characteristics" type="object">
          Common characteristics of disputed mappings
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="quality_outliers" type="object" optional>
  Analysis of quality outliers and anomalies (when include\_outliers=true)

  <Expandable title="Quality Outliers Object">
    <ResponseField name="low_quality_outliers" type="array">
      Mappings with unusually low quality scores

      <Expandable title="Quality Outlier Object">
        <ResponseField name="source_concept_id" type="integer">
          Source concept identifier
        </ResponseField>

        <ResponseField name="target_concept_id" type="integer">
          Target concept identifier
        </ResponseField>

        <ResponseField name="confidence_score" type="number">
          Confidence score
        </ResponseField>

        <ResponseField name="outlier_reason" type="string">
          Why this is considered an outlier
        </ResponseField>

        <ResponseField name="potential_issues" type="array">
          Potential quality issues identified
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="high_quality_outliers" type="array">
      Mappings with exceptionally high quality
    </ResponseField>

    <ResponseField name="inconsistent_mappings" type="array">
      Mappings with inconsistent quality indicators
    </ResponseField>

    <ResponseField name="outlier_patterns" type="array">
      Common patterns in outlier mappings
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="quality_trends" type="object" optional>
  Historical quality trends (when include\_trends=true)

  <Expandable title="Quality Trends Object">
    <ResponseField name="quality_over_time" type="array">
      Time series of quality improvements

      <Expandable title="Quality Time Point Object">
        <ResponseField name="date" type="string">
          Date of measurement
        </ResponseField>

        <ResponseField name="average_confidence" type="number">
          Average confidence at this time
        </ResponseField>

        <ResponseField name="validation_rate" type="number">
          Validation rate at this time
        </ResponseField>

        <ResponseField name="new_mappings_quality" type="number">
          Quality of newly added mappings
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="quality_improvement_rate" type="number">
      Annual rate of quality improvement (0.0-1.0 fraction)
    </ResponseField>

    <ResponseField name="fastest_improving_areas" type="array">
      Areas with most rapid quality improvement
    </ResponseField>

    <ResponseField name="declining_quality_areas" type="array">
      Areas with declining quality
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="recommendations" type="array" optional>
  Recommendations for quality improvement (when include\_recommendations=true)

  <Expandable title="Quality Recommendation Object">
    <ResponseField name="recommendation_type" type="string">
      Type of quality improvement recommendation
    </ResponseField>

    <ResponseField name="title" type="string">
      Brief title of the recommendation
    </ResponseField>

    <ResponseField name="description" type="string">
      Detailed description
    </ResponseField>

    <ResponseField name="priority" type="string">
      Implementation priority
    </ResponseField>

    <ResponseField name="expected_improvement" type="string">
      Expected quality improvement
    </ResponseField>

    <ResponseField name="affected_vocabulary_pairs" type="array">
      Vocabulary pairs that would benefit
    </ResponseField>

    <ResponseField name="implementation_effort" type="string">
      Estimated implementation effort
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Analysis metadata and processing information

  <Expandable title="Metadata Object">
    <ResponseField name="analysis_date" type="string">
      Date when quality analysis was performed
    </ResponseField>

    <ResponseField name="data_freshness" type="string">
      Timestamp of underlying mapping data
    </ResponseField>

    <ResponseField name="analysis_scope" type="object">
      Scope of the quality analysis
    </ResponseField>

    <ResponseField name="calculation_time_ms" type="number">
      Time taken to perform analysis
    </ResponseField>

    <ResponseField name="confidence_calculation_method" type="string">
      Method used to calculate confidence scores
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.omophub.com/v1/mappings/quality/SNOMED/ICD10CM" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (with vocab_release) theme={null}
  curl -X GET "https://api.omophub.com/v1/mappings/quality/SNOMED/ICD10CM?vocab_release=2025.1" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.omophub.com/v1/mappings/quality/SNOMED/ICD10CM', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const qualityData = await response.json();
  const { quality_overview } = qualityData.data;

  console.log('=== Mapping Quality Analysis ===');
  console.log(`Total mappings analyzed: ${quality_overview.total_mappings_analyzed.toLocaleString()}`);
  console.log(`Overall quality rating: ${quality_overview.overall_quality_rating}`);
  console.log(`Average confidence: ${(quality_overview.overall_average_confidence * 100).toFixed(1)}%`);
  console.log(`High-quality mappings: ${quality_overview.high_quality_percentage.toFixed(1)}%`);
  console.log(`Validated mappings: ${quality_overview.validated_percentage.toFixed(1)}%`);

  // Display domain quality
  console.log('\n=== Quality by Domain ===');
  Object.entries(quality_by_domain).forEach(([domainId, domainData]) => {
    console.log(`${domainData.domain_name}:`);
    console.log(`  Average confidence: ${(domainData.average_confidence * 100).toFixed(1)}%`);
    console.log(`  Total mappings: ${domainData.total_mappings.toLocaleString()}`);
    
    const dist = domainData.quality_distribution;
    console.log(`  Quality distribution:`);
    console.log(`    Excellent: ${dist.excellent.toLocaleString()}`);
    console.log(`    Good: ${dist.good.toLocaleString()}`);
    console.log(`    Moderate: ${dist.moderate.toLocaleString()}`);
    console.log(`    Poor: ${dist.poor.toLocaleString()}`);
    
    if (domainData.most_reliable_vocabulary_pairs.length > 0) {
      console.log(`  Most reliable pairs: ${domainData.most_reliable_vocabulary_pairs.slice(0, 3).join(', ')}`);
    }
    
    if (domainData.quality_challenges.length > 0) {
      console.log(`  Quality challenges: ${domainData.quality_challenges.slice(0, 2).join(', ')}`);
    }
  });

  // Display vocabulary pair quality
  console.log('\n=== Top Quality Vocabulary Pairs ===');
  const vocabPairs = [];
  Object.entries(qualityData.data.quality_by_vocabulary_pair).forEach(([sourceVocab, sourceData]) => {
    Object.entries(sourceData.target_vocabularies).forEach(([targetVocab, pairData]) => {
      vocabPairs.push({
        pair: `${sourceVocab} → ${targetVocab}`,
        confidence: pairData.average_confidence,
        mappings: pairData.total_mappings,
        rating: pairData.quality_rating
      });
    });
  });

  vocabPairs.sort((a, b) => b.confidence - a.confidence)
    .slice(0, 10)
    .forEach(pair => {
      console.log(`${pair.pair}: ${(pair.confidence * 100).toFixed(1)}% avg confidence (${pair.mappings.toLocaleString()} mappings, ${pair.rating})`);
    });

  // Display quality metrics
  if (quality_metrics) {
    console.log('\n=== Quality Metrics ===');
    
    if (quality_metrics.confidence_score_distribution) {
      const confDist = quality_metrics.confidence_score_distribution;
      console.log('Confidence Score Statistics:');
      console.log(`  Mean: ${(qualityData.data.quality_overview.overall_average_confidence * 100).toFixed(1)}%`);
      if (confDist.percentiles) {
        console.log(`  25th percentile: ${(confDist.percentiles['25'] * 100).toFixed(1)}%`);
        console.log(`  50th percentile: ${(confDist.percentiles['50'] * 100).toFixed(1)}%`);
        console.log(`  75th percentile: ${(confDist.percentiles['75'] * 100).toFixed(1)}%`);
      }
    }
    
    if (quality_metrics.mapping_source_analysis) {
      console.log('\nQuality by Mapping Source:');
      Object.entries(quality_metrics.mapping_source_analysis).forEach(([source, data]) => {
        if (data.average_confidence) {
          console.log(`  ${source}: ${(data.average_confidence * 100).toFixed(1)}% avg confidence`);
        }
      });
    }
  }

  // Display recommendations
  if (qualityData.data.recommendations) {
    console.log('\n=== Quality Improvement Recommendations ===');
    qualityData.data.recommendations.slice(0, 5).forEach((rec, i) => {
      console.log(`${i + 1}. ${rec.title} (${rec.priority} priority)`);
      console.log(`   ${rec.description}`);
      console.log(`   Expected improvement: ${rec.expected_improvement}`);
      if (rec.affected_vocabulary_pairs.length > 0) {
        console.log(`   Affects: ${rec.affected_vocabulary_pairs.slice(0, 3).join(', ')}`);
      }
    });
  }
  ```

  ```python Python theme={null}
  import requests

  source_vocab = "SNOMED"
  target_vocab = "ICD10CM"
  url = f"https://api.omophub.com/v1/mappings/quality/{source_vocab}/{target_vocab}"

  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  data = response.json()

  print("=== MAPPING QUALITY ANALYSIS ===")
  overview = data['data']['quality_overview']
  print(f"Total mappings analyzed: {overview['total_mappings_analyzed']:,}")
  print(f"Overall quality rating: {overview['overall_quality_rating']}")
  print(f"Average confidence: {overview['overall_average_confidence']:.3f}")
  print(f"High-quality mappings: {overview['high_quality_percentage']:.1f}%")
  print(f"Validated mappings: {overview['validated_percentage']:.1f}%")
  print(f"Disputed mappings: {overview['disputed_percentage']:.1f}%")

  # Domain quality analysis
  print(f"\n=== QUALITY BY DOMAIN ===")
  domain_quality = data['data']['quality_by_domain']
  domain_df = pd.DataFrame([
      {
          'domain': info['domain_name'],
          'total_mappings': info['total_mappings'],
          'avg_confidence': info['average_confidence'],
          'excellent': info['quality_distribution']['excellent'],
          'good': info['quality_distribution']['good'],
          'moderate': info['quality_distribution']['moderate'],
          'poor': info['quality_distribution']['poor']
      }
      for domain_id, info in domain_quality.items()
  ])

  domain_df = domain_df.sort_values('avg_confidence', ascending=False)
  print(domain_df.to_string(index=False, float_format='%.3f'))

  # Vocabulary pair quality analysis
  print(f"\n=== VOCABULARY PAIR QUALITY ===")
  vocab_pairs = []
  for source_vocab, source_data in data['data']['quality_by_vocabulary_pair'].items():
      for target_vocab, pair_data in source_data['target_vocabularies'].items():
          vocab_pairs.append({
              'source': source_vocab,
              'target': target_vocab,
              'pair': f"{source_vocab} → {target_vocab}",
              'avg_confidence': pair_data['average_confidence'],
              'total_mappings': pair_data['total_mappings'],
              'validation_rate': pair_data['validation_rate'],
              'quality_rating': pair_data['quality_rating']
          })

  vocab_pair_df = pd.DataFrame(vocab_pairs)
  vocab_pair_df = vocab_pair_df.sort_values('avg_confidence', ascending=False)

  print("Top 10 Quality Vocabulary Pairs:")
  top_pairs = vocab_pair_df.head(10)
  for _, row in top_pairs.iterrows():
      print(f"{row['pair']}: {row['avg_confidence']:.3f} confidence, {row['total_mappings']:,} mappings ({row['quality_rating']})")

  print("\nBottom 5 Quality Vocabulary Pairs:")
  bottom_pairs = vocab_pair_df.tail(5)
  for _, row in bottom_pairs.iterrows():
      print(f"{row['pair']}: {row['avg_confidence']:.3f} confidence, {row['total_mappings']:,} mappings ({row['quality_rating']})")

  # Quality metrics analysis
  if 'quality_metrics' in data['data']:
      metrics = data['data']['quality_metrics']
      print(f"\n=== DETAILED QUALITY METRICS ===")
      
      # Confidence distribution
      if 'confidence_score_distribution' in metrics:
          conf_dist = metrics['confidence_score_distribution']
          print(f"Confidence Score Statistics:")
          if 'percentiles' in conf_dist:
              for percentile, value in conf_dist['percentiles'].items():
                  print(f"  {percentile}th percentile: {value:.3f}")
          
          if 'skewness' in conf_dist:
              print(f"  Skewness: {conf_dist['skewness']:.3f}")
          if 'kurtosis' in conf_dist:
              print(f"  Kurtosis: {conf_dist['kurtosis']:.3f}")
      
      # Semantic similarity analysis
      if 'semantic_similarity_analysis' in metrics:
          sem_analysis = metrics['semantic_similarity_analysis']
          print(f"\nSemantic Similarity Analysis:")
          print(f"  Average similarity: {sem_analysis['average_similarity']:.3f}")
          print(f"  Similarity-confidence correlation: {sem_analysis['similarity_confidence_correlation']:.3f}")
          print(f"  Low similarity, high confidence: {sem_analysis['low_similarity_high_confidence']:,}")
          print(f"  High similarity, low confidence: {sem_analysis['high_similarity_low_confidence']:,}")
      
      # Mapping source analysis
      if 'mapping_source_analysis' in metrics:
          source_analysis = metrics['mapping_source_analysis']
          print(f"\nQuality by Mapping Source:")
          for source, source_data in source_analysis.items():
              if 'average_confidence' in source_data:
                  print(f"  {source}: {source_data['average_confidence']:.3f} avg confidence")

  # Outlier analysis
  if 'quality_outliers' in data['data']:
      outliers = data['data']['quality_outliers']
      print(f"\n=== QUALITY OUTLIERS ===")
      
      if outliers.get('low_quality_outliers'):
          print(f"Low Quality Outliers ({len(outliers['low_quality_outliers'])}):")
          for outlier in outliers['low_quality_outliers'][:5]:
              print(f"  Concepts {outlier['source_concept_id']} → {outlier['target_concept_id']}")
              print(f"    Confidence: {outlier['confidence_score']:.3f}")
              print(f"    Reason: {outlier['outlier_reason']}")
      
      if outliers.get('outlier_patterns'):
          print(f"\nCommon Outlier Patterns:")
          for pattern in outliers['outlier_patterns'][:3]:
              print(f"  - {pattern}")

  # Trends analysis
  if 'quality_trends' in data['data']:
      trends = data['data']['quality_trends']
      print(f"\n=== QUALITY TRENDS ===")
      print(f"Quality improvement rate: {trends['quality_improvement_rate']:.2f}% annually")
      
      if trends.get('fastest_improving_areas'):
          print(f"Fastest improving areas:")
          for area in trends['fastest_improving_areas'][:3]:
              print(f"  - {area}")
      
      # Plot quality trend
      if trends.get('quality_over_time'):
          quality_history = trends['quality_over_time']
          dates = [point['date'] for point in quality_history]
          confidences = [point['average_confidence'] for point in quality_history]
          validation_rates = [point['validation_rate'] for point in quality_history]
          
          fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(12, 10))
          
          # Confidence trend
          ax1.plot(dates, confidences, marker='o', linewidth=2)
          ax1.set_title('Average Confidence Score Over Time')
          ax1.set_ylabel('Confidence Score')
          ax1.tick_params(axis='x', rotation=45)
          ax1.grid(True, alpha=0.3)
          
          # Validation rate trend
          ax2.plot(dates, validation_rates, marker='s', linewidth=2, color='green')
          ax2.set_title('Validation Rate Over Time')
          ax2.set_xlabel('Date')
          ax2.set_ylabel('Validation Rate')
          ax2.tick_params(axis='x', rotation=45)
          ax2.grid(True, alpha=0.3)
          
          plt.tight_layout()
          plt.show()

  # Recommendations
  if 'recommendations' in data['data']:
      print(f"\n=== QUALITY IMPROVEMENT RECOMMENDATIONS ===")
      recommendations = data['data']['recommendations']
      for i, rec in enumerate(recommendations[:7], 1):
          print(f"{i}. {rec['title']} ({rec['priority']} Priority)")
          print(f"   {rec['description']}")
          print(f"   Expected improvement: {rec['expected_improvement']}")
          print(f"   Implementation effort: {rec['implementation_effort']}")
          if rec.get('affected_vocabulary_pairs'):
              print(f"   Affects: {', '.join(rec['affected_vocabulary_pairs'][:3])}")
          print()

  # Create comprehensive quality dashboard
  fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(16, 12))

  # 1. Domain quality comparison
  domain_names = domain_df['domain']
  domain_confidences = domain_df['avg_confidence']
  ax1.barh(domain_names, domain_confidences, color='skyblue')
  ax1.set_xlabel('Average Confidence Score')
  ax1.set_title('Quality by Medical Domain')
  ax1.set_xlim(0, 1)

  # 2. Quality distribution pie chart
  quality_counts = [
      domain_df['excellent'].sum(),
      domain_df['good'].sum(),
      domain_df['moderate'].sum(),
      domain_df['poor'].sum()
  ]
  quality_labels = ['Excellent', 'Good', 'Moderate', 'Poor']
  colors = ['#2ecc71', '#3498db', '#f39c12', '#e74c3c']
  ax2.pie(quality_counts, labels=quality_labels, colors=colors, autopct='%1.1f%%')
  ax2.set_title('Overall Quality Distribution')

  # 3. Vocabulary pair quality heatmap
  if len(vocab_pair_df) > 0:
      # Create pivot table for heatmap
      pivot_data = vocab_pair_df.pivot_table(
          values='avg_confidence', 
          index='source', 
          columns='target',
          fill_value=0
      )
      
      sns.heatmap(pivot_data, annot=True, fmt='.2f', cmap='RdYlGn', ax=ax3)
      ax3.set_title('Vocabulary Pair Quality Matrix')
      ax3.set_xlabel('Target Vocabulary')
      ax3.set_ylabel('Source Vocabulary')

  # 4. Confidence score histogram
  if 'quality_metrics' in data['data'] and 'confidence_score_distribution' in data['data']['quality_metrics']:
      conf_dist = data['data']['quality_metrics']['confidence_score_distribution']
      if 'histogram_bins' in conf_dist:
          bins = conf_dist['histogram_bins']
          bin_centers = [(bin['min'] + bin['max']) / 2 for bin in bins]
          bin_counts = [bin['count'] for bin in bins]
          
          ax4.bar(bin_centers, bin_counts, width=0.05, alpha=0.7, color='lightcoral')
          ax4.set_xlabel('Confidence Score')
          ax4.set_ylabel('Number of Mappings')
          ax4.set_title('Confidence Score Distribution')
          ax4.set_xlim(0, 1)

  plt.tight_layout()
  plt.show()

  # Summary report
  print(f"\n=== SUMMARY REPORT ===")
  print(f"• Analyzed {overview['total_mappings_analyzed']:,} mappings across {len(domain_quality)} domains")
  print(f"• Overall system quality rating: {overview['overall_quality_rating'].upper()}")
  print(f"• {overview['high_quality_percentage']:.1f}% of mappings are high-quality (confidence > 0.8)")
  print(f"• {overview['validated_percentage']:.1f}% of mappings are officially validated")
  print(f"• Top quality domain: {domain_df.iloc[0]['domain']} ({domain_df.iloc[0]['avg_confidence']:.3f} avg confidence)")
  print(f"• Best vocabulary pair: {vocab_pair_df.iloc[0]['pair']} ({vocab_pair_df.iloc[0]['avg_confidence']:.3f} confidence)")

  if 'recommendations' in data['data']:
      high_priority_recs = [r for r in data['data']['recommendations'] if r['priority'] == 'high']
      print(f"• {len(high_priority_recs)} high-priority improvement recommendations identified")
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "quality_overview": {
      "total_mappings_analyzed": 4578923,
      "mappings_with_quality_data": 3456789,
      "overall_average_confidence": 0.847,
      "overall_quality_rating": "good",
      "high_quality_percentage": 72.3,
      "validated_percentage": 68.9,
      "disputed_percentage": 2.7
    },
    "quality_by_vocabulary_pair": {
      "SNOMED": {
        "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
        "target_vocabularies": {
          "ICD10CM": {
            "target_vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
            "total_mappings": 156789,
            "average_confidence": 0.923,
            "median_confidence": 0.950,
            "confidence_std_dev": 0.087,
            "equivalence_distribution": {
              "exact": 89234,
              "broader": 45678,
              "narrower": 12345,
              "related": 9532
            },
            "validation_rate": 0.847,
            "quality_rating": "excellent",
            "primary_use_cases": ["billing", "quality_reporting", "clinical_documentation"]
          },
          "HCPCS": {
            "target_vocabulary_name": "Healthcare Common Procedure Coding System",
            "total_mappings": 67890,
            "average_confidence": 0.756,
            "median_confidence": 0.780,
            "confidence_std_dev": 0.145,
            "equivalence_distribution": {
              "exact": 23456,
              "broader": 34567,
              "narrower": 6789,
              "related": 3078
            },
            "validation_rate": 0.623,
            "quality_rating": "good",
            "primary_use_cases": ["billing", "procedure_coding"]
          }
        },
        "overall_outgoing_quality": 0.875
      }
    },
    "quality_by_domain": {
      "Condition": {
        "domain_name": "Condition",
        "total_mappings": 2847562,
        "average_confidence": 0.891,
        "quality_distribution": {
          "excellent": 1456789,
          "good": 987654,
          "moderate": 345678,
          "poor": 57441
        },
        "most_reliable_vocabulary_pairs": [
          "SNOMED → ICD10CM",
          "ICD10CM → SNOMED", 
          "SNOMED → ICD10"
        ],
        "least_reliable_vocabulary_pairs": [
          "Read → ICPC2",
          "Local → Standard"
        ],
        "quality_challenges": [
          "Complex conditions often map to broader categories",
          "Regional terminology variations affect consistency",
          "Rare diseases have limited mapping coverage"
        ]
      },
      "Drug": {
        "domain_name": "Drug",
        "total_mappings": 987654,
        "average_confidence": 0.823,
        "quality_distribution": {
          "excellent": 456789,
          "good": 345678,
          "moderate": 123456,
          "poor": 61731
        },
        "most_reliable_vocabulary_pairs": [
          "RxNorm → NDC",
          "NDC → RxNorm"
        ],
        "least_reliable_vocabulary_pairs": [
          "SNOMED → RxNorm",
          "Local drug codes → RxNorm"
        ],
        "quality_challenges": [
          "Generic vs brand name mapping complexity",
          "Dosage form variations affect precision",
          "Discontinued medications create gaps"
        ]
      }
    },
    "quality_metrics": {
      "confidence_score_distribution": {
        "histogram_bins": [
          {"min": 0.0, "max": 0.1, "count": 12456},
          {"min": 0.1, "max": 0.2, "count": 23456},
          {"min": 0.8, "max": 0.9, "count": 456789},
          {"min": 0.9, "max": 1.0, "count": 678901}
        ],
        "percentiles": {
          "25": 0.734,
          "50": 0.847,
          "75": 0.923,
          "95": 0.978
        },
        "skewness": -0.342,
        "kurtosis": 2.156
      },
      "semantic_similarity_analysis": {
        "average_similarity": 0.823,
        "similarity_confidence_correlation": 0.756,
        "low_similarity_high_confidence": 23456,
        "high_similarity_low_confidence": 12345
      },
      "mapping_source_analysis": {
        "official_mappings": {
          "average_confidence": 0.912,
          "total_count": 2345678,
          "validation_rate": 0.923
        },
        "community_mappings": {
          "average_confidence": 0.734,
          "total_count": 456789,
          "validation_rate": 0.456
        },
        "algorithmic_mappings": {
          "average_confidence": 0.678,
          "total_count": 567890,
          "validation_rate": 0.234
        }
      }
    },
    "quality_outliers": {
      "low_quality_outliers": [
        {
          "source_concept_id": 12345,
          "target_concept_id": 67890,
          "confidence_score": 0.123,
          "outlier_reason": "Very low confidence despite official mapping",
          "potential_issues": [
            "Semantic mismatch",
            "Outdated mapping relationship"
          ]
        }
      ],
      "outlier_patterns": [
        "Algorithmic mappings between distant concept classes",
        "Legacy mappings not updated with vocabulary revisions",
        "Cross-domain mappings with semantic drift"
      ]
    },
    "recommendations": [
      {
        "recommendation_type": "validation_review",
        "title": "Review disputed SNOMED to HCPCS mappings",
        "description": "Systematic review of 2,847 disputed mappings between SNOMED procedures and HCPCS codes to improve validation rate",
        "priority": "high",
        "expected_improvement": "Increase HCPCS mapping quality by 15-20%",
        "affected_vocabulary_pairs": ["SNOMED → HCPCS"],
        "implementation_effort": "moderate"
      },
      {
        "recommendation_type": "algorithmic_improvement", 
        "title": "Enhance semantic similarity algorithms for drug mappings",
        "description": "Improve algorithmic mapping quality between drug vocabularies using enhanced semantic similarity models",
        "priority": "medium",
        "expected_improvement": "Increase drug domain confidence by 10%",
        "affected_vocabulary_pairs": ["RxNorm → NDC", "SNOMED → RxNorm"],
        "implementation_effort": "high"
      }
    ]
    },
    "meta": {
      "request_id": "req_quality_analysis_234567",
      "timestamp": "2024-12-22T10:00:00Z",
      "vocab_release": "2025.2",
      "analysis_scope": {
        "vocabularies_included": 23,
        "domains_analyzed": 15,
        "mapping_relationships_analyzed": 4578923
      },
      "confidence_calculation_method": "weighted_semantic_similarity_with_validation"
    }
  }
  ```
</ResponseExample>

## Usage Examples

### SNOMED to ICD10CM Quality

Analyze mapping quality between SNOMED and ICD10CM:

```javascript theme={null}
const quality = await fetch('/v1/mappings/quality/SNOMED/ICD10CM');
```

### RxNorm to NDC Quality

Analyze drug vocabulary mapping quality:

```javascript theme={null}
const drugQuality = await fetch('/v1/mappings/quality/RxNorm/NDC');
```

### With Specific Vocabulary Release

Query quality metrics for a specific vocabulary version:

```javascript theme={null}
const versionedQuality = await fetch('/v1/mappings/quality/SNOMED/HCPCS?vocab_release=2025.1');
```

## Related Endpoints

* [Get Concept Mappings](/api-reference/mappings/get-concept-mappings) - Individual concept mapping quality
* [Get Vocabulary Mappings](/api-reference/mappings/get-vocabulary-mappings) - Quality within vocabulary pairs
* [Get Mapping Coverage](/api-reference/mappings/get-mapping-coverage) - Coverage vs quality analysis

## Notes

* Quality analysis requires substantial computational resources for large datasets
* Confidence scores are calculated using multiple factors including semantic similarity and validation status
* Official mappings generally have higher quality than algorithmic or community mappings
* Quality can vary significantly between vocabulary pairs and domains
* Disputed mappings may indicate areas needing expert review
* Quality trends help identify improvement or degradation over time
* Outlier analysis reveals mappings that may need special attention
* Quality thresholds help focus on the most reliable mappings for production use
