2023:Labeled Value (Value Extractor)

WIP	This article is a work-in-progress or created as a placeholder for testing purposes. This article is subject to change and/or expansion. It may be incomplete, inaccurate, or stop abruptly. This tag will be removed upon draft completion.

A Labeled Value is an extractor type that can be used when configuring several data extraction tools such as a Value Reader or Data Type. It is designed to return text segments that have a spatial relationship to a defined label.

About

A Labeled Value is configured using two extractors: the Label Extractor and the Value Extractor. When the Label Extractor is set, Grooper uses spatial context to determine what value to return (for more on spatial context, see the Data Context wiki article).

The Labeled Value extracts information similarly to collating a Key-Value Pair. Unlike a Key-Value Pair, the extractor is self-contained in one object. There is no need to set one object as a "Key" and another object as a "Value". Instead, both the "Label" and the "Value" can be set on one object.

How To

Selecting the Extractor

Configuring on a Value ReaderConfiguring on a Data TypeConfiguring on Other Object Types

Configuring on a Value Reader
In your Node Tree, create or select a Value Reader. Visit the Value Reader Wiki Page for instructions on how to create a Value Reader. Select the "Value Reader" tab. Click the drop down list next to Extractor and select Labeled Value.

Configuring on a Data Type
In your Node Tree, create or select a Data Type. Visit the Data Type Wiki Page for instructions on how to create a Data Type. Select the "Data Type" tab. Click the drop down list next to Local Extractor and select Labeled Value.

Configuring on Other Object Types

The Labeled Value extractor can be used on a multitude of object types. Any object that has an extractor property can be configured with an Labeled Value. The configuration process on other objects is identical to both the Value Reader and Data Type objects. Simply select Labeled Value as your extractor type. Examples where you can use an Labeled Value include: A Data Type's Value Extractor property A Document Type's Positive Extractor property The Labeled Value extractor's Label Extractor property (Yes, you can configure a Labeled Value within a Labeled Value). The Pattern-Based Separation Provider's Value Extractor property

Click here to return to the top of the section

Basic Setup

Once you select Labeled Value as your extractor, you will need to set both your label and your value to be extracted.

Configuring the Label ExtractorConfiguring the Value ExtractorThe Final Result

Configuring the Label Extractor
Once Labeled Value is set as the extractor on the object you are configuring, click on the "Tester" tab. Click the drop down next to the Label Extractor property and select an extractor to use. For the purposes of this example, we are going to use a List Match extractor. However, any extractor can be used to capture the desired label.
Configure your chosen extractor to collect the desired label.

Configuring the Value Extractor
Once Labeled Value is set as the extractor on the object you are configuring, click on the "Tester" tab. Click the drop down next to the Value Extractor property and select an extractor to use. For the purposes of this example, we are going to use a Reference to another extractor that has been previously configured. However, any extractor can be used to capture the desired values.
FYI The extractor we are referencing is configured to return dates. The goal when setting up the Value Extractor is not to collect an individual text segment, but rather collect the type of information you are trying to extract. The Label Extractor will let Grooper know which individual text segment to extract. In this case, the "Invoice Date".
Configure your chosen extractor to collect the desired values. When both the Label Extractor and Value Extractor are set up properly, the label will be outlined in blue while the extracted value will be highlighted in green.

The Final Result

Once your Label Extractor and Value Extractor are set up, you should see some results. As you can see in this example, since the "Order Date" was set as the Label Extractor, the date value that is returned is the closest to the label. If you set your Label Extractor and Value Extractor up properly and Grooper is still not returning the results you want, look below at the Advanced Setup section. There you will find information about more properties you can configure to increase the accuracy of your results.

Click here to return to the top of the section

Advanced Setup

So, you have your Label Extractor and Value Extractor properly configured, but you are still not getting the results you want. There are a couple of properties you can configure to try and improve your results: Maximum Distance and Maximum Noise.

Maximum DistanceMaximum Noise

Maximum Distance

Sometimes Grooper will produce an undesirable result based on layout of the document. The Labeled Value extractor will not return a result if the value is further away from the label than Grooper expects. When this happens, the Maximum Distance property can be configured to improve your results.

By default, the Maximum Distance is set at 2in to the right and 2in to the bottom. This setting is telling Grooper to look for a value that is located two inches to the right and two inches below the Label Extractor.

If Grooper finds a result within that 2x2 region, it will return that result as the value. If Grooper finds multiple results within that 2x2 region, multiple factors will be considered when returning a result, including proximity to the label and number of "noise" characters present (for more information on noise, see the following tabs).

In the picture to the right, we can see that the extractor is working appropriately. With the layout of the Order Date and Invoice Date, Grooper is able to pick out the Order Date with the default settings. The desired value falls within the Maximum Distance of 2x2 inches to the right and bottom of the label.
However, in this picture, Grooper is extracting the wrong value. There are many times where the spatial layout of a document would require additional configuration. So, why is Grooper grabbing the wrong value?
With the default Maximum Distance selected, all values within this zone are considered. Both the Invoice Date and the Order Date are within the range of the Maximum Distance. Since the Invoice Date is closer to the "Order Date" label, Grooper is returning this as the value.
If we change the Maximum Distance to just "2in" to the right, we see that the zone changes. Only the correct date is within the range of the Maximum Distance.
With the Maximum Distance properly configured, we see that Grooper now extracts the correct value.

Maximum Noise
After you have your Label Extractor and Value Extractor properly configured you may find that you are still not getting results. This could possibly be due to noise characters between your label and your value. Noise characters are any alpha-numeric characters that come between your label and value. By default, the Labeled Value extractor accounts for 5 noise characters between the label and the value. If there are more than 5 noise characters, you may not get results until the Maximum Noise property is increased.
In this example we are trying to extract the Mailing Address for Tarah Dactyl. First, we have created a List Match extractor as our Label Extractor for "Mailing Address".
Next, we have referenced a pre-configured extractor designed to collect all generic text segments on the document.
However, with both of those properly configured, we are still not getting the desired result. To the right of the label, you can see that we have some noise characters: "Street" (highlighted in yellow). If we count the letters in the word "Street" we can see that we have 6 noise characters. That is more than the preconfigured 5 allowable noise characters. NOTE: Notice that the colon next to the label is not included in the noise character count. Only alpha-numeric characters count as noise. Punctuation and whitespaces do not.
Here we have increased the Maximum Noise to 6, and as you can see, we are now getting the result that we want. NOTE: It is best practice not to increase your Maximum Noise too high. In some cases it could produce undesirable results. Noise characters can often be helpful in avoiding collecting false positives.

Click here to return to the top of the section

See Also

• Key-Value Pair (Collation Provider)
• Data Context
• Value Reader
• Data Type