HealthVault Data Types

Request for interest: Explanation Of Benefits (EOB) data type creation

timsell — Wed, 04 Nov 2009 21:46:00 GMT

Would your HealthVault application benefit from being able to create or consume EOB data in a HealthVault record? If so, we'd like to hear from you. We're in the research and design phase of creating a new HealthVault data type to store EOB data and are requesting samples and scenarios describing usage of this type of data.

Please add your ideas, scenarios and comments and we'll be in touch with next steps.

Using the Cholesterol Profile data type

ericgu — Tue, 03 Nov 2009 19:22:09 GMT

This document contains general guidelines for using the Cholesterol Profile data type. It covers the members of the data type where we believe guidance is most useful, and does not cover members that are easily understood. See the CholesterolProfile class documentation for information about all members.

The cholesterol profile data type stores cholesterol or lipid profile test results. The values are stored using the concentration by weight and the unit mg/dl. These concentrations can also be expressed by molecular count, using the unit mmol/l.

There are conversions between the two units but the conversion factor depends on the substance.

For cholesterol, 100 mg/dl = 2.586 mmol/l

For triglycerides, 100 mg/dl = 1.129 mmol/l

Cholesterol Profile and Lab Test Results

The cholesterol profile information can stored either in the cholesterol profile data type or as individual tests.

Applications that store this data in HealthVault should base the destination on the source of the data. Data that is hand-entered by a user should be stored using the Cholesterol Profile type, and data that is added directly from a lab test provider should be stored as individual lab tests.

Applications that consume this data should search for it in both types, and place appropriate levels of review on it based on the source of the data.

Using the Lab Test Results Type

ericgu — Tue, 03 Nov 2009 00:41:49 GMT

This document contains general guidelines for using the Lab Test Results data type. It covers the members of the data type where we believe guidance is most useful, and does not cover members that are easily understood. See the LabTestResults class documentation for information about all members.

The lab test results data type can support many different types of lab data, and is therefore complex to understand. We will look at a few sample scenarios to illustrate how to structure data, and then go into the details of the data elements.

Storing a single test result

To store the result of an insulin test, we will create a single group named “Insulin”, and then add a single result to it. In a complex data type, it is often simplest to create most detailed data first. We’ll start by storing the result and reference range:

StructuredMeasurement value = new StructuredMeasurement();
value.Value = 17;
value.Units = new CodableValue("mcIU/ml", new CodedValue("uIU-per-ml", "lab-results-units"));
GeneralMeasurement measurement = new GeneralMeasurement();
measurement.Display = "17 mcIU/ml";
measurement.Structured.Add(value);
TestResultRange resultRange = new TestResultRange();
resultRange.RangeType = new CodableValue("Reference range");
resultRange.Value = new TestResultRangeValue();
resultRange.Value.Minimum = 3;
resultRange.Value.Maximum = 28;
resultRange.Text = new CodableValue(String.Format("{0} - {1}", resultRange.Value.Minimum, resultRange.Value.Maximum));

The numeric value is stored in a StructuredMeasurement instance, and added to the GeneralMeasurement, which also stores a textual value suitable for display to the consumer.

The result range is stored in the TestResultRange.

These are combined together:

LabTestResultValue resultValue = new LabTestResultValue();
resultValue.Ranges.Add(resultRange);
resultValue.Measurement = measurement;

into the LabTestResultValue. We will now create the LabTestResultDetails instance, which holds the information about a test and the result:

LabTestResultDetails details = new LabTestResultDetails();
details.Name = "Insulin";
details.ClinicalCode = new CodableValue("Insulin SerPl-sCnc", new CodedValue("20448-7", "loinc", "regenstrief", "2.22"));
details.Substance = new CodableValue("SER/PLAS");
details.When = new ApproximateDateTime(new DateTime(2009, 10, 10, 3, 23, 24));
details.Value = resultValue;
details.Note = "Insulin levels must be evaluated in context.";

The Name element holds a consumer-friendly name, and the clinical code holds the clinical name and code for the test.

We will now add this test to a test group:

LabTestResultGroup group = new LabTestResultGroup(new CodableValue("Insulin"));
group.LaboratoryName = new Organization("Lab");
group.Status = new CodableValue("C");
group.Results.Add(details);

The group stores a set of tests that are done together. In this case, we only have one test result to add.

Finally, we wrap this up in the top-level object, and save it out to the record.

LabTestResults labTestResult = new LabTestResults();
labTestResult.OrderedBy = new Organization("General Hospital");
labTestResult.When = new ApproximateDateTime(new DateTime(2009, 10, 10, 3, 23, 24));
labTestResult.Groups.Add(group);
PersonInfo.SelectedRecord.NewItem(labTestResult);

Storing a panel of tests

Storing a panel of tests is the same as storing individual tests, except that multiple results are added to the group, and the group name should be the panel name (“CBC”, for example).

Adding explanatory information

If there is additional explanatory information that is important when interpreting a test result, they can be placed in the Note member of the result (see the first code sample). The Note member supports pre-formatted tabular information (carriage returns and tabs are preserved in the output). This allows Note to be used for information such as the following:

                      Male            Female
