Blood Test Data Search

The pat2vec library provides comprehensive functionality for searching and retrieving blood test data from clinical records. This section explains how to use the blood test search methods to extract laboratory results for your patient cohorts.

Overview

The blood test search functionality allows you to:

Retrieve laboratory results for specific patients or patient cohorts
Filter results by date ranges
Extract standardized blood test measurements
Access both numeric values and metadata

Data Fields

When searching for blood test data, the following fields are retrieved:

Field	Description
`client_idcode`	Unique patient identifier
`basicobs_itemname_analysed`	Name/type of the blood test (e.g., “Hemoglobin”, “Creatinine”)
`basicobs_value_numeric`	Numeric result value
`basicobs_entered`	Date and time when the result was recorded
`clientvisit_serviceguid`	Unique identifier for the clinical visit
`updatetime`	Timestamp when the record was last updated

Basic Usage

1. Initialize Pat2vec

First, set up your pat2vec configuration and initialize the main object:

import pat2vec
from pat2vec.util.config_pat2vec import config_class
from pat2vec.main_pat2vec import main

# Configure pat2vec
config_obj = config_class(
    testing=False,  # Set to False for production use
    verbosity=9,
    proj_name='blood_analysis_project'
)

# Initialize pat2vec object
pat2vec_obj = main(config_obj=config_obj, cogstack=True)

2. Search Blood Test Data

# Define patient IDs
patient_ids = ['PATIENT001', 'PATIENT002', 'PATIENT003']

# Search for blood test data
df_bloods = pat2vec.pat2vec_get_methods.get_method_bloods.search_bloods_data(
    cohort_searcher_with_terms_and_search=pat2vec_obj.cohort_searcher_with_terms_and_search,
    client_id_codes=patient_ids
)

# View the results
print(df_bloods.head())

Advanced Parameters

Date Range Filtering

You can specify custom date ranges to focus on specific time periods:

df_bloods = pat2vec.pat2vec_get_methods.get_method_bloods.search_bloods_data(
    cohort_searcher_with_terms_and_search=pat2vec_obj.cohort_searcher_with_terms_and_search,
    client_id_codes=patient_ids,
    start_year=2020,
    start_month=1,
    start_day=1,
    end_year=2023,
    end_month=12,
    end_day=31
)

Alternative Field Mapping

If your data uses different field names, you can specify them:

df_bloods = pat2vec.pat2vec_get_methods.get_method_bloods.search_bloods_data(
    cohort_searcher_with_terms_and_search=pat2vec_obj.cohort_searcher_with_terms_and_search,
    client_id_codes=patient_ids,
    client_idcode_name="patient_id.keyword",  # Different patient ID field
    bloods_time_field="test_date"             # Different timestamp field
)

Function Parameters Reference

Parameter	Type	Default	Description
`cohort_searcher_with_terms_and_search`	callable	None	Required. The pat2vec search function
`client_id_codes`	str or list	None	Required. Patient ID(s) to search for
`client_idcode_name`	str	“client_idcode.keyword”	Field name for patient IDs
`bloods_time_field`	str	“basicobs_entered”	Field name for timestamps
`start_year`	int	1995	Start year for date range
`start_month`	int	1	Start month for date range
`start_day`	int	1	Start day for date range
`end_year`	int	2025	End year for date range
`end_month`	int	12	End month for date range
`end_day`	int	12	End day for date range
`additional_custom_search_string`	str	None	Additional Elasticsearch query string

Working with Results

Basic Data Exploration

# Check the shape of results
print(f"Retrieved {len(df_bloods)} blood test records")

# View unique test types
print("Available blood tests:")
print(df_bloods['basicobs_itemname_analysed'].unique())

# Check date range of results
print(f"Date range: {df_bloods['basicobs_entered'].min()} to {df_bloods['basicobs_entered'].max()}")

Data Processing Examples

# Convert date strings to datetime
df_bloods['basicobs_entered'] = pd.to_datetime(df_bloods['basicobs_entered'])

# Filter for specific test types
hemoglobin_results = df_bloods[
    df_bloods['basicobs_itemname_analysed'].str.contains('Hemoglobin', na=False)
]

# Group by patient and test type
patient_summary = df_bloods.groupby(['client_idcode', 'basicobs_itemname_analysed']).agg({
    'basicobs_value_numeric': ['count', 'mean', 'std'],
    'basicobs_entered': ['min', 'max']
}).round(2)

Error Handling

The function includes built-in validation and will raise helpful error messages:

try:
    df_bloods = pat2vec.pat2vec_get_methods.get_method_bloods.search_bloods_data(
        cohort_searcher_with_terms_and_search=pat2vec_obj.cohort_searcher_with_terms_and_search,
        client_id_codes=patient_ids
    )
except ValueError as e:
    print(f"Search error: {e}")

Integration with Other Pat2vec Methods

Blood test data can be combined with other clinical data types:

# Get multiple data types for the same patients
df_demographics = pat2vec.pat2vec_get_methods.get_method_demo.search_demographics(
    cohort_searcher_with_terms_and_search=pat2vec_obj.cohort_searcher_with_terms_and_search,
    client_id_codes=patient_ids
)

df_drugs = pat2vec.pat2vec_get_methods.get_method_drugs.search_drug_orders(
    cohort_searcher_with_terms_and_search=pat2vec_obj.cohort_searcher_with_terms_and_search,
    client_id_codes=patient_ids
)

# Combine datasets for comprehensive patient profiles
# (Further processing would depend on your specific analysis needs)

Best Practices

Date Range Optimization: Use appropriate date ranges to avoid retrieving unnecessary historical data
Batch Processing: For large cohorts, process patients in smaller batches to manage memory usage
Data Validation: Always check the retrieved data for completeness and expected ranges
Field Mapping: Verify that field names match your Elasticsearch index schema
Error Handling: Implement proper error handling for production use

Troubleshooting

Common Issues:

No results returned: Check patient IDs exist in the database and date ranges are appropriate
Field not found errors: Verify field names match your Elasticsearch schema
Memory issues: Reduce date ranges or process smaller patient batches
Timeout errors: Consider implementing retry logic for large queries