Cord Blood              <17.400          <17.400
1-3 Days                <13.300          <13.300
1-4 Weeks        0.600 - 10.000   0.600 - 10.000
1 Month-5 Years  0.550 -  7.100   0.460 -  8.100
6-18 Years       0.370 -  6.000   0.360 -  5.800
Adult            0.450 -  4.500   0.450 -  4.500

The HealthVault shell will preserve this formatting when it displays the Note – other applications should do the same thing.

Non-numeric test results

Some lab tests do not return a quantitative result, but instead have a narrative or qualitative result. These results can also be placed in the Note field, and if range information is included, it can be stored in the Text member of the TestResultRange.

Using the Immunization data type

ericgu — Mon, 02 Nov 2009 19:58:37 GMT

This document contains general guidelines for using the Immunization data type. It covers the members of the data type where we believe guidance is most useful, and does not cover members that are easily understood. See the Immunization class documentation for information about all members.

The Immunization type records the information that is related to an immunization.

Name

The Name member stores information about the type of the immunization. The coded part of name should be coded directly to the HL7 CVX code set, as maintained by the CDC. This vocabulary is available from HealthVault with the name “vaccines-cvx” and the family “HL7”. The version should be stored using "2.3_<month>_<year>”, with “2.3” indicating the HL7 section and the month and year listed on the CDC web page. For example, something coded to the July 30, 2009 code set would use “2.3_7_2009” as the version.

The HealthVault team will keep the vocabularies as up to date as possible, but applications should always code to the most recent release from the CDC if possible.

The display text of the name member is intended to be displayed to consumers. A coding application should consider using a more consumer-friendly name if the full vaccine name as defined in the code set might cause consumer confusion.

Manufacturer

The coded part of manufacturer should be coded directly to the HL7 MVX code set, as maintained by the CDC. The associated HealthVault vocabulary has name “vaccine-manufacturers-mvx” and family “HL7”. The version follows the same rules as the CVX code set, but note that CVX and MVX are updated on separate schedules, so the version between them is typically different.

For Review: Medical Image Study

timsell — Thu, 09 Jul 2009 21:43:00 GMT

We've had several requests for a new data type to store medical images and we are now at a point in our research and design that we'd like to hear from our larger HealthVault community. We've found that DICOM is the generally accepted format for storing medical images today so we've designed this data type to include structural and metadata similaities while limited the exposed data to what we believe is the most consumer friendly.

If you use DICOM today, those same images can be added to HealthVault in their native format using this data type. All the metadata stored in a DICOM file remains intact for all systems to reuse with this approach. By adding a level of structured XML that exposes some of this data, it allows for new and existing HealthVault applications to use the data without needing to fully parse the DICOM file or files.

There are a few scenarios we've targeted in the design of this data type:

Systems generating medical images can now store those images in a patient's HealthVault record instead of creating a DVD, CD or other portable media. Today, when a patient requests a copy of their medical images from a CT, MRI, mamogram, etc, those images are burned to portable media which gets added to the shoebox of all the other studies the patient has requested. The intent of this data type is to help replace that shoebox full of discs.
The shoebox full of discs serves a purpose of being an electronic history of various studies that can be taken for a second opinion or further analysis. For systems that understand medical images, they should also be able to understand medical images stored in HealthVault.
The consumer should be able to accurately transfer their existing medical images to their HealthVault record. This new data type should be capable of storing all existing medical images that can be uploaded by a consumer.

We fully expect consuming applications to crack open the actual image files to get all the details of the study, series, but we hope that the defined schema will help make the decision on what to open a bit easier.

The image data stored using this data type will be large in both quantity and size and our current XML storage approach doesn't optimize for binary content like images. To help mitigate this, HealthVault provides seperate binary storage we call blob storage (blobs). Each instance of data in HealthVault can also include a blob of additional data and with the introduction of this data type, the HealthVault platform will support multiple named blobs per data instance. You'll find in this data type that we use blobs in a few places. Specifically, blobs are used to store the set of medical images, a directory listing all blob names for the original images, a collection of key images, and a preview image for a study, series, and images.

We have a few specific questions that we'd like your help in answering:

The first is around the use of c-FIND. In our research, we found that there are additional required elements for c-FIND that are perhaps less meaningful for consumers. If you use c-FIND today and/or have scenarios where it applies to HealthVault data, please let us know. We expect consuming applications to crack open the actual image files to get all the details of the study, series, but we hope that the defined schema will help make the decision on what to open a bit easier.
The second question is around XDS-i support. We would like to hear from you if you currently use XDS-i and how you would plan to use this element in your HealthVault connected scenarios.
The last is whether the list of elements we have defined is the right set. We've picked the ones we think are meaningful for consumers and that represent the data being stored.

Take a look and let us know what you think by using the Data Types forum.

Medical Image Study type

A collection of medical images. DICOM data is stored in the named blob portion of the data type, and it is recommended that normal DICOM conventions are used for naming. An application may store XDS-i manifest information in XML format in the xds-i element.

Element	Type	Occurrence	Description
when	date-time	1	The date and time the study was created. DICOM tags (0008,0020) and (0008,0030)
patient-name	string	0..1	The name of the patient as contained in the medical image. DICOM tag (0010,0010)
description	string	0..1	A description of the study. DICOM tag (0008,1030)
series	medical-image-study-series	1..N	A collection of series.
reason	codable-value	0..1	The reason for the study. DICOM tag (0032,1030)
preview-blob-name	string	0..1	The name of the blob holding a smaller version of the image suitable for web viewing or email. For example jpeg.
key-images	medical-image-study-series-image	0..N	The important images in the study.
study-instance-uid	string	0..1	The study instance UID. DICOM tag (0020,000D)

Medical Image Study Series

The details describing a specific series of images.

Element	Type	Occurrence	Description
acquisition-datetime	date-time	1	The date and time that the image was acquired. DICOM tag: (0008,0022), (0008,0032)
description	string	0..1	A description of the series. DICOM tag (0008,103E)
images	medical-image-study-series-image	1..N	The collection of images.
institution-name	organization	0..1	The name of the institution where the images were acquired. DICOM tag (0008,0080)
referring-physician	person	0..1	The physician who ordered the study. DICOM tag (0008,0090)
modality	codable-value	0..1	The method (or modality) in which the images were acquired. DICOM tag (0008,0060)
body-part	codable-value	0..1	The body part that was imaged. DICOM tag (0018,0015)
preview-blob-name	string	0..1	The name of the blob holding a smaller version of the image suitable for web viewing or email. For example jpeg.
series-instance-uid	string	0..1	The series instance UID. DICOM tag (0020, 000E)

Medical Image Study Series Image

Information about a single image in a series.

Element	Type	Occurrence	Description
image-blob-name	string	1	The name of the blob holding the original data for this image. DICOM tag (0008, 0018)
image-preview-blob-name	string	0..1	The name of the blob holding a smaller version of the image suitable for web viewing or email. For example jpeg.

Using the Peak Flow data type

ericgu — Sat, 17 Jan 2009 03:20:00 GMT

This document contains general guidelines for using the PeakFlow data type. It does not cover all the information that is stored in the type – see the PeakFlow documentation for more information.

The PeakFlow data type is used to store peak flow measurements obtained as part of ongoing peak flow tracking.

A measurement can store values for pef, fev1, or fev6. In addition, there may be information useful to interpret the measurement (such as measurement context, notes about the measurement, etc.) in the MeasurementPlags property.

The Peak Flow data type is versioned on top of the previous Spirometry data type, which has been deprecated. Current data that was stored as Spirometry measuments may now be accessed as PeakFlow measurements.

Using the Exercise and AerobicSession types

ericgu — Sat, 17 Jan 2009 03:20:00 GMT

This document contains general guidelines for using the Exercise and AerobicSession data types. It does not cover all the information that is stored in the type – see the Exercise and AerobicSession documentation for more information.

The Exercise data type is a replacement for the AerobicSession type.

In most cases, when a HealthVault data type is updated, applications can use simply switch from using the old data type to updated one. Because of the nature of the changes between the two types, some applications may need to contain code that handles both types of data. More information about scenarios where that is necessary is contained later in the document.

The Exercise type

The Exercise type records the completion of an exercise. The simplest Exercise record contains the exercise activity and the date and time of the activity:

DateTime exerciseDateTime = DateTime.Now;

ApproximateDateTime exerciseDataTimeApprox =
        new ApproximateDateTime(
            new ApproximateDate(exerciseDateTime.Year, exerciseDateTime.Month, exerciseDateTime.Day),
            new ApproximateTime(exerciseDateTime.Hour, exerciseDateTime.Minute, exerciseDateTime.Second));

CodableValue activity = new CodableValue("Lacrosse", new CodedValue("Lacrosse", "exercise-activities));

Exercise exercise = new Exercise(exerciseDataTimeApprox, activity);

The Exercise type also supports setting the Title, Distance, and Duration of the exercise.

Adding exercise details

In addition to this very basic information, an application may store details about the exercise session in the Details collection.

Each detail describes the type of the detail and the value of the detail. The value is stored as a StructuredMeasurement, storing a value and the units of the value.

StructuredMeasurement averageHeartrate = new StructuredMeasurement();
averageHeartrate.Value = averageHeartrateInt;
averageHeartrate.Units = new CodableValue("BPM");

The type (or kind) of detail is stored as a coded value.

CodedValue averageHeartrateDetailKind = new CodedValue(ExerciseDetail.AverageHeartrate_BPM, "exercise-details");

A list of the kinds of information that can be stored in details is in the exercise-details vocabulary. To make it easier for applications to code data correctly, the ExerciseDetail class defines a set of static strings that correspond to entries in the exercise-details vocabulary. The name of the constant encodes both the detail that is being stored and the units of the detail.

The measurement and the kind are stored in the ExerciseDetail instance:

ExerciseDetail averageHeartrateDetail = new ExerciseDetail(averageHeartrateDetailKind, averageHeartrate);

Finally, that instance is inserted into the Details dictionary on the exercise instance.

exercise.Details.Add(ExerciseDetail.AverageHeartrate_BPM, averageHeartrateDetail);

Loading exercise details

Applications that are interested in a specific detail can simply look for it in the details dictionary:

if (exercise.Details.ContainsKey(ExerciseDetail.AverageHeartrate_BPM))
{
double value = exercise.Details[ExerciseDetail.AverageHeartrate_BPM].Value.Value;
}

Segments

Some exercises are composed of segments, such as the laps in a race or the legs of a triathlon. An application that wishes to store such data can store ExerciseSegment instances in the Segments collection.

The ExerciseSegment class stores the same set of values as the Exercise class, and it also stores an offset that stores the offset of the start of the segment from the start of the exercise.

ExerciseSamples data type

Some heart rate monitors and cycling computers collect samples (such as heart rate, altitude, position, etc.) at regular intervals during an exercise session. The set of samples for a given type of measurement is stored in the ExerciseSamples data type, and these are associated with an Exercise session through the related items or client items.

ExerciseSamples altitudeSamples = new ExerciseSamples();
altitudeSamples.Name = new CodableValue(ExerciseSamples.Altitude_meters, new CodedValue(ExerciseSamples.Altitude_meters, "exercise-sample-names"));
altitudeSamples.Unit = new CodableValue("Meters", new CodedValue("Meters", "exercise-units"));
altitudeSamples.SamplingInterval = samplingInterval;

This sets up the ExerciseSamples instance. The coding for the kind of information stored in a sample is similar to the coding for an exercise detail. In this case, we’re storing altitude expressed in meters.

Next, we need to store the actual samples, which is handled by the ExerciseSampleData property. Each sample may store either one or two double values, depending on the type of information that is being stored (currently, position data is the only sample kind that stores two values). The application should use either the SingleValuedSamples or TwoValuedSamples collection based on the kind of data that is stored.

This code adds a series of altitude values:

double offsetInSeconds = 0.0;
foreach (double altitude in altitudeSampleList)
{
    ExerciseSampleOneValue altitudeSample = new ExerciseSampleOneValue(offsetInSeconds, altitude);
    offsetInSeconds += samplingInterval;

    altitudeSamples.ExerciseSamplesData.SingleValuedSamples.Add(altitudeSample);
}

In this case, because altitude is a single-valued sample, we create an instance of ExerciseSampleOneValue() to store the altitude value and the offsetInSeconds from the start of the sample set, and store it in the SingleValuedSamples collection.

The ExerciseSamples data type also supports data that is collected at irregular intervals, such as positions stored when a user presses a button on a device.

It is recommended that ExerciseSample instances are related to Exercise instances using related items.

Fetching ExerciseSample data

To provide efficient storage of the sample data, it is stored in the OtherData section of the object, which is not fetched by default. This allows an application to examine a ExerciseSamples instance to see if it is interesting before incurring the overhead of fetching the data.

For example, the following code will look for and process any altitude samples that it finds…

HealthRecordSearcher searcher = PersonInfo.SelectedRecord.CreateSearcher();
HealthRecordFilter filter = new HealthRecordFilter(ExerciseSamples.TypeId);
searcher.Filters.Add(filter);

HealthRecordItemCollection samplesList = searcher.GetMatchingItems()[0];

foreach (ExerciseSamples samples in samplesList)
{
    if (samples.Name.Text == ExerciseSamples.Altitude_meters)
    {
            // query again to load the sample data
        ExerciseSamples fullSample =
                    (ExerciseSamples) PersonInfo.SelectedRecord.GetItem(samples.Key.Id,
                             HealthRecordItemSections.Core | HealthRecordItemSections.OtherData);
        ProcessAltitudeSample(fullSample);
    }
}

After the right kind of sample is found, the object is queried, this time including the sample data itself.

ExerciseSample encoding

HealthVault Connection Center may apply a compress/encode step (using gzip and base64 encode) to the comma-separated data. This can be detected by looking for a ContentEncoding that is not null.

The current version (0903 release) of the ExerciseSamples data type does not directly support this format. Applications wishing to read sample data that is generated from devices connected through Connection Center can use the following method:

    foreach (ExerciseSamples sample in samples)
    {
        ProcessCompressedAndEncodedData(sample);
        foreach (ExerciseSampleOneValue sampleItem in sample.ExerciseSamplesData.SingleValuedSamples)
        {
            int k = 12;
        }
    }

// Handle unpacking/decompressing data if it is in that format.
private void ProcessCompressedAndEncodedData(ExerciseSamples sample)
{
    if (sample.OtherData.ContentEncoding == null)
    {
        return;
    }
    // Only valid encoding here is base64, so we go with that...
    byte[] buffer = Convert.FromBase64String(sample.OtherData.Data);
    if (buffer.Length < 2)
    {
        return;
    }
    // look at the bytes to see if they are the proper gzip header...
    if ((buffer[0] != 31) ||
        (buffer[1] != 139))
    {
        return;    // nothing we can do
    }
    // gzip decompress...
    using (MemoryStream bufferStream = new MemoryStream(buffer))
    {
        using (GZipStream decompress = new GZipStream(bufferStream, CompressionMode.Decompress))
        {
            using (StreamReader reader = new StreamReader(decompress))
            {
                string result = reader.ReadToEnd();
                sample.OtherData.Data = result;
                sample.OtherData.ContentEncoding = null;
                sample.OtherData.ContentType = "text/csv";
            }
        }
    }
}

Exercise and AerobicSession

Exercise is a new version of the AerobicSession data type, and therefore the two types interoperate through versioning when queries are performed. Existing applications that query for AerobicSession instances will see Exercise instances translated into AerobicSession instances, and vice versa.

There are two important caveats to this:

The sample data is only accessible through the type that actually stored the data, so if your application needs access to sample data, it will need to deal with both types natively.
The transforms between the two types may perform well enough for your application if there is lots of data present. This would be another reason to deal with both types natively.

To deal with both types natively, the application will need to be authorized for both types. When a query is performed, a collection containing both AerobicSession and Exercise instances will be returned, and the application may then process instances of each type separately.

Calories and Energy

In the AerobicSession data type, there are two properties – Energy and EnergyFromFat – that have ambiguous definitions. The descriptions say that they store the food energy consumed, which leads some developers to store amounts measured in calories, but the remarks say that the unit is kilojoules, so other developers convert calories to kilojoules and store that number.

The Exercise class defines analogous measures using calories (using the CaloriesBurned_calories and FatCaloriesBurned_calories detail types), but this presented a problem during versioning – if we version the new details to the Energy and EnergyFromFat properties in AerobicSession, some of the data that versions forward will be incorrect.

We therefore decided to add two “shadow details” to Exercise. The EnergyOld_kj and EnergyFromFatOld_kj details version with the properties in AerobicSession, so applications that deal with exercise may want to look at these values, with the caveat that the number in it may be measured in kJ or in calories.

Upgrading Aerobic Sessions to Exercises

To improve performance and reduce application complexity when an application may have to deal with data of either type, it is permissible for applications to upgrade existing AerobicSession instances to Exercise instances.

This can be done in the following manner by an application authorized to access both types:

Perform a query to fetch all AerobicSession instances as Exercise instances. This can be accomplished by adding the Exercise type ID to the HealthRecordFilter.View.TypeVersionFormat collection.
Loop over each Exercise instance.
Fetch the instance as an AerobicSession. If the instance has sample data associated with it, create a separate ExerciseSamples instance for each sample set in the AerobicSession. Add the instance ID of the new ExerciseSamples object to the Exercise instance related items collection.
Add the instance id of the AerobicSession object to the Exercise instance related item collection.
Save the new Exercise instance.
Delete the AerobicSession instance.

Using the Pregnancy data type

ericgu — Tue, 02 Dec 2008 02:53:00 GMT

This document contains general guidelines for using the Pregnancy data type. It does not cover all the information that is stored in the type – see the Pregnancy member documentation for more information.

The Pregnancy data type stores details about a pregnancy, from conception through labor and delivery.

Initially, the Pregnancy instance will likely contain only a few details, such as the estimated due date for the pregnancy. More information may be added as the pregnancy progresses, and when there is a resolution to the pregnancy, a delivery instance is added for each of the fetuses.

The delivery information may contain a Baby instance containing information about the baby. The information stored in the Baby instance may be copied to a new health record for the child when such a record is created.

The pregnancy instance is not intended to store information pertaining to the mother’s health during the pregnancy. If the mother has (for example) gestational diabetes during her pregnancy, that would be stored in a condition in her health record.

The following is an example of the pregnancy record that would be created for the birth of twins…

Pregnancy pregnancy = new Pregnancy();

// information that may be available early in the pregnancy
pregnancy.DueDate = new ApproximateDate(2008, 10, 31);
pregnancy.LastMenstrualPeriod = new HealthServiceDate(2008, 1, 25);
pregnancy.ConceptionMethod = new CodableValue("Artificial insemination: In vitro fertilization (IVF)",
new CodedValue("InVitroFertilization", "conception-methods", "wc", "1"));
pregnancy.FetusCount = 2;

// information available at time of delivery...
pregnancy.GestationalAge = 37;

Delivery delivery1 = new Delivery();
delivery1.Location = new Organization("General Hospital");
delivery1.TimeOfDelivery = new ApproximateDateTime(new ApproximateDate(2008, 11, 1), new ApproximateTime(00, 15, 35));
delivery1.LaborDuration = 123;
delivery1.Anesthesia.Add(new CodableValue("Epidural analgesia", new CodedValue("EpiduralAnalgesia", "anesthesia-methods", "wc", "1")));

delivery1.DeliveryMethod = new CodableValue("Caesarean section", new CodedValue("CSection", "delivery-methods", "wc", "1"));
delivery1.Outcome = new CodableValue("Live birth", new CodedValue("LiveBirth", "pregnancy-outcomes", "wc", "1"));

delivery1.Baby = new Baby();
delivery1.Baby.Name = new Name("Thomas John Andersen");
delivery1.Baby.Gender = new CodableValue("Male", new CodedValue("male", "gender-types", "wc", "1"));
delivery1.Baby.Weight = new WeightValue(2.5, new DisplayValue(5.5, "pounds"));
delivery1.Baby.Length = new Length(0.46, new DisplayValue(18, "inches"));
delivery1.Baby.HeadCircumference = new Length(0.31, new DisplayValue(12.4, "inches"));

pregnancy.Delivery.Add(delivery1);

Delivery delivery2 = new Delivery();
delivery2.Location = new Organization("General Hospital");
delivery2.TimeOfDelivery = new ApproximateDateTime(new ApproximateDate(2008, 11, 1), new ApproximateTime(01, 20, 52));
delivery2.LaborDuration = 198;
delivery2.Anesthesia.Add(new CodableValue("Epidural analgesia", new CodedValue("EpiduralAnalgesia", "anesthesia-methods", "wc", "1")));

delivery2.DeliveryMethod = new CodableValue("Caesarean section", new CodedValue("CSection", "delivery-methods", "wc", "1"));
delivery2.Outcome = new CodableValue("Live birth", new CodedValue("LiveBirth", "pregnancy-outcomes", "wc", "1"));

delivery2.Baby = new Baby();
delivery2.Baby.Name = new Name("Elizabeth Marie Andersen");
delivery2.Baby.Gender = new CodableValue("Female", new CodedValue("female", "gender-types", "wc", "1"));
delivery2.Baby.Weight = new WeightValue(2.4, new DisplayValue(5.3, "pounds"));
delivery2.Baby.Length = new Length(0.44, new DisplayValue(17.5, "inches"));
delivery2.Baby.HeadCircumference = new Length(0.32, new DisplayValue(12.6, "inches"));

pregnancy.Delivery.Add(delivery2);

PersonInfo.SelectedRecord.NewItem(pregnancy);

Using the GeneticSnpResults data type

ericgu — Mon, 01 Dec 2008 22:08:00 GMT

This document contains general guidelines for using the GeneticSnpResults data type. It does not cover all the information that is stored in the type – see the GeneticSnpResults member documentation for more information.

The GeneticSnpResults type is used to store the results of a test that determines single nucleotide polymorphisms in a person’s genome.

Important properties

GenomeBuild

The GenomeBuild provides a definition for the SNP ids that are stored in the result data. The definitions of the SNPs themselves are in the NCBI dbSNP database.

Chromosome

The chromosome on which the SNP is located.

NumberingScheme

The numbering scheme (0-based or 1-based) which defines the physical locations of the start and end positions on the chromosome.

Saving results

Because of the amount of data in a typical result set (currently on the order of a million individual SNPs), the results are grouped into separate instances by chromosome, and the data is stored in a compact format in the other-data section of the instance.

The following code illustrates how to create and save a set of SNP test results:

// for each chromosome in the results
{
GeneticSnpResults resultsForOneChromosome = new GeneticSnpResults(when, genomeBuild, chromosome, numberingScheme);

// set optional properties

    { // for each SNP result for the current chromosome
        SnpItem item = new SnpItem("rs1891906", "-", "GT", "SNP_C-315533", 940106, 940107);
        resultsForOneChromosome.SnpData.SnpItems.Add(item.ReferenceSnpId, item);
    }

    PersonInfo.SelectedRecord.NewItem(resultsForOneChromosome);
}

The when value should be set to the date and time when the results were generated, and should be the same across all chromosomes of a set of result.

Loading results

Loading a set of results will require processing multiple instances. There may be multiple sets of results in a single HealthVault record, and it is therefore recommended that applications load the results in two phases. In the first phase, the instances are loaded and then examined to see if they contain data that is of interested, and then the other-data for those instances is retrieved one instance at a time.

The following code illustrates this technique:

HealthRecordSearcher searcher = PersonInfo.SelectedRecord.CreateSearcher();
HealthRecordFilter filter = new HealthRecordFilter(GeneticSnpResults.TypeId);
searcher.Filters.Add(filter);

HealthRecordItemCollection items = searcher.GetMatchingItems()[0];
List<HealthRecordItemKey> interestingItems = new List<HealthRecordItemKey>();

// figure out which ones are interesting...
foreach (GeneticSnpResults resultsForOneChromosome in items)
{
    if (IsInteresting(resultsForOneChromosome))
    {
        interestingItems.Add(resultsForOneChromosome.Key);
    }
}

// fetch the results data for each of the interesting ones...
foreach (HealthRecordItemKey key in interestingItems)
{
GeneticSnpResults results = (GeneticSnpResults)PersonInfo.SelectedRecord.GetItem(key.Id,
HealthRecordItemSections.Core | HealthRecordItemSections.Xml | HealthRecordItemSections.OtherData);

    foreach (SnpItem snpItem in results.SnpData.SnpItems.Values)
    {
        // process the item here...
    }
}

Implementation details

The low-level details of the format of the results data can be found in the schema for the type (link). Details about how the .NET classes deal with this format can be found here (link).

HealthVault comma-separated data support types

ericgu — Sat, 01 Nov 2008 21:17:00 GMT

The HealthVault comma-separated data format is used to store data in a space-efficient format in the other-data section of data types.

The actual data types provide a layer of abstraction on top of the comma-separated types, and it is recommended that data is accessed through those abstractions rather than using the underlying support types. However, it can be useful to understand how the support types work.

The underlying comma-separated format follows the “C-style” rules for character escaping, where a “\” can be placed in front of any character to escape it.

In addition, the format supports the concept of an “escape”, which is a “name=value” pair that is placed in the comma-separated list instead of a value. The meaning of escapes is defined by a particular data type.

List entry definition

Each item in the comma-separated list is represented as an instance of a class derived from OtherItemDataCsvItem. There are 3 primitive item types derived from this base class:

OtherItemDataCsvString is a string value.
OtherItemDataCsvDouble is a double value.
OtherItemDataCsvEscape is an escape.

class OtherItemDataCsv

This class handles converting between the instance-based model that is used by the data type class and the underlying string representation.

To store data to the string representation, the data type calls SetOtherData() and passes in a collection of OtherItemDataCsvItem instances. This method will take the individual instances in the collection, call the ToString() method on them, and then place the resulting string values into the comma-separated format, applying appropriate character escaping.

To convert data from the string representation to a collection, the data type calls GetAsString(). This returns a collection of OtherItemDataCsvItem that contains either string items or escape items. If the data type knows that the data contains only double values and escapes, it can instead call GetAsDouble(), and all string values will be converted to doubles as a convenience.

Note that there is no type information stored in the raw string format, so all items are inherently strings when they are retrieved, and any interpretation to a different type is done based on information that the data type has, not information stored with the data.

For Review: Updates to Spriometer Measurement

timsell — Wed, 24 Sep 2008 20:16:00 GMT

If you haven't already read through the proposed changes for this data type, please take a look at:

http://blogs.msdn.com/healthvaultdatatypes/archive/2008/09/17/for-review-updates-to-spirometer-measurement.aspx

Here is a draft version of the updated data type:

Peak Flow Measurement type

Element	Type	Occurrence	Description
when	approx-date-time	1..1	The date and time of the measurement.
pef	flow-value	0..1	The peak expiratory flow, measured in liters/second.
pef-best	flow-value	0..1	The highest PEF measurement, measured in liters/second.
fev1	volume-value	0..1	The forced expiratory volume in one second, measured in liters.
fev6	volume-value	0..1	The forced expiratory volume in six seconds, measured in liters.
measurement-flags	codable-value	0..1	Additional information about the measurement. Examples: Incomplete measurement.

Note: fev1 has been updated from type flow-value to type volume-value to accurately describe this data element.

Volume-Value type

Element

Type

Occurrence

Description

liters

positiveDouble

1..1

The volume measurement in liters (L).

display

display-value

0..1

The display value for the volume measurement.

The display value contains the volume measurement value stored in the user's preference of units.

Sample: LabTestResults

ericgu — Fri, 19 Sep 2008 20:48:00 GMT

LabTestResults ltr = new LabTestResults();

ltr.OrderedBy = new Organization("39502605");

ltr.When = new ApproximateDateTime("2008-01-26 20:05:00.000");

LabTestResultGroup grp = new LabTestResultGroup(new CodableValue("CBC With Differential/Platelet"));

grp.LaboratoryName = new Organization("MB");

grp.Status = new CodableValue("C");

ltr.Groups.Add(grp);

LabTestResultDetails details = new LabTestResultDetails();

details.CollectionMethod = new CodableValue("Methodraw");

details.ClinicalCode = new CodableValue("Monocytes", new CodedValue("11112-0", "loinc", "regenstrief", "2.22")); // code to a real vocab (loinc?) here...

details.Name = "Monocytes";

details.Status = new CodableValue("F");

details.When = new ApproximateDateTime(); // needs to be set to a real value - was DateTime.Parse("2008-01-26 06:56:00.000"));

details.Value = new LabTestResultValue();

details.Value.Ranges.Add(new TestResultRange(new CodableValue("ReferenceRange"), new DoubleRange(4, 13)));

details.Value.Measurement = new GeneralMeasurement();

details.Value.Measurement.Display = "19%";

details.Value.Measurement.Structured.Add(new StructuredMeasurement(19, new CodableValue("%", new CodedValue("pcnt", "lab-results-units"))));

grp.Results.Add(details);

PersonInfo.SelectedRecord.NewItem(ltr);

Proposed: Updates to Spirometer Measurement

timsell — Thu, 18 Sep 2008 05:39:00 GMT

In working with some of you, we’ve determined that the Spriometer Measurement data type is serving a bit of double-duty in its current form. As it turns out, there are two primary but very different types of measurements that this data type is currently thought to store: Spriometry and Peak Flow.

Spirometry is a clinical diagnostic test using clinical devices to map out the lung function of a patient who suffers from a debilitating lung disease. Patients typically are brought into the clinic several times per year to chart out their decline in capacity, volume, force, etc. These visits can range from once per year to many times per year. A typical measurement would include FEV1, FET, SVC, Percentage 25 to 75, Percentage 25 to 50, and a bunch of other values.

Peak Flow, on the other hand, is typically a home monitoring test for people with asthma only. These tests are done at the convenience of the consumer and a high frequency (daily). The measurements are primarily PEF although some can also determine FEV1 (6).

To date, all of solution providers that we have contacted are using the Spriometer Measurement data type to store peak flow measurements – by means of a device or an application. A new data element has been suggested to store the personal best flow measurement at the time of the current flow measurement was taken. By storing this personal best along with the current flow measurement, an application can more easily track and graph the improvement or decline over time.

Assuming everyone is using this data type in the same way (speak up if you’re not), then we propose the following updates:

1. Rename the existing Spirometer Measurement data type to Peak Flow Measurement.

2. Add Personal Best as a new element to the data type.

3. Remove Spirometry specific data elements from the data type. We’ll revisit this and most likely introduce a specific data type for Lung Functions/Spriometry when we hear from partners with this type of clinical scenario.

If your application uses the current Spriometer Measurement data type and you have any comments or questions about this pending update, please post them to the Data Types forum.

For Review: Pregnancy

timsell — Thu, 18 Sep 2008 01:46:00 GMT

This is a new data type designed to store pregnancy related information. The Pregnancy data type supplements (and would be related to) existing data types like appointments, conditions and medications to help with scenarios that a consumer might find in a pregnancy diary or when talking with a doctor about past pregnancies.

The structure we created includes a top level Pregnancy type which in turn contains Delivery and Resolution sub types. One thing you will notice is that there are no required elements in this data type. This is so the consumer can use the type to build up a record of the pregnancy over time.

Pregnancy type

All the high level information is stored at this level.

Element	Type	Occurrence	Description
due date	approx-date	0..1	The approximate due date.
last-menstrual-period	approx-date	0..1	The first day of the last menstrual cycle.
conception-method	codable-value	0..1	The method of conception.
fetus-count	positiveInteger	0..1	The number of fetuses.
mother-maiden-name	string	0..1	The maiden name of the mother.
father-name	string	0..1	The name of the father.
delivery	delivery	0..1	Details about the delivery.
resolution	resolution	0..N	Details about the resolution for each fetus.

Delivery sub type

The details describing the delivery event are stored in this sub type.

Element	Type	Occurrence	Description
gestational-age	positiveInteger	0..1	Number of weeks of pregnancy at the time of delivery.
delivery-location	organization	0..1	The place where the delivery occurred.
delivery-method	codable-value	0..1	The method of the delivery.
anesthesia	codable-value	0..N	The anesthesia used during labor and delivery.
complications	codable-value	0..N	Any complications during labor and delivery.
labor-duration	positiveDouble	0..1	The duration of the labor in minutes.

Resolution sub type

The details describing the resolution of the pregnancy are stored in this sub type.

Element	Type	Occurrence	Description
when	approx-date-time	0..1	The data and time of the resolution.
outcome	codable-value	0..1	The outcome for a fetus.
child-name	string	0..1	The name of the child.
gender	codable-value	0..1	The gender of the child.
weight	weight-value	0..1	The birth weight of the child.
length	length-value	0..1	The birth length of the child.

Vocabularies referenced in the Pregnancy data type

There are several vocabularies mentioned above and described in this section.

Conception Method

Intercourse

Intracervical insemination

Intrauterine insemination

In vitro fertilization

Gamete Intrafallopian transfer

Zygote intrafallopian transfer

Delivery Method

Vaginal

Assisted vaginal

Caesarean section

Anesthesia

Systemic analgesics

Local anesthesia

Regional analgesia

Epidural analgesia

Spinal block

Combined spinal-epidural block

General anesthesia

Pudendal block

Complications

Breech

Placenta previa

Big baby (Macrosomia)

Emergency home birth

Pre-term labor

Induced labor

Uterine rupture

Cephalopelvic disproportion

Water break

Episiotomy

Outcome

Live birth

Miscarriage

Stillborn

Abortion

Gender

Male

Female

If this is a type that you would find useful and have any comments or questions, please post them to the Data Types forum.

For Review: Genetic SNP Result

ericgu — Thu, 28 Aug 2008 20:30:08 GMT

This type is intended to store the results of a genetic SNP test. If you want to know more about what a SNP is, I recommend reading the NCBI primer.

The data stored in this type is fairly simple – a small amount of metadata, and then a large list of results.

Element	Type	Occurrence	Description
when	approx-date-time	1	The date and time of the test
genome-build	string	1	The genome build that defines the SNPs. Example: NCBI Build 36.3
chromosone	string	1	The chromosone on which the SNPs are located. Examples: 1, 22, X, MT

The SNP results are stored in the other data portion of the instance, in comma-separated format. Each SNP is encoded as follows:

[refSNP id],[strand orientation],[result]

Where:

refSNP id: identifier from NCBI dbSNP database
strand orientation: "+" encodes top, "-" encodes bottom.
result: the result of the test

Example:

rs1891906,-,GT

Any comments on this type should be made in the following data type forum post.