Introduction

  • Portrait Miner Overview
© 2015 Pitney Bowes Software Inc. Email: software.support@pb.com


Portrait Miner Overview

Portrait Miner is a powerful predictive analytics solution that enables customer insight professionals and business users alike to achieve a clear picture of their customers for the purpose of greater customer understanding, uncovering areas of opportunity, achieving optimal segmentation and predicting future behavior.

Bridging the gap between standard Business Intelligence tools with a limited scope for exploring data, and number-crunching solutions which require statistical programmers to build queries and produce models, Portrait Customer Analytics is a next-generation solution designed for unparalleled ease of use – and fast actionable insight.

The solution utilizes powerful 3D data visualization and rapid modeling automation to uncover important data relationships and deliver propensity scores at the push of a button, boosting predictive model accuracy and increasing the speed of analytic results.

Portrait Miner can be used to predict profit-impacting behaviors and propensities, including customer churn, cross sell and up sell opportunities, campaign planning and segmentation, customer satisfaction and loyalty, and customer lifetime value.

Parent topic: Introduction


Getting started

  • Starting Portrait Miner
  • To add or remove details of Portrait Miner servers
  • Browsing to open or save a file, session or database table
  • Working with files on local disks
  • Manipulating focus files in Portrait Miner
  • Viewing and editing text files in Portrait Miner
  • About text encoding
  • Working with session files


Starting Portrait Miner

  1. Do one of the following:
    • Double-click on the Portrait Miner shortcut icon on your desktop. Portrait Miner starts.
    • Go to the Windows Start menu and, under Programs>Portrait Miner, choose Portrait Miner.
  2. If a login window appears, enter your username and password for the Portrait Miner server and click OK.

    Your system administrator should be able to tell you which server to use (if there is a choice) and what your username and password for that server are. (If your server's operating system is Windows, your username and password must be appropriate for the Windows domain that you configured in the server details.)

    If you haven't used Portrait Miner before and the Server menu is empty, see To add or remove details of Portrait Miner servers.

    Once you are logged in to a Portrait Miner server, you can run further Portrait Miner applications, which connect to the same server without prompting you to log in again. You remain logged in to the Portrait Miner server until you explicitly log out (by choosing File>Logout in any Portrait Miner application) or quit your last open Portrait Miner application (by choosing File>Exit or by clicking on [image] in the application's main window).

Parent topic: Getting started


To add or remove details of Portrait Miner servers

The first time that you use Portrait Miner, the Server menu in the login window is empty (unless your system administrator has set it up for you).

If you want to add an entry to the Server menu, you need to know the network name of the Portrait Miner server as well as its port number. Your system administrator should be able to supply you with this information.

Parent topic: Getting started

To add a server to the Server menu

  1. In the login window click Servers to display the Servers dialog box:

  2. Click Add to display the Add Server Configuration dialog box:

  3. In the Name box, enter the server description used in the Server list of the login window.
  4. In the Server box, enter the network name of the Portrait Miner server (for example, yourserver.yourco.com).
  5. Select either Unix or Windows according to the operating system of the Portrait Miner server. If you select Windows, specify the Windows domain that you will log in to, or use the default setting ("Local") to specify a local account on the server.
  6. In the Port box, enter the number of the port for which the server has been configured.
  7. Click OK to add the new server details.
  8. In the Servers dialog box, click Close to return to the login window.

To edit the details for a server

  1. Click on the Servers button.
  2. Highlight an available server and click on Edit.

    The Edit Server Configuration dialog box appears, which is essentially the same as the Add Server Configuration dialog box [see To add a server to the Server menu].

  3. Amend the name, server, or port as required and click on OK.
  4. Click on Close, to close the Servers dialog box.

To remove a server from the Servers menu

  1. Click on the Servers button.
  2. Highlight the server that you want to remove and click on Remove.
  3. Click on Close.


Browsing to open or save a file, session or database table

In Portrait Miner, whenever you open or save a file, session, or database table, a Portrait Miner file browser appears. This is similar to the file browsers in other Windows applications, but has variants that let you browse files on your PC, files on your Portrait Miner server (in the client-server version of the software), and tables in your databases.

When you open or save a dataset, the file browser contains up to three tabs, labeled "Quadstone," "All Files," and "RDBMS," as in the following example:

Parent topic: Getting started

Browsing files in Portrait Miner

The "Quadstone" and "All Files" tabs both show files and folders in Portrait Miner, but the former is slightly more restrictive:
 | "Quadstone" tab | "All Files" tab
Folders shown | All folders except: folders with filename extensions .rdx and .xtr, which contain data files for foci; folders whose names start with a dot (.) | All folders
Files shown when Files of Type is set to All Files | All files except: files with filename extensions .fcs, .mid, .mdh, .spa, and .x86; files whose names end with a tilde (~); files whose names begin with a dot (.) | All files
Files shown when Files of Type is set to a particular type of file | Only files with the given filename extension(s) | As "Quadstone"

If you are saving a dataset as a flat file or focus, make sure you choose the required type from the Files of Type selector.

Note:
  • Portrait Miner normally shows the same files and folders that a file browser shows under the Quadstone tab. You can display the files and folders that a file browser shows under the All Files tab by choosing View>Show Hidden Files.
  • Portrait Miner generates log files for administration purposes. To go to the folder containing these log files, click on [image] on the toolbar.
  • To go to the previous, next, or parent folder, click on [image], [image], or [image] on the toolbar.
  • To go directly to the default folder, (the setting of the qsexplorer home preference), click on
  • You can go directly to an arbitrary folder by choosing View>Go To... and typing the folder name.

Browsing databases, namespaces, and tables

You can browse databases using the "RDBMS" tab, when it is present. ("RDBMS" stands for "Relational Database Management System.") The tab initially shows a list of available databases. You can browse within a database hierarchy, down to the level of individual tables, in just the same way as you browse in the filesystem.

See also

To set up a database connection

Browsing sessions on your PC

You can browse for previously saved sessions (.pms files) using the File > Open Session menu. In this case, the file browser shows a single tab, labeled "My Computer" with the .pms file extension preselected.

In these cases, the file browser shows a single tab, labeled "My Computer":

You can browse to and save files on your PC just as you would in any other Windows application.

Browsing files on your PC

You can save some kinds of file on your PC (or on a network drive accessible from your PC). Such files include exported graphics and saved crosstabs.

In these cases, the file browser shows a single tab, labeled "My Computer":

You can browse to and save files on your PC just as you would in any other Windows application.


Working with files on local disks

Even if you do not have direct access to your Portrait Miner server machine, you can save and open some files (such as scripts, images, and crosstabs) on your PC. To use a data file that is on your PC (or an accessible network drive), you can drag a data file from Windows Explorer to a folder in Portrait Miner.

A copy of the file appears in the folder on the Portrait Miner server, which you can then use directly.

Note: As well as dragging files from Windows Explorer to Portrait Miner, you can drag files in the opposite direction to copy them from the Portrait Miner server to a local disk.

See also

Viewing and editing text files in Portrait Miner
Parent topic: Getting started


Manipulating focus files in Portrait Miner

A focus is stored on disk as a .ftr file (the "focus file") together with a collection of data files and other files in two folders, with names ending in .rdx ("Raw Data eXtract") and .xtr ("eXTRa"). The folders are normally hidden from view in Portrait Miner and in the "Quadstone" tab of a Portrait Miner file browser [see Browsing to open or save a file, session or database table].

A new focus that is created by copying an existing focus or by importing data from another kind of dataset (or as a result of running a TML script) is independent of other foci. On the other hand, a focus that is saved from Decision Studio with a new name, or one that is created by making a linked copy is dependent on data folders belonging to other foci.

Because of the potential interdependence of foci, you should not copy, move, rename, or delete focus files and folders using operating-system utilities, for example, Windows Explorer or UNIX command-line tools. Instead, you should always use Portrait Miner (or Portrait Miner data-build commands).
Parent topic: Getting started

Copying or moving a focus file to another folder

  1. In Portrait Miner, click on the focus file that you want to copy or move.
  2. Do one of the following:
    If copying the file | If moving the file
    Choose Edit>Copy. | Choose Edit>Cut.
    Right-click and choose Copy. | Right-click and choose Cut.
    Click on [image] on the toolbar. | Click on [image] on the toolbar.
    Press CTRL+C. | Press CTRL+X.
  3. Browse to the destination folder.
  4. Choose Edit>Paste, right-click and choose Paste, click on [image] on the toolbar, or press CTRL+V.
Note:
  • You can copy a focus file as an independent focus (as above), in which case the data itself is duplicated; or you can create a linked copy, which shares data with the original focus. You do this by using Paste Link instead of Paste. (There is no toolbar shortcut for this.) You cannot create a linked copy when you move a focus file.
  • You can also choose a new name for a focus that you move or copy by choosing Paste As or (when copying) Paste Link As.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build commands qscopy, qslink, and qsmove.
  • You can also copy or move non-focus files (but not create linked copies) in the same way.

See also

Using Portrait Miner data-build commands for data import, processing, and export

Renaming a focus file

  1. In Portrait Miner, click on the file that you want to rename.
  2. Choose Edit>Rename, right-click and choose Rename, or simply click a second time on the filename.

    The filename becomes editable.

Note:
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsmove.
  • You can also rename non-focus files and folders in the same way.

See also

Using Portrait Miner data-build commands for data import, processing, and export

Deleting a focus file

You can use Portrait Miner to recursively delete an entire chain of foci: select the focus to delete, and all foci which depend on it are also deleted. Confirmation of which foci will be deleted is displayed, and you have the choice to continue, or to stop the delete operation completely.

  1. In Portrait Miner, click on the focus file that you want to delete.
  2. Choose Edit>Delete, right-click and choose Delete, click [image] on the toolbar, or press Delete.
Note:
  • This user interface accesses most of the functionality provided by the Portrait Miner data-build command qsremove.
  • You can also delete non-focus files and folders in the same way. Before deleting a folder, you must first delete any focus files contained within that folder.

See also

Using Portrait Miner data-build commands for data import, processing, and export

Creating an archive file

You can create an archive file from a focus or a folder that contains a set of related foci or subfolders.

In Portrait Miner, right-click on the file or folder that you want to archive and choose Archive for a folder, or Export>to Archive for a focus.

In the Archive to ZIP file dialog box, specify an output file name.

Note:
  • If you create an archive file from a folder that contains foci that link to data outside the folder, the external data is copied into the archive. This ensures that you always get a consistent set of related foci when you extract from the archive file.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsarchive.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export

Extracting from an archive file

In Portrait Miner, right-click the archive file that you want to extract from and choose Extract.

In the Extract from ZIP archive dialog box, choose an output folder and whether to overwrite existing files.

Note: This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsunzip.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export


Viewing and editing text files in Portrait Miner

How you edit or view a file from Portrait Miner depends on its file type. You may be able to:
  • right-click on the file and choose Edit, to edit (or view) the file in Notepad;
  • right-click on the file and choose View, to view the file in an appropriate application;
  • double-click on the file as an alternative to one of the above.
File type | Edit | View | Double-click
Text data file (.txt, .dat, .csv, .tab, .fdf), flat-data description file (.fdd) |  |  | — (Open [see Creating a focus from data in a text file])
SQL file (.sql) |  |  | — (Open)
Notepad. TML script file (.tml), FDL derivation file (.fdl), categorical binning hierarchy file (.hrc) |  |  | Edit
Log file (.log) |  |  | View
XML file (.xml, .qmml, etc.) |  |  | View
Note:
  • Even if you do not have direct access to your Portrait Miner server machine, you can still view and, where appropriate, edit text files on the server. There are two versions of Portrait Miner: a client-server version, and Portrait Miner Desktop. If you use the client-server version, when you use Portrait Miner to view or edit a text file in Notepad, you are actually working with a local copy of the file. If you save the file but Notepad remains open, the version on the server remains unchanged; Portrait Miner only copies the updated version on your PC back to the server when you quit Notepad.
  • You must use an ISO-8859-1 (Latin-1) encoding when saving text files.

See also

Manipulating focus files in Portrait Miner

Working with files on local disks

XML in Portrait Miner

Parent topic: Getting started


About text encoding

Text files in Portrait Miner may be encoded in Unicode as defined by the file's byte order mark (BOM). If a file on Windows has no BOM it is assumed to be what Windows describes as 'ANSI' with respect to the machine locale, for example Windows 1215 in Europe and the US, CP932 in Japan. On Solaris a file with no BOM is assumed to be latin-1 encoded.

Parent topic: Getting started


Working with session files

If you are working within one of Portrait Miner's viewer tools (that is, Crosstab, 3D, Profile, or Map viewer) and want to save your current view, you can using the File > Save Session option in the Decision Studio window. Files are saved with the file extension (.pms) are are prefixed by default with the focus file name.
Saved sessions can be loaded from within Decision Studio, or alternatively, you can double-click the .pms file in the Portrait Miner explorer window.
Note:
Session files are directly linked to the associated focus file and must reside in the same directory.

Loading or opening a saved session

You can load saved sessions for the following Portrait Miner tools:

  • Crosstab viewer
  • 3D viewer
  • Profile viewer
  • Map viewer
    Note: All saved session files are directly linked to the focus file they were created from.
To load a saved session from Portrait Miner
  1. Open Portrait Miner and navigate to your saved session directory.
  2. Double-click on the saved session file (.pms). The session will load the associated focus data and the saved session.
To open a saved session from Decision Studio
  1. Open Decision Studio.
  2. Select File > Open Session and browse for the relevant session file (.pms). The session will load the associated focus data and saved session.

Saving a session

You can save session information for the following Portrait Miner tools:

  • Crosstab viewer
  • 3D viewer
  • Profile viewer
  • Map viewer
To save a session
  1. With your session open, change to the Decision Studio window and select File>Save Session.
  2. In the Save Session dialog box, add your filename to the default prefix. Note: The prefix identifies the focus file related to the session.
Parent topic: Getting started


Working with flat files, database tables, and foci

  • About Portrait Miner wizards
  • Opening a focus for visualizing, segmenting, and modeling
  • To sort a focus
  • To convert a transaction-oriented focus to a customer-oriented focus
  • Creating a focus from data in a text file
  • Creating a focus from data in a database
  • Creating a focus from a SAS or third-party dataset
  • Exporting records to a data file, database table, or focus
  • About combining foci
  • To join fields from one focus to another focus using Portrait Miner
  • To join fields from one focus to another focus using Decision Studio
  • Merging records from two foci
  • To set up a database connection
  • How Portrait Miner imports database types
  • Using the Data Build Manager for data import, processing, and export
  • Using Portrait Miner data-build commands for data import, processing, and export


About Portrait Miner wizards

Portrait Miner wizards are opened from Portrait Miner, after selecting a focus or other file, and provide user-interface access to the Portrait Miner data-build commands.

Each wizard displays the command parameters on a Parameters tab. Values in the Parameters tab can be altered either by typing directly into the field, or by clicking Browse [image] to display a further dialog box from where a value can be selected.

When all mandatory parameters — indicated by a red asterisk in the parameter field — have been selected, click Go to run the associated data-build command. If required, you can stop the command by clicking the Stop button; for example, if you selected the wrong parameters.

After the command has completed, the results are displayed on the Output tab. If there are any errors associated with processing the command, an error message is displayed on the Error tab.

See also

Using Portrait Miner data-build commands for data import, processing, and export
Parent topic: Working with flat files, database tables, and foci


Opening a focus for visualizing, segmenting, and modeling

Once you have customer data in the form of a focus, you can open it in Decision Studio for analysis, using a range of tools [see Decision Studio tools] for visualizing, segmenting, and modeling.

A focus can be opened using one of the following options:

  • In Portrait Miner, double-click on the focus that you want to open or right-click on the focus and choose Open.
  • In a Decision Studio window with a focus currently open, choose File>Close, to close the existing focus. Then choose File>Open, or click on [image] on the toolbar, and browse to the focus that you want to open.

    (If you have modified a focus since you created or opened it, Decision Studio gives you the opportunity to save your changes before you close it.)

Note:
  • If you are warned that the focus is read-only, use File>Save As, or click on [image] on the toolbar, and choose a new name or location for your focus, or copy the focus to a new location. Some product features and options do not work with a read-only focus.
  • You can only have one focus open at a time in a given Decision Studio session.

    (However, you can have more than one Decision Studio session at a time.)

  • Two or more users can open, and simultaneously work with, the same focus in Decision Studio. (Of course, you should ensure that when you save the focus, you avoid saving over another user's work).

See also

Creating a focus from data in a database

Creating a focus from data in a text file

Starting Portrait Miner

Parent topic: Working with flat files, database tables, and foci


To sort a focus

You can sort the records in a focus according to the values in up to three fields.
To sort a focus:
  • In Portrait Miner, right-click on the focus that you want to sort and choose Transform>Sort.

In the Sort Focus dialog box, choose up to three key fields to determine the order of the sorted focus. Additionally, you can change the location of the new focus or choose to overwrite a previously created output focus.

Note:
  • If you choose more than one field, the primary sort key is the selected field that appears first in the focus and the secondary sort key is the selected field that appears second. (If you choose three fields, the other field is the tertiary sort key.)
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qssort.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Working with flat files, database tables, and foci

To check the sort order of a focus

In Portrait Miner, right-click on the focus you want to check, and choose Transform>Check Sort Order.

In the Check Sort Order dialog box, choose key fields; Portrait Miner will check whether the focus is sorted by these fields.


To convert a transaction-oriented focus to a customer-oriented focus

For customer-level data analysis, you need customer-oriented data. If you have a transaction-oriented focus — that is, a focus in which each record represents a customer transaction — you can compute per-customer aggregate statistics to create fields in a new customer-oriented focus. You can use the new focus for analysis straightaway or first join [see About combining foci] it to other customer-oriented foci.
To convert a focus:
  • In Portrait Miner, right-click on the transaction-oriented focus and choose Transform>Aggregate Records.

In the Aggregate Records dialog box, choose the file containing field definitions and the key fields that uniquely identify a customer. You can also change the location of the new focus or choose to overwrite a previously created output focus.

Note:
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsmeasure.
  • To track state changes in a transaction stream, you should use the related Portrait Miner data-build command qstrack.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export

Viewing and editing text files in Portrait Miner

Parent topic: Working with flat files, database tables, and foci


Creating a focus from data in a text file

To use Portrait Miner to analyze a dataset in the form of a text file, you first need to create a focus from the data file.
To create a focus:
  • In Portrait Miner, double-click on the file, or right-click on the file and choose Open.
Two windows appear:
  • The Flat File Format Information window shows Decision Studio's initial attempt to make sense of the data, highlighting any problems encountered.

    You can close this window at any point.

  • The other window is the New Focus wizard, which initially shows Step 1 of a five-step import process:

    You can move between steps using the Next and Back buttons. At any stage, you can click on Finish to accept the choices made so far and create a new focus from your dataset.

    Before clicking on Finish, you can choose where to save your focus, by clicking on the Browse button in the Save focus as pane and browsing [see Browsing to open or save a file, session or database table] to choose a location.

    At each step, the New Focus wizard shows Decision Studio's current interpretation of the names and types of fields in the flat file, together with a small sample of the data viewed with this interpretation.

Step 1: Choose delimited or fixed-width format In the Choose format pane, choose Delimited if field values are separated by commas, pipes, or some other delimiter; choose Fixed Width if field values start and end at the same fixed character positions in each line of the file.

Step 2: Set flat-file format details The Format options pane shows a summary of the format details that are currently set.

If Decision Studio has interpreted the flat-file format incorrectly (for example, if it has chosen the wrong field separator), click on Set Format in the Format options pane, to open the Set Flat File Format window (along with a Raw Data preview window):

The version shown on the left is for delimited field data; the version on the right is for fixed-width fields.

(When you choose fixed-width fields and move from Step 1 to Step 2, the Set Flat File Format and Raw Data windows appear automatically.)

If the first row of your file consists of field names rather than data, check the Column Headings option.

The Field Separator, Read Null As, Read Dates As, Read Date Marker As, and Read Strings As settings allow you to specify detailed aspects of the flat-file format , with common options available in drop-down menus. Set Field Separator to "nothing" for a flat file with fixed-width fields.

For fixed-width fields, use the table to specify the field names and their start and end positions. You can use the Raw Data window as a guide for this: the "ruler" at the top shows character positions, and as you move the mouse pointer over the sample data, hover text gives the position of the character currently under the pointer.

Step 3: Set field format details The table of field details expands to include three editable rows (with white backgrounds):

The first two rows contain each field's current name and type. For a string field, the third row contains its (maximum) length in characters. For a date field, the third row contains the date format.

You can type a new field name, string length, or customized date format [see Customized date formats] directly.

If you click on a field's type, a menu appears, showing the four available datatypes [see Datatypes]. For date fields, a menu of the three standard date formats [see Standard date formats] is available.

Step 4: Save format details If you will need to reuse your format settings at a later date, you can create a flat-data description (FDD) file by clicking on Export Format and choosing a location.

Step 5: Select fields to import By default, Decision Studio imports all fields in a flat file. If you don't need all the fields, click on Select Fields in the Select Fields pane. The Select Fields dialog box appears, with all fields from the external data source initially in the Include pane:

Use the arrow buttons between the Exclude and Include panes to choose the fields from the flat file that you want to include in your focus.

The [image] and [image] buttons move highlighted fields, while the [image] and [image] buttons move all fields from one pane to the other.

Use the [image] and [image] buttons at the right of the window to rearrange highlighted fields in the Include pane.

Note:
  • You can click on Show Data in the New Focus wizard to view the data as it appears in the file. You may find it helpful to do this if Decision Studio is unable to work out the format of the file.
  • To aid in setting the file-format details for a flat file with fixed-width fields, you can copy-and-paste or drag an external description of the data to the table in the Set Flat File Format dialog box.

    The description can be in the form of an Excel spreadsheet or plain text with two or three columns of tab-separated values. The first column of data, which is optional, contains the field names; the next two (or only two) columns contain start and end positions for the fields.

  • Decision Studio bases its initial interpretation of a flat file on a subset of the records. To change the number of records Decision Studio uses for this, change the settings of the data format sample size preference; to change the sensitivity of Decision Studio to badly-formatted data, change the setting of the coarse cutoff percentage preference.

    If Decision Studio needs more information to interpret the flat file correctly, it reads a larger subset of records. To change the number of records Decision Studio uses in this case, change the setting of the data sample size preference.

  • When Decision Studio has finished importing the flat file, it creates an appropriate log file. You should examine this file if Decision Studio reports any errors or warnings during the import process.

    In Portrait Miner, you can click on [image] to go to the directory containing log files% — the subdirectory shared/logs (UNIX) or shared\logs (Windows) of the Portrait Miner installation directory.

    The required log file is the most recent log file whose name starts with the name of the original flat file. (You can sort the log files into date/time order by clicking on the Modified column heading.)

  • Decision Studio changes any invalid field names to valid field names.
  • If a flat file has an associated flat-data description (FDD) file, you can use it to set the initial file format: click on Import Format in Step 1 of the import process. (You can then make changes to the format in the usual way.)

    Alternatively, you can start the New Focus wizard by double-clicking on the FDD file in Portrait Miner.

  • An integer value is qualified as "small" in the New Focus wizard if it is specified as a smallinteger [see Datatypes] in an FDD file. A smallinteger field takes up less disk space than a normal integer field, but can only hold a limited range of values.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build commands qsgenfdd and qsimportflat.

See also

Creating a focus from data in a database

empty lines

extraction max errors

extraction max warnings

ignore extraction warnings

permit data format errors

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Working with flat files, database tables, and foci


Creating a focus from data in a database

To use Portrait Miner to analyze a dataset in the form of a database table — or some combination of tables and views — you first need to create a focus from the data in the database.
Parent topic: Working with flat files, database tables, and foci

Importing data from a database table

To import data:
  • In Portrait Miner, navigate to the Database tab and open a database connection. For more information, see To set up a database connection.
  • Double-click the database table, or right-click and choose Open.

The New Focus dialog box displays:

This New Focus dialog shows a preview of the data, including field names and field types.
  • In the Save focus as pane, click on Browse, and browse [see Browsing to open or save a file, session or database table] to choose a location for the focus.
  • Click OK to create the new focus.

If you do not want to import all the fields from the table, click Select Fields. The Select Fields dialog displays:

All fields from the external data source that can be imported are initially displayed in the Include pane.
  • Use the arrow buttons to choose the fields from the table that you want to include in your focus.

    The [image] and [image] buttons move highlighted fields, while the [image] and [image] buttons move all fields from one pane to the other.

    Use the [image] and [image] buttons at the right of the window to rearrange highlighted fields in the Include pane.

  • When you have selected the required fields, cli OK to return to the New Focus dialog.
Note:
  • You cannot import a column in this way if its name is not a valid identifier [see Basic expressions] in FDL.
  • Real-number fields with greater than 15-digit precision in a database are treated by default as string fields in Portrait Miner. By changing the preserve numeric types on import preference, you can force them to be treated as real fields (with truncated precision).

See also

Creating a focus from data in a text file

To set up a database connection

Importing data by querying a database

You can create a focus from a combination of tables and views in a database, by specifying an SQL query that selects the data you require.
  • In Portrait Miner, double-click on an SQL file containing the query that you want to use, or right-click on the file and choose Open.

In the Import from Query dialog box, choose a location for the focus that you want to create; enter or modify the SQL query if necessary; and choose a database connection [see To set up a database connection].

Note:
  • If you open the Import from Query dialog box using an SQL file, Portrait Miner derives a focus name from the filename, and uses the file's contents as the initial SQL query. However, once the dialog box is open, the file itself is no longer relevant: it is the query in the dialog box, not the query in the file, that is actually executed.
  • The SQL is passed as-is to the database as a single statement; a terminating semicolon is not required (and may be invalid syntax for some database systems).
  • This user interface is a way of accessing some of the functionality provided by the Portrait Miner data-build command qsimportdb.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export


Creating a focus from a SAS or third-party dataset

To use Portrait Miner to analyze a third-party dataset, you need to create a focus from the dataset. Portrait Miner can import data from various third-party datasets, including those created by SAS, SPSS, and Excel. (See http://support.quadstone.com/info/requirements/ for a complete list of supported formats.)
Parent topic: Working with flat files, database tables, and foci

Creating a focus from a SAS dataset

  • In Portrait Miner, double-click the dataset file that you want to import, or right-click and choose Open.

In the Focus Import dialog box, you can choose the fields that you want to import (by default, all fields are imported) and choose whether to import field and value label metadata into the created focus. Additionally, you can change the location of the new focus or choose to overwrite the output focus.

Note:
  • SAS metadata is read from a format.sas7bcat SAS catalog file that must be present in the same folder as the source SAS dataset.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsimportstat.
  • You can audit [see Creating a Profile and Audit of a focus] a third-party dataset without first creating a focus: simply right-click on the dataset in Portrait Miner and choose Audit.

Creating a focus from Excel or other third-party dataset

  • In Portrait Miner, double-click on the dataset file that you want to import, or right-click and choose Open.

In the Focus Import dialog box, you can choose the fields that you want to import (by default, all fields are imported). Additionally, you can change the location of the new focus or choose to overwrite the output focus.

Note:
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsimportstat.
  • You can audit [see Creating a Profile and Audit of a focus] a third-party dataset without first creating a focus: simply right-click on the dataset in Portrait Miner and choose Audit.
  • You can open an Excel workbook in Excel by right-clicking on it in Portrait Miner and choosing Send to Excel.

See also

About Portrait Miner wizards

Creating a focus from data in a database

Creating a focus from data in a text file

Exporting records to a SAS file or other third-party dataset


Exporting records to a data file, database table, or focus

You can export records from a focus to a flat file, database table, or another focus from Decision Studio, or to a flat file [see To export records to a flat file using Portrait Miner], another focus [see Exporting records to a focus using Portrait Miner], or a SAS or other third-party dataset [see Exporting records to a SAS file or other third-party dataset] using Portrait Miner.
Parent topic: Working with flat files, database tables, and foci

Exporting records from Decision Studio to a flat file, database table, or focus

You can export records from a focus or highlighted segments in a graphical viewer to a flat file, a database table, or another focus.
  1. Do one of the following:
    • In the Decision Studio window, choose Focus>Export Data.
    • In the Profile Viewer, Crossdistribution Viewer, Map Viewer, or Decision Tree Builder, highlight the segments [see Highlighting segments in a graphical display] that you want to export and then choose Segments or click on [image] on the toolbar.

    The Export Records dialog box appears:

  2. Click on the Browse button.
  3. Browse [see Browsing to open or save a file, session or database table] to the required location and choose a name and type for your exported dataset.
  4. If you want to choose a subset of the fields in the focus, click on the Select button.

    A field-selection dialog box appears, with all fields initially in the Selected pane (unless you have interpreted some fields in the focus as export fields [see To set or clear an analysis candidate, categorical, geographical, export or key interpretation], in which case those fields are selected):

    Use the arrow buttons between the Not Selected and Selected panes to choose the fields that you want to appear in the exported dataset.

    The [image] and [image] buttons move highlighted fields, while the [image] and [image] buttons move all fields from one pane to the other.

    Use the [image] and [image] buttons at the right of the window to rearrange highlighted fields in the Selected pane.

  5. If you are creating a flat file, optionally click on Format, to control the export format [see Controlling flat-file export format].
  6. Click on OK, to export the data.

To export records to a flat file using Portrait Miner

To export records:
  • In Portrait Miner, right-click on the focus that you want to export and choose Export>as Text.

In the Export Text dialog box, you can choose the fields from the focus to export, and modify the output file name and location. Click Next to display the Format tab and choose the export options, similar to those in the Export Options dialog box [see Controlling flat-file export format], for the output file.

Note:
  • You can choose which fields to export either by selecting field names or by choosing one or more tags [see Working with field groups].
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsexportflat.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export

Controlling flat-file export format

In Decision Studio, if you click Format in the Export Records dialog box, when exporting data to a flat file, the Export Options dialog box appears:

Here you can specify a field separator, a string to use in place of the null [see The null value] value, the format to use for date values, and whether to use single- or double-quotation marks (or none) around string values. If you choose to use quotation marks around string values, you have the option of using them for all values (instead of using them only when the content of the value makes it necessary).

If you choose a text file as your export file, you have the option to generate a flat-data description (FDD) file to accompany it. If you choose an FDD file as your export file (in which case Portrait Miner automatically creates one or more associated data files), the option to generate an FDD file is already checked.

You can include field names at the top of your data files by checking the Column Headings option.

You can export data in a fixed-width format by checking the Fixed Column Width option. Column widths in this format depend on the type and size of each field.

Exporting records to a SAS file or other third-party dataset

Portrait Miner can export data in various third-party statistical formats, including those for SAS, SPSS, and Excel.

In Portrait Miner, right-click on the focus that you want to export, and choose Export>for Another Program.

In the Export for Another Program dialog, you can choose the fields to export, which program to export to, and change the location of the output file.

Note:
  • You can choose which fields to export either by selecting field names or by choosing one or more tags [see Working with field groups].
  • If you do not specify which fields to export, Portrait Miner exports all fields in the focus.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsexportstat.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export

Exporting records to a focus using Portrait Miner

You can export a subset of the fields or records from an existing focus to a new focus.

In Portrait Miner, right-click on the focus that you want to export, and choose Export>as Focus. In the Export as Focus dialog box, you can choose the fields to export, and where to save the exported focus. You can also select a subset of the records in the focus using an FDL expression [see Expressions].

Note:
  • You can choose which fields to export either by selecting field names or by choosing one or more tags [see Working with field groups].
  • If you do not specify which fields to export, Portrait Miner exports all fields in the focus.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsimportfocus.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export


About combining foci

Portrait Miner provides two ways of combining the fields from multiple foci to create a new focus, the first of which ("focus join") is a variant of a left join. You can use focus join in Portrait Miner [see To join fields from one focus to another focus using Portrait Miner] or via the qsjoin Portrait Miner data-build command.

The second method uses Decision Studio to import fields from a focus in a variant of a two-table left join.

You can also merge the records of multiple foci, in Portrait Miner [see Merging records from two foci] or via the qsmerge Portrait Miner data-build command.

See also

dblookup

Merging records from two foci

Parent topic: Working with flat files, database tables, and foci


To join fields from one focus to another focus using Portrait Miner

Given two foci that share key fields of the same name and type, you can join selected fields from one focus to the other to create a new focus, provided that both foci are sorted [see To sort a focus] by the key fields (according to the standard Portrait Miner collation order).
To join fields from one focus to another:
  • In Portrait Miner, right-click on the initial focus and choose Combine>Join Fields.

In the Join Fields dialog box, you can choose the secondary focus from which the fields will be added, and up to three key fields used to join the selected fields to the primary focus. You can also change the location of the new focus or, rather than create a new focus, choose to overwrite a previously created output focus.

Note:
  • The join operation is essentially a left join (with your initial focus being the table on the left). However, if there is a customer with more than one record in the initial focus, Portrait Miner matches the records for that customer with successive records for the same customer in the other focus. The number of records in the new focus is always the same as the number of records in the initial focus.
  • The key fields in the two foci must be both string fields, both date fields, or both numeric fields.
  • You can choose which fields to add either by selecting field names or by choosing one or more tags [see Working with field groups].
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsjoin.

See also

About Portrait Miner wizards

About combining foci

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Working with flat files, database tables, and foci


To join fields from one focus to another focus using Decision Studio

If two foci share key fields of the same name and type, you can join selected fields from one focus to the other to create a new focus. To do this, you must ensure that both foci are sorted by the key fields, in accordance with the standard Portrait Miner collation order.
  1. Open the first focus in Decision Studio and choose Focus>Import Fields.
  2. Browse [see Browsing to open or save a file, session or database table] to the second focus and click on Import.

    The Import Fields dialog box appears:

  3. In the Select join key field pane, choose the corresponding key fields for the first focus and the second focus.
  4. Click on Select Fields in the Select Fields pane, to select the fields that you want to include from the second focus. At the very least, you must exclude the external key field for the join.

    The Select Fields dialog box appears, with all fields from the second focus initially in the Include pane:

    Use the arrow buttons between the Exclude and Include panes to choose the fields that you want to join.

    The [image] and [image] buttons move highlighted fields, while the [image] and [image] buttons move all fields from one pane to the other.

    Use the [image] and [image] buttons at the right of the window to rearrange highlighted fields in the Include pane.

  5. Back in the Import Fields dialog box, click on OK.
Note:
  • The join operation is essentially a left join (with the first focus being the table on the left). However, if there is a customer with more than one record in the second focus, Decision Studio only considers the first record for that customer. Therefore, when you join fields to a focus using Decision Studio, the number of records in the focus always remains the same.
  • Decision Studio automatically excludes any field in the second focus that has the same name as a field in the first focus.
  • The key fields in the two foci must be both string fields, both date fields, or both numeric fields.

See also

About combining foci

To join fields from one focus to another focus using Portrait Miner

Parent topic: Working with flat files, database tables, and foci


Merging records from two foci

Given two foci with fields of the same names and types and records sorted [see To sort a focus] by the key fields (according to the standard Portrait Miner collation order), you can merge the records in the foci to create a new focus that contains the records from both foci. The new focus is sorted in the same way as the original foci.

In Portrait Miner, right-click on the primary focus and choose Combine>Merge Records.

In the Merge Records dialog, choose the secondary focus, and specify the key fields. You can also choose a location for the output focus.

Note:
  • By default, a record from the secondary focus that has the same keys as a record in the primary focus is discarded. You can change this behavior by checking the appropriate box in the dialog box.
  • In order to merge two foci, the fields to be merged must contain compatible data types.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsmerge.

See also

About Portrait Miner wizards

About combining foci

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Working with flat files, database tables, and foci


To set up a database connection

To be able to connect to a database, you first need to set up a database connection.
  1. In Portrait Miner, under the Databases tab, click on New Connection.

    The Edit Database Connection dialog box appears.

  2. Enter the DSN (data source name) for the database.

    Ask your system administrator if you don't know what this is.

  3. Enter the username and password that you use to connect to the database.
  4. Click on OK.

    A new database connection appears in the list of available databases in Portrait Miner.

Note:
  • Portrait Miner stores your database connections on disk in encrypted form. Once you have set up a database connection, you don't need to reenter your username or password for the database unless they change. If you do need to amend your connection details, highlight the connection in the Available Databases pane of the Databases tab and click on Edit Connection.
  • Your system administrator may have set up a "partial" database connection for you, consisting of just a DSN. Before you can connect to the database, you need to complete the database connection: highlight the partial database connection and click on Edit Connection to enter your username and password.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsdbaccess.

See also

How Portrait Miner imports database types

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Working with flat files, database tables, and foci


How Portrait Miner imports database types

Parent topic: Working with flat files, database tables, and foci

Importing to Portrait Miner from a database

Portrait Miner maps the following database types into its datatypes, based on the size of the database type and the Databases preference settings.
Database type | Scale | Precision | represent large integers as strings | preserve numeric types on import | Portrait Miner field type
char, char2, varchar, varchar2, nchar, nchar2, nvarchar, nvarchar2 |  |  |  |  | string
date, time, timestamp, datetime, smalldatetime |  |  |  |  | date
int, integer, tinyint, smallint, byteint, bit |  |  |  |  | integer
bigint |  |  | false false true | true false | real string string
decimal, dec, numeric, number | < 0 | 15 > 15 > 15 |  | true false | real real string
decimal, dec, numeric, number | 0 | 0 10 > 10 [image] 15 > 15 > 15 > 10 | false false false true | true false | real integer real real string string
float, double, real |  |  |  |  | real
decimal, dec, numeric, number | > 0 | 15 > 15 > 15 |  | true false | real real string
money |  |  |  | true false | real string
smallmoney |  |  |  |  | real
Note:
  • In rows marked with [image], there may be some loss of precision.
  • In rows marked with [image], values too large to store as integer will be converted to Null.

See also

represent large integers as strings

preserve numeric types on import

Exporting from Portrait Miner to a database

The database types that Portrait Miner exports depend on both the target database and the ODBC driver. Portrait Miner suggests a suitable type for the database that you specify, while the ODBC driver interprets that suggestion into one of types in that database.

See also

To set up a database connection


Using the Data Build Manager for data import, processing, and export

The Data Build Manager is a Portrait Miner application that supports data preparation and model deployment.

To build a focus or deploy a model, you typically use a sequence of data-build commands [see Using Portrait Miner data-build commands for data import, processing, and export] and other operations. Doing this manually takes time, and it is easy to make mistakes along the way. You may also prefer to run a regular data-build or deployment process unattended, perhaps overnight. If something goes wrong (such as running out of disk space), you probably want to fix the problem and carry on from where you left off, rather than starting all over again. Likewise, if the operations needed for successive builds overlap to some extent, you might save on processing time by performing such operations once only. But it is hard to keep track of dependencies between operations, and easy to forget which operations have already been done.

The Data Build Manager uses a special file called a "build plan," which describes how to build an analysis dataset or deploy a model. The build plan contains a number of "targets" with dependencies between them, and the sequences of operations required to build the targets.

To open a build plan (a .qsb file):
  • In Portrait Miner, double-click on the file, or right-click on the file and choose Open.

You can examine the details of the build plan by clicking on elements in the Build plan pane, and viewing their descriptions in the pane on the right.

The hierarchy (or "tree") of elements in the Build plan pane is reminiscent of the file-system view in Portrait Miner or Windows Explorer, and you can expand and collapse parts of the view in a similar way. Use Options>Expand tree (resp. Options>Collapse tree) to show the fully expanded (resp. collapsed) hierarchy.

At the top of the hierarchy is an element representing the build plan itself. Other elements of particular interest are the targets (marked with [image] or similar) and the parameters (marked with [image]).

To assign a value to a parameter, highlight the parameter in the Build plan pane, and edit the value in the Parameter pane on the right.

Once you have set parameters appropriately, execute your build plan by clicking on Build. A progress window appears. While the job is running, you can click on Stop to halt execution of the build plan. Once the job is complete, click on Done to close the progress window.

Note:
  • The build plan uses an XML-based file format. For more information on the Data Build Manager and the format of build plans, see Using the Data Build Manager.
  • The Data Build Manager is a way of accessing the functionality provided by the Portrait Miner data-build command qsbuild.

See also

Using Portrait Miner data-build commands for data import, processing, and export

XML in Portrait Miner

Parent topic: Working with flat files, database tables, and foci


Using Portrait Miner data-build commands for data import, processing, and export

As well as applications like Portrait Miner and Decision Studio, Portrait Miner includes a comprehensive suite of command-line utilities called Portrait Miner data-build commands. You can use data-build commands for a variety of tasks:
  • Data import/export between foci, flat files, and database tables
  • Processing data in foci (sorting, derivation, measurement, etc.)
  • Joining foci
  • Managing focus files (copying, moving, renaming, and deleting)
  • Producing reports

The data-build commands are particularly useful for automating complex data-build processes, as you can combine them in UNIX shell scripts or Windows batch files.

See Portrait Miner data-build command and TML reference for detailed information on individual commands.

Note: To use the data-build commands, you must have command-line access to Portrait Miner. Ask your system administrator to configure your command path to include the directory containing the commands.

See also

Using the Data Build Manager for data import, processing, and export
Parent topic: Working with flat files, database tables, and foci


Working with Decision Studio

  • Working with Decision Studio Tools
  • Working with lists and tabular data in Decision Studio
  • Working with Decision Studio


Working with Decision Studio Tools

  • Decision Studio tools
  • Tool relationships
  • To link and unlink tools
  • To maximize screen space for a Decision Studio tool
Parent topic: Working with Decision Studio


Decision Studio tools

These Decision Studio tools are available for visualizing, segmenting, and modeling customer datasets:
Tool | Purpose
Table Viewer
  • Viewing your focus, at the level of individual customer records
  • Deriving fields using FDL
Binning Editor | Grouping customer records into bands of values or categories in a field
Crosstab Viewer | Viewing summary data in tabular form
Crossdistribution Viewer | Viewing summary data as a one- to three-variable crossdistribution graph
Profile Viewer | Viewing summary data in a set of one-variable segmentations
Map Viewer | Viewing summary data on a geographical or other pre-defined map
Decision Tree Builder | Building decision-tree segmentations of your customer dataset
Scorecard Builder | Building scorecard models of your customer dataset
Cluster Builder | Building clustering models of your customer dataset

To start a Decision Studio tool, either choose its name from the Tools menu or click on the corresponding button on the toolbar.

Parent topic: Working with Decision Studio Tools


Tool relationships

Every Decision Studio tool [see Decision Studio tools] needs a source of data, whether it be data to be displayed or data on which to base a model. Normally, the source of data for a tool is the focus that is currently open, taking account of any record selections [see Selecting customer records] that are in place.

You can also make one or more tools follow another [see To link and unlink tools], so that whenever you highlight a segment [see Highlighting segments in a graphical display] in the leading tool the following tools treat that segment as their data source.

A following tool can also lead another tool. You can see how tools are related to one another in the Decision Studio window's tool hierarchy pane, which is on the 'Focus' tab on the left hand side of the main window. Note that this is not the default tab so is typically hidden:

In this example, Table Viewer 5 and Profile Viewer 6 are both using the focus "DBUSA" as their data source. Crossdistribution Viewer 4 is following Profile Viewer 6.

Note:
  • When no segments are graphically highlighted in a tool (always the case if the tool is a Table Viewer, Scorecard Builder, or Cluster Builder instance), the tool's own source of data is used as the data source for any following tools.
  • Just as a focus can have binnings associated with it, so can the output of a tool. You can modify the binnings that are associated with the output of a tool by linking a Binning Editor to that output [see To link and unlink tools]. But if you select different segments in the tool (so that the output changes), Decision Studio discards any binnings that you have created.

See also

To show more detail in a selected segment of a graph
Parent topic: Working with Decision Studio Tools

Viewing the tool hierarchy selectively

  • Click on a [image] (collapsed) or [image] (expanded) symbol to expand or collapse part of the tool hierarchy view.

To bring a tool window to the foreground

Either double-click on the tool name in the tool hierarchy pane or right-click on the tool name and choose Bring To Front.


To link and unlink tools

Parent topic: Working with Decision Studio Tools

To link an open tool to the output of another tool

At the top right of each tool's toolbar there is a drop down menu titled Leader, where another tool may be selected as the data source. Alternatively, in the tool hierarchy pane [see Tool relationships] of the Decision Studio window, drag the icon representing the desired following tool and drop it on the icon representing the desired leading tool.

To open a new tool following another tool

In the tool hierarchy pane [see Tool relationships] of the Decision Studio window, click to highlight the name of the desired leading tool.

Any tools that you start subsequently are linked to the highlighted tool.

To revert to the default behavior for new tools, highlight the focus at the top of the tool hierarchy pane instead.

Note: You can also start a linked tool by right-clicking on a prospective leader in the tool hierarchy pane and choosing the prospective follower from the Drilldown in menu.

See also

To show more detail in a selected segment of a graph

To break a link between tools

Do one of the following:
  • In the Leader drop down menu on the tool bar select None.
  • In the tool hierarchy pane [see Tool relationships] of the Decision Studio window, drag the icon representing the following tool and drop it on the icon representing the focus.
  • Link the following tool to a different leading tool.
  • Close the leading tool.

    The tool that was following is then linked to the focus or tool that provided the data source for the original leading tool.

Note: If you drag a tool icon to a different place in the tool hierarchy, any tools that are linked to that tool continue to follow it.


To maximize screen space for a Decision Studio tool

Choose View or press F11

This maximizes the window and hides the toolbar and other user-interface elements, to increase the space available for viewing the main area of the window.

Repeat the action to return to the original view.

Parent topic: Working with Decision Studio Tools


Working with lists and tabular data in Decision Studio

  • Sorting in lists and tables
  • Exporting tabular data from Decision Studio
  • To set the display format for numeric and date values
Parent topic: Working with Decision Studio


Sorting in lists and tables

In most tables in Decision Studio (notable exceptions being views in the Table Viewer and Crosstab Viewer), you can reorder the rows in various ways, by right-clicking on a column header and choosing a sorting option.

Similarly, in most lists in Decision Studio, you can reorder the list items by right-clicking anywhere in the list pane.

In most cases, three standard sorting options are available: unsorted (that is, the default order), ascending and descending; but there may be additional options depending on the kind of data in the list or column.

Note:
  • In most places, if you click repeatedly (with the left mouse button) on the header of a table column that has sorting options, Decision Studio cycles through the available options. If there are a lot of options, it is usually easier to right-click and choose from the menu; but for columns with only the three standard sorting options, the desired row ordering is at most two clicks away.
  • In the Decision Studio window, the Interpretations column has options for sorting by each of the possible interpretation types. When you choose Sort by Categorical, for instance, Decision Studio displays fields with categorical binnings before other fields.
  • The User Tags column on the main window connot be sorted.
  • Sorting rows in a table or items in a list usually only affects the way that the information appears in the current context. An exception is reordering categories [see To reorder categories] in a categorical binning: any Decision Studio tool that uses the binning shows the bins in the order that you specify in the Binning Editor.

See also

To sort a focus
Parent topic: Working with lists and tabular data in Decision Studio


Exporting tabular data from Decision Studio

You can use Edit>Copy to copy tabular data from Decision Studio tools to the clipboard, as you would in other Windows applications. There are also four variants of the standard clipboard copy operation:
Option | Purpose
Copy All Tables | Copy cells from all tabbed panes, instead of from just the current one.
Copy without Headers | Omit row and column headings.
Copy with Repeated Labels | Repeat headings for each row and column (you may find this useful for creating pivot tables in Excel).
Copy Expanded Segments | Copy the data in a two-column list format, instead of a tabular format.

It is also possible to highlight cells in a tabular view, and drag the data directly to Windows applications (such as Microsoft Excel) that can read data in a tabular format.

You can also copy tabular views and crosstab [see Crosstabs as a basis for segmenting and visualizing data] data from Decision Studio directly to Microsoft Excel, and if you have tabular data in Decision Studio that you would like to share with colleagues, you can e-mail it to them.

Parent topic: Working with lists and tabular data in Decision Studio

Highlighting regions of a table

You can highlight one or more rectangular regions in a tabular view as you would in other Windows applications. In most tabular views, you can also click on headings to highlight complete rows or columns of the table.

Exporting tabular data to Microsoft Excel

You can copy tabular views or underlying crosstab data to Excel:
  • To copy a tabular view to Excel, do one of the following:
    • In the Table Viewer, choose File>View to Excel.
    • In the Decision Tree Builder, Scorecard Builder, or Cluster Builder, choose File>Export>View to Excel.
    • Click on [image] on the toolbar.
  • To copy crosstab data from the Crosstab Viewer or Profile Viewer to Excel, choose File>Export>Crosstab to Excel, or click on [image] on the toolbar.
Note:
  • A new workbook is created when exporting data to Excel.
  • If you highlight cells in a tabular view [see Highlighting regions of a table], Decision Studio exports only those cells to Excel. Otherwise, the entire table or crosstab is exported.
  • By choosing View as Excel Link instead of View to Excel, or Crosstab as Excel Link instead of Crosstab to Excel, you create a dynamic link, so that any changes in your tabular view or crosstab are automatically propagated to Excel.


To set the display format for numeric and date values

  1. In the Decision Studio window, choose Edit>View Preferences.

    The Format dialog box appears. One of its five tabbed panes controls the display formats for numeric and date values:

    Pane | Description
    Data Display | The number of displayed decimal places for numbers; the alignment of numbers; whether to strip trailing zeroes when displaying decimal fractions; whether to use a (locale-specific) thousands separator when displaying numbers; Whether to display dates as American (MM/DD/YYYY), European (DD/MM/YYYY), or YMD (YYYY/MM/DD); whether to display times according to a 12-hour or 24-hour clock
  2. Click on OK, to confirm any changes and close the dialog box.
Note: Your settings apply throughout the current session, and for future Decision Studio, and Portrait Miner sessions. However, they do not apply to the import and export of flat files, or the evaluation of FDL expressions.

See also

To set global options for graphical displays
Parent topic: Working with lists and tabular data in Decision Studio


Working with Decision Studio

  • To orient a graphical display using the mouse
  • Highlighting segments in a graphical display
  • Exporting graphical views from Decision Studio
Parent topic: Working with Decision Studio


To orient a graphical display using the mouse

Drag the graph or decision tree view using one of the three mouse buttons:
  • To rotate the graph, drag with the left mouse button.
  • To move the graph from side to side or vertically, drag with the right mouse button.
  • To move the graph toward you or away from you, drag up/down with the middle mouse button.
Note:
  • If your mouse has only two buttons, you can emulate the middle mouse button by holding down the Alt key while pressing the left mouse button.
  • When moving a decision tree with the right mouse button, drag on the background, to avoid the pop-up menu that appears when you right-click on a segment.
Parent topic: Working with Decision Studio

To restore the original view

Choose View>Home or click on [image] on the toolbar.

Note:

In the Map Viewer, if the menu option View>Auto is checked, the original view may have been from above, rather than the view that corresponds to the View>Home option.

To view a map graph from above

Choose View>Top or click on [image] on the toolbar.

To zoom in on selected segments in a decision tree

  1. Highlight the segments [see Highlighting segments in a graphical display] that you are interested in.
  2. Choose View>Zoom on Selection or click on [image] on the toolbar. Alternatively, you can right-click on one of the highlighted segments, and choose Zoom on Selection.

    The Decision Tree Builder zooms in (or out) so that the highlighted segments and their subsegments are visible.

Note:

If no segments are highlighted, View>Zoom on Selection (or [image]) has the same effect as View>Home (or [image]).


Highlighting segments in a graphical display

You can highlight segments in graphical displays in the Binning Editor, Profile Viewer, Crossdistribution Viewer, Map Viewer, and Decision Tree Builder. Highlighted segments can be used as a data source for linked tools [see Tool relationships], and can be used to derive fields [see To derive a field from a graphical segmentation] describing them.
Parent topic: Working with Decision Studio

To highlight a single segment

Click on the segment to highlight it.
Note:
  • If the segment is already highlighted as part of a group of segments, click on the background first to clear the existing highlighting.
  • In the Map Viewer, to highlight a segment that is represented by a line link (as opposed to a block), click on the arrow in the middle of the line link.

To clear highlighting or extend it to more than one segment

Do one of the following:
  • Hold down CTRL on the keyboard and click on a segment.

    The segment is highlighted if it wasn't highlighted before and vice versa.

  • Hold down CTRL on the keyboard and drag with the left mouse button to create a "rubber band" rectangle.

    When you release the mouse button, segments that lie wholly or partially within the rectangle are highlighted if they weren't before and vice versa.

Note: In the Map Viewer, you can select blocks or line links, but not both at once. If you drag a "rubber band" rectangle over a region containing both blocks and line links, only the blocks are selected.


Exporting graphical views from Decision Studio

If you have a graphical view in the Profile Viewer, Crossdistribution Viewer, Map Viewer, Decision Tree Builder, or Scorecard Builder, and you would like to include it in a report or share it with colleagues, you can save the view as a file.
Parent topic: Working with Decision Studio

To save a graphical view to a file

In the Profile Viewer, Crossdistribution Viewer, Map Viewer, Decision Tree Builder, or Scorecard Builder, choose File>Export>View as Image, and browse [see Browsing to open or save a file, session or database table] to a location in which to save your graphical view.

Decision Studio exports your image as a JPEG file.

Note:
  • Decision Studio saves a graphical view at the same size as it appears in the viewer or modeling tool.
  • To use a saved graphical view in a report, import or place the file in your target document.
  • In the Profile Viewer, you can also use File>Export>View as HTML, to create a web page containing the current view.


Working with the PSS Connector

  • Introduction
  • Portrait Miner extensions
  • Decision Studio extensions
  • Authentication
  • Command line extensions
  • Exporting Rules from Portrait Miner User Interface
  • Exporting Rules in Batch


Introduction

The Portrait Shared Services (PSS) connector supports integration between Portrait Miner and other Portrait Suite of products, including: Portrait Dialogue, Portrait Interaction Optimizer and Portrait Explorer.

For information on installing the PSSConnector, see Installing the PSSConnector in the Miner Administration Guide.

Parent topic: Working with the PSS Connector


Portrait Miner extensions

The following extensions are available in Portrait Miner.

  • On the toolbar, the Manage connection to Portrait Shared Services button allows the user to login or logout from Portrait Shared Services. With a Windows-based Portrait Customer Analytics server, your connection to the Portrait Shared Services is established automatically using Windows Authentication, if possible. To connect using a different account, you should logout and then log back in again using the appropriate account credentials.
  • On the toolbar, the Manage rules in the Portrait Shared Repository button allows the user to view the list of analytics rules that have been published to the repository. You must select a PSS logical domain, and then you can view the rules that are published to that domain. You can export a rule back to the server filesystem as a QMML file using the Save as mouse right-click on a rule.
  • When selecting a .qmml file in Miner, the Publish rule to Portrait Shared Repository mouse right-click action will publish the model QMML as a rule to the Portrait Shared Repository. You are prompted for the name, type and description for the rule, and the name of the PSS logical domain to publish it into.

The toolbar applications are also available through the Portrait Miner Launch menu.

Parent topic: Working with the PSS Connector


Decision Studio extensions

The Portrait Shared Services extensions for Decision Studio provide the user with the ability to publish a derived field as a rule to the Portrait Shared Repository, from where it can be used by other applications.

Rules can only be published from the Table Viewer.

The Decision Studio Table Viewer also provides the Manage connection to Portrait Shared Services application, to allow the user to login or logout using an explicit username and password, or using Windows Authentication where possible. The application provides the same functionality as in Portrait Miner.

The Decision Studio Crosstab Viewer provides the ability to publish the current crosstab to the PSS. These crosstab specifications can then be used when generating reports from the Portrait Explorer application in the Marketing HQ.

Parent topic: Working with the PSS Connector


Authentication

You need to be authenticated with the Portrait Shared Services in order to manage, publish or retrieve rules stored in the Portrait Shared Repository.

If your Windows login account is configured as a Windows Authentication account in the Portrait Dialogue Admin application, then the Miner applications will automatically authenticate you, and you do not need to take any explicit action to login. Such accounts do not require any -username or -password options for the command-line utilities either.

If you are using a login account that is not configured to use Windows Authentication, then you must login from Portrait Miner explicitly. The Portrait Miner and Decision Studio applications will automatically prompt you for login credentials if you have not already logged in. Command line utilities require explicit -username and -password options.

Once you have logged in from one of the Portrait Miner applications, you remain logged in for that application, until you exit or explicitly log out. You must authenticate separately for each application you run.

Parent topic: Working with the PSS Connector


Command line extensions

Data Build Command extensions

The following DBCs are provided by the extension. The commands all require explicit -username and -password arguments, unless Windows Authentication is enabled in Portrait Campaign Manager for your user account.

  • DBCs for Mappings (.xml files)
  • DBCs for Rules (.qmml files)
  • DBCs for Decision Optimizations (.qsor files)
  • DBCs for Explorer Datasets
Parent topic: Working with the PSS Connector


DBCs for Mappings (.xml files)

  • pssmappingpublish
  • pssmappingretrieve
Parent topic: Command line extensions


pssmappingpublish

The command is used to publish a set of rule-input mappings to a customer domain in the Portrait Shared Repository. The parameters for the command are as follows:
Publish a rule input-mappings file to the Portrait Shared Repository

     Required:
       -domain <domain name>
          The Portrait Campaign Manager customer domain to publish the mappings
          into
       -input <XML mappings file>
          The file containing the rule-input mapping definition

     Optional:
       -username <username>
          The Portrait Shared Services user account to use. Optional if you can
          connect using Windows Authentication.
       -password <password>
       The password for the Portrait Shared Services user account.
Parent topic: DBCs for Mappings (.xml files)


pssmappingretrieve

The command retrieves a set of rule input-mappings for a customer domain and saves them as an XML file. The parameters for the command are as follows:
Fetch rule input-mappings from the Portrait Shared Repository and save to a file.

     Required:
       -domain <domain name>
          The Portrait Campaign Manager customer domain to fetch the mappings
          from.
       -output <XML mappings file>
          The name of the file for the mapping definition to be written to.

     Optional:
       -username <username>
          The Portrait Shared Services user account to use. Optional if you can
          connect using Windows Authentication.
       -password <password>
       The password for the Portrait Shared Services user account.
Parent topic: DBCs for Mappings (.xml files)


DBCs for Rules (.qmml files)

  • pssrulepublish
  • pssrulelist
  • pssruleretrieve
  • pssruledescribe
Parent topic: Command line extensions


pssrulepublish

The command is used to publish the contents of a QMML file as a rule to the Portrait Shared Repository. The parameters for the command are as follows:
Publish a QMML rule to the Portrait Shared Repository.

     Required:
       -domain <domain name>
          The Portrait Campaign Manager customer domain into which the rule is
          to be published.
       -name <rule name>
          The name to be used to publish this rule in the repository.
       -description <text | @filename>
          Description for the rule. If the @filename form is used, take the
          description from a file. Optional with -replace.
       -type <Value | Propensity | Uplift>
          The type of the rule being published - Value, Propensity or Uplift.
          Optional with -replace.
       -input <QMML file>
          The name of the QMML file containing the rule. The file must contain
          only a single ruleset and the ruleset must have a single output.

     Optional:
       -username <username>
          The Portrait Shared Services user account to use. Optional if you can
          connect using Windows Authentication.
       -password <password>
          The password for the Portrait Shared Services user account.
       -replace
          Replace the QMML for an existing rule rather than publish a new one.
          When replacing, the -type and -description parameters are optional.
Parent topic: DBCs for Rules (.qmml files)


pssrulelist

The command is used to list the details of all of the rules associated with a specified domain. The list of rules is returned in plain text form, but can also be reported as an XML document. The parameters for the command are as follows:
List all of the rules in a customer domain in the Portrait Shared Repository.

     Required:
       -domain <domain name>
          The customer domain to fetch the rules from.

     Optional:
       -username <username>
          The Portrait Shared Services user account to use. Optional if you can
          connect using Windows Authentication.
       -password <password>
          The password for the Portrait Shared Services user account.
       -xml
          Show output in XML format.
Parent topic: DBCs for Rules (.qmml files)


pssruleretrieve

The command retrieves the compiled QMML for a rule in the Portrait Shared Repository. The parameters for the command are as follows:
Fetch a QMML rule from the Portrait Shared Repository and save it to a file.

     Required:
       -domain <domain name>
          The customer domain to fetch the rule from.
       -name <rule name>
          The name of the published rule in the Portrait Shared Repository.
       -output <QMML file>
          The name of the file where the rule is to be saved to.

     Optional:
       -username <username>
          The Portrait Shared Services user account to use. Optional if you can
          connect using Windows Authentication.
       -password <password>
          The password for the Portrait Shared Services user account.
Parent topic: DBCs for Rules (.qmml files)


pssruledescribe

The command lists the names and types of the inputs to, and output from, a rule in the Portrait Shared Repository. It also shows how the rule input-mappings will apply, by describing the mapping to a field or function, if a mapping is defined. The parameters for the command are as follows:
Describe a QMML rule in the Portrait Shared Repository.

     Required:
       -domain <domain name>
          The Portrait Campaign Manager customer domain
       -name <rule name>
          The name of the rule in the customer domain

     Optional:
       -username <username>
          The Portrait Shared Services user account to use. Optional if you can
          connect using Windows Authentication.
       -password <password>
       The password for the Portrait Shared Services user account.
Parent topic: DBCs for Rules (.qmml files)


DBCs for Decision Optimizations (.qsor files)

  • pssoptpublish
  • pssoptlist
  • pssoptretrieve
  • pssoptreport
  • pssoptdescribe
Parent topic: Command line extensions


pssoptpublish

The command is used to publish the contents of a QSOR decision optimization results file to the Portrait Shared Repository. The parameters for the command are as follows:
 Publish a decision optimization to the Portrait Shared Repository.

     Required:
       -domain <domain name>
          The Portrait Campaign Manager customer domain into which the optimization
          is to be published.
       -name <optimization name>
          The name to be used to publish this optimization in the repository.
       -description <text | @filename>
          Description for the optimization. If the @filename form is used, take the
          description from a file. Optional with -replace.
       -input <QSOR file>
          The name of the decision optimization result file.

    Optional:
       -username <username>
          The Portrait Shared Services user account to use.
       -password <password>
          The password for the Portrait Shared Services user account.
       -replace
           Replace the details for an existing optimization rather than publish a
           new one. When replacing, the -description parameter is optional.
Parent topic: DBCs for Decision Optimizations (.qsor files)


pssoptlist

The command is used to list the details of all ofo the decision optimizations associated with a specified domain. The list of optimizations is returned in plain text form, but can also be reported as an XML document. The parameters for the command are as follows:
List all of the decision optimizations in a particular customer domain in the
Portrait Shared Repository.

     Required:
       -domain <domain name>
          The customer domain to fetch the optimizations from.

     Optional:
       -username <username>
          The Portrait Shared Services user account to use.
       -password <password>
          The password for the Portrait Shared Services user account.
       -xml
          Show output in XML format.
Parent topic: DBCs for Decision Optimizations (.qsor files)


pssoptretrieve

The command retrieves a decision optimization from the Portrait Shared Repository. The parameters for the command are as follows:
Retrieve a decision optimization from the Portrait Shared Repository and save it to a file.

     Required:
       -domain <domain name>
          The customer domain to fetch the optimization from.
       -name <optimization name>
          The name of the published decision optimization in the Portrait
          Shared Repository.
       -output <QSOR file>
          The name of the file where the optimization is to be saved to.

     Optional:
       -username <username>
          The Potrait Shared Services user account to use.
       -password <password>
          The password for the Portrait Shared Services user account.
Parent topic: DBCs for Decision Optimizations (.qsor files)


pssoptreport

The command retrieves the report associated with a decision optimization from the Portrait Shared Repository and saves it to a file. The parameters for the command are as follows:
Fetch a report associated with a decision optimization from the Portrait
Shared Repository and save it to a file.

     Required:
       -domain <domain name>
          The customer domain to fetch the optimization from.
       -name <optimization name>
          The name of the published decision optimization in the Portrait
          Shared Repository.
       -output <HTML file>
          The name of the file where the report is to be saved to.

     Optional:
       -username <username>
          The Portrait Shared Services user account to use. Optional if you can
          connect using Windows Authentication.
       -password <password>
          The password for the Portrait Shared Services user account.
Parent topic: DBCs for Decision Optimizations (.qsor files)


pssoptdescribe

The command lists the names of the outcomes, and the names and types of the inputs to, and output from, a decision optimization rule in the Portrait Shared Repository. It also shows how the rule input-mappings will apply, by describing the mapping to a field or function, if a mapping is defined. The parameters for the command are as follows:
Describe a decision optimization in the Portrait Shared Repository.

     Required:
       -domain <domain name>
          The Portrait Campaign Manager customer domain
       -name <optimization name>
          The name of the optimization in the customer domain

     Optional:
       -username <username>
          The Portrait Shared Services user account to use. Optional if you can
          connect using Windows Authentication.
       -password <password>
          The password for the Portrait Shared Services user account.
Parent topic: DBCs for Decision Optimizations (.qsor files)


DBCs for Explorer Datasets

  • pssdatasetupdate
Parent topic: Command line extensions


pssdatasetupdate

The command is used to update an existing Portrait Explorer dataset with a new Focus file. The parameters for the command are as follows:
Publish a new dataset version for a specifically named dataset in the Portrait Shared Repository

     Required:
       -name <dataset name>
          The name of the dataset in the Portrait Shared Repository that the dataset version is for.
       -input <focus file path>
          The file path on the Portrait Analytics Web Services server machine to be uploaded as the
          dataset version.
     Optional:
       -username <username>
          The Portrait Shared Services user account to use. Optional if you can connect using Windows
          Authentication.
       -password <password>
          The password for the Portrait Shared Services user account.
       -timeout <timeout value (in minutes)>
          The maximum amount of time to wait, after the dataset version build has been initiated, for
          the build status to complete (successfully or unsuccessfully). If this argument is omitted
          or is specified with a value of 0 then the default timeout limit of 10 minutes is applied.
          Note: When the timeout has been reached and the process for this command exits, the dataset
          version build will continue on the server. You may contact an Explorer admin user to verify
          whether the dataset version build did later complete successfully or not.
Parent topic: DBCs for Explorer Datasets


Exporting Rules from Portrait Miner User Interface

  • Exporting Rules from Decision Studio
  • Export Rules from Portrait Miner
  • Creating contact optimization rules
Parent topic: Working with the PSS Connector


Exporting Rules from Decision Studio

The PSSConnector plug-in component adds new toolbar buttons to the Portrait Miner Decision Studio module user interface specifically; a Publish rule to the Portrait Shared Repository button is added to the Table Viewer tool.

This button allows you to export a derived field rule definition to the selected Customer Domain in Portrait Dialogue. If you provide a Name of a rule which already exists, the definition of the rule will be updated.

The Decision Studio Table Viewer also provides a button to start the Manage connection to Portrait Shared Services application, to allow you to login or logout using an explicit username and password, or using Windows Authentication where possible.

This user interface is a way of accessing much of the functionality provided by the data-build command pssrulepublish.

Parent topic: Exporting Rules from Portrait Miner User Interface


Export Rules from Portrait Miner

Portrait Miner has been extended to provide an alternative interface for you to integrate analytical results with Portrait Dialogue.
  • Authentication: On the Portrait Miner toolbar, the Manage connection to Portrait Shared Services application allows you to login or logout from Portrait Shared Services.

    With a Windows-based Portrait Miner server, your connection to the Portrait Shared Services is established automatically using Windows Authentication, if possible.

    To connect using a different account, you should logout and then log back in again using the appropriate account credentials.
  • Viewing exported rules: On the Portrait Miner toolbar, the Manage rules in the Portrait Shared Repository application allows you to view the list of analytics rules that have been published. You must select a Customer Domain, and then you can view the rules that are published to that domain. This user interface is a way of accessing much of the functionality provided by the data-build commands pssrulelist and pssruledescribe.

    You can export a rule back to the server filesystem as a QMML file using the Save as mouse right-click on a rule.This user interface is a way of accessing much of the functionality provided by the data-build command pssruleretrieve.

  • Exporting rules: When selecting a .qmml file in the Portrait Miner, the Publish rule to Portrait Shared Repository mouse right-click action allows you to publish the model (QMML) description as a rule for use in Portrait Dialogue. You are prompted for the name, type and description for the rule, and the name of the customer domain to publish it into. This user interface is a way of accessing much of the functionality provided by the data-build command pssrulepublish.

The toolbar applications are also available through the Portrait Miner Launch menu.

Parent topic: Exporting Rules from Portrait Miner User Interface


Creating contact optimization rules

Portrait Optimizer is an extension to Portrait Miner which allows you to create and deploy contact optimization rules to Portrait Dialogue. You can find out more details in the Portrait Optimizer user guide.

Parent topic: Exporting Rules from Portrait Miner User Interface


Exporting Rules in Batch

The following Data Build Commands (DBCs) are provided to allow you to export analytical rules to Portrait Dialogue as part of a batch or scheduled process. The commands all require explicit -username and -password arguments, unless Windows Authentication is enabled for your user account.

  • Data Mapping
  • Rule Integration
  • Contact optimization integration
Parent topic: Working with the PSS Connector


Data Mapping

If your analytic datasets are built using field names that are different from the underlying field names in Portrait Dialogue or Interaction Optimizer, or need to be resolved by Portrait Dialogue expressions rather than field references (for example, if analytics is being performed on a transaction measurement), then you must publish a rule input mappings definition. This controls how Portrait Dialogue or Interaction Optimizer sources the data for input values required by the analytics rule from the target system, when an analytics rule or decision optimization is executed within a Portrait Dialogue dialog activity or an Interaction Optimizer interaction.

Note:
  • There should be a one-to-one mapping for each field in the mapping file – multiple mappings per source or destination field are not permitted.
  • pssmappingpublish
  • pssmappingretrieve
  • Rule input mapping format
Parent topic: Exporting Rules in Batch


pssmappingpublish

Publish a set of rule-input mappings to a PSS logical domain.

Synopsis
pssmappingpublish -domain <domain name>-input <XML mappings file>
    [-password <password>][-replace][-username <username>]

Optional arguments

Option | Effect
-password | The password for Portrait Shared Services.
-username | The username for Portrait Shared Services.
Parent topic: Data Mapping


pssmappingretrieve

Retrieve a set of rule input-mappings for a PSS logical domain and save them as an XML file.

Synopsis
pssmappingretrieve -domain <domain name>
    -output <XML mappings file> -target <the name of the target system the mapping is for>
    [-password <password>][-replace][-username <username>]

Optional arguments

Option | Effect
-password | The password for Portrait Shared Services.
-username | The username for Portrait Shared Services.
Parent topic: Data Mapping


Rule input mapping format

A rule-input mappings file is XML-based and it provides the source (how the field is sourced in the target system) and inputName (what the rule input is called) names. You do not need to provide mappings for fields which have the same name in both the target system and rule. The <mapping system=""> tag is used to specify for which target system the mapping should be used. To target Portrait Dialogue, the mapping system should be set to PD and for Interaction Optimizer it should be set to IO. There can only be a single mapping for any one system within a logical domain.

For example, deploying rules to Portrait Dialogue would use the following format:
<?xml version="1.0" encoding="UTF-8"?>
<mapping system="PD">
    <inputMap inputName="Analytics-RuleInputName" inputType="string" source="TargetSystem-DataSource" sourceType="FIELD or FUNCTION"/>
    ...
</mapping>

The mapping file is deployed with the pssmappingpublish DBC.

When the rule input-mappings need to be changed (for example, if you create a rule which makes use of additional fields which were not previously mapped), you can import a new set of mappings for that domain and the new mappings will take effect immediately; any subsequent execution of Analytics Rule or Decision Optimization operations in Portrait Dialogue dialogs in that domain will immediately pick up the new mapping definition.

A inputMap element in a mapping file has the following attributes:
  • inputName: This is the name of the rule input, this will generally be the name of the field in a Portrait Miner dataset on which the rule was built.
  • inputType: This attribute describes the type of the field in the Analytics environment. The attribute takes values integer, real, string or date. It is for description only - it does not have any effect on the meaning of the field mapping.
  • source: This, in conjunction with the sourceType attribute determines how the input value for the value is obtained in the target system. In Portrait Dialogue, if the sourceType value is FIELD then this attribute would specify the name of the corresponding customer domain field to use as the source for the input. If the sourceType is FUNCTION, this attribute contains the Portrait Dialogue function to use to get the input value.
  • sourceType: You can set this attribute as either sourcetype="FIELD" for either Portrait Dialogue or Interaction Optimizer,or sourcetype="FUNCTION", and specifies whether Portrait Dialogue should source the rule input from a Customer Domain field or a Portrait Dialogue expression.

If the sourcetype is defined as FUNCTION, then the value of the source attribute must be a valid Portrait Dialogue expression which returns a single value of one of the following data types: string, integer, float, datetime/date, or boolean (wherea Boolean is mapped to the integer values 0 for false and 1 for true).

Example

Here is an example of a mapping file that uses functions:

<?xml version="1.0" ?>
<mapping system="PD">
   <!-- Maps to the answer of an integer question in a
     questionnaire. Returns NULL if the customer has not answered
     that questionnaire -->
   <inputMap inputName="TI_Q1" inputType="integer" sourceType="FUNCTION"
     sourceName="AnswerInt(1014,'Q1', '')" />

   <!-- Maps to the answer of single choice question (radio buttons)
     in a questionnaire. Returns the alternative key (e.g. "A1"),
     and NULL if the customer has not answered that questionnaire
   -->
   <inputMap inputName="TI_Q2" inputType="string" sourceType="FUNCTION"
              source="AnswerSingleChoice(1014, 'Q2')" />

   <!-- Maps to the answer of a boolean alternative of a question
     (checkboxes) in a questionnaire. Returns true/false, and NULL
     if the customer has not answered that questionnaire -->
   <inputMap inputName="TI_Q2_BOOL" inputType="integer" sourceType="FUNCTION"
              source="IsAnswered(1014, 'Q2', 'A1')" />

   <!-- Checks if a message of a specific template has been created
     for the customer. Returns true/false -->
   <inputMap inputName="TI_MSG_TEMPLATE_1170" inputType="integer" sourceType="FUNCTION"
              source="hasMessages[templateid = 1170]" />

   <!-- Checks if a customer has a specific value in a category with
     values. Returns true/false -->
   <inputMap inputName="TI_CATEGORY_1011_I5" inputType="integer" sourceType="FUNCTION"
              source="hasCategories[Name = 'CATEGORY_1011' and
              Value = 'I5']" />

   <!-- Checks if a customer has been treated by a dialog operation
     (requires participant logging in the dialog). Returns
     true/false -->
   <inputMap inputName="TI_OFFER_1" inputType="integer" sourceType="FUNCTION" ~
              source="HasOperationHistory(4519)" />

   <!-- Checks if a customer has been treated by a dialog branch
     (requires participant logging in the dialog). Returns
     true/false -->
   <inputMap inputName="TI_OFFER_2" inputType="integer" sourceType="FUNCTION"
              source="HasBranchHistory(1231)" />

   <!-- Counts the number of Orders a customer has -->
   <inputMap inputName="count_orders" inputType="integer" sourceType="FUNCTION"
              source="NumberOf(Orders) " />
              </mapping>
Parent topic: Data Mapping


Rule Integration

  • pssrulepublish
  • pssrulelist
  • pssruleretrieve
  • pssruledescribe
Parent topic: Exporting Rules in Batch


pssrulepublish

Publish the contents of a QMML file as a named rule in a PSS logical domain including a description and its rule type.

Synopsis
          pssrulepublish -domain <domain name> -name <rule name>
          -description <text | @filename>
          -type <value | propensity | uplift>
          -input <QMML rule file>
          [-password <password>][-replace][-username <username>]

Optional arguments

Option | Effect
-password | The password for Portrait Shared Services.
-replace | Replace the QMML for an existing rule rather than publish a new one. When replacing, the -type and -description parameters are optional.
-username | The username for Portrait Shared Services.
Parent topic: Rule Integration


pssrulelist

List the details of all the rules associated with a specified PSS logical domain

Synopsis
          pssrulelist -domain <domain name>
          [-password <password>][-username <username>][-xml]

Optional arguments

Option | Effect
-password | The password for Portrait Shared Services.
-username | The username for Portrait Shared Services.
-xml | Show output in XML format.
Parent topic: Rule Integration


pssruleretrieve

Retrieve the compiled QMML for a named rule in a PSS logical domain to file.

Synopsis
          pssruleretrieve -domain <domain name>-name<rule name>
          -output <QMML file>
          [-password <password>][-username <username>]

Optional arguments

Option | Effect
-password | The password for Portrait Shared Services.
-username | The username for Portrait Shared Services.
Parent topic: Rule Integration


pssruledescribe

List the names and types of the inputs to, and output from, a named rule in a PSS logical domain. It also shows how the rule input-mappings will apply, by describing the mapping to a field or function, if a mapping is defined. The parameters for the command are as follows:

Synopsis
          pssruledescribe -domain <domain name>-name <rule name>
          [-password <password>][-replace][-username <username>]

Optional arguments

Option | Effect
-password | The password for Portrait Shared Services.
-username | The username for Portrait Shared Services.
Parent topic: Rule Integration


Contact optimization integration

A set of DBCs are provided with Portrait Optimizer to allow contact optimization models to be deployed to the PSS.

  • pssoptpublish
  • pssoptlist
  • pssoptretrieve
  • pssoptreport
  • pssoptdescribe
Parent topic: Exporting Rules in Batch


pssoptpublish

Deploy a contact optimization result to a PSS logical domain with a given name and description.

Synopsis
          pssoptpublish -domain <domain name> -name <optimization name>
          -description <text | @filename> -input <QSOR file>
          [-password <password>][-replace][-username <username>]

Optional arguments

Option | Effect
-password <password> | The password for Portrait Shared Services.
-replace | Replace the details for an existing optimization rather than publish a new one. When replacing, the -description parameter is optional.
-username <password> | The username for Portrait Shared Services.
Parent topic: Contact optimization integration


pssoptlist

List the contact optimizations in a PSS logical domain.

Synopsis
          pssoptlist -domain <domain name>
          [-password <password>] [-username <username>][-xml]

Optional arguments

Option | Effect
-password <password> | The password for Portrait Shared Services.
-xml | Show output in XML format.
-username <username> | The username for Portrait Shared Services.
Parent topic: Contact optimization integration


pssoptretrieve

Get a single contact optimization from a PSS logical domain and save it to a contact optimization result archive.

Synopsis
          pssoptretrieve -domain <domain name> -name <optimization name>
          -output <QSOR file>
          [-password <password>] [-username <username>]

Optional arguments

Option | Effect
-password <password> | The password for Portrait Shared Services.
-username <username> | The username for Portrait Shared Services.
Parent topic: Contact optimization integration


pssoptreport

Get a single contact optimization report from a PSS logical domain and save it to a file.

Synopsis
          pssoptreport -domain <domain name> -name <optimization name>
          -output <HTML file>
          [-password <password>] [-username <username>]

Optional arguments

Option | Effect
-password <password> | The password for Portrait Shared Services.
-username <username> | The username for Portrait Shared Services.
Parent topic: Contact optimization integration


pssoptdescribe

Get the parameters of a single contact optimization report from a PSS logical domain. It also shows how the rule input-mappings will apply, by describing the mapping to a field or function, if a mapping is defined for the specified target system.

Synopsis
          pssoptdescribe -domain <domain name> -name <optimization name>
          [-target <system name>] [-password <password>] [-username <username>]

Optional arguments

Option | Effect
-target <system name> | The name of the target system for the field mappings e.g. PD for Portrait Dialogue or IO for Interaction Optimizer.
-password <password> | The password for Portrait Shared Services.
-username <username> | The username for Portrait Shared Services.
Parent topic: Contact optimization integration


Viewing customer records in a focus

  • Viewing customer records


Viewing customer records

In Decision Studio, you can use the Table Viewer to view the raw data in individual customer records. To open the Table Viewer from the Decision Studio window, choose Tools>Table Viewer or click on [image] on the toolbar.

The Table Viewer initially shows data for the first 100 customers in your focus (the first record block), taking into account any record selections [see Selecting customer records] that are in place.

You can control the fields [see To choose the fields that you want to view] and records [see To show a different record block] that the Table Viewer shows and you can view basic statistics [see To show field statistics] for every displayed field.

Note: If a value in a string field is a URL (for example http://www.portraitsoftware.com/), the Table Viewer shows the value in blue and underlines it. You can double-click on the value to view the associated resource in your web browser.

See also

To derive a field using the Table Viewer
Parent topic: Viewing customer records in a focus

To choose the fields that you want to view

  1. Choose View>Hide / Show.

    The Hide/Show/Re-order Fields dialog box appears:

    • Use the [image] and [image] buttons between the Hide and Show panes to move highlighted fields from one pane to the other.

      The [image] and [image] buttons move all fields, regardless of highlighting.

    • Use the [image] and [image] buttons to the right of the Show pane to reorder fields.
  2. Click on OK.
Note:
  • You can also hide fields from view by highlighting them in the Table Viewer and choosing Field>Hide, or right-clicking and choosing Hide.

    To show a field that you have hidden in this way, you need to use the Hide/Show/Re-order Fields dialog box, as above.

  • Hiding and reordering fields only affects the view in the Table Viewer. The underlying focus is unchanged.

To show a different record block

Do one of the following:
  • Choose View>Next Record Block or click on [image] at the bottom of the scrollbar to see the next block of 100 records.
  • Choose View>Previous Record Block or click on [image] at the top of the scrollbar to see the previous block of 100 records.
  • Choose View>Go to Record and enter a record number to jump to a particular record block.
Note: The Table Viewer takes into account any record selections [see Selecting customer records] that are in place.

To show field statistics

Choose View>Statistics.

The Table Viewer shows the minimum non-null [see The null value] value, maximum non-null value, and number of occurrences of null in each field:

Note: For reasons of efficiency, the Table Viewer doesn't keep statistics up-to-date at all times. When field statistics are out of date, the Table Viewer shows them as grayed-out.
  • To update the statistics for a field or set of fields, highlight the fields and choose Field>Update Statistics, or right-click on a field and choose Update Statistics.


Selecting customer records in a focus

  • Selecting customer records
  • Value selection or filtering using a categorical field
  • Value selection or filtering using a non-categorical field or statistic


Selecting customer records

You can select records in a focus according to the values in a field, either by specifying a required set of values [see To select records in a focus by value] or by specifying the number of records [see To select a given number of records] that you want. Graphical viewers and modeling tools that use the focus operate on selected records only.
Note:
  • You can apply record selections based on more than one field at the same time, in which case the effect of the record selections is cumulative; that is, the selected records satisfy all the chosen conditions.
  • If there is a record selection associated with a field, an "S" appears in the Selection column in the Decision Studio window. For a non-categorical field, the selected intervals also appear in this column in standard mathematical notation, %TODO: Expand upon this. together with a "+N" or "-N" depending on whether the null [see The null value] value is included.
  • Selections can be cleared or modified even after a focus is saved and re-opened.
  • You can reduce the time a selection takes to apply by closing other windows that you no longer need.
  • The presence of a record selection does not improve the speed of operations on the focus.

See also

Focus metadata
Parent topic: Selecting customer records in a focus

To select records in a focus by value

  1. In the Decision Studio window, highlight the field that you want to use for record selection.
  2. Choose Field>Select Values or right-click and choose Select Values or click on [image] on the toolbar.

    The Select Values dialog box appears.

  3. Make a record selection based on the values in the field.

    There are different options for categorical selection [see Value selection or filtering using a categorical field] and non-categorical selection [see Value selection or filtering using a non-categorical field or statistic].

  4. Click on OK, to confirm your selection and close the Select Values window.
Note:
  • You can also open the Select Values window from most field lists via the right click menu on a field.
  • In the Crosstab Viewer, Map Viewer, Profile Viewer and Crossdistribution Viewer you can access the Select Values window by right-clicking on a field in the graph configuration area.

To select a given number of records

  1. In the Decision Studio window, highlight the numeric field that you want to use for record selection.
  2. If there is an existing record selection on the field, you must remove the selection [see To remove a record selection from a field].
  3. Choose Field>Select Quantity or right-click and choose Select Quantity.

    The Select Quantity dialog box appears:

  4. Choose whether to select the records with the highest (top) or the lowest (bottom) values.
  5. Enter either a percentage of the available records or an exact number of records, and choose "%" or "#" accordingly from the drop-down menu.
  6. Choose whether to adjust the quantity up or down in case of ties.

    It may be the case that, when all the records are sorted according to their values in the chosen field, records with the same value in the field straddle the chosen quantity threshold. Rather than arbitrarily including some of those customer records, Decision Studio offers you the choice of including them all (adjusting the quantity up) or excluding them all (adjusting the quantity down).

  7. Click on OK, to confirm your selection and close the Select Values window.
Note: Once you have made a record selection by quantity, it is indistinguishable from a record selection made by selecting values. Indeed, you can select by value [see To select records in a focus by value] to fine-tune your record selection if required. However, you can't select by quantity again without first removing the selection.

To remove a record selection from a field

  1. In the Decision Studio window, highlight the field with the associated record selection.
  2. Choose Field>Clear Selection, or right-click and choose Clear Selection, or click on [image] on the toolbar.

To remove all record selections from a focus

Choose Focus>Clear All Selections.


Value selection or filtering using a categorical field

When you use values in a categorical [see Field interpretations] field to select records by value [see To select records in a focus by value] in a focus, or apply a filter to a categorical field that is associated [see To associate a field or statistic with a crosstab/graph aspect] with some aspect of a crosstab or graph, the Select Values or Filter window looks like this:

The panes show selected and unselected categories, which are either the actual values in the field (the base categories) or the categories in the active binning [see To modify a categorical binning], if there is one.

You can move highlighted categories from one pane to another using one of the single-arrow buttons or select/deselect all categories using one of the double-arrow buttons. To swap selected and unselected categories, click on [image].

See also

To select a given number of records

Value selection or filtering using a non-categorical field or statistic

Parent topic: Selecting customer records in a focus


Value selection or filtering using a non-categorical field or statistic

When you use values in a non-categorical numeric or date field to select records by value [see To select records in a focus by value] in a focus, or apply a filter to a non-categorical field or statistic that is associated [see To associate a field or statistic with a crosstab/graph aspect] with some aspect of a crosstab or graph, the Select Values or Filter window looks like this:

The horizontal bar represents the range of values in the field or statistic, with filled portions representing selected values. The downward-pointing wedge at each end of a selected range is either filled ( [image]) to indicate that the end-point value is included in the range or outlined ( [image]) to indicate that the end-point value is excluded from the range.

When you highlight a selected range by clicking on it, the pane below the bar shows the values for the two end points, along with details of whether they are included. You can move from one selected range to another by using the arrow buttons on either side of this pane.

Note:
  • If a field or statistic has no record selection/filter associated with it, the horizontal bar in the Select Values or Filter window shows a single selected range, with both end points included.
  • The null [see The null value] value is included or excluded according to the setting of the Null Handling menu.

    If you explicitly select a given range of records, you can choose whether your selection includes records containing the null value (Always Include) or excludes them (Always Exclude or Exclude From Explicit Selection).

    To select only records containing the null value, choose Select Exclusively.

    To select all records containing a non-null value, don't select an explicit range (by changing values or dragging end points), but simply choose Always Exclude.

See also

To select a given number of records

Value selection or filtering using a categorical field

Parent topic: Selecting customer records in a focus

To add a range to the selection

Click on [image].

If there are unselected values to the right of the currently highlighted range, the new range fills the first available gap to the right. Otherwise, if there are unselected values to the left of the currently highlighted range, the new range fills the first available gap to the left. If there are no unselected values, Decision Studio divides the largest existing selected range to create a pair of new ranges.

To remove a range from the selection

  1. Click on the range to highlight it.
  2. Click on [image].
Note: To remove all selected ranges, click on [image].

To include or exclude an end point in a range

Double-click on the corresponding wedge to change its state, or highlight the range by clicking on it and choose Included or Excluded from the appropriate drop-down list.
Note:
  • You can disable the left end point of the leftmost selected range (or the right end point of the rightmost selected range) by choosing Disabled from the end point's drop-down menu (instead of Included or Excluded). The wedge marking the end point then disappears to indicate that the selected range is open-ended.
  • For a selection based on dates, ranges always include their end points.

To adjust an end point of a range

Drag the corresponding wedge left or right, or drag the entire range to change both end points simultaneously, preserving the length of the range.

Alternatively, highlight the range and enter a value in the appropriate text box.

Note: You can use the [image] or [image] button beside an end-point text box to force the end point to jump to the next lowest or highest value that actually occurs in the data.

To invert a range selection

Click on [image].

The gaps between selected ranges become the new selected ranges.


Grouping customer records by binning a field in a focus

  • To modify a categorical binning
  • To modify a non-categorical binning
  • Modifying a user-defined non-categorical binning
  • Options for displaying a binning
  • To attach an extra binning to a non-categorical field
  • Applying a binning to more than one field
  • To optimize a binning for a field


To modify a categorical binning

  1. In the Decision Studio window, highlight the categorical [see Field interpretations] field whose binning you want to modify. Choose Tools>Binning Editor, or press CTRL+B, or click on [image] on the toolbar.
  2. Alternatively, from field lists in the modeling tools, highlight the field, right-click and choose Binning Editor.
  3. Alternatively, in the graphical viewers, right-click on a field in the graph configuration area and choose Binning Editor.

    The Binning Editor opens, showing a graph of the current binning for the field that you selected. At the bottom left of the window is the Hierarchy pane, which potentially shows a hierarchy of progressively coarser-grained categorical binnings for the current field. The highlighted binning is the current binning.

    If there is no binning attached to the field, the Binning Editor creates a binning called "unnamed node," using the default parameters [see To delete a categorical binning from a field].

  4. Optionally highlight a different binning in the Hierarchy pane; or create a new one by highlighting an existing binning in the hierarchy and clicking on New.

    When you create a new binning in this way, the original binning that you highlighted is the parent of the new binning.

  5. Merge or split categories [see To merge or split categories] to create a coarser or finer binning, renaming [see To rename a category] the new categories appropriately.
  6. Reorder the categories [see To reorder categories] in the binning if desired.
  7. Click on Apply or OK to confirm your changes to the categorical binning hierarchy.

    Alternatively, click on Reset to discard all the changes that you have made to the categorical binning hierarchy since you last applied changes.

Note:
  • When you apply changes, a categorical binning hierarchy acts like a single binning. In most other respects, the individual levels of the hierarchy act like separate binnings, with the current binning being akin to the primary [see To set the primary binning for a non-categorical field] binning for a non-categorical field.
  • You can modify binnings on other fields without leaving the Binning Editor by clicking the Fields tab and highlighting the desired field.

See also

To modify a non-categorical binning
Parent topic: Grouping customer records by binning a field in a focus

To merge or split categories

  1. In the Categories pane, highlight the categories that you want to merge or the previously merged single category that you want to split.

    The Parent Categories pane shows the corresponding categories in the parent binning (or base categories).

  2. Do one of the following:
    • Click on Merge or right-click in the Categories pane and choose Merge.

      The Binning Editor merges the highlighted categories into one category, named as a combination of the original category names separated by ampersands.

    • Click on Split or right-click in the Categories pane and choose Split. The Binning Editor splits the highlighted category into its parent categories.

To rename a category

  1. In the Categories pane, either double-click on the category, or highlight the category by clicking on it then click on Rename.
  2. Enter a new name for the category and press Return.

To reorder categories

  1. Click on Reorder or right-click in the Categories pane.
  2. Choose how to reorder the categories:
    • By count, descending (+) or ascending (-)
    • Alphabetically by category name
    • By category number, ascending
Note: When ordering a binning by category numbers, merged categories follow unmerged categories and are sorted by the highest-numbered category in each parent; for example, a merge of bins 2 and 4 precedes a merge of bins 1 and 5.

To rename a categorical binning

You can give meaningful names to the binnings in the categorical binning hierarchy for a field.
  1. In the Hierarchy pane of the Binning Editor, highlight the binning that you want to rename.
  2. Click on Rename or simply click again on the name of the binning.
  3. Enter your chosen name for the binning and press Return.

To delete a categorical binning from a field

  1. In the Hierarchy pane of the Binning Editor, highlight the binning that you want to delete.
  2. Click on Delete.
Note: To delete all categorical binnings from one or more fields, simply clear the categorical interpretation [see To set or clear an analysis candidate, categorical, geographical, export or key interpretation] on the fields.

To set the default parameters for new categorical binnings

  1. Choose Binning>Default Parameters or click on [image] on the toolbar.
  2. Under the Categorical tab, set the maximum number of separate categories and the minimum number of records in a single category.
  3. Click on OK, to confirm your choices.
Note:
  • If the number of records containing a given value falls below the minimum number of records for a single category - usually because the field contains too many distinct values - records containing that value are unclassified. Unclassified records are not shown by default in the Binning Editor; to display them, choose View>Unclassified Data.
  • To apply the new default parameters to a field that already has a categorical interpretation, you must clear the existing categorical interpretation [see To set or clear an analysis candidate, categorical, geographical, export or key interpretation].


To modify a non-categorical binning

  1. In the Decision Studio window, highlight the non-categorical [see Field interpretations] numeric or date field whose binning you want to modify. Choose Tools>Binning Editor, or press CTRL+B, or click on [image] on the toolbar.
  2. Alternatively, from field lists in the modeling tools, highlight the field, right-click and choose Binning Editor.
  3. Alternatively, in the graphical viewers, right-click on a field in the graph configuration area and choose Binning Editor.

    The Binning Editor opens, showing a graph of the primary binning [see To set the primary binning for a non-categorical field] for the field that you selected.

    If there is no binning attached to the field, the Binning Editor creates a binning using the default parameters [see To set the default parameters for new non-categorical binnings].

  4. From the Style pane, select the required binning type.
    • For an equal-range binning, you can set either the target number of internal bins (bins between the end bins [see End bins]) or the target bin width.
    • For an equal-population binning, you can set the target number of internal bins.
    • For a date-valued equal-range or equal-population binning, you can also specify the units in which bin widths are measured (days, weeks, etc.).
    • For a user-defined binning, click on Edit to specify individual bin boundaries [see Modifying a user-defined non-categorical binning] in the User Defined dialog box.
  5. Click on Apply or OK, to confirm your changes to the binning.

    Alternatively, click on Reset to discard all the changes that you have made to the binning since you last applied changes.

Note:
  • For fields of real type, to force the Binning Editor to locate bin boundaries at integer values, check Binning>Whole Number Boundaries.
  • The final number of internal bins may differ from the target number for a field of integer type, or if Binning>Whole Number Boundaries is checked. This happens for one of two reasons:
    • The range of the field does not include enough whole-number boundaries.
    • Binning>Automatically Adjust Number of Bins is checked, and at least one of the end-bin boundaries is to be chosen automatically; in this case the Binning Editor may adjust the number of bins to locate bin boundaries at round-number values. To force the final number of bins to be the same as the target number, uncheck Binning>Automatically Adjust Number of Bins, and click on Apply or OK.
  • For a user-defined binning, changes take effect when you click on OK in the User Defined dialog box. There is therefore no need to click on Apply in the Binning Editor (and you can't return to the original binning using Reset).
  • You can modify binnings on other fields without leaving the Binning Editor by clicking the Fields tab and highlighting the desired field.

See also

To attach an extra binning to a non-categorical field

To modify a categorical binning

Parent topic: Grouping customer records by binning a field in a focus

End bins

Equal-population and equal-range binnings in Decision Studio divide a numeric or date range into a series of bins. Most of these bins are "internal," but there may be a special "end bin" at each end of the range.

When Decision Studio creates a numeric binning with end bins, it uses an intelligent algorithm to classify some values as outliers. Records containing these outlying values fall in the end bins, while the majority of records fall in the internal bins.

In the Decision Studio Binning Editor, you can control the use of end bins in equal-range and equal-population binnings by using the drop-down menus in the Min End Bin and Max End Bin panes:
  • If you choose Auto for a numeric equal-range binning, the Binning Editor chooses the end-bin boundary automatically.
  • If you choose Auto for a date binning or equal-population binning, the Binning Editor omits the end bin.
  • Choose Fixed at to specify a fixed end-bin boundary.
  • Choose None to omit the end bin in every case.

You can also control end bins in a user-defined binning [see Modifying a user-defined non-categorical binning].

To delete a non-categorical binning from a field

  1. In the Binning Editor, if not already looking at the non-categorical field whose binning you want to delete, click the Fields tab and highlight the field.
  2. Choose Binning>Delete Binnings or right-click in the Fields pane and choose Delete Binnings or click on [image] on the toolbar.
Note:
  • You can simultaneously delete binnings from several non-categorical fields by choosing Delete Binnings on Multiple Fields. A Select Fields dialog box appears, in which you can choose the fields whose binnings you want to delete.
  • As their names suggest, the Delete Binnings and Delete Binnings on Multiple Fields options delete all binnings associated with a non-categorical field. If you have used the multiple-binnings feature of Decision Studio to attach more than one binning to a field [see To attach an extra binning to a non-categorical field], you can delete an individual binning by choosing Binning>Manage Multiple Binnings: highlight the required binning in the Manage Multiple Binnings dialog box and click on Delete.

To set the default parameters for new non-categorical binnings

  1. In the Binning Editor, choose Binning>Default Parameters or click on [image] on the toolbar.
  2. Under the Non-Categorical tab, choose the target number of bins (excluding null [see The null value] and unclassified bins and end bins [see End bins]), the binning type [see To modify a non-categorical binning], and whether to show bins with proportional bin widths [see Histogram and bar-graph options].
  3. Click on OK, to confirm your choices.
Note:

To apply the new default parameters to a field that is already binned, you must delete [see To delete a non-categorical binning from a field] the existing binning.


Modifying a user-defined non-categorical binning

When you click on Edit in the Binning Editor for a user-defined binning, the User Defined dialog box appears:

Work from the existing binning (perhaps formerly an equal-range or equal-population binning), or click on Quick Start to begin with a preset [see Using quick-start preset binnings] binning. Then adjust the binning to suit your needs:
  • Change bin boundaries by editing them in the table directly or by manipulating the graphical view (which works like the graphical view for record selection/filtering [see Value selection or filtering using a non-categorical field or statistic]).
  • Increase the number of bins by highlighting a bin (in the table or the graphical view) and clicking on Split Range.

    The bin splits into two equal-sized bins.

  • Decrease the number of bins by highlighting a bin and clicking on Delete Range.

    The bin merges with the neighboring bin to its right (or to its left in the case of the rightmost bin).

  • Control the use of end bins [see End bins] by choosing Both, None, Lower, or Upper from the drop-down menu.
Note: By changing the value of a bin boundary, or by checking or clearing an Include From check box, you can leave one or more bins defined in such a way that they cannot possibly contain any values. Such invalid bins are highlighted as red rows in the table, and labeled "not valid."

To remove all invalid bins from your binning, click on Delete Non-Valid.

See also

To modify a non-categorical binning
Parent topic: Grouping customer records by binning a field in a focus

Using quick-start preset binnings

When you click on Quick Start in the User Defined dialog box, the User Defined Presets dialog box appears:

By choosing an appropriate preset type from the drop-down menu, you can quickly create a binning where the bins between the Bin From and Bin To values have useful properties:
  • In a Stride binning, all the bins (except possibly the rightmost bin) have a given width.
  • In a Log binning, there are a given number of bins with logarithmically increasing or decreasing width.
  • In an Equal Width binning, there are a given number of bins of equal width.
  • In a Normal binning, the bin widths are those you would obtain for an equal-population binning if the underlying data were normally distributed between the Bin From and Bin To values: the closer a bin is to the mean value of the field, the narrower it is.
Note:
  • If there are values to the left of the Bin From value or to the right of the Bin To value, records containing them fall into extra bins (which may or may not be classified as end bins [see End bins]).
  • If you check Bin Zero Separately and there is a bin containing the value 0, that bin splits into up to three bins: one for values less than 0, one for 0 itself, and one for values greater than 0.

    This is useful where zero is a special value; for example, customers with a zero spend figure may form a distinct segment.


Options for displaying a binning

The Binning Editor shows a graphical view of the highlighted binning, applied to the data for the highlighted field.

You can modify aspects of this view by setting global Decision Studio display options [see To set global options for graphical displays] or by showing or hiding [see To show or hide segments for null and unclassified values in a graph] bins for null and unclassified values.

You can also affect the display of a non-categorical binning, both in the Binning Editor and elsewhere, by choosing between histogram and bar-graph options [see Histogram and bar-graph options] for the binning.

The Binning Editor also shows detailed numerical information about a binning and the number of records in each bin.

See also

To modify a categorical binning

To modify a non-categorical binning

Parent topic: Grouping customer records by binning a field in a focus

Histogram and bar-graph options

Besides the binning type and the bin boundaries that define a binning, each binning has a display mode associated with it: either histogram or bar graph (the latter being the default for a non-categorical binning and the only option for a categorical binning).
  • In a histogram, each bin (other than an end bin [see End bins], a zero-width bin, or the null [see The null value] or unclassified bin) has visual width proportional to the underlying interval width. The Binning Editor plots probability density as bar height:

    For a given bin (other than a zero-width bin or the null or unclassified bin), you can calculate the record count by multiplying together the total number of records, the probability density, and the interval width. % Not the visual width, which for end bins is different. (For a date binning, the bin width is measured in days.)

    The histogram display best approximates a graph of the distribution of values in a field.

    To view a non-categorical binning as a histogram in the Binning Editor, check View>Histogram or select [image] on the toolbar.

  • In a bar graph, all bins have the same visual width (although the underlying interval widths may vary in a non-categorical binning). The Binning Editor plots the record count for each bin as bar height.

    When the interval widths in a binning vary greatly, the bar graph display most clearly shows bin boundaries and record counts.

    To view a non-categorical binning as a bar graph in the Binning Editor, uncheck View>Histogram or deselect [image] on the toolbar.

Because the display mode is a property of a binning rather than merely a viewing option in the Binning Editor, you must either make your change permanent (by clicking on Apply) or discard your change when you switch to another binning or close the Binning Editor.
Note:
  • The display mode for a binning affects graphical views in the Profile Viewer and Crossdistribution Viewer: divisions on axes are equal-width or proportional according to the mode. The exception is where the extent of a block in a given direction conveys information: in this case, the Binning Editor display setting has no effect, so as not to mislead.
  • In the Binning Editor, in both histogram and bar-graph views, the visual area of a bin (other than an end bin, a zero-width bin, or the null or unclassified bin) is proportional to the number of records in the bin.


To attach an extra binning to a non-categorical field

You can attach one or more binnings to a non-categorical field in a focus, though at a given time only one of these — the primary binning — is accessible to Decision Studio tools other than the Binning Editor.
  1. In the Binning Editor, if not already looking at the field you want to bin, click the Fields tab and highlight the field.
  2. Choose Binning>Manage Multiple Binnings or right-click in the Fields pane and choose Manage Multiple Binnings.
  3. In the Manage Multiple Binnings dialog box, do one of the following:
    • Click on Add.

      The Binning Editor creates a new binning, with the default parameters [see To set the default parameters for new non-categorical binnings] for a non-categorical binning

    • Highlight an existing binning and click on Duplicate.

      The Binning Editor creates a copy of the highlighted binning.

Note:
  • To use the new binning, you must make it the primary binning [see To set the primary binning for a non-categorical field] for the field.
  • To help you remember which binning is which, you can give binnings meaningful names: double-click on the binning in the Manage Multiple Binnings dialog box.
Parent topic: Grouping customer records by binning a field in a focus

To set the primary binning for a non-categorical field

  1. In the Binning Editor, if not already looking at the field you want to bin, click the Fields tab and highlight the field.
  2. Choose Binning>Manage Multiple Binnings or right-click in the Fields pane and choose Manage Multiple Binnings.
  3. In the Manage Multiple Binnings dialog box, click on Make Primary.


Applying a binning to more than one field

You can reuse a binning by creating it on one field and applying it to other, similar fields. You can copy and paste [see To copy a binning to another non-categorical field] a non-categorical binning between fields or save it to a binning file [see To save a non-categorical binning] and then apply the binning [see To apply a saved non-categorical binning to a new field] to another field. You can also save a categorical binning hierarchy [see To save a categorical binning hierarchy] and then apply the hierarchy [see To apply a saved categorical binning hierarchy to a new field] to another field.
Note: Typically, you would apply a saved binning or categorical binning hierarchy to a field in a different focus: for non-categorical fields in the same focus, copying and pasting is simpler.
Parent topic: Grouping customer records by binning a field in a focus

To copy a binning to another non-categorical field

  1. In the Binning Editor, if not already looking at the non-categorical field whose binning you want to copy, click the Fields tab and highlight the field.
  2. Choose Binning>Copy Binning or right-click in the Fields pane and choose Copy Binning or click on [image] on the toolbar.
  3. Highlight the field to which you want to apply the binning.
  4. Choose Binning>Paste Binning or right-click in the Fields pane and choose Paste Binning or click on [image] on the toolbar.

    The Binning Editor creates a copy of the binning, named after the original field.

Note:
  • Instead of pasting a binning to a single field, you can simultaneously apply it to several fields by choosing Paste Binning To Multiple Fields instead of Paste Binning. In this case, a Select Fields For Paste dialog box appears, in which you can choose a group of fields. The Binning Editor applies a copy of the binning to each of the fields that you choose.
  • If you have used the multiple-binnings feature of Decision Studio to attach more than one binning to a field, note that the Copy Binning and Paste Binning options apply to the primary binnings [see To set the primary binning for a non-categorical field] associated with the field.

To save a non-categorical binning

  1. In the Binning Editor, if not already looking at the non-categorical field whose binning you want to save, click the Fields tab and highlight the field.
  2. Choose File>Save As or click on [image] on the toolbar and choose a location and name for your binning file.

To apply a saved non-categorical binning to a new field

  1. In the Binning Editor, if not already looking at the non-categorical field to be binned using the saved binning, click the Fields tab and highlight the field.
  2. Choose File>Open or click on [image] on the toolbar.

    Binning files have filename extension .bng (or .qsbng).

To save a categorical binning hierarchy

  1. In the Binning Editor, if not already looking at the field whose categorical binning hierarchy you want to save, click the Fields tab and highlight the field.
  2. Choose File>Export[Categorical Hierarchy]\ and choose a location and name for your categorical binning hierarchy file.

    Categorical binning hierarchy files have filename extension .hrc.

To apply a saved categorical binning hierarchy to a new field

  1. In the Binning Editor, if not already looking at the field to be binned using the saved categorical binning hierarchy, click the Fields tab and highlight the field.
  2. Choose File>Import Categorical Hierarchy or click on [image] on the toolbar.
Note:
  • When you apply a saved categorical binning hierarchy to a field, it overwrites any previous categorical binning hierarchy — or non-categorical binnings — associated with the field.
  • If you apply a saved categorical binning hierarchy to a field without a categorical interpretation, Decision Studio automatically applies a categorical interpretation to the field.


To optimize a binning for a field

You can use the Binning Editor to find a coarse binning that best approximates a fine binning, in terms of predicting a given objective. In this way, you can improve a scorecard or decision tree while minimizing the risk of overfitting the model to your data.
  1. Make sure that the field whose binning you want to optimize is interpreted as an analysis candidate [see Field interpretations] (or that there are no analysis candidates in the focus).
  2. Make sure that the appropriate modeling objective is set.
  3. Build a scorecard . Do not close the Scorecard Builder window.

    By building a scorecard, you ensure that the statistics that are required for optimization are in place.

  4. In the Binning Editor, if not already looking at the field whose binning you want to optimize, click the Fields tab and highlight the field.
  5. Choose Binning>Optimize or click on [image] on the toolbar.

    The Optimize Binning dialog box appears:

  6. Choose the source binning, by specifying whether to use the current binning or an equal-population or equal-range binning with a given number of bins.

    The source binning should be much finer than the desired result; as a rough guide, choose around ten times the number of bins that you want to end up with.

  7. Click on Create Source Binning.

    The graph in the Binning Editor shows the source binning you have chosen, color-coded with the objective match rate for each bin.

  8. Choose the number of internal bins and the minimum bin size for your target binning.
  9. Click on Optimize.

    The graph in the Binning Editor now shows the target binning generated using these parameters, again color-coded with the objective match rate for each bin.

  10. Click on Accept if you want to bin the field using this binning. (You can then close the Scorecard Builder window.)
Note:
  • Binning optimization only works with internal bins. End bins are not affected.
  • By default, the Binning Editor uses information gain as a quality measure for how well a coarser binning approximates the initial binning. Using the drop-down menu in the Optimization pane, you can choose to use the Gini measure for this instead.
  • Binning optimization is an iterative process: if you are not happy with the source binning, you can change the parameters in the Source Binning pane at any time and click again on Create Source Binning; if you are not happy with the target binning, you can change the parameters in the Target Binning and Optimization panes and click again on Optimize.
  • For a non-categorical field, when you click on Accept, the new binning becomes the primary binning [see To set the primary binning for a non-categorical field] for the field. Unless you check Backup Current Binning before accepting the binning, it overwrites the existing primary binning.
Parent topic: Grouping customer records by binning a field in a focus


Deriving new fields in a focus

  • To derive a field using the Table Viewer
  • To derive a field from a Decision Studio model or crosstab
  • Fields associated with decision trees, scorecards, clustering models, and abstract crosstabs
  • To derive a field from a graphical segmentation
  • To derive fields in a focus using Portrait Miner


To derive a field using the Table Viewer

  1. Choose Derive>New or click on [image] on the toolbar.

    The Table Viewer initially creates an empty Preview} column at the right of the table.

  2. In the newly highlighted text box to the left of the "=" sign, enter a name for the new field.

    Choose a field name that is descriptive — but not too long. The name must start with a letter, and must contain no characters other than letters, digits, and underscores. It must not clash with the name of another field in the focus.

  3. In the text box to the right of the "=" sign, enter an FDL expression or expression list [see Expressions], to define the field in terms of existing fields.
  4. Choose Derive>Calculate, click on [image] on the toolbar, or simply press Return.

    The Table Viewer derives the new field, which appears in place of the Preview} column.

Note:
  • If the expression or expression list is too long to fit comfortably on a single line, you can use the Multi-Line Expression Editor: choose Derive>Edit or click on [image] on the toolbar.
  • To override the default datatype [see Datatypes] for a field, open the Multi-Line Expression Editor to reveal additional derivation options.

    You can also set a seed [see About random-number functions in FDL] for random-number computations here. If you don't specify a seed, the system picks one for you (based on the system clock), and the sequence of results will be different at different times.

  • If you press the Tab key (repeatedly) while entering a derivation expression, the Table Viewer cycles through possible completions for the current word, considering names of FDL functions and fields in the focus. Completions of FDL function names include the necessary parentheses and commas, where applicable, to indicate the required number of arguments. If you haven't just typed part of a word, the Table Viewer considers all function and field names as possible completions.
  • Alternatively, you can include any field name from the focus in a derivation expression by picking it from a list: choose Derive>Field Browser.
  • If you are unsure of the precise syntax of an FDL function — or simply to save typing — choose Derive>Function Browser for assisted function entry [see Assisted function entry in the Table Viewer].
  • To derive a field based on values in another table, use the FDL function dblookup.
  • Decision Studio generates values for all records regardless of whether a selection is currently applied.

See also

To derive fields in a focus using Portrait Miner
Parent topic: Deriving new fields in a focus

Assisted function entry in the Table Viewer

When you choose Derive>Function Browser or click on [image] in the course of entering a derivation expression in the Table Viewer, the Derivation Functions dialog box appears. If you highlight a class of functions (or All) in the Function Family pane, a list of the FDL functions in that class (or all available FDL functions) appears in the Functions pane.

When you highlight a function in the Functions pane, a brief description of the function appears. (For functions that are not built in to FDL, click on Details to see a fuller description.)

You can enter the required arguments for the function in the Parameters pane.

Below the parameters pane, you can see the actual FDL expression corresponding to your choice of function and parameters. When you click on OK, the Table Viewer pastes that expression into your derivation expression at the cursor.

Note:
  • When you use the Derivation Functions dialog box to enter a function in the Field Aggregation function family, there are two special parameters ("where" and "by"), which do not correspond to actual function arguments. Instead they produce special FDL syntax for aggregation functions.

    The "where" parameter is a boolean [see Boolean data]-valued FDL expression used to select the records to aggregate over. If you omit the parameter, Decision Studio aggregates over all currently selected records in the focus.

    The "by" parameter is a breakdown field — or a comma-separated list of breakdown fields. To calculate the value of the aggregation function for a record, Decision Studio aggregates over records that share the record's bin for every breakdown field.

  • When you use the Derivation Functions dialog box to enter the isselected FDL function, there is a special parameter ("expand"), which doesn't correspond to an actual function argument. When you check the box for this parameter, instead of generating the expression isselected(), the Table Viewer inserts an expression that evaluates to true for just those records that are selected at that time.

    Both expressions produce the same result — until you select different records in the focus. Then the result of the isselected() expression will change, but the result of the expanded expression will remain the same.

To edit a derivation expression using the Table Viewer

  1. Click on the field whose derivation expression you want to edit.
  2. Edit the derivation expression, if necessary using the Multi-Line Expression Editor.
  3. Choose Derive>Calculate, click on [image] on the toolbar, or simply press Return.


To derive a field from a Decision Studio model or crosstab

  1. If you want a field to reflect selected segments of a decision tree, highlight the segments of interest [see Highlighting segments in a graphical display] in the Decision Tree Builder.
  2. Do one of the following:
    • In the Decision Tree Builder, choose Tree>Generate Fields.
    • In the Scorecard Builder, choose Scorecard>Generate Fields.
    • In the Cluster Builder, choose Clustering>Generate Fields.
    • In the Crosstab Viewer, Profile Viewer, Crossdistribution Viewer, or Map Viewer, choose Segments>Generate Fields.
    • In any modeling tool or graphical viewer, click on [image] on the toolbar.
    A Generate Results Fields dialog box appears.
  3. Check the results fields [see Fields associated with decision trees, scorecards, clustering models, and abstract crosstabs] that you want to generate, changing the field names as required.
  4. Click on OK.

    Decision Studio generates the results fields in the focus.

Note:
  • Each results field is marked as a derived field and has an associated FDL definition, which you can view or edit [see To derive a field using the Table Viewer] using the Table Viewer. There are instructional comments in the derivation text to help you carry out simple "what if?" analyses.
  • Decision Studio generates values for all records regardless of whether a selection is currently applied.

See also

To build a clustering model

To build a decision tree

To create a textual crosstab view

To derive a field from a graphical segmentation

To save a Decision Studio model or segmentation for deployment as QMML (XML)

Parent topic: Deriving new fields in a focus


Fields associated with decision trees, scorecards, clustering models, and abstract crosstabs

The following results fields capture different aspects of decision trees, abstract crosstabs, scorecards and clustering models:
Field | Applicable to | Description
Segment index | Any decision tree or abstract crosstab | The identifying number of the segment in which a record falls- considering only "leaf" (lowest-level, childless) segments in a decision tree
Selected segments | Any decision tree or graphical viewer | 1 for records in highlighted segments; 0 for other records
Match rate | Binary tree | The original match rate for the "leaf" segment in which a record falls, that is, the proportion (between 0 and 1) of records in the segment that match the objective (ignoring records with null [see The null value] in the objective field)
Predicted outcome | Binary tree or continuous scorecard | For a decision tree: the bin index of the most common original value in the objective for the "leaf" segment in which a record falls: usually 1 for the value 0, 2 for the value 1, and 3 for null [see The null value] For a scorecard: the score computed by applying the scorecard , equivalent to the predicted value of the objective
Decision | Binary tree or binary scorecard | For a decision tree: 1 if the original match rate for the segment in which a record falls is above the threshold value [see To set the decision threshold for a decision tree] for the tree; 0 otherwise For a scorecard: 1 for records with scores above the cutoff score [see To set the cutoff score for a scorecard] for the scorecard; 0 for other records
Most popular category | Categorical tree | The bin index of the most common original category in the objective for the segment in which a record falls
Objective mean | Continuous tree | The original mean value of the objective for the "leaf" segment in which a record falls
Uplift as difference | Binary uplift + tree | The original uplift, that is, the original match rate for the treated population minus that for the control population, for the segment in which a record falls
Uplift as quotient | Binary uplift x tree | The original uplift ratio, that is, the original match rate for the treated population divided by that for the control population, for the segment in which a record falls (If the match rate for the control population is zero, the record is assigned a very large positive number.)
Uplift of mean | Continuous uplift tree | The original uplift, that is, the original mean value of the objective for the treated population minus that for the control population, for the segment in which a record falls
Score | Binary scorecard | The score computed by applying the scorecard
Odds | Binary scorecard | The odds of defaulting, responding, churning, or being satisfied or dissatisfied, given by [image] , where s is the score and a and b are the even-odds point and doubling factor [see To set the score/odds relationship for a scorecard] respectively
Probability | Binary scorecard | The probability of defaulting, responding, churning, or being satisfied or dissatisfied, given by
Cluster index | Clustering model | The identifying number of the cluster [see To build a clustering model] in which a record falls (or null [see The null value] for a record in the null cluster [see The null value in clustering]) (A categorical binning is applied, and the value -1 is assigned a category named "Outliers.")
Cluster distance | Clustering model | The normalized distance [see Measuring size and separation of clusters] between a record and the center of the cluster in which it falls
Cluster separation | Clustering model | The separation measure for a record, given by [image] , where [image] is the distance to the nearest cluster center and [image] is the distance to the second-nearest cluster center
Note:
  • The word "original" in the table above indicates that, for decision trees, the values in certain generated fields are from the population upon which the decision tree was built, rather than any population to which it is later applied.
  • The segment-index field for an abstract crosstab takes into account all the breakdown fields in the crosstab, including any that the viewer currently lists in the [image] (Information only) bar.
  • The selected-segments field for abstract crosstabs is only available when saving a model for deployment in the graphical viewers.

See also

To derive a field from a Decision Studio model or crosstab

To save a Decision Studio model or segmentation for deployment as QMML (XML)

Parent topic: Deriving new fields in a focus

To set the decision threshold for a decision tree

In the Decision Tree Builder, alter the match-rate decision threshold, accept rate, or reject rate using the pane below the toolbar:

Legitimate values for these three parameters are those that appear in the gains view [see Options for displaying a decision tree] of the decision tree.

When you enter a value for the decision threshold or reject rate, the actual value (shown in the non-editable box to the right) is the nearest legitimate value above the value that you enter. For the accept rate, the actual value is the nearest legitimate value below the value that you enter. The Decision Tree Builder adjusts the other values accordingly.

To set the cutoff score for a scorecard

In the Scorecard Builder, alter the cutoff score, accept rate (target rate), or bad rate (hit rate) using the pane below the toolbar.

The Scorecard Builder adjusts the other values accordingly.

Note:
  • You cannot set a cutoff score for a scorecard built using a continuous objective: in a value model, you are not making a yes/no decision.
  • The default setting is determined by the Scorecard Builder preferences cutoff, bad rate, and accept rate.

To set the score/odds relationship for a scorecard

  1. In the Scorecard Builder, choose Scorecard>Form.
  2. In the Scaling pane of the Scorecard Form dialog box, alter the even-odds point and doubling factor as required:
    • The even-odds point is the score corresponding to odds of 1.
    • When you add the doubling factor to a score, the corresponding odds doubles (for a response or churn model — for a risk model, the odds are halved).
  3. Click on OK.
Note:
  • These options are not available when you are using a continuous objective, as there is no concept of odds associated with continuous scorecards.
  • When you change the even-odds point or doubling factor, the new value doesn't apply until you next build a scorecard.


To derive a field from a graphical segmentation

You can derive a 0/1 field from a graphical segmentation to indicate inclusion in or exclusion from selected segments.
  1. In the Profile Viewer, Crossdistribution Viewer, Map Viewer, or Decision Tree Builder, highlight segments of interest [see Highlighting segments in a graphical display].
  2. Choose Segments>Flag Selected or click on [image] on the toolbar.

    A New Field Name dialog box appears.

  3. Enter a name for the derived field and click on OK.

    Decision Studio creates a new field, with 1 in records that fall in highlighted segments and 0 in other records.

Note:
  • The new field is marked as a derived field and has an associated FDL definition, which you can view or edit [see To derive a field using the Table Viewer] using the Table Viewer.
  • The new field is interpreted as categorical [see Field interpretations], with category names "Not Selected" and "Selected" for the values 0 and 1 respectively.

See also

To create a graph on a map

To create a multi-variable crossdistribution graph

To create a set of single-variable profile graphs

To derive a field from a Decision Studio model or crosstab

To save a Decision Studio model or segmentation for deployment as QMML (XML)

Parent topic: Deriving new fields in a focus


To derive fields in a focus using Portrait Miner

You can derive fields using a set of field definitions in a derivations file.
To derive fields in a focus, use one of the following options:
  • In Portrait Miner, right-click on the focus in which you want to derive fields and choose Transform>Derive Fields.
  • In Portrait Miner, right-click on a derivation file and choose Derive Fields.

In the Derive Fields dialog box, choose a derivations file containing the field definitions. Alternatively, if you selected a derivations file, choose a focus. You can also change the location of the new focus or choose to overwrite a previously created output focus.

Note: This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsderive.

See also

About Portrait Miner wizards

To derive a field using the Table Viewer

Using Portrait Miner data-build commands for data import, processing, and export

Viewing and editing text files in Portrait Miner

Parent topic: Deriving new fields in a focus


Renaming and deleting fields in a focus

  • To rename a field using the Table Viewer
  • To rename fields by adding a prefix or suffix
  • To delete a field


To rename a field using the Table Viewer

  1. Click on the field whose name you want to change.
  2. In the text box to the left of the "=" sign, enter a new field name and press Return.

    The name must start with a letter, and must contain no characters other than letters, digits, and underscores. It must not clash with the name of another field in the focus.

When you rename a field, you invalidate any derived fields (including model-generated fields) whose derivation expressions involve the original field name.
Note:
  • You can't rename a field while it is in use by a Decision Studio tool.

See also

To rename fields by adding a prefix or suffix

Parent topic: Renaming and deleting fields in a focus


To rename fields by adding a prefix or suffix

You can rename one or more fields in a focus, by adding a common prefix or suffix to the field names.
  1. In Portrait Miner, right-click on the focus whose fields you want to rename and choose Transform>Rename Fields. The Rename Fields dialog box appears.
  2. Optionally, change the location of the output focus.
  3. Do one or both of the following:
    • Choose the string to add as a prefix.
    • Choose the string to add as a suffix.
  4. Choose one or more fields to rename.
  5. Click on OK.
Note:
  • Each resulting field name must not clash with the name of another field in the focus.
  • The Rename Fields dialog box is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsrenamefields.

See also

About Portrait Miner wizards

To rename a field using the Table Viewer

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Renaming and deleting fields in a focus


To delete a field

  1. Click on the field that you want to delete.
  2. In the Decision Studio window, choose Field>Delete, or right-click on the field and choose Delete.
  3. In the Table Viewer, choose Field>Delete or click on [image] on the toolbar. You can also delete a field by right-clicking on the field header and choosing Delete.
Note:
  • You can't delete a field while it is in use by a Decision Studio tool.
  • You can also delete a field in the Decision Studio window using the Field>Delete or by choosing Delete when right-clicking a field.

See also

To choose the fields that you want to view

To rename a field using the Table Viewer

Parent topic: Renaming and deleting fields in a focus


Working with focus metadata

  • Focus metadata
  • Field display labels
  • Field interpretations
  • Attaching a comment to a focus or field using Decision Studio
  • Viewing focus and field metadata
  • Copying focus metadata from one focus to another
  • Editing focus metadata in Excel


Focus metadata

Metadata is "data about data." Besides the raw customer data that you import from a database or create by taking transaction measurements, a focus contains metadata. Some of this metadata applies to the focus as a whole, while other metadata applies to individual fields in the focus.

Metadata associated with the focus as a whole

  • The numbers of records and fields in the focus
  • The data-build command commands used to create the focus (if created using data-build commands)
  • An optional comment

Metadata associated with a field in a focus

  • The field's name and datatype [see Datatypes]
  • Any display label [see Field display labels] associated with the field
  • Any user tags [see User tags] associated with the field
  • Any interpretations [see Field interpretations] associated with the field
  • Any binnings associated with the field
  • Any record selection [see Selecting customer records] that is based on values in the field
  • The FDL expression [see About Field Derivation Language] used to define the field (if the field was derived)
  • Any comment associated with the field
  • A record of whether the field was imported into (joined to) the focus from another data source
  • The minimum and maximum values in the field
  • The number of occurrences of the null [see The null value] value in the field
Note: The relationships between tools in a Decision Studio session are not stored in a focus file.

See also

Attaching a comment to a focus or field using Decision Studio

Copying focus metadata from one focus to another

Creating a Profile and Audit of a focus

Viewing focus and field metadata

Parent topic: Working with focus metadata


Field display labels

It is often not desirable or possible to edit a field's name. However, some of the displays in Decision Studio can show a display label in place of the field name. Tools that support display labels are the Crossdistribution Viewer, Crosstab Viewer, Profile Viewer, Map Viewer and Decision Tree Builder.

The Decision Studio window has a Display Label column that shows the display label that will be used for each field. Note: The Display Label column is optional and can be shown by clicking Edit>Column Layout.

Parent topic: Working with focus metadata

To edit the display label for a field

  1. In the Decision Studio window highlight the field.
  2. Click a second time in the Display Label field to edit the name directly. Alternatively, with the display label entry highlighted, you can:
    • Choose Field>Properties, or
    • Right-click and choose Properties, or
    • Click [image] on the toolbar.

See also

Aggregation functions for crosstabs
Note:
  • Unlike field names, there are no restrictions on the characters that are used in display labels.
  • Field display labels are saved with the focus and can be exported and imported along with other metadata items.
  • Display labels cannot be used in FDL expressions.


Field interpretations

In Decision Studio, you can associate one or more of the following interpretations with a field:

Field interpretation | Meaning
Objective | The field is the modeling/visualization objective in the focus.
Partition | The field is the treated/control partition field for uplift analysis. The first bin or category (usually the value 0) denotes the control segment and the second bin or category (usually the value 1) denotes the treated segment.
Analysis candidate | The field is a candidate for use in Decision Tree Builder, Scorecard Builder and Cluster Builder models.
Categorical | Values in the field form a discrete, unordered set. Categorical fields are treated differently from other fields in the Binning Editor, Decision Tree Builder, Cluster Builder and Select Values dialog box.
Geographical | The field is associated with a map so that you can use it in the Map Viewer.
Export | The field is to be included by default when you export segments to a file or database table. (Typically, it is the unique identifier, for example, a customer number.)
Key | The field is associated with Portrait Explorer and identifies the key field. You can only have one key field.
Note:
  • A focus contains at most one field with the objective interpretation and at most one field with the partition interpretation.
  • If there are no analysis candidates in a focus, the Decision Tree Builder, Scorecard Builder and Cluster Builder treat all suitable fields as analysis candidates.
  • Likewise, if there are no fields with export interpretation in a focus, Decision Studio treats all fields as though they are export fields.
  • In the Scorecard Builder, you can interpret a field as a "weight." This kind of interpretation is local to the Scorecard Builder and does not form part of the focus metadata.
Parent topic: Working with focus metadata

To set or clear an analysis candidate, categorical, geographical, export or key interpretation

  1. In the Decision Studio window, highlight the fields whose interpretation you want to change.
  2. Select Tag>Interpretations on the main menu and then select Analysis Candidate [image], Categorical [image], Geographical [image], Export [image], or Key [image]). Alternatively, right-click the field and select the interpretation ( [image], [image], [image], [image], or [image]) . The appropriate icon will display in the field's Interpretations column.
Note:
  • You can set field interpretations in the Table Viewer, from the Tag>Interpretations menu, or by right-clicking on a field name (column heading).
  • To remove an interpretation, select it a second time using the steps described above.

To set or clear the objective or partition field in a focus

  1. In the Decision Studio window, highlight the field that you want to set as the objective or partition field.
  2. Select Tag>Interpretations on the main menu and then select Objective ( [image]) or Partition ( [image] ). Alternatively, right-click the field and select the interpretation ( [image] or [image]). The appropriate icon will display in the field's Interpretations column.
Note:
  • If you have already set an objective or partition field, and then choose to interpret a different field in that way, Decision Studio clears the original interpretation for you.
  • To remove the objective or partition interpretation from a field without assigning the interpretation to another field, highlight the field, and choose the appropriate option from the Tag>Interpretations menu again.


Attaching a comment to a focus or field using Decision Studio

You can add descriptions and other comments to a focus and to individual fields within a focus. This information can be useful when you share datasets with other people — or even when you return to an analysis dataset that you haven't worked with for a while.
In the Decision Studio window:
  • To add a focus comment, choose Focus>Edit Focus Comments.
  • To add a field comment, click in the Comment field and add your comment. Alternatively, you can:
    • highlight the required field and choose Field>Properties
    • right-click and choose Properties, or click on [image] on the toolbar.

Field comments appear in the Comments column in the Decision Studio window. Field and focus comments also appear elsewhere [see Viewing focus and field metadata].

Note:
  • If you check the HTML box, Decision Studio treats balanced pairs of tags, for example <b>...</b>, as HTML markup, and displays the comment accordingly.

See also

Focus metadata
Parent topic: Working with focus metadata


Viewing focus and field metadata

The Decision Studio window displays focus metadata [see Focus metadata], including the main field statistics. You can choose to display different information using the Edit>Column Layout menu; your choice applies in the current and future Decision Studio sessions.

The Interpretations column shows letters corresponding to the field interpretations [see Field interpretations] that have been applied to the field. The following letters may also appear in the Interpretations column:

Letter | Meaning
B | The field has a binning associated with it.
D | The field is a derived field.
J | The field was imported into (joined to) the focus from another data source.

The Comments column shows any comments [see Attaching a comment to a focus or field using Decision Studio] associated with fields.

Note: For reasons of efficiency, the Decision Studio window doesn't keep statistics up-to-date at all times. When field statistics are out of date, the Decision Studio window grays them out.
  • To update the statistics for a single field, highlight the field and choose Field>Update Statistics, or right-click on the field and choose Update Statistics.
  • To update the statistics for every field in the focus, choose Focus>Update All Statistics.
Parent topic: Working with focus metadata

To view focus information in Decision Studio

In the Decision Studio window, choose Focus>Focus Information.

A window appears, showing basic information about the focus, and focus history. Any comments [see Attaching a comment to a focus or field using Decision Studio] associated with the focus also appear.

To view field information in Decision Studio

In the Decision Studio window, highlight a field and choose Field>Properties, or right-click and choose Properties, or click on [image] on the toolbar.

To view focus and field information in Portrait Miner

In Portrait Miner, right-click on a focus, and choose Metadata>Show.

In the Display Focus Information dialog box, you can choose the amount of field information to include.

A window then appears, showing basic information about the focus, and focus history. Any comments [see Attaching a comment to a focus or field using Decision Studio] associated with the focus also appear.

Information on fields (if requested) appears below the focus information. If you chose to display detailed field information, this includes field statistics, as well as any comments associated with fields.

Note: This Display Focus Information dialog box is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsdescribe.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export

To view dependencies and file sizes for a focus

A focus is stored on disk as a .ftr file (the "focus file") together with a collection of data files and other files in two folders, with names ending in .rdx ("Raw Data eXtract") and .xtr ("eXTRa"). The folders are normally hidden from view in Portrait Miner and in the "Quadstone" tab of a Portrait Miner file browser [see Browsing to open or save a file, session or database table].

A new focus that is created by copying an existing focus or by importing data from another kind of dataset (or as a result of running a TML script) is independent of other foci. On the other hand, a focus that is saved from Decision Studio with a new name, or one that is created by making a linked copy is dependent on data folders belonging to other foci.

For a particular focus, you can find out which other foci it depends on, and which foci are dependent on it, as well as the amount of disk space used for storing data and metadata: in Portrait Miner, right-click on the focus, and choose Properties.

In the Display Focus Properties dialog, you can choose to save the focus-properties report as an XML or HTML file. The properties of the focus are also displayed in the Output tab, in the format selected for the output file.

Note: This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsinfo.

See also

About Portrait Miner wizards

Using Portrait Miner data-build commands for data import, processing, and export


Copying focus metadata from one focus to another

You can copy focus metadata [see Focus metadata] from one focus to another, including definitions of derived fields, field interpretations, binnings, record selections, field and focus comments, and focus history.

One way of doing this is to save focus metadata in a file and then apply the saved metadata to another focus. Another way is to use one focus directly as a metadata "template" for another focus.

Note: When you apply a metadata template to a focus, field and focus comments are not included. Also, you cannot apply a metadata template to a target focus if the target focus already has field interpretations, selections, or binnings.

See also

Using Portrait Miner data-build commands for data import, processing, and export
Parent topic: Working with focus metadata

To save focus metadata

In the Decision Studio window, choose Focus>Export Metadata, and browse [see Browsing to open or save a file, session or database table] to choose a location in which to save the focus-metadata file.

To export metadata from a focus using Portrait Miner

In Portrait Miner, right-click on the focus, and choose Metadata>Export.

The Export Metadata dialog appears. You can choose a location for the saved metadata file (or simply accept the default).

Note: This user interface is a way of accessing the functionality provided by the Portrait Miner data-build command qsexportmetadata (and has exactly the same effect as saving metadata from Decision Studio).

To apply saved metadata to a new focus

In Portrait Miner, do one of the following:
  • Right-click on the focus-metadata (.qsfm) file, and choose Import as Metadata to Focus.

    In the Import Metadata to Focus dialog box, choose the target focus.

  • Right-click on the target focus, and choose Metadata>Import.

    In the Import Metadata to Focus dialog box, choose the focus-metadata file.

You can choose exactly what kind of metadata to import and change the target for the focus. Once the parameters are defined, click Next to choose import details.
Note:
  • Unless you explicitly select fields, Portrait Miner imports field-related metadata for all fields in the focus.
  • The default behavior is to overwrite the target focus with a focus containing the chosen metadata. If you clear the relevant check box, you can specify a location for a new focus instead.
  • When importing metadata, categorical interpretations are classified as binnings, not interpretations.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsimportmetadata.

See also

About Portrait Miner wizards


Editing focus metadata in Excel

You can edit focus metadata [see Focus metadata] in Excel, including field display labels, interpretations, tags, derivations, and comments.
  1. Export a metadata file [see To save focus metadata] from a focus. For a newly imported dataset, this will be a blank template, and for a dataset you've worked on it will contain all the labels, tags, binnings, derivations and other details you've added.
  2. To create an Excel file to edit, right-click on the metadata file and choose Import to Excel.
  3. To edit the metadata in Excel, right-click on the Excel file and choose Send to Excel. More details of how to edit the metadata are contained within the Excel file.
  4. To create a focus metadata file, right-click on the Excel file and choose Export as Quadstone Focus Metadata.
Parent topic: Working with focus metadata


Working with field groups

  • Tagged field groups
  • User tags


Tagged field groups

You can manage groups of fields according to the tags added to a field.
Parent topic: Working with field groups

About tags

A tag can be a user tag or an interpretation. Each user tag is represented by a colored marker containing its initial letter. The colors of these markers are generated automatically.
The Tags tab on the left side of the Decision Studio window shows the current tags. Each tag is shown on a separate row with:
  • A status indicator, and a drop-down menu to control whether or not fields with this tag should be shown:
    • No preference: Fields that have this tag may or may not be shown, depending on the choices made for other tags.
    • Show Fields With This Tag: Fields that have this tag will be shown unless they also have a tag that is set to be hidden. Fields that do not have this tag will be hidden unless one of their tags is also set to be shown.
    • Always Hide Fields With This Tag: Fields that have this tag will be hidden even if the field has another tag that is set to be shown.
  • For user tags, its colored marker.
  • The name of the tag.
  • In parentheses, the number of fields that have this tag. In the case of the Derived interpretation this text also shows the number of newly-created fields if they are hidden from view.
When any tool is launched, the fields that are shown within it are based on the current display in the Decision Studio window. However, most field lists in the application also have an All Focus Fields check box that allows all fields to be viewed regardless of the view in the Decision Studio window.
  • The Scorecard Builder always shows the fields with the Analysis interpretation. The fields shown in the Decision Studio window have no effect on this.
  • The Decision Tree Builder and Cluster Builder show the fields with the Analysis interpretation as well as any fields that were shown in the Decision Studio window but do not have the Analysis interpretation when they were launched. In addition any fields that had Analysis interpretation when the tool was launched, but have had that interpretation removed, will remain to be shown.
  • The viewers (Crosstab Viewer, Map Viewer, Crossdistribution Viewer and Profile Viewer) show all fields that are currently visible in the Decision Studio window, plus any that have been used in the crosstab specification during the tool's lifetime.
Note: If using a focus with a large number of fields, set up a view of the fields that are of interest to you in the Decision Studio window before launching tools.

See also

User tags

Field interpretations

Showing or hiding fields in Decision Studio

Click on the tag status menu to choose what field group is shown or hidden. Alternatively, clicking directly on the status icons will cycle through the three available states.

The number of fields currently shown, and the total number of fields is shown in a status bar at the bottom of the window.

Note: When Decision Studio is started or a focus is loaded, all tags have the No preference state, hence all fields will be shown.

To show all fields

To reset the view to the default, where all tags are set to No preference and all fields are shown, right click anywhere in the Tags tab and select Show All Fields.


User tags

In Decision Studio fields can be given tags, and fields can be shown or hidden based on these tags. A tag is simply a word that is associated with a field. A field can have any number of tags and a tag can be associated with any number of fields.
Parent topic: Working with field groups

To create a tag

  1. In the Decision Studio window, highlight the fields that you want to tag.
  2. Right-click and select Add User Tag > New , or alternatively, select Tag > New or Tag > Add User Tag > New from the main menu.
  3. Enter a name for the tag and click OK. Note: Avoid using tag names that start with the same letter to ensure each gets a different letter in the User Tags column within the Decision Studio window.
  4. Choose, from the Tag these Fields options:
    • None, to create a tag that is not associated with any fields.
    • Selected Fields, to create a tag and add it to the fields that are currently highlighted in the Decision Studio window.
    • Fields Matching Regular Expression, to create a tag and add it to fields that match a regular expression. For example, .*Code regular expression matches all fields which end in Code.
  5. Click OK.

See also

Regular expressions

To delete a tag

  1. In the Decision Studio window, right-click the tag in the User section of the Tag panel.
  2. Select Delete from the menu.

To rename a tag

  1. In the Decision Studio window, right-click the tag in the User section of the Tag panel.
  2. Select Rename from the menu.

To add a field to a tagged group

  1. In the Decision Studio window, highlight the fields that you want to tag.
  2. Choose Add User Tag either by right-clicking on the highlighted fields or from the Tag menu.
  3. Click the desired tag name. Note: Where the field or fields already have the tag, the name is grayed out.

To remove a field from a tagged group

  1. In the Decision Studio window, highlight the fields from which you want to clear a tag.
  2. Choose Clear Tag either by right-clicking on the highlighted fields or from the Tag menu.
  3. Click the tag name. Where none of the fields have the tag, the name is grayed out.
Note: A tag that is not associated with any field is not saved with the focus.

To view field tags

  1. In the Decision Studio window, highlight a field.
  2. Choose Field>Properties, or right-click and choose Properties, or click on [image] on the toolbar.

To edit regular expression tags

If you have created a regular expression tag, you can update the regular expression and reapply it against all fields.

  1. In the Decision Studio window, right-click the regular expression tag in the User panel (left side menu).
  2. Select Edit and update the name or regular expression.
  3. Click OK. The system reaplies the regular expression to all fields.
Note: The edit option is only available in the current session. When you reload a saved focus, the regular expression tag is available but you can no longer edit the values.


Summarizing, segmenting, and visualizing focus data using crosstabs

  • Crosstabs as a basis for segmenting and visualizing data
  • Aggregation functions for crosstabs
  • To create a textual crosstab view
  • Arranging fields and statistics in a crosstab or graph
  • To show more detail in a selected segment of a graph
  • To apply a crosstab to a focus


Crosstabs as a basis for segmenting and visualizing data

Decision Studio uses abstract crosstabs as the basis not only for crosstab views but also for profile, crossdistribution, and map graphs.

A crosstab in this sense consists of zero or more breakdown fields, together with one or more statistics. The statistics are evaluated for every cell of the potentially multi-dimensional segmentation that is defined by the binnings on the breakdown fields.

Once you have specified an abstract crosstab and the statistics have been computed, you can arrange the fields and statistics [see Arranging fields and statistics in a crosstab or graph] as you please within your tabular crosstab view or graph.

See also

Aggregation functions for crosstabs
Parent topic: Summarizing, segmenting, and visualizing focus data using crosstabs

To specify the fields and statistics in a crosstab

  1. In the Crosstab Viewer, Profile Viewer, Crossdistribution Viewer, or Map Viewer, choose Edit>Edit Crosstab or click on [image] on the toolbar.

    The Select Fields and Aggregation Functions dialog box appears.

  2. Highlight the required breakdown fields in the Available Fields pane and click on [image], to add the highlighted fields to the Selected Fields pane.
  3. For each required statistic:
    1. Highlight the aggregation function [see Aggregation functions for crosstabs] in the Available Functions pane.
    2. If the aggregation function takes an argument, highlight the required field in the Function Parameters pane.
    3. Click on [image], to add the statistic to the Selected Aggregation Functions pane.

    (In fact, you can highlight multiple aggregation functions and/or fields at the same time, in which case, when you click on [image], you get all the valid function/field combinations as statistics.)

  4. Click on OK to create the crosstab.
Note:
  • If a viewer is following [see Tool relationships] another viewer (except for a Profile Viewer following another kind of viewer or vice versa), you can check Use Leader Specification to make the following viewer inherit the leading viewer's abstract crosstab specification (along with its highlighted segment data).

    The Use Leader Specification option is selected by default (where applicable) when you drill down [see To show more detail in a selected segment of a graph] using the Segments>Drill Down menu.

  • The Estimated Size bar in the dialog box gives a rough indication of how large the crosstab will be in terms of data. If the bar fills the space available, it is likely that the crosstab will be too big to be evaluated or will take a long time to access.

    You can change the limit for crosstab size by setting a preference [see To set Portrait Miner preferences]: in the Aggregation section, change the value for the max size option. (Portrait Miner uses this value when it computes the crosstab; however, the Estimated Size bar does not use it for its estimate.)

  • To remove a field or statistic from the Selected Fields or Selected Aggregation Functions pane, highlight the field or statistic and click on [image] to the right of the pane.

To save a crosstab from Decision Studio

If you want to reuse a textual crosstab, a crossdistribution graph, a set of profile graphs, or a map graph, or share it with someone who doesn't have full access to Portrait Miner, you can save the underlying abstract crosstab (including evaluated statistics).
  1. Choose File>Save As, or click on [image] on the toolbar.
  2. Browse [see Browsing to open or save a file, session or database table] to the required location and choose a name for the crosstab.

Each Decision Studio viewer saves its own kind of crosstab (with a unique filename extension), which you can open in one or more Decision Studio viewers. (You can also use the filename extension .qsxt for a generic crosstab.)

Decision Studio viewer | Filename extension | Compatible Decision Studio viewers
Crosstab Viewer | .qstv | Crosstab Viewer, Map Viewer and Crossdistribution Viewer
Crossdistribution Viewer | .qsdv | Crosstab Viewer, Map Viewer and Crossdistribution Viewer
Profile Viewer | .qspv | Profile Viewer
Map Viewer | .qsmv | Crosstab Viewer, Map Viewer and Crossdistribution Viewer
Any | .qsxt | Dependent on the actual crosstab type

See also

Exporting tabular data from Decision Studio

To apply a crosstab to a focus

To open a crosstab in Decision Studio

To save a Decision Studio model or segmentation for deployment as QMML (XML)

XML in Portrait Miner

To open a crosstab in Decision Studio

If you want to open a previously saved textual crosstab, a crossdistribution graph, a set of profile graphs, or a map graph, you can load the underlying abstract crosstab specification, which will then be applied to the current focus.
  1. Choose File>Open or click on [image] on the toolbar.
  2. Browse [see Browsing to open or save a file, session or database table] to the required crosstab file.
Note:
  • Breakdown fields and statistics that are not compatible with the current focus are not loaded.
  • When all breakdown fields and statistics are compatible with the current focus, the saved crosstab layout [see Arranging fields and statistics in a crosstab or graph] is also loaded.

See also

To save a crosstab from Decision Studio
© 2015 Pitney Bowes Software Inc. Email: software.support@pb.com


Aggregation functions for crosstabs

The following aggregation functions are available for use in abstract crosstabs [see Crosstabs as a basis for segmenting and visualizing data] in Decision Studio. Except where otherwise noted, an aggregation function takes a single numeric, string, or date field as an argument.

On most displays the functions are re-labelled with display labels. The labels can be edited in the Function Labels tab when editing view preferences via Edit in the Decision Studio window. View preferences are remembered for future sessions for each user. Function labels are not saved with the focus.

See also

Field display labels
Function | Default label | Result
Any [see any] | Sample value of | A non-null value in the field, drawn from an arbitrary non-null record in the segment
ConfIntLower [see confintlower] | 95% lower bound of | The lower bound of a 95% confidence interval for the mean of the field in the segment
ConfIntUpper [see confintupper] | 95% upper bound of | The upper bound of a 95% confidence interval for the mean of the field in the segment
Count [see count] | Quantity | The number of records in the segment (This function does not take an argument.)
CountNonNull [see countnonnull/countnonnulls] | Quantity not missing | The number of records in the segment for which the field has non-null values [see The null value]
CountNull [see countnull/countnulls] | Quantity missing | The number of records in the segment for which the field contains null [see The null value]
CountUnique [see countunique] | Distinct value of | The number of unique values that occur in the field, potentially including the null value
CountUniqueNonNull [see countuniquenonnull] | Distinct non-missing values of | The number of unique values, excluding the null value, that occur in the field
ExpectedCount [see expectedcount] | Expected quantity | The number of records that would be expected in the segment if the fields of the crosstab were independent of one another (This function does not take an argument.)
ExpectedProportion [see expectedproportion] | Expected proportion | The proportion of the population that would be expected in the segment if the fields of the crosstab were independent of one another (This function does not take an argument.)
First [see first] | First value of | The first non-null value in the field for the segment
Last [see last] | Last value of | The last non-null value in the field for the segment
Max [see max (one argument)] | Maximum | The maximum non-null value in the field for the segment
Mean [see mean (one argument)] | Average | The mean (common average) of the non-null values in the field for the segment (This function requires a numeric field as an argument.)
Median [see median] | Median | The median (middle value) of the non-null values in the field for the segment (This function requires a numeric or string field as an argument.)
Min [see min (one argument)] | Minimum | The minimum non-null value in the field for the segment
Mode [see mode] | Most common | The mode (most-common value) of the non-null values in the field for the segment
ModeRatio [see moderatio] | Purity of | The proportion of non-null records in the segment that contain the most-common non-null value in the field
PercentageRate [see percentagerate] | Percentage of | The percentage of non-null records in the segment that contain the value 1 in the field The field must contain only the values 0 and 1.
Proportion [see proportion] | Proportion | The number of records in the segment, as a proportion of the total number of records (This function does not take an argument.)
SegmentIndex (segindex) [see segindex] | Segment index | A positive number uniquely identifying the segment within the crosstab (This function does not take an argument.)
Significance [see significance] | Significance of | The statistical significance of any discrepancy between the mean value of the field in the segment and the mean value of the field for the whole population, with a sign indicating the direction of the deviation (This function requires a numeric field as an argument.)
StandardDeviation (stdev) [see stdev] | Std. dev. of | The standard deviation of the non-null values in the field for the segment (This function requires a numeric field as an argument.)
Sum [see sum (one argument)] | Sum of | The sum of the non-null values in the field for the segment (This function requires a numeric field as an argument.)
Variance [see variance] | Variance of | The variance of the non-null values in the field for the segment (This function requires a numeric field as an argument.)
Note: Certain aggregation functions (such as Median and Mode) can produce string or date results — when you apply them to string or date fields. Because the graphical viewers cannot display string or date statistics, you cannot apply such functions to string or date fields except in the Crosstab Viewer (which can display string and date statistics).
Parent topic: Summarizing, segmenting, and visualizing focus data using crosstabs


To create a textual crosstab view

  1. In the Decision Studio window, highlight one or more fields that you want to use in your crosstab.
  2. Choose Tools>Crosstab Viewer or click on [image] on the toolbar.

    The Crosstab Viewer opens and displays a table — broken down by the fields that you highlighted — of record counts and average values for a numeric objective , if one is set.

Note:
  • If you start the Crosstab Viewer without highlighting any fields, the Select Fields and Aggregation Functions dialog box [see Crosstabs as a basis for segmenting and visualizing data] appears. If you then click on OK without choosing any fields, the Crosstab Viewer shows summary statistics for the entire population.
  • To change the underlying crosstab [see Crosstabs as a basis for segmenting and visualizing data] at any time, choose Edit>Edit Crosstab or click on [image] on the toolbar.
  • If there are any string fields in the requested crosstab that have neither a categorical nor a geographical interpretation, the Crosstab Viewer prompts you to interpret them, so that they can be binned appropriately. You can choose the default categorical interpretation, use a saved categorical hierarchy, or interpret the field as geographical.

See also

To open a crosstab in Decision Studio

Arranging fields and statistics in a crosstab or graph

Parent topic: Summarizing, segmenting, and visualizing focus data using crosstabs

Crosstab views

By default, the Crosstab Viewer includes all fields as row headers [image], the one exception being that if you highlight exactly two fields in the Decision Studio window before opening the Crosstab Viewer, the Crosstab Viewer makes one a row header and the other a column header.

When there are both row and column headers, there is only room to show one tabulated statistic at a time; if you have more than one, the Crosstab Viewer tabulates each statistic in its own tabbed pane:

As well as the ordinary bins of the breakdown fields, there are three extraordinary bins: the null [see The null value] bin, the unclassified bin, and the special crosstab summary bin, which contains all customer records. So, for example, the records that fall in both the 50 — 59 Age bin and the summary Gender bin are simply the records that fall in the 50 — 59 Age bin. What this means in practice is that when you include summary bins in a crosstab view, you can read off the information for every possible crosstab involving any of the breakdown fields.

The Crosstab Viewer has the following view options:

  • Choose View>Null Data, or click [image] on the toolbar, to turn the display of null bins on or off.
  • Choose View>Summary Data, or click [image] on the toolbar, to turn the display of summary bins on or off.
Note:

Although every binning contains a bin for the null value, not every binning contains an unclassified bin.

See also

To maximize screen space for a Decision Studio tool

To set the display format for numeric and date values


Arranging fields and statistics in a crosstab or graph

You can arrange fields and statistics by using the graph configuration area at the bottom of the Crosstab Viewer, Profile Viewer, Crossdistribution Viewer, or Map Viewer:

  • The fields and statistics that are present in the underlying crosstab [see Crosstabs as a basis for segmenting and visualizing data] are represented as movable buttons, for example:

  • The [image] (Information only) bar at the bottom of the graph configuration area shows fields and statistics that are part of the underlying crosstab but don't feature in the displayed table or graph.
  • The green ( [image]) parts of the graph configuration area represent aspects of the crosstab or graph with which you can associate fields:
    Icon Crosstab/graph aspect
    x (left — right) axis, in the Crossdistribution Viewer or Profile Viewer
    y (front — back) axis, in the Crossdistribution Viewer
    z (vertical) axis, in the Crossdistribution Viewer
    Treated/control segment comparison dimension, in the Crossdistribution Viewer or Crosstab Viewer; typically for use with a partition field
    Row breakdown field, in the Crosstab Viewer
    Column breakdown field, in the Crosstab Viewer
    Location for plotted blocks and raised regions, in the Map Viewer
    Location for the starts of arrows, in the Map Viewer
    Location for the ends of arrows, in the Map Viewer
  • The lilac ( [image]) parts of the graph configuration area represent aspects of the crosstab or graph with which you can associate statistics:
    Icon Crosstab/graph aspect
    Block color (block, region, or arrow color in the Map Viewer)
    Block height (block or region height in the Map Viewer)
    Block width
    Block depth
    Block volume
    Tabulated statistic, in the Crosstab Viewer
    Thickness of an arrow, in the Map Viewer
Parent topic: Summarizing, segmenting, and visualizing focus data using crosstabs

To associate a field or statistic with a crosstab/graph aspect

Drag the field or statistic (that is, the corresponding movable button in the graph configuration area) and drop it next to the icon for the desired crosstab/graph aspect.

As you drag a field or statistic, the mouse pointer changes to reflect what will happen when you release the mouse button:

Pointer | Action
 | Associate the field or statistic with the crosstab/graph aspect.
 | Swap the dragged field or statistic and the field or statistic under the mouse pointer.
 | Do nothing.
Note:
  • You can associate a statistic with more than one aspect of a graph by creating an extra movable button for the statistic: right-click on the statistic and choose Duplicate.

    To remove an unwanted duplicate statistic, drag one copy on top of another; drop when the mouse pointer changes to

    You can duplicate a field in the same way in the Map Viewer — for simultaneous use with plotted blocks/regions and arrows.

  • When you right-click on a movable button representing a field you can launch a Binning Editor to edit the binning, or a Select Values dialog box to change the record selection. These operation apply to the whole dataset, not just the current view.
  • When you right-click on a movable button representing a field or statistic, you also have the option of filtering values out from the graph. This is a filter on the current view only. If you choose Filter, a Filter dialog box appears. There are different options for categorical filtering [see Value selection or filtering using a categorical field] and non-categorical filtering [see Value selection or filtering using a non-categorical field or statistic].

    You cannot add, edit, or remove a filter while a segment in the graph is highlighted. Decision Studio removes all filters when the crosstab or graph updates.

  • When you use the comparison ( [image]) dimension — often with a partition field — you can configure the comparison functions displayed. Right-click on a statistic and choose Delta Configuration. In the Configure Function Delta Types dialog box, you can choose to include all records, treated records, or control records — or one of several ratios and differences. In the Crossdistribution Viewer, axis and color-scale legends are annotated accordingly.

To remove a field or statistic from a crosstab or graph

Drag the field or statistic (that is, the corresponding movable button) from its current location to the [image] bar.


To show more detail in a selected segment of a graph

In the Profile Viewer, Crossdistribution Viewer, or Map Viewer, do one of the following:
  • Double-click on a segment. (To show more detail for multiple segments, highlight the segments [see Highlighting segments in a graphical display] and continue to press the CTRL key while double-clicking on the last segment.)

    Decision Studio opens another viewer of the same type, with the same crosstab specification [see Crosstabs as a basis for segmenting and visualizing data] .

  • Highlight a segment or segments [see Highlighting segments in a graphical display] of interest. From the Segments>Drill Down menu, choose a tool in which to profile the selected segments: the Crosstab Viewer, Profile Viewer, Crossdistribution Viewer, or Map Viewer.

    If you choose the Profile Viewer from one of the other three viewers, or vice versa, you must specify the fields and statistics [see To specify the fields and statistics in a crosstab] that you require in your segment profile. In all other cases, Decision Studio uses the same crosstab specification [see Crosstabs as a basis for segmenting and visualizing data].

In either case, the new viewer is linked [see Tool relationships] to the original viewer and the newly created graph shows more detail of the highlighted segments (where possible).

Note:
  • If you highlight new segments in the first graph, the second graph updates accordingly.
  • The same drilldown behavior applies to all pairs of tools in a tool-following relationship [see Tool relationships].
  • In the Map Viewer, the level of detail available is dependent on the map.
Parent topic: Summarizing, segmenting, and visualizing focus data using crosstabs


To apply a crosstab to a focus

You can apply a crosstab specification [see Crosstabs as a basis for segmenting and visualizing data] to a focus to create a new crosstab.
  • In Portrait Miner, right-click on the crosstab that you want to apply, and choose Apply to Focus.

In the Apply Crosstab dialog, choose the crosstab that you want to apply, the focus to which you want to apply it, and the crosstab file that you want to create.

Note:
  • By default, when you apply a crosstab to a focus, the binnings for the breakdown fields come from the new focus. By checking the appropriate box, you can use the binnings associated with the original crosstab instead.
  • This user interface is a way of accessing some of the functionality provided by the Portrait Miner data-build command qsxt.

See also

About Portrait Miner wizards

To open a crosstab in Decision Studio

Using Portrait Miner data-build commands for data import, processing, and export

Viewing and editing text files in Portrait Miner

Parent topic: Summarizing, segmenting, and visualizing focus data using crosstabs


Visualizing and segmenting focus data graphically

  • To create a set of single-variable profile graphs
  • To create a multi-variable crossdistribution graph
  • To create a graph on a map
  • To create a category map from a categorical binning hierarchy
  • Options affecting the display of graphs and decision trees
  • Creating a Profile and Audit of a focus


To create a set of single-variable profile graphs

  1. In the Decision Studio window, highlight one or more fields that you want to use to profile your data.
  2. Choose Tools>Profile Viewer or click on [image] on the toolbar.

    The Profile Viewer opens and displays a graph of record counts by bin for each of your chosen fields.

Note:
  • If a numeric objective is set in the focus, the Profile Viewer shows the mean of the objective as block color (unless you have changed the objective function preference).
  • If you start the Profile Viewer without highlighting any fields, the Select Fields and Aggregation Functions dialog box [see Crosstabs as a basis for segmenting and visualizing data] appears.
  • To change the underlying crosstab [see Crosstabs as a basis for segmenting and visualizing data] at any time, choose Edit>Edit Crosstab or click on [image] on the toolbar.
  • If there are any string fields in the requested crosstab that have neither a categorical nor a geographical interpretation, the Profile Viewer prompts you to interpret them, so that they can be binned appropriately. You can choose the default categorical interpretation, use a saved categorical hierarchy, or interpret the field as geographical.
  • You can associate [see Arranging fields and statistics in a crosstab or graph] multiple statistics with block height, to compare similar statistics on a single set of axes for each profiled field.

    As long as there is no statistic associated with block color, the Profile Viewer uses rainbow coloring to distinguish the overlaid graphs associated with different statistics.

  • If you associate multiple statistics with block height, you should ensure that graphs are scaled jointly [see To scale a set of profile graphs jointly or independently]; otherwise, you cannot compare values for the different statistics.

See also

To open a crosstab in Decision Studio

Arranging fields and statistics in a crosstab or graph

Histogram and bar-graph options

Options affecting the display of graphs and decision trees

To orient a graphical display using the mouse

To scale a set of profile graphs jointly or independently

Parent topic: Visualizing and segmenting focus data graphically


To create a multi-variable crossdistribution graph

  1. In the Decision Studio window, highlight one or more (typically two or more) fields that you want to use to break down your data.
  2. Choose Tools>Crossdistribution Viewer or click on [image] on the toolbar.

    The Crossdistribution Viewer opens and displays a plot of record counts in segments defined by your chosen fields.

Note:
  • The Crossdistribution Viewer represents record count by block height by default if you highlight one or two breakdown fields, while it uses block volume if you highlight three breakdown fields.
  • If you highlight more than three breakdown fields, the Crossdistribution Viewer only uses three of them initially, with the remainder appearing in the [image] (Information only) bar, at the bottom of the window.
  • If a numeric objective is set in the focus, the Crossdistribution Viewer shows the mean of the objective as block color (unless you have changed the objective function preference).
  • If you have set a partition field in the focus, the Crossdistribution Viewer includes it in the crosstab and assigns it to the comparison [see Arranging fields and statistics in a crosstab or graph] ( [image]) dimension. For a statistic involving Count, Mean, PercentageRate, or Sum, the Crossdistribution Viewer shows the statistic for the treated population minus the statistic for the control population. For all other statistics, the Crossdistribution Viewer shows the statistic for the whole population. You can change the displayed comparison [see To associate a field or statistic with a crosstab/graph aspect].
  • If you start the Crossdistribution Viewer without highlighting any fields, the Select Fields and Aggregation Functions dialog box [see Crosstabs as a basis for segmenting and visualizing data] appears.
  • To change the underlying crosstab [see Crosstabs as a basis for segmenting and visualizing data] at any time, choose Edit>Edit Crosstab or click on [image] on the toolbar.
  • If there are any string fields in the requested crosstab that have neither a categorical nor a geographical interpretation, the Crossdistribution Viewer prompts you to interpret them, so that they can be binned appropriately. You can choose the default categorical interpretation, use a saved categorical hierarchy, or interpret the field as geographical.

See also

To open a crosstab in Decision Studio

Arranging fields and statistics in a crosstab or graph

Histogram and bar-graph options

Options affecting the display of graphs and decision trees

To orient a graphical display using the mouse

Parent topic: Visualizing and segmenting focus data graphically


To create a graph on a map

  1. In the Decision Studio window, associate one or more fields with a map by interpreting them as geographical fields (if they don't already have the Geographical icon [image] next to them in the Interpretations column):
    1. Highlight the fields to be associated with a map.
    2. Choose Tag>Interpretation>Geographical.

      A Portrait Miner file browser [see Browsing to open or save a file, session or database table] appears.

    3. Browse to the required map file.

      The Geographical icon [image] in the Interpretations column in the Decision Studio window indicates the presence of a geographical interpretation.

  2. Highlight the geographically-interpreted fields that you want to use in your map graph. The fields must all be associated with the same map.
  3. Choose Tools>Map Viewer or click on [image] on the toolbar.

    The Map Viewer opens and displays your chosen map, with the record count in each region represented by block height (if you only highlighted one field).

Note:
  • You can also interpret a field as geographical from the Binning Editor: right-click on the field name in the Fields pane and choose Interpretations>Geographical.
  • If you highlight two or more geographical fields, the Map Viewer only uses two of them initially, with the remainder appearing in the [image] (Information only) bar, at the bottom of the window. Instead of showing record counts, the map shows line links between regions, where the thickness of a line links represents the number of records that connect the start region to the end region.

  • If a numeric objective is set in the focus, the Map Viewer shows the mean of the objective as block color or line-link color, depending on the type of graph (unless you have changed the objective function preference).
  • If you start the Map Viewer without highlighting any fields, the Select Fields and Aggregation Functions dialog box [see Crosstabs as a basis for segmenting and visualizing data] appears.
  • To change the underlying crosstab [see Crosstabs as a basis for segmenting and visualizing data] at any time, choose Edit>Edit Crosstab or click on [image] on the toolbar. The breakdown fields must all be associated with the same map.

See also

To open a crosstab in Decision Studio

Arranging fields and statistics in a crosstab or graph

Options affecting the display of graphs and decision trees

To create a category map from a categorical binning hierarchy

To orient a graphical display using the mouse

Parent topic: Visualizing and segmenting focus data graphically


To create a category map from a categorical binning hierarchy

  1. In Portrait Miner, right-click on the categorical binning hierarchy file from which you want to create a category map, and choose Create Category Map.

    The Create Category Map dialog box appears.

  2. Choose the location for the new category map.
  3. Optionally, choose the type of category map to create.
  4. Optionally, choose not to overwrite any existing category map of the same name.
  5. Click on OK.
Note: This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsmapgen.

See also

About Portrait Miner wizards

To create a graph on a map

To save a categorical binning hierarchy

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Visualizing and segmenting focus data graphically


Options affecting the display of graphs and decision trees

There are a number of options that control how graphs appear. Some are global and apply to all your graphs, while others only apply to an individual graph.

See also

To maximize screen space for a Decision Studio tool

Field display labels

Parent topic: Visualizing and segmenting focus data graphically

To set global options for graphical displays

  1. In the Decision Studio window, choose Edit>View Preferences.

    The Format dialog box appears. Three of its five tabbed panes control the display of graphs:

    Pane | Description
    Graph Options | Choice of elements to be included with graphs (axis bars, axis labels, grid, tick marks, and tick labels); choice of colors for graph elements; choice of colors for bins in the Binning Editor; choice of colors and color scaling [see To change the color range for blocks in a graph or decision tree] for graph blocks; and whether to invert black, white, and gray when printing (and saving the image of) a graph
    Tick Label Font | Font selector for tick labels, that is, field values
    Axis Label Font | Font selector for axis labels, that is, field names
    Function Labels | Alternative display text for aggregation function names
  2. Click on OK, to confirm any changes and close the dialog box.
Note:
  • Your settings are saved for future Decision Studio sessions, Profile and Audits, and Model Snapshots.
  • The Axis Label Font setting also governs the font used to label decision trees.
  • In the Bin Colors pane, the Bins and Outliers settings are the colors that the Binning Editor uses for normal bins and end bins respectively. (The Bins setting is also the color Decision Tree Builder uses for the bar graphs on segments in continuous trees.)
  • In the Element Colors pane, the Map setting is the color that the Map Viewer uses for the outline of the map itself.

See also

To set the display format for numeric and date values

To change the color range for blocks in a graph or decision tree

  1. In the Decision Studio window, choose Edit>View Preferences. The Format dialog box appears, with the Graph Options tab selected.
  2. Use the drop-down color selectors in the Block Colors pane to choose colors to represent "High," "Mid," and "Low" values (by default, red, green, and blue respectively). The exact interpretation of these colors depends on the form of color scale chosen. For a decision tree, the interpretation of these three colors depends on the settings in the View Configuration for Decision Tree dialog box [see To control the use of color and depth in a decision tree].

  3. In the Viewer Color Map pane, choose the form of color scale used:

    Scaling | Description
    Linear | An even spread of colors between the minimum and maximum values, with the minimum represented by the Mid color and the maximum represented by the High color
    Linear With Zero (default)

    If there are no negative values: an even spread of colors between zero and the maximum value, with zero represented by the Mid color and the maximum represented by the High color

    If there are no positive values: an even spread of colors between the minimum value and zero, with the minimum represented by the Low color and zero represented by the Mid color

    If there are both negative and positive values: an even spread of colors over a range of values centered on zero, with the minimum (or negative of the maximum) represented by the Low color, zero represented by the Mid color, and the maximum (or negative of the minimum) represented by the High color
    Maximum Discrimination | A non-linear spread of colors between the minimum and maximum values, such that each perceived gradation of color corresponds to roughly the same number of records (hence maximizing discrimination between values), with the minimum value represented by the Low color, the median value represented by the Mid color, and the maximum value represented by the High color
  4. Use the Number of colors setting to control the number of distinct colors used.
  5. Click on OK.

To hide or show a color legend for a graph

In the Profile Viewer, Crossdistribution Viewer, or Map Viewer, choose View>Legend or click on [image] on the toolbar.

Note:

A color legend is not available in the Decision Tree Builder.

To show or hide segments for null and unclassified values in a graph

In the Binning Editor, Profile Viewer, Crossdistribution Viewer, or Map Viewer:
  • Choose View>Null Data, or click [image] on the toolbar, to turn the display of null bins on or off.
  • Choose View>Unclassified Data to turn the display of unclassified bins on or off.

To show or hide empty categories in a graph

In the Profile Viewer or Crossdistribution Viewer, choose View>Empty Categories to turn the display of empty categories on or off.

To scale a set of profile graphs jointly or independently

In the Profile Viewer, by default, all the profile graphs share a common scale on the vertical axis. To scale the graphs independently, choose View>Scale Globally to remove the check mark against this option.

Note:

You can associate multiple statistics with block height, so that two or more graphs share a common set of axes. If you choose independent scaling in this case, the vertical axis is unlabeled, and you cannot compare values for the different statistics.

To show or hide the vertical axis in a map graph

In the Map Viewer, check or uncheck the View>Show Height Axis menu option.

To control the use of color and depth in a decision tree

  1. In the Decision Tree Builder, choose View>Configuration.

    The View Configuration for Decision Tree dialog box appears.

  2. Using the drop-down menus, choose what, if anything, to represent as the depth and color of each segment.
  3. Set Center Segment Color Scale at to

    Root of Tree to use the middle color of the color range [see To change the color range for blocks in a graph or decision tree] (green by default) for the root segment;

    Mid-range to use the middle color (green by default) to represent the value midway between the extremes that occur in the decision tree.

    50% of Population Matching Objective etc. (the option depends on tree type) to use the middle color (green by default) to represent a particular value of match rate, objective mean, uplift etc.

  4. Click on OK.


Creating a Profile and Audit of a focus

A Profile and Audit of a focus is an HTML-format report containing detailed information on the focus, including profiles of some or all fields in the focus, optionally in relation to one or more target fields.

To create a Profile and Audit in Portrait Miner, right-click on the focus that you want to audit, and choose Create Profile and Audit.

In the Create Profile and Audit dialog box, you can choose which fields or tagged field groups to profile, whether to ignore a partition field, and which target fields to use. (If there is an objective in the focus, it is the default target field.) You can also select a subset of the records in the focus using an FDL expression [see Expressions].

After completion, the audit report is displayed on the Audit tab of the Create Profile and Audit dialog.

Note:
  • You can choose which fields to report on either by selecting field names or by choosing one or more tags [see Working with field groups].
  • You can choose one of four options for the formats of images used in the HTML output:

    svg SVG (scalable vector graphics) only. SVG offers the best image quality and smallest file sizes, but readers of your report must have a web browser with an SVG plugin to view or print these images.

    smallpng SVG plus screen-optimized PNG (portable network graphics) bitmaps. Even without an SVG plugin, readers will be able to see the images in your report (but print quality will be relatively poor).

    largepng SVG plus both printer- and screen-optimized PNG bitmaps. Readers will be able to view or print your report without needing an SVG plugin (but more disk space will be needed, and the report may be slower to view).

    none No images.

  • You can control further aspects of the appearance of Model Snapshot and Profile and Audit reports by setting preferences [see To set Portrait Miner preferences] in the Audits and Snapshots section of the Preferences window.
  • For Portrait Miner to be able to notify you by e-mail when the report is ready, you must set the emailaddress and emailserver preferences appropriately.
  • By default, Portrait Miner saves a Profile and Audit as a single .qshtml file, with embedded images. Although you can open this file in Portrait Miner (by double-clicking on it), you can't use it directly outside Portrait Miner.

    To create a web page that is suitable for placing on a web server right-click on a .qshtml file, and choose Unpack to Folder. Choose a location for the folder and click on OK. This is a way of accessing much of the functionality provided by the Portrait Miner data-build command qshtmlunpack.

  • You can create a Profile and Audit of a third-party dataset by right-clicking on the file in Portrait Miner and choosing Audit. In the dialog that appears, you can choose a location for the temporary focus that Portrait Miner creates in the course of preparing the report; in the report, the name of this focus appears instead of the name of the original dataset.
  • The Create Profile and Audit dialog is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsaudit.

See also

About Portrait Miner wizards

Creating a Model Snapshot

To set global options for graphical displays

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Visualizing and segmenting focus data graphically

Using a reference report to compare foci

A comparison report is like a normal Profile and Audit report, except that it includes side-by-side profiles of fields in two foci, together with details of the differences between various statistics, allowing you to observe changes over time, for instance.

To create a comparison report, create a Profile and Audit report for your first focus in the usual way; this is your "reference report." Then create a Profile and Audit report for your second focus, but in the Create Profile and Audit dialog, specify the reference report that you created earlier.

Note:
  • Categorical fields must have the same binnings in both foci.
  • By default, the comparison report includes the same fields as in the reference report. If you explicitly choose fields to include in the comparison report, they are added to the previously profiled fields.
  • The comparison report uses the same target fields as in the reference report. Any explicitly specified target fields are ignored.


Test/training methodology

  • Test/training methodology for robust modeling
  • To partition a focus into sample subpopulations
  • To apply a Decision Studio model or segmentation to a different population


Test/training methodology for robust modeling

When you build a model, you need some means of determining its quality. Not only do you need to know how well it describes historical data, but you also need to know how robust it is as a predictor of future behavior.

The problem of overfitting For a scorecard or decision tree, % or clustering model, you can use a quality measure such as the Gini measure to give an indication of how accurately the model describes a dataset: in general, the higher the number, the better. But you must be careful to avoid overfitting, which can occur if your model is too specific to the dataset that was used to build it.

In principle, you can build a decision tree or scorecard that fits a given dataset perfectly. For example, given sufficient resources you could bin your customer-identifier field so that there is one customer in each bin, interpret that field as the sole analysis candidate, and build a decision tree with as many levels as needed to make every leaf segment homogeneous in respect of the objective.

Clearly, such an extremely overfit model is of limited use. It is just as complicated as the original historical dataset and takes no advantage of patterns in the data. It certainly provides no insights into customer behavior. But too simple a model may not take advantage of patterns in the data either.

To a certain extent, you can apply business knowledge to decide which fields to include in a model and even how to bin those fields. But there is always the temptation to squeeze a little more from a model and thus risk overfitting. For that reason, you need some means of testing your model.

A solution — training and test datasets One way to avoid overfitting is to partition your focus [see To partition a focus into sample subpopulations] into training and test datasets, with perhaps 67% of the data in the training set and 33% of the data reserved for the test set. You can build a model using data in the training set and then, when you are satisfied with its descriptive power, apply it to the test set [see To apply a Decision Studio model or segmentation to a different population] to test its predictive power. If your chosen quality measure drops markedly when you apply the model (for example, if the Gini drops by more than around 2%), you should suspect overfitting.

If your model isn't sufficiently robust, you can go back to the training set and try to improve the model (by changing included fields, binnings, quality measures, etc.).

However, if you repeat this process too many times, you risk overfitting all over again because you are now using the whole focus to influence the form of the model. The solution is to use three sample subpopulations, with perhaps 60% of the data used for training, 30% for testing, and the remaining 10% for validation. You can now afford to use the feedback from testing to refine the model. After a few iterations, you can apply the model to the validation set [see To apply a Decision Studio model or segmentation to a different population] to check its robustness.

Parent topic: Test/training methodology

Automatic pruning in the Decision Tree Builder

In the Decision Tree Builder, you can use automatic pruning [see To prune part of a decision tree automatically] in conjunction with test and training datasets to create decision trees that are more robust. Using cost-complexity pruning, the Decision Tree Builder automatically identifies the pruned tree that performs best on the test set.


To partition a focus into sample subpopulations

  1. Decide on the number of subpopulations n and their relative sizes [image] (where [image]).
  2. In the Table Viewer, derive a field [see To derive a field using the Table Viewer] using one of the following:
    • If you want two subpopulations (n = 2), use the numericTestTrainSplit function.
    • If you want three subpopulations (n = 3), use the numericTestTrainValidateSplit function.
    • If you want subpopulations of equal size ( [image]), use the sampleEqualSize function.
    • Otherwise, use the following definition:

      For example, to create four subpopulations, containing (approximately) 40%, 30%, 20%, and 10% of the total population respectively, you could use the following field definition:

      a := rndUniform();

      case a < 0.4 : 1; // 0.4 = 40%

      a < 0.7 : 2; // 0.7 = 40% + 30%

      a < 0.9 : 3; // 0.9 = 40% + 30% + 20%

      default : 4

    The focus is now partitioned according to the values in the field that you have derived. Depending on the expression you chose, the values are 1, 2, ..., n, or 0, 1, ..., n-1.

  3. Interpret the field as categorical [see To set or clear an analysis candidate, categorical, geographical, export or key interpretation].
  4. Optionally, rename [see To rename a category] the new categories appropriately.

To use a particular subpopulation, select records [see Selecting customer records] with the required value in the field.

Note:
  • You can use the testTrainSplit function as an alternative to the numericTestTrainSplit function.
  • You can use the testTrainValidateSplit function as an alternative to the numericTestTrainValidateSplit function.
  • As an alternative to using the Select Values dialog box to switch between subpopulations, you can use the Binning Editor. Link [see To link and unlink tools] your analysis and visualization tools to the output of the Binning Editor; switch between subpopulations by highlighting the required bin of the field that you have derived.

See also

sampleExactNumber

sampleExactPercentage

sampleStratified

Parent topic: Test/training methodology


To apply a Decision Studio model or segmentation to a different population

  • The simplest way to apply a model to a different population is to change the current record selection [see Selecting customer records] .
  • If you want to apply a decision tree, scorecard, or clustering model to a population in a separate focus file, save your model [see To save a decision tree, scorecard, or clustering model] then open the other focus file and apply the saved model [see To apply a saved decision tree, scorecard, or clustering model].
  • If the new population is a group of highlighted segments [see Highlighting segments in a graphical display] in another Decision Studio tool, simply link [see To link and unlink tools] the tool in which you built your model or segmentation to the appropriate data source.

The tool updates its display to show your model or segmentation applied to the new population.

In the case of the Decision Tree Builder, you can still see the statistics for the original population. In the tree view, the Decision Tree Builder shows original statistics in brackets above the applied statistics:

In textual views [see Options for displaying a decision tree], the Decision Tree Builder shows tables of figures for both original and applied populations.

Note:
  • You can control which sets of figures the Decision Tree Builder shows by choosing View>Data>Original or View>Data>Applied.
  • If you haven't set an objective in the new population, an applied decision tree just shows the number of records in each segment. A gains table [see Options for displaying a decision tree] for the new population is available for binary and uplift trees.
  • If you build a decision tree and then change the tree type, the Decision Tree Builder shows the same tree overlaid with statistics and perhaps graphs for the new tree type. The Decision Tree Builder shows the original statistics in brackets, as though the model were applied to a different population.

See also

Test/training methodology for robust modeling To save a Decision Studio model or segmentation for deployment as QMML (XML)
Parent topic: Test/training methodology

To save a decision tree, scorecard, or clustering model

  1. Having built a model in the Decision Tree Builder, Scorecard Builder, or Cluster Builder, choose File>Save As or click on [image] on the toolbar.
  2. Choose a name and location for your saved decision-tree, scorecard, or clustering-model file in the Portrait Miner file browser [see Browsing to open or save a file, session or database table].

See also

To build a clustering model

To build a decision tree

To apply a saved decision tree, scorecard, or clustering model

  1. In the Decision Tree Builder, Scorecard Builder, or Cluster Builder as appropriate, choose File>Open or click on [image] on the toolbar.

    A Portrait Miner file browser [see Browsing to open or save a file, session or database table] appears.

  2. Browse to the required decision-tree, scorecard, or clustering-model file.
Note: The current focus must contain fields with the same names and types as those used by the model.


Building decision trees for segmentation and predictive modeling

  • To build a decision tree
  • Options for displaying a decision tree
  • Controlling the building of a decision tree
  • To remove unwanted segments from a decision tree


To build a decision tree

  1. Optionally interpret some fields as analysis candidates [see To set or clear an analysis candidate, categorical, geographical, export or key interpretation].

    If there are fields with an analysis candidate interpretation, the Decision Tree Builder only considers those fields when creating decision-tree branches.

  2. Interpret a field as the modeling objective .
  3. For uplift trees only, interpret a field as the partition field. (You can only build an uplift tree if the partition field contains 0 and 1 and no other values, including the null value.)
  4. Choose Tools>Decision Tree Builder or click on [image] on the toolbar.
  5. If necessary, change the tree type (to binary tree, categorical tree, or continuous tree) using the drop-down menu on the toolbar.
    If you are not using a partition field:
    • Use a categorical tree for an objective with categorical values (or a binary tree for a two-valued objective).
    • Use a continuous tree for a non-categorical objective.
    If you want to use a partition field to do uplift modeling:
    • For a two-valued objective, use a binary uplift + tree for additive modeling or use a binary uplift x tree for multiplicative modeling.
    • Use a continuous tree for a non-categorical objective.
    • You cannot use a categorical objective with more than two values.
  6. If necessary, change the default build options [see Controlling the building of a decision tree].
  7. Choose Tree>Build to End or click on [image] on the toolbar, to build a decision tree:

Note:
  • To add another level to the current (non-applied) tree, choose Tree>Build Next Level or click on [image].
  • In each decision-tree view [see Options for displaying a decision tree], two panes to the left show included fields (analysis candidates) and excluded fields (other fields in the focus).

    You can interpret a field as an analysis candidate by moving it from the lower pane to the upper pane (and vice versa), by using the arrow buttons between the panes. If you are building one level of the tree at a time, you can even use a different set of analysis candidates for each level of the tree.

    Fields that are used in the current decision tree appear in boldface (regardless of whether they are currently analysis candidates).

  • When you start to build a decision tree, the Decision Tree Builder prompts you to interpret any string fields that do not have a categorical interpretation, so that they can be binned appropriately. You can either choose the default categorical interpretation or use a saved categorical hierarchy. If you click on Cancel when prompted to choose an interpretation for a string field, the Decision Tree Builder ignores that analysis candidate, along with any remaining string fields without a categorical interpretation.

See also

Controlling the building of a decision tree

To apply a Decision Studio model or segmentation to a different population

Parent topic: Building decision trees for segmentation and predictive modeling

To clear a decision tree

To clear a decision tree in the Decision Tree Builder, choose Tree>Clear or click on [image] on the toolar.
Note: If the Decision Tree Builder is showing the Gains View or the Graph View, it changes to show the Tree View.


Options for displaying a decision tree

The following Decision Tree Builder views are available:
View | Description
Tree View | A graphical representation of a decision tree, with the whole population represented at the top and each complete level below that representing a finer segmentation
Table View | A tabular representation of the decision tree, showing statistics for each numbered segment and an FDL-style expression describing each segment For an uplift tree, the total size is the sum of the treated and control population sizes, excluding any other records.
List View | An alternative presentation of some of the above information, in list form
Gains View | A cumulative gains table, for the "leaf" (lowest-level, childless) segments of the decision tree, sorted in descending order of match rate
Graph View | A Qini graph, available for uplift trees only

To change to a different view, either choose the view from the View menu or click on the corresponding button on the toolbar.

See also

Options affecting the display of graphs and decision trees

To orient a graphical display using the mouse

Parent topic: Building decision trees for segmentation and predictive modeling

To expand or collapse part of a decision tree

To concentrate on interesting parts of a tree, you can collapse or fold a subtree.
  1. Highlight segments [see Highlighting segments in a graphical display] that you want to fold or unfold.
  2. Choose Segments>Fold or Segments>Unfold.

    When you fold segments, the Decision Tree Builder hides the descendants of highlighted segments and marks highlighted segments with a "+" sign to indicate that some descendants are hidden.

Alternatively, you can right-click on a segment and choose Fold or Unfold from the menu that appears.

Note:
  • Folding is not the same thing as pruning [see To prune part of a decision tree manually]. When you fold part of a decision tree, only the view of the tree changes, whereas pruning affects the underlying model.
  • If you continue building the tree, the Decision Tree Builder may split hidden segments (but the child segments will also be hidden).


Controlling the building of a decision tree

You can set various constraints [see To view or alter tree-building constraints] that govern how the Decision Tree Builder builds a decision tree. You can also exert a degree of manual control by locking [see To lock or unlock segments in a decision tree] segments in a tree or pruning [see To remove unwanted segments from a decision tree] a tree.

See also

To build a decision tree

To remove unwanted segments from a decision tree

Parent topic: Building decision trees for segmentation and predictive modeling

To view or alter tree-building constraints

Choose Tree>Constraints.

The following settings are available in the Tree Constraints dialog box:

Setting | Applicable to | Description
Maximum number of levels in tree | All tree types | The largest number of generations in any branch of the tree (including the "root" segment) This only applies when you "build to end." The Decision Tree Builder stops building the tree once this number of levels is generated. If you choose Tree>Build Next Level or click on [image] , the Decision Tree Builder ignores this setting.
Minimum I-gain for split | Binary and categorical trees | The smallest acceptable value of the information gain for a split (a value between 0 and 1)
Minimum R-Square gain for split | Continuous trees | The smallest acceptable value of the [image] measure for a split (a value between 0 and 1)
Minimum uplift significance for split | Uplift trees | The smallest acceptable value of the uplift significance measure for a split (a value between 0 and 1)
Threshold for multi-valued splits | Categorical trees and uplift trees | The number of categories in a categorical analysis candidate — excluding null [see The null value] and unclassified — beyond which the Decision Tree Builder no longer considers all possible split permutations For an analysis candidate with more categories than this, the Decision Tree Builder only considers splits involving a single category on one side and the remainder on the other.
Minimum segment size | All tree types except uplift trees | The smallest number of records in a "leaf" (lowest-level, childless) segment The Decision Tree Builder ignores splits that would result in one or more segments with fewer records. If you check the Treat Minimum Segment Size as Percentage box, this number is treated as a percentage of the number of records in the population that you use to build the tree.
Minimum segment size in treated population, minimum segment size in control population | Uplift trees | The smallest number of records, in the treated and control populations respectively, in a "leaf" (lowest-level, childless) segment The Decision Tree Builder ignores splits that would result in one or more segments with fewer records in the appropriate population. The Treat Minimum Segment Size as Percentage box interprets values as percentages of the total population, not as percentages of the individual treated or control populations.

For categorical trees, there are two additional check boxes, to force the Decision Tree Builder to treat null and unclassified bins in the objective as ordinary categories.

To lock or unlock segments in a decision tree

Before you continue building a partially built decision tree, you can exclude selected segments from consideration, by locking them.
  1. Highlight segments [see Highlighting segments in a graphical display] that you want to lock or unlock.
  2. Choose Segments>Lock or Segments>Unlock.

    When you lock segments, the Decision Tree Builder marks leaf segments beneath any highlighted segments with a padlock symbol [image].

Alternatively, you can right-click on a segment and choose Lock or Unlock from the menu that appears.


To remove unwanted segments from a decision tree

You can remove unwanted segments in a tree by pruning.
Note: Pruning is not the same thing as folding [see To expand or collapse part of a decision tree]. When you prune part of a decision tree, the underlying decision tree changes, whereas folding only affects the display of the tree.

See also

To lock or unlock segments in a decision tree

To clear a decision tree

Parent topic: Building decision trees for segmentation and predictive modeling

To prune part of a decision tree manually

You can selectively remove uninteresting segments from a decision tree.
  1. Highlight segments [see Highlighting segments in a graphical display] whose descendants you want to remove.
  2. Choose Segments>Prune.

    The Decision Tree Builder removes the descendants of highlighted segments and marks highlighted segments with a padlock symbol to indicate that they are locked.

Alternatively, you can right-click on a segment and choose Prune from the menu that appears.

To prune part of a decision tree automatically

You can automatically remove overfit segments from a decision tree after building, by employing a test/training methodology [see Test/training methodology for robust modeling] and using the Autoprune [see Automatic pruning in the Decision Tree Builder] option.
  1. Build your decision tree [see To build a decision tree] on the training population.
  2. Apply this decision tree [see To apply a Decision Studio model or segmentation to a different population] to the test population.
  3. Choose Tree>Autoprune or click on [image].

The Decision Tree Builder automatically removes the segments which do not increase the performance of the decision tree on the test population.


Building scorecards for segmentation and predictive modeling

  • About the Scorecard Wizard
  • Building a scorecard using the Scorecard Wizard
  • Building a scorecard using the Scorecard Builder
  • Refining a scorecard by adding or removing fields
  • Options for displaying a scorecard
  • Controlling the building of a scorecard


About the Scorecard Wizard

The Scorecard Wizard automates scorecard modeling using best-practice methodology: performing optimized binning, then variable reduction, and finally building a sequence of models on test and training data to establish the best "model size." The modeling methodology consists of the following stages.

Test/training methodology Part of the source data is used for training, and part for testing: this split can be generated at random or using a designated binary indicator field.

Optimized binning The training data is used to select a binning for each analysis candidate that maximizes its univariate predictive power against the objective.

For non-categorical fields, the optimized binning wizard [see To optimize a binning for a field] is used iteratively to choose the best binning. The number of bins is increased until the number of "turning points" in the plot of the average objective value by bin exceeds a configurable threshold (a "turning point" being a change of sign in the slope of the graph). Intuitively, this ensures that the profile of average objective value as a function of each analysis candidate is relatively "smooth," with not too many ups and downs.

For categorical fields, categories where the average objective value is not significantly different from the overall mean are merged together. A standard difference of means test [see significance] is used, with a Bonferroni correction applied based on the total number of categories, that appear for the field. Thus, all categories where the confidence level [image] are merged (with [image] a configurable significance threshold).

During this phase, fields with suspiciously high correlation to the objective are excluded from further analysis (with a warning message). A warning is also issued for fields where any individual bin contains a small number of records. Both thresholds are configurable.

Variable Reduction The variable reduction phase reduces the pool of analysis candidates (independent predictors) from those initially marked to a smaller set of n, in order to decrease run-time of the final "right-sizing" phase.

The process partitions the analysis candidates into groups of up to 2n fields and builds a scorecard (using the training data) on each group, discarding the worst fields by stepwise exclusion [see Refining a scorecard by adding or removing fields] until only the best n fields of the group remain. By repeating this procedure, eventually the n best overall fields are identified.

Right-sizing The right-sizing phase chooses the scorecard that best balances complexity (number of predictors) against generalizability (as measured by test-set performance). The training data is used to build a sequence of n scorecards with the first containing all n analysis candidates, and each subsequent model excluding the worst predictor. The performance of each model is then assessed on the test data, with the best model size chosen using a configurable criterion. As a final step, the weights in the selected model are refit based on all data (i.e. both test and training) to improve accuracy. All interim models can be saved along with the final model if desired.

Results Various outputs are (optionally) generated, including:

  • An HTML report summarizing how the methodology was applied, including the input parameters and links to the detailed execution log. This includes a table of performance data that can be easily charted within Excel.
  • The final recommended model (in .qssc [see To save a decision tree, scorecard, or clustering model] and QMML [see To save a Decision Studio model or segmentation for deployment as QMML (XML)] formats).
  • A Model Snapshot [see Creating a Model Snapshot] report for the recommended model.
  • The final dataset including the selected analysis candidates, optimized binnings, and model predictions. Intermediate datasets can also be saved if desired, containing the metadata generated by the methodology to that point. These are often useful to drill down and explore the decisions made during the process.

See also

Building a scorecard using the Scorecard Wizard

Parent topic: Building scorecards for segmentation and predictive modeling


Building a scorecard using the Scorecard Wizard

Save your modeling focus, with the objective field, analysis candidates and categorical variables marked. This preparation can be automated by importing focus metadata [see Copying focus metadata from one focus to another] into the modeling focus.

In Portrait Miner, right-click a focus and choose Predict>Scorecard Wizard.

In the Scorecard Wizard dialog box, you can choose whether you optimize binnings, select a reduced set of variables for the final model building phase, or build a right-sized scorecard model. You can also configure advanced details which influence the model building algorithm.

Note:
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsscorecardwizard.

See also

About the Scorecard Wizard

About Portrait Miner wizards

Building a scorecard using the Scorecard Builder

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Building scorecards for segmentation and predictive modeling


Building a scorecard using the Scorecard Builder

  1. Optionally interpret some fields as analysis candidates [see To set or clear an analysis candidate, categorical, geographical, export or key interpretation].

    The Scorecard Builder only computes scoring statistics for fields that are analysis candidates (unless there are none, in which case it computes statistics for all fields).

  2. Interpret a field as the modeling objective .
  3. Choose Tools>Scorecard Builder or click on [image] on the toolbar.

    The Scorecard Builder opens.

  4. If you are using a binary (0/1) objective, choose the appropriate model type from the Scorecard>Model Type menu: risk, response, churn, satisfaction, or dissatisfaction.

    For a continuous objective, only the value model type is available.

  5. Again if you are using a binary objective, you can choose Scorecard>Invert Objective Value, to change the sense of the 0/1 objective field.

    By default, 1 in the objective indicates a defaulter, responder, churner, satisfied customer, or dissatisfied customer, according to the chosen model type.

  6. If necessary, change the default build options [see Controlling the building of a scorecard].
  7. Choose Scorecard>Build or click on [image] on the toolbar, to build a scorecard.
Note:
  • When you open the Scorecard Builder, it prompts you to interpret any string fields that do not have a categorical interpretation, so that they can be binned appropriately. You can either choose the default categorical interpretation or use a saved categorical hierarchy. If you click on Cancel when prompted to choose an interpretation for a string field, the Scorecard Builder ignores that analysis candidate, along with any remaining string fields without a categorical interpretation.
  • Your choice of model type affects the labeling of values, graphs, etc. (but only after you re-build your scorecard). There is also a more fundamental distinction between risk models and the other binary-objective model types: when applying a risk model, you typically accept customers in segments with a low predicted default rate; but when applying a response, churn, satisfaction, or dissatisfaction model, you typically target customers in segments with a high predicted response/churn/satisfaction/dissatisfaction rate.
  • If your focus contains a field that represents a record weight, highlight that field in the Scorecard Builder and choose Fields>Set Weight, before building a scorecard. For positive integer weights [image], [image], ..., the scorecard is the same as you would get from a larger dataset with [image] occurrences of the first record, [image] of the second, and so on. The weight interpretation is local to the Scorecard Builder instance.

See also

Building a scorecard using the Scorecard Wizard

Controlling the building of a scorecard

To apply a Decision Studio model or segmentation to a different population

Parent topic: Building scorecards for segmentation and predictive modeling


Refining a scorecard by adding or removing fields

In the Field View [see Options for displaying a scorecard] of the Scorecard Builder, the upper pane shows fields that are (to be) included in the scorecard, while the lower pane shows the remaining analysis candidates. A scorecard involving fewer fields is potentially easier/quicker to deploy and perhaps more robust [see Test/training methodology for robust modeling], though it may be a less-accurate model.

Using the arrows between the panes, you can manually include or exclude fields — perhaps on the basis of Gini, Cramer's V or information gain. You can also automate this process of field selection, potentially taking into account interactions between fields.

  1. Use Fields>Auto Include (or Fields>Auto Exclude) or click on [image] (or [image]) on the toolbar, to include (or exclude) fields.

    The Auto Include Options (or Auto Exclude Options) dialog box appears.

  2. Choose from the following selection criteria:
    • Stepwise Linear Fit
    • Stepwise Quality Measure

    The algorithm considers the quality of the temporary scorecards obtained by including (or excluding) each field in turn. Having included (or excluded) the single field that results in the best temporary scorecard, the algorithm repeats, until it has included (or excluded) the required number of fields.

    The quality of the temporary scorecard is determined by the currently selected quality measure [see To change the quality measure used to build a scorecard] — or linear regression if you choose the "linear fit" option. The temporary scorecard, however, is always built using the linear regression quality measure.

  3. Specify the number of fields to include or exclude at a time.
  4. Click on OK, to set the auto-include or -exclude options.
Note: You can build a good first scorecard by excluding all fields initially and then auto-including the required number of fields using stepwise linear fit.
Parent topic: Building scorecards for segmentation and predictive modeling


Options for displaying a scorecard

The following Scorecard Builder views are available:

View | Description
Field View | A two-pane view of analysis candidates and associated statistics, with fields that are included in the scorecard in the upper pane and those that are excluded in the lower pane
Tabbed View | A tabbed-pane view of the scorecard, showing weights (bin scores) and statistics for one field at a time
Scorecard View | A simpler view of the scorecard, showing the weights (bin scores) for all fields in one view
Graph View | One of five graphs [see Scorecard Builder graphs], alongside panes showing lists of included and excluded fields
Correlation Matrix | A correlation matrix for the analysis candidates

Initially, the Scorecard Builder shows the field view (and other views are unavailable until you build or open a scorecard). To change to a different view, either choose the view from the View menu or click on the corresponding button on the toolbar.

Parent topic: Building scorecards for segmentation and predictive modeling

Scorecard Builder graphs

The following graphs are available in the Scorecard Builder:

Graph | Description
Gini | The Gini curve for the scorecard model
Histogram | Superimposed plots of customers that match the objective and customers that don't match the objective against assigned score
Cumulative Histogram | A cumulative version of the above
Strategy Curve | A strategy curve, to help you pick a suitable cutoff score
Weights | A graphical representation of the scorecard, with a graph of weights (bin scores) for each field in the scorecard

You can choose the graph to display from the drop-down menu at the top right of the graph.

See also

Options affecting the display of graphs and decision trees

To orient a graphical display using the mouse


Controlling the building of a scorecard

You can control how a scorecard is built by using a different quality measure [see To change the quality measure used to build a scorecard], solver [see To change the solver used to build a scorecard], or form [see To change the form of a scorecard].
Parent topic: Building scorecards for segmentation and predictive modeling

To change the quality measure used to build a scorecard

The quality of a scorecard is an estimate of its accuracy. In building a scorecard, the Scorecard Builder attempts to maximize the scorecard quality as determined by one of three quality measures.
From the Scorecard>Quality Measure menu, choose one of the following:
  • Linear regression
  • Logistic regression
  • Probit regression
Note: For a continuous (non-binary) objective, the only quality measure available is linear regression.

To change the solver used to build a scorecard

Given a quality measure, the Scorecard Builder uses one of five solvers to attempt to maximize the scorecard quality. You can choose which solver the Scorecard Builder uses and control some aspects of the solver's behavior.

  1. Choose Scorecard>Solver.

    The Scorecard Solver dialog box appears.

  2. From the Method menu, choose one of the following:
    • Simplex
    • Powell
    • Quasi-Newton
    • Conjugate gradient
    • Levenberg — Marquardt
Note: In general, you should not need to change the quality measure or any of the settings in the Scorecard Solver dialog box. When you choose the quality measure [see To change the quality measure used to build a scorecard], the Scorecard Builder chooses the most powerful solver available for that measure.

To change the form of a scorecard

In building a scorecard, the Scorecard Builder either treats each bin of each included field as an independent variable or it assigns weights within each field and then transforms those weights according to the relative importance of the fields in the model.
  1. Choose Scorecard>Form.

    The Scorecard Form dialog box appears.

  2. In the Form pane, choose "one weight per bin" or "one weight per field."
  3. If you chose the simpler "one weight per field," specify how the Scorecard Builder transforms weights within each field.


Building association and sequencing rules

  • About the Association Rule Wizard
  • Building association and sequencing rules using the Association Rule Wizard


About the Association Rule Wizard

The Association Rule Wizard automates discovery of association and sequencing rules. This is typically used to explore detailed customer transaction, basket or event data for applications such as:

Market basket analysis identify combinations of products that commonly appear (or don't appear) together within a single purchase transaction (basket of items).

Best next product determine the most common sequence in which products or services are purchased; for example, banking customers are more likely to open an investment/trading account after opening a high-interest savings account.

Marketing impact analysis identify patterns of marketing communications that are more likely to occur before a purchase

Data preparation Association Rule Wizard runs directly against transaction or event data stored in a focus dataset, benefitting from Portrait Miner's high-performance data access.
  • For Market Basket analysis, you should use an item-level dataset containing one record per item. The dataset should contain a basket identifier field that groups items in the same basket, as well as a product identifier field (binned and categorical) that indicates the product name or code for each item. The dataset should be sorted by the basket identifier key field.
  • For Next Product analysis, you should pick a dataset with one record per product or service. The dataset should contain a basket identifier — often the customer identifier — that groups products together, along with the product identifier (binned and categorical) and a product timestamp (integer or date) that indicates the order in which products were acquired. The dataset should be sorted by the basket identifier key field.

Algorithm parameters Association Rule Wizard is based on the industry-standard apriori algorithm and includes a broad range of functionality to control rule discovery. For more information on the Apriori algorithm, see the Apriori documentation on your Portrait Miner release media (DVD/zip). The documentation is located in \server\Components\ext\qsruleminer\docs\apriori_docs.

You can restrict rule discovery to particular products of interest, and control various parameters that define what an interesting rule is (support, confidence, rule complexity, extended rule selection measures). Note that these settings can impact execution time: in particular, reducing the minimum support value will increase run time unless a maximum rule complexity (number of antecedents) is also specified.

Terminology Association Rule Wizard uses a variety of terms that might be unfamiliar, including:

Rule In general, a rule asserts that if a set of conditions is satisfied (the left-hand side, or antecedent of the rule), then some other condition will occur (the right-hand side, or consequent of the rule). In association and sequencing rules, the conditions in the rule correspond to the presence of particular items in the basket. For example, a simple rule might be: if a basket contains bread, then it will also contain jam.

Antecedent The left-hand side of a rule, i.e. the set of items that must appear in the basket for the rule to be relevent.

Consequent The right-hand side of a rule, i.e. the set of items that the rule predicts will be present when the left-hand side (antecedent) is satisfied.

Support The (absolute) support of an item set is the number of baskets that contain all items in the set. Relative support is the same number expressed as a percentage of the total number of baskets.

Rule Support The support of a rule is the support of the rule's antecedent, i.e. the proportion of baskets for which the left-hand side of the rule applies. This measures how often the rule is relevant.

Rule Confidence The confidence of a rule is the support of the set of all items that appear in the rule (on left or right), divided by the support of the rule's antecedent. It measures the likelihood that the rule's consequent (right-hand side) is true given that the antecedent of the rule is satisfied, i.e. the likelihood that the rule is correct.

Absolute Confidence Difference to Prior The difference in the posterior and the prior confidence measures (with and without the antecedent items). This measures how much more (or less) likely the rule's consequent is when the left-hand side of the rule is true. For example, the rule "if bread, then jam" is not very interesting if it's confidence is similar to the rule "if (anything) then jam".

Lift Value The ratio of the posterior and the prior confidence measures (with and without the antecedent items).

Results Various outputs are (optionally) generated, including:
  • An interactive HTML model report summarizing the rules created, their metrics and the option to filter on interesting rules.
  • A scored new dataset creating an aggregated dataset (one record per basket identifier) indicating whether each selected rule is satisfied for that group of records.
  • The rules as deployable code in Transaction Measurement Language format.
  • The rules as an optional export in the Predictive Model Markup Language (PMML) format, using the "Deploy" tab, as shown below
Parent topic: Building association and sequencing rules


Building association and sequencing rules using the Association Rule Wizard

Save your modeling focus, with the product identifier field binned and categorical. This preparation can be automated by importing focus metadata [see Copying focus metadata from one focus to another] into the modeling focus.

In Portrait Miner, right-click a focus and choose Predict>Association Rule Wizard.

In the Association Rule Wizard dialog box, you can choose the type of association rules to build, select the parameters to identify interesting rules, and which basket identifier (defaults to first field), product identifier (defaults to objective field) and product timestamp field (defaults to partition field) to analyze. You can restrict the rules created to always include a specific set of products.

Note:
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsruleminer.

See also

About the Association Rule Wizard

About Portrait Miner wizards

Parent topic: Building association and sequencing rules


Building Naive Bayes models for segmentation and predictive modeling

  • About the Naive Bayes Wizard
  • Building a propensity model using the Naive Bayes Wizard


About the Naive Bayes Wizard

The Naive Bayes Wizard builds a propensity model using Bayes' Theorem, combined with a ("naive") presumption of conditional independence, to predict the value of an objective field category, from evidence given by one or more analysis candidates. A Naive Bayes model essentially defines a set of crosstabs: for each analysis candidate there is a crosstab which contains the frequency counts of analysis bins with respect to objective categories.

A count of zero requires special attention and the Naive Bayes model incorporates a threshold parameter that specifies a default (usually very small) probability to use when the count is zero.

The Naive Bayes Wizard requires that each field (whether objective or analysis candidate) be binned so that for each field, only a small, finite number of values are considered by the model. The objective field is treated as categorical; while the analysis candidates take their binning from the modeling dataset. values are treated as separate categories.

Results Various outputs are (optionally) generated, including:

  • An HTML audit report summarizing how the Naive Bayes model propensity was applied, including the input parameters and comparison with the historical responses.
  • The final recommended model in Field Derivation Language [see About Field Derivation Language], QMML [see To save a Decision Studio model or segmentation for deployment as QMML (XML)] and Predictive Model Markup Language (PMML) formats.
  • The final dataset including the model prediction.

See also

Building a propensity model using the Naive Bayes Wizard
Parent topic: Building Naive Bayes models for segmentation and predictive modeling


Building a propensity model using the Naive Bayes Wizard

Save your modeling focus, with the objective field, analysis candidates and categorical variables marked. This preparation can be automated by importing focus metadata [see Copying focus metadata from one focus to another] into the modeling focus.

In Portrait Miner, right-click a focus and choose Predict>Naive Bayes Wizard.

In the Naive Bayes Wizard dialog box, you can choose which objective field and category and analysis candidates to analyze, the Naive Bayes threshold to use and details of the modeling results created.

See also

About the Naive Bayes Wizard

About Portrait Miner wizards

Parent topic: Building Naive Bayes models for segmentation and predictive modeling


Building clustering models for segmentation and predictive modeling

  • About clustering models in Portrait Miner
  • To build a clustering model
  • Options for displaying a clustering model
  • Controlling the building of a clustering model


About clustering models in Portrait Miner

Clustering is an undirected (objective-free) modeling technique, used to segment a population into clusters of similar records based on the observed values of one or more analysis fields.
  • Each cluster in a clustering model has a center, which you can think of as a record containing a value for each analysis candidate (except that a categorical [see Field interpretations] field is treated as though it were a set of indicator fields [see Categorical fields in clustering]).
  • Each record in the focus belongs to the cluster whose center is closest to the record, according to a normalized sum-of-squares distance metric [see Measuring size and separation of clusters].

See also

Controlling the building of a clustering model

To build a clustering model

Parent topic: Building clustering models for segmentation and predictive modeling

Measuring size and separation of clusters

The idea of clustering rests on some measure of distance or closeness between records.

Consider two records [image] and [image] (where [image] is the value of field j in record i). First normalize the values so that each field has mean 0 and standard deviation 1 (for the dataset on which the model is to be built):

where [image] and [image] are respectively the mean and standard deviation of field j. Now define the distance between the records [image] and [image] as the ordinary Euclidean sum-of-squares distance between the normalized records [image] and [image]:

(Note that there is no square root.)

Given this distance metric, it is possible to quantify the size of a cluster (using one of two measures, radius and ESS) and how well separated a cluster is from other clusters. By extension, you can also quantify the quality of a clustering model.
  • The radius of a cluster is the maximum distance between a record in the cluster and the cluster center. An ideal cluster has zero radius.
  • The ESS of a cluster is the sum of the distances of all the records in the cluster from the center of the cluster. An ideal cluster has zero ESS.

    For a clustering model, the total ESS is the sum of the ESS values for each of the clusters. An ideal model has zero total ESS.

  • The separation for a record is [image], where [image] is the distance between the record and the nearest cluster center and [image] is the distance between the record and the second-nearest center. Values range between 0 and 1; a higher value indicates that the record has a stronger attachment to its assigned cluster.

    The separation for a cluster is the minimum separation for a record in the cluster. A well separated cluster has a value close to 1.

    The separation for a clustering model is the minimum separation for a record in the dataset. A good model has a value close to 1.

Note:
  • For the purpose of computing the distance metric, a categorical field should be considered as a set of indicator fields [see Categorical fields in clustering].
  • When you apply a clustering model to a new dataset, values are normalized with respect to the scale parameters of the original dataset.

How Decision Studio builds a clustering model

The Cluster Builder in Decision Studio implements a non-hierarchical k-means clustering algorithm, also known as "Lloyd's Method."

The algorithm ignores any binning on a non-categorical field. It excludes non-categorical analysis candidates with zero standard deviation as well as categorical analysis candidates with records in only one category. It creates a dummy field for each non-empty category of an included categorical analysis candidate.

Given a set of initial clusters (chosen at random), the algorithm iteratively moves records between clusters to minimize the total ESS:
  1. Each record is allocated to the cluster whose center it is nearest to (according to the distance metric). In the case of a record being equidistant from two or more clusters, the record is allocated to the first cluster with the minimum distance.
  2. Outliers [see Parameters for a clustering model] are excluded.
  3. The cluster means are (re-)calculated and for the next iteration the cluster centers are set to be these cluster means.
  4. Iterations continue until one of the termination criteria [see Termination criteria for a clustering model] is satisfied.

Categorical fields in clustering

The clustering algorithm treats a categorical analysis candidate as though it were a set of numeric indicator fields, one per category (including the null [see The null value] and unclassified categories). Each category in the original field is represented by the value 1 in the corresponding indicator field and the value 0 in each of the other indicator fields.

For example, a categorical field such as Gender, with three categories, Male, Female, and null, is represented by three indicator fields, which appear in the Cluster Builder as Gender (Male), Gender (Female), and Gender (Null). A record for a female customer has values 0, 1, and 0 respectively for these indicator fields. A typical cluster center might have values 0.3, 0.2, and 0.5 in these fields. (The values for indicator fields corresponding to a categorical field always add up to 1.)

When Cluster Builder shows the number of dimensions used to build a clustering, each indicator field counts as one dimension.

The null value in clustering

When computing distance, the null [see The null value] value in a non-categorical field is considered equally close to all cluster centers — that is, its contribution to the distance is zero and the distance from a cluster center is determined by the rest of the fields. % Duplicates text in the "Categorical fields in clustering" topic. The null category in a categorical analysis candidate is treated in the same way as any other category. If all the analysis candidates are non-categorical, records which contain the null value for all of them are ignored (and produce a null cluster-index result).
Note: When applying a clustering model, the Cluster Builder treats categorical values that were empty or not present at build time by assigning records containing them to the null cluster.


To build a clustering model

  1. Optionally interpret some fields as analysis candidates [see To set or clear an analysis candidate, categorical, geographical, export or key interpretation].

    If there are fields with an analysis candidate interpretation, the Cluster Builder only considers those fields when creating clustering models.

  2. Choose Tools>Cluster Builder or click on [image] on the toolbar.
  3. If necessary, change the default build options [see Controlling the building of a clustering model].
  4. Choose Clustering>Build to End or click on [image] on the toolbar, to build a clustering model.

    The Cluster Builder continues until it satisfies one or more of the termination criteria [see Termination criteria for a clustering model] for a clustering model.

  5. Optionally, to create a further iteration of the clustering model, choose Clustering>Do Next Iteration or click on [image] on the toolbar.

    (If the clustering model has converged or the build parameters have changed, this option is not available.)

Note:
  • The Cluster Builder is an undirected model-building tool. It therefore takes no account of any objective that you have set.
  • The panes on the left of the Cluster Builder window show included fields (analysis candidates) and excluded fields (other fields in the focus), with fields that appear in the current clustering model shown in boldface.

    You can interpret a field as an analysis candidate by moving it from the lower pane to the upper pane (and vice versa), by using the arrow buttons between the panes.

  • When you start to build a clustering model, the Cluster Builder prompts you to interpret any string fields that do not have a categorical interpretation, so that they can be binned appropriately. You can either choose the default categorical interpretation or use a saved categorical hierarchy. If you click on Cancel when prompted to choose an interpretation for a string field, the Cluster Builder ignores that analysis candidate, along with any remaining string fields without a categorical interpretation.
  • Statistics for clustering models appear in the Clustering Results pane. These include measures of model quality (total ESS and separation) as well as model-building parameters.

    Statistics for the clusters in the last model to be built appear in the Cluster Details pane (except for the outlier and null clusters). These include measures of cluster quality (ESS, separation, and radius) as well as the number of records in each cluster and the field values that describe each cluster's center.

  • To clear the history of clustering models produced along with the current model details, choose Clustering>Clear or click on [image] on the toolbar.
  • Clusters in a clustering model are numbered: each record has an associated cluster index between 1 and the number of clusters — unless it is considered an outlier [see Parameters for a clustering model], in which case it has cluster index -1.

    You can derive a field [see To derive a field from a Decision Studio model or crosstab] containing the cluster index.

See also

About clustering models in Portrait Miner

Controlling the building of a clustering model

To apply a Decision Studio model or segmentation to a different population

Parent topic: Building clustering models for segmentation and predictive modeling

Choosing the right number of clusters

The algorithm [see How Decision Studio builds a clustering model] that the Cluster Builder uses to build a clustering model requires you to specify the target number of clusters [see Parameters for a clustering model] in advance.
If you choose an inappropriate number of clusters, the Cluster Builder may be unable to find a good clustering model:
  • If you specify too few clusters, the Cluster Builder merges distinct clusters. In the worst case, it may break up a "natural" cluster and distribute its contents to neighboring clusters, resulting in a model that doesn't capture the real clusters at all.
  • If you specify too many clusters, the Cluster Builder will divide some clusters into small parts.
Your business knowledge may suggest a suitable number of clusters to look for, or you may have to experiment with different values and see which leads to the best model. One method that works reasonably well is to exploit the fact that, although it is hard to detect that you have too few clusters, if you have too many, the separation measure will tend to be low.
  1. Start by choosing a fairly large number of clusters and build several models, trying to maximize the separation measure.
  2. If you cannot get a separation measure statistic close to 100%, reduce the number of clusters by one and try again.
  3. Continue until, for your chosen number of clusters, you can at least occasionally obtain a clustering model with a high separation measure.
Note:
  • You may not always get the number of clusters that you specify, as the Cluster Builder excludes any empty clusters from a clustering model.
  • Beware that a model may have a high separation measure simply because it classifies a large proportion of records as outliers.

Optimizing a clustering model

The separation measure gives a reasonably good indication of when there are too many clusters. But, once you have the right number of clusters, it is not as helpful in distinguishing between good and bad models.

One way to optimize your model is to keep the number of clusters fixed and build a large set of clustering models, trying to minimize the total ESS.

Note: Beware that a model may have a high separation measure simply because it classifies a large proportion of records as outliers.

Avoiding overfitting when building a clustering model

As with any model-building technique, you need to assess and avoid overfitting. Employ a test/training methodology [see Test/training methodology for robust modeling] and be cautious when using the following:
  • Analysis fields with a large number of categories
  • A large number of analysis candidates (in which case another possible problem is that the majority of records end up as outliers)
  • A large target number of clusters


Options for displaying a clustering model

The following Cluster Builder views are available:

View | Description
Table View | A two-table view, showing statistics for successive clustering models in the upper table and statistics for the clusters of the most recent model in the lower table, alongside panes showing lists of included and excluded fields
Graph View | A two- or three-dimensional graph [see Cluster Builder graphs], alongside a pane listing fields in the focus (with fields involved in the model shown in boldface)

Initially, the Cluster Builder shows the table view (and the graph view is unavailable until you build or open a clustering model). To change between the table and graph views, either choose the view from the View menu or click on the corresponding button on the toolbar.

Parent topic: Building clustering models for segmentation and predictive modeling

Cluster Builder graphs

In the graph view of the Cluster Builder:
  • Highlight any number of fields in the left pane and click on 2D graph to obtain a set of profile [see To create a set of single-variable profile graphs] graphs for those fields.
  • Highlight up to three fields in the left pane and click on 3D graph to obtain a crossdistribution [see To create a multi-variable crossdistribution graph] graph broken down by your chosen fields.

In either case, the Cluster Builder associates the following statistics with aspects of the graph:

Statistic for segment | Graph aspect
count | Block height (or volume for a three-field crossdistribution graph)
mode of cluster index | Block color
mode ratio [see moderatio] of cluster index | Block brightness

The purer a segment is — with respect to the ideal of all records falling within a single cluster — the brighter the block color for that segment is. (A mode ratio of 1 for a segment indicates that all records in that segment are in the same cluster.)

Each graph view shows a legend, with blocks for 50%, 75%, and 100% brightness, to give a useful indication of how each color varies with brightness.


Controlling the building of a clustering model

You can control how the Cluster Builder builds a clustering model by choosing Clustering>Parameters and changing settings in the Clustering Parameters dialog box:

See also

About clustering models in Portrait Miner

To build a clustering model

Parent topic: Building clustering models for segmentation and predictive modeling

Parameters for a clustering model

In the upper half of the Clustering Parameters dialog box, there are settings for general clustering model parameters:

Setting | Description
Number of clusters | The target number of separate clusters in the clustering model
Outlier limit | A multiplier m that determines the records to be treated as outliers The Cluster Builder treats a record as an outlier if, for some non-categorical analysis candidate, the difference between the value for the record and the value for the closest cluster center exceeds m standard deviations of the field. If the outlier limit is not set, no records are considered outliers.
User-defined seed | A seed for initializing the cluster centers in the clustering algorithm If the user-defined seed is not set, the Cluster Builder chooses a seed (based on the system clock) for each build. Setting the seed allows repeatable clustering models to be generated.
To reproduce a previously built clustering model, set the random seed to the one shown for the model in the Clustering Results pane.

Termination criteria for a clustering model

In the lower half of the Clustering Parameters dialog box, there are settings that govern when the Cluster Builder stops looking for improved clustering models:

Setting | Description
Maximum iterations | The maximum number of iterations of the clustering algorithm that the Cluster Builder will perform
Minimum movement | The number of records n such that, if the Cluster Builder reclassifies fewer than n records between clusters in the course of an iteration, it will not perform any further iterations You can specify the number of records either in absolute terms or as a percentage of the total population.
Note: The Cluster Builder algorithm terminates when either termination criterion is satisfied. Therefore it usually terminates without having satisfied the other criterion.


Applying models and segmentations to new customer and transaction data

  • To save a Decision Studio model or segmentation for deployment as QMML (XML)
  • To convert a Decision Studio model or segmentation for deployment in SAS
  • To convert a Decision Studio model or segmentation for deployment in SQL
  • Model metadata
  • Creating a Model Snapshot


To save a Decision Studio model or segmentation for deployment as QMML (XML)

You can save a model or segmentation as a QMML (XML) document to deploy it via the Derive Fields [see To derive fields in a focus using Portrait Miner] wizard, the Portrait Miner data-build command qsderive or for Portrait Dialogue or Portrait Interaction Optimizer (via QMML).
  1. If your model or segmentation is not already expressed in terms of derived fields in a focus, do one of the following:
    • For a decision tree, scorecard, or clustering model, derive generated fields [see To derive a field from a Decision Studio model or crosstab] to encapsulate the important features of your model.
    • For a graphical segmentation, derive a flag field [see To derive a field from a graphical segmentation] for key segments of the population identified from your graph.
    • For a crosstab (textual or graphical), derive an index field [see To derive a field from a Decision Studio model or crosstab] fully representing the segmentation.
    • For a model or segmentation based on business rules, derive fields using the Table Viewer [see To derive a field using the Table Viewer].
  2. In the Table Viewer, choose File>Export as QMML or click on [image] on the toolbar.

    A Portrait Miner file browser appears.

  3. Browse [see Browsing to open or save a file, session or database table] to a location in which to save your QMML document, and choose a name for it.

    Decision Studio saves a QMML document containing definitions of derived fields in the focus.

Note:
  • When you choose File>Export as QMML, Portrait Miner automatically parses the QMML. This removes the need for you to use the qsqmmledit -parse data-build command. If there is an error, Portrait Miner notifies you of the derivations that could not be parsed. In this case, a QMML file is created, but without the structured representation of the problem derivations.
  • When you choose File>Export as QMML, the QMML document contains a ruleset that lists all derived fields that are highlighted in the Table Viewer, or all derived fields if no fields are highlighted. Regardless of which fields appear in the ruleset, the QMML document contains definitions for all the derived fields.
  • If you want to include user-defined FDL functions when parsing QMML in Decision Studio, you can define globally-accessible functions by storing them in a file (or files) in a folder listed in the derivation libraries preference [see derivation libraries].

See also

About Transaction Measurement Language

To apply a Decision Studio model or segmentation to a different population

To convert a Decision Studio model or segmentation for deployment in SAS

To convert a Decision Studio model or segmentation for deployment in SQL

To save a crosstab from Decision Studio

Using Portrait Miner data-build commands for data import, processing, and export

XML in Portrait Miner

Parent topic: Applying models and segmentations to new customer and transaction data


To convert a Decision Studio model or segmentation for deployment in SAS

You can convert to SAS format using Portrait Miner. A separate SAS statement is created for each field derivation.

In Portrait Miner, right-click on the QMML file that you want to convert and choose Convert to SAS.

In the Convert to SAS format dialog box, choose the required output fields and a location to save the SAS model.

Note:
  • The convert to SAS functionality is experimental.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsqmml2sas.

See also

About Portrait Miner wizards

To save a Decision Studio model or segmentation for deployment as QMML (XML)

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Applying models and segmentations to new customer and transaction data


To convert a Decision Studio model or segmentation for deployment in SQL

You can convert to SQL format using Portrait Miner. A separate SQL SELECT statement is created for each field derivation. Portrait Miner supports the following database types:
  • Oracle
  • Teradata
  • Microsoft SQL Server

In Portrait Miner, right-click on the QMML file that you want to convert and choose Convert to SQL.

In the Convert QMML to SQL dialog box, choose the source table and the target database type.

Note:
  • The convert to SQL functionality is experimental.
  • In SQL, evaluation of integer types to boolean is not permitted.
  • This user interface is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsqmml2sql.

See also

About Portrait Miner wizards

To save a Decision Studio model or segmentation for deployment as QMML (XML)

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Applying models and segmentations to new customer and transaction data


Model metadata

Metadata is "data about data." Each model that you build, be it a decision tree, scorecard, or clustering model, has metadata associated with it:
  • The date and time that the model was built
  • Who built the model
  • The focus on which the model was based
  • The version of Decision Studio that was used to build the model
  • Model comments (which you can edit in Decision Studio)
  • Model-building parameter settings that were in effect at the time that the model was built

When you save [see To save a decision tree, scorecard, or clustering model] a model, the model file contains this metadata along with the description of the model itself.

To see the other metadata associated with a decision tree or scorecard, choose Tree (in the Decision Tree Builder) or Scorecard (in the Scorecard Builder).

See also

Creating a Model Snapshot
Parent topic: Applying models and segmentations to new customer and transaction data

Attaching comments to a model

You can add comments to a decision tree or scorecard, which can be useful when you share your models with other people — or even when you return to them after not having worked with them for a while.
  • In the Decision Tree Builder, to attach comments to a decision tree, choose Tree>Edit Model Comments.
  • In the Scorecard Builder, to attach comments to a scorecard, choose Scorecard>Edit Model Comments.

In either case, a dialog box appears with three editable comment areas, in which you can record the observation window applicable to the model, details of how you validated the model, and any other notes that you wish to make.

Note:
  • Model comments appear as part of a Model Snapshot report [see Creating a Model Snapshot], along with any comments that you add when you create the report.
  • If you check the HTML box, Decision Studio treats balanced pairs of tags, for example <b>...</b>, as HTML markup, and displays the comment accordingly.


Creating a Model Snapshot

A Model Snapshot is an HTML-format report containing a detailed description of a decision tree or scorecard, including various model statistics and profiles of all the fields involved in the model.

To create a Model Snapshot in Portrait Miner, right-click on the saved model [see To save a decision tree, scorecard, or clustering model] that you want to study, and choose Create Model Snapshot.

In the Decision Tree Snapshot or Scorecard Snapshot dialog box, you can choose to view a report for the focus or a different focus, and you can optionally report on all fields or no fields, as opposed to the fields involved in the model.

Note:
  • If you specify a description for the Model Snapshot, it appears, along with any model comments [see Attaching comments to a model], in the "User Supplied Metadata" section of the report.

  • You can choose one of four options for the formats of images used in the HTML output:

    svg SVG (scalable vector graphics) only. SVG offers the best image quality and smallest file sizes, but readers of your report must have a web browser with an SVG plugin to view or print these images.

    smallpng SVG plus screen-optimized PNG (portable network graphics) bitmaps. Even without an SVG plugin, readers will be able to see the images in your report (but print quality will be relatively poor).

    largepng SVG plus both printer- and screen-optimized PNG bitmaps. Readers will be able to view or print your report without needing an SVG plugin (but more disk space will be needed, and the report may be slower to view).

    none No images.

  • You can control further aspects of the appearance of Model Snapshot and Profile and Audit reports by setting preferences [see To set Portrait Miner preferences] in the Audits and Snapshots section of the Preferences window.
  • For Portrait Miner to be able to notify you by e-mail when the report is ready, you must set the emailaddress and emailserver preferences appropriately.
  • By default, Portrait Miner saves a Model Snapshot as a single .qshtml file, with embedded images. Although you can open this file in Portrait Miner (by double-clicking on it), you can't use it directly outside Portrait Miner.

    To create a web page that is suitable for placing on a web server right-click on a .qshtml file, and choose Unpack to Folder. Choose a location, select or create a folder and click OK.

  • The Create Profile and Audit dialog box is a way of accessing much of the functionality provided by the Portrait Miner data-build command qsdtsnapshot or qsscsnapshot.

See also

About Portrait Miner wizards

Creating a Profile and Audit of a focus

To set global options for graphical displays

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Applying models and segmentations to new customer and transaction data


Portrait Miner preferences

  • Using preferences
  • Decision Studio binnings and functions
  • Decision Studio visualization tools
  • Decision Tree Builder
  • Scorecard Builder
  • Date formatting
  • File browsing
  • Flat files
  • Databases
  • Audits and snapshots
  • E-mail notification
  • System tuning and administration
  • Systems integration and RealTime


Using preferences

  • To set Portrait Miner preferences
Parent topic: Portrait Miner preferences


To set Portrait Miner preferences

You can customize several aspects of Portrait Miner to suit your individual requirements.
  1. In Portrait Miner, choose Edit>Preferences.
  2. Choose the relevant section from the left pane of the Preferences window.

    The options that are available in the selected section appear in the right pane.

  3. Make changes as follows:
    • Check or clear a check box to change an on/off option.
    • Click in the Value cell to edit a number or text. (To abandon your changes while editing a number or text, right-click in the cell and choose Cancel.)

      If up/down arrows appear in the cell, you can use these to change the numeric value.

      If the cell contains a drop-down menu, you can choose an option from the menu.

      If [image] appears, you can click on this to browse [see Browsing to open or save a file, session or database table] for a file or folder.

  4. Click on Save to confirm your changes.
  5. Click on Exit to close the Preferences window.
Note:
  • Preference settings only come into effect when you start an application.
  • When you have overridden the default value for an option, its name appears in boldface in the Preferences window.
  • To undo a preference setting, restoring the preference to the value that it had before you opened the Preferences window, right-click on the name of the preference and choose Undo.
  • To restore the system default for a preference, right-click on the name of the preference and choose Restore default.

    To restore the system defaults for all preferences in the current section, choose Edit>Restore section name Defaults. To restore the system defaults for all preferences, choose Edit>Restore All Defaults.

  • If you set the value of any of the date write, full write, read, or time write preferences to European, American, or YMD in the Preferences window, the other three preferences are set to the same value.
  • System defaults for preferences are not necessarily the same as factory defaults: your system administrator may have overridden some settings. In the descriptions of individual preferences, the factory defaults are indicated.
  • Any options that you set in the Preferences window apply equally to all parts of Portrait Miner.
  • If you see a warning about an unrecognized preference, the likely explanation is that one of your settings concerns a preference that is obsolete. You can remove the setting altogether by right-clicking on the name of the preference and choosing Restore default. (The entry for the preference still appears in the Preferences window until you save and exit.)
  • If you find that you cannot change the setting of a preference, this may be because your system administrator has locked it to prevent users from making changes.
  • Certain preferences are intended for expert use only, and, as such, are hidden by default. They should normally only be changed by the administrator of Portrait Miner. To view all preferences, choose View>Show All Preferences.

See also

To set global options for graphical displays

To set the display format for numeric and date values

Parent topic: Using preferences


Decision Studio binnings and functions

  • auto end bins
  • auto end bins for equal popn
  • default binning type
  • default min bin size (Categorical Binning)
  • default number of bins (Categorical Binning)
  • default number of bins (Numeric Binning)
  • display equal width
  • max number of date bins
Parent topic: Portrait Miner preferences


auto end bins

Section Numeric Binning

Purpose Control whether Decision Studio creates end bins [see End bins] when binning a numeric field.

Valid values

Value | Description
true (default) | Create "smart" end bins for numeric binnings (but see auto end bins for equal popn).
false | Do not create end bins for numeric binnings.
Parent topic: Decision Studio binnings and functions


auto end bins for equal popn

Section Numeric Binning

Purpose Control whether Decision Studio creates end bins [see End bins] when binning a numeric field with an equal-population binning.

Valid values

Value | Description
true | Treat equal-population binnings in the same way as equal-range binnings: use the setting of auto end bins.
false (default) | Do not create end bins for equal-population binnings.
Parent topic: Decision Studio binnings and functions


default binning type

Section Numeric Binning

Purpose Set the default type of binning that Decision Studio applies to numeric and date fields.

Valid values

Value | Description
equal range (default) | Create equal-range binnings by default.
equal population | Create equal-population binnings by default.
Note:

You can override this setting on a per-focus basis: in the Binning Editor, choose Binning>Default Parameters or click on [image] on the toolbar; under the Non-categorical tab, choose from the Bin Type menu.

Parent topic: Decision Studio binnings and functions


default min bin size (Categorical Binning)

Section Categorical Binning

Purpose Set the minimum bin size for a categorical field in Decision Studio.

Valid values A non-negative integer, by default 0

When Decision Studio creates a categorical binning on a field, it only creates bins for values that occur in at least the specified number of records. Other values are unclassified.

Note: You can override this setting on a per-focus basis: in the Binning Editor, choose Binning>Default Parameters or click on [image] on the toolbar; under the Categorical tab, set Min Category Size.

See also

default number of bins (Categorical Binning)
Parent topic: Decision Studio binnings and functions


default number of bins (Categorical Binning)

Section Categorical Binning

Purpose Set the maximum number of bins for a categorical field in Decision Studio.

Valid values A non-negative integer, by default 250

When Decision Studio creates a categorical binning on a field, it only creates bins for at most the specified number of values (choosing the most common values first). Other values are unclassified.

Note: You can override this setting on a per-focus basis: in the Binning Editor, choose Binning>Default Parameters or click on [image] on the toolbar; under the Categorical tab, set Max Number of Categories.

See also

default min bin size (Categorical Binning)
Parent topic: Decision Studio binnings and functions


default number of bins (Numeric Binning)

Section Numeric Binning

Purpose Set the default target number of bins for a numeric or date binning in Decision Studio.

Valid values A non-negative integer, by default 10

Note:
  • The target number of bins excludes end bins [see End bins] and bins for null [see The null value] and unclassified values.
  • You can override this setting on a per-focus basis: in the Binning Editor, choose Binning>Default Parameters or click on [image] on the toolbar; under the Non-categorical tab, set Target Internal Bins.
Parent topic: Decision Studio binnings and functions


display equal width

Section Numeric Binning

Purpose Set the default display mode that Decision Studio uses for numeric and date binnings: histogram or bar graph [see Histogram and bar-graph options].

Valid values

Value | Description
true (default) | Use the bar-graph display mode.
false | Use the histogram display mode.
Note:
  • The display mode for a binning also affects graphical views in the Profile Viewer and Crossdistribution Viewer.
  • You can override this setting on a per-focus basis: in the Binning Editor, choose Binning>Default Parameters or click on [image] on the toolbar; under the Non-categorical tab, choose from the Graph menu.
Parent topic: Decision Studio binnings and functions


max number of date bins

Section Date Binning

Purpose Set the maximum number of bins for a date field (bin width is adjusted accordingly). This avoids, for example, inadvertently binning a range of centuries by seconds.

Valid values An integer between 1 and 1,000, %This is not in the ini file by default 100

Parent topic: Decision Studio binnings and functions


Decision Studio visualization tools

  • max size
  • objective function
Parent topic: Portrait Miner preferences


max size

Section Aggregation

Purpose Set the size of the largest crosstab [see Crosstabs as a basis for segmenting and visualizing data] that Decision Studio can create.

Valid values A non-negative integer, by default 100,000

Note: To calculate the size of a crosstab in this sense, compute

for a crosstab involving N breakdown fields, with [image], [image], ..., [image] bins respectively (including end bins [see End bins] where applicable, and null [see The null value] and unclassified bins). For example, a crosstab with breakdown fields Income and Age, binned in 10 and 8 internal bins respectively, has size [image].
Parent topic: Decision Studio visualization tools


objective function

Section Aggregation

Purpose Set the aggregation function [see Aggregation functions for crosstabs] that Decision Studio applies to an objective by default when you create a crosstab view [see To create a textual crosstab view], profile graph [see To create a set of single-variable profile graphs], crossdistribution graph [see To create a multi-variable crossdistribution graph], or map graph [see To create a graph on a map]. (For graphs, Decision Studio associates the result with block color.)

Valid values

Value | Description
any | Show an arbitrary value [see any] of the objective.
countnonnull | Show the non-null record count [see countnonnull/countnonnulls] for the objective.
countnull | Show the null record count [see countnull/countnulls] for the objective.
countunique | Show the number of unique values [see countunique] for the objective, potentially including the null value.
countuniquenonnull | Show the number of unique values [see countuniquenonnull] for the objective, not including the null value.
first | Show the value of the objective for the first record [see first].
last | Show the value of the objective for the last record [see last].
max | Show the maximum value [see max (one argument)] of the objective.
mean (default) | Show the mean value [see mean (one argument)] of the objective.
median | Show the median (middle value) [see median] of the objective.
min | Show the minimum value [see min (one argument)] of the objective.
mode | Show the mode (most common value) [see mode] of the objective.
moderatio | Show the proportion of records that contain the most common value [see moderatio] of the objective.
percentagerate | Show the percentage of records that contain the value 1 [see percentagerate] for the (binary) objective.
significance | Show the significance of the difference between the mean of the objective for the segment and that for the overall population.
stdev | Show the standard deviation of values [see stdev] in the objective.
sum | Show the sum of values [see sum (one argument)] in the objective.
variance | Show the variance of values [see variance] in the objective.
Parent topic: Decision Studio visualization tools


Decision Tree Builder

  • infinite uplift replacement value
Parent topic: Portrait Miner preferences


infinite uplift replacement value

Section Decision Tree Builder

Purpose The uplift value for a segment in a binary uplift x tree can be infinite. This value is used to represent infinite uplift wherever it is reported (text views, results fields etc.).

Valid values A non-negative real number, by default

Parent topic: Decision Tree Builder


Scorecard Builder

  • accept rate
  • attribute transformation
  • bad rate
  • cutoff
  • doubling odds
  • even odds
  • initial card
  • invert objective
  • iterations
  • model
  • number of decimal places of accuracy
  • one weight per characteristic
  • quality measure
  • runs
  • solver
  • tolerance
Parent topic: Portrait Miner preferences


accept rate

Section Scorecard Builder

Purpose Set the initial accept-rate [see Fields associated with decision trees, scorecards, clustering models, and abstract crosstabs] (or target-rate) threshold that the Scorecard Builder uses.

Valid values A real number between 0 and 1, by default 0.5

Note: You should normally set no more than one of cutoff, bad rate, and accept rate, as the first of these that is set (in the order listed here) always takes precedence over either of the others.
Parent topic: Scorecard Builder


attribute transformation

Section Scorecard Builder

Purpose Control how the Scorecard Builder transforms values for individual bins in a one-weight-per-field [see one weight per characteristic] model.

Valid values

Value | Description
log odds (default) | Use the log of the odds (the "weight of evidence").
mean | Use the mean.
odds | Use the odds.
log mean | Use the log of the mean.
Note:

You can override the setting of this preference by changing the form [see To change the form of a scorecard] in the Scorecard Form dialog box.

Parent topic: Scorecard Builder


bad rate

Section Scorecard Builder

Purpose Set the initial bad-rate [see Fields associated with decision trees, scorecards, clustering models, and abstract crosstabs] (or hit-rate) threshold that the Scorecard Builder uses.

Valid values A real number between 0 and 1, by default 0.5

Note: You should normally set no more than one of cutoff, bad rate, and accept rate. as the first of these that is set (in the order listed here) always takes precedence over either of the others.
Parent topic: Scorecard Builder


cutoff

Section Scorecard Builder

Purpose Set the initial cutoff score [see Fields associated with decision trees, scorecards, clustering models, and abstract crosstabs] that the Scorecard Builder uses.

Valid values A real number, by default 500

Note: You should normally set no more than one of cutoff, bad rate, and accept rate, as the first of these that is set (in the order listed here) always takes precedence over either of the others.
Parent topic: Scorecard Builder


doubling odds

Section Scorecard Builder

Purpose Set the initial doubling factor [see Fields associated with decision trees, scorecards, clustering models, and abstract crosstabs] that the Scorecard Builder uses for the relationship between score and odds.

Valid values A positive real number, by default 20

See also

even odds
Parent topic: Scorecard Builder


even odds

Section Scorecard Builder

Purpose Set the initial even-odds point [see Fields associated with decision trees, scorecards, clustering models, and abstract crosstabs] that the Scorecard Builder uses for the relationship between score and odds.

Valid values A positive real number, by default 500

See also

doubling odds
Parent topic: Scorecard Builder


initial card

Section Scorecard Builder

Purpose Set the initial scorecard that the Scorecard Builder uses when applying an iterative solver.

Valid values

Value | Description
linear (default) | Use linear regression (discriminant analysis) to generate an initial scorecard.
fixed | Use an initial scorecard with equal weights for all variables.
current | Use the current scorecard as an initial scorecard.
random | Use a pseudo-randomly [see About random-number functions in FDL] generated initial scorecard.
Note:

You can override the setting of this preference by changing the starting card [see To change the solver used to build a scorecard] in the Scorecard Solver dialog box.

Parent topic: Scorecard Builder


invert objective

Section Scorecard Builder

Purpose Change the 1/0 interpretation of the objective.

Valid values

Value | Description
true | Interpret records with a 0 in the objective as defaulters/churners/responders.
false (default) | Interpret records with a 1 in the objective as defaulters/churners/responders.
Note:

You can override the setting of this preference by using the Scorecard>Invert Objective Value menu option.

Parent topic: Scorecard Builder


iterations

Section Scorecard Builder

Purpose Set the maximum number of iterations that an iterative scorecard solver uses.

Valid values A positive integer, by default 1000

Note: You can override the setting of this preference by changing the maximum number of iterations [see To change the solver used to build a scorecard] in the Scorecard Solver dialog box.

See also

tolerance
Parent topic: Scorecard Builder


model

Section Scorecard Builder

Purpose Control the default model type .

Valid values

Value | Description
risk (default) | Build a risk model.
response | Build a response model.
churn | Build a churn model.
satisfaction | Build a satisfaction model.
dissatisfaction | Build a dissatisfaction model.
Parent topic: Scorecard Builder


number of decimal places of accuracy

Section Scorecard Builder

Purpose Control the number of decimal places of accuracy to which the Scorecard Builder performs approximate calculations, such as the Gini value for a scorecard.

Valid values An integer between 1 and 8, by default 3

Note: You can override the setting of this preference by choosing Scorecard>Solver in the Scorecard Builder and changing the number of decimal places of accuracy.
Parent topic: Scorecard Builder


one weight per characteristic

Section Scorecard Builder

Purpose Control whether the Scorecard Builder uses one weight per field or one weight per bin.

Valid values

Value | Description
true (default) | Use one weight per field.
false | Use one weight per bin.
Note:

You can override the setting of this preference by changing the form [see To change the form of a scorecard] in the Scorecard Form dialog box.

See also

attribute transformation
Parent topic: Scorecard Builder


quality measure

Section Scorecard Builder

Purpose Set the quality measure that the Scorecard Builder uses.

Valid values

Value | Description
linear (default) | Use linear regression (discriminant analysis).
logistic | Use logistic regression.
probit | Use probit regression.
Note:

You can override the setting of this preference by choosing a quality measure [see To change the quality measure used to build a scorecard] from the Scorecard>Quality Measure menu.

Parent topic: Scorecard Builder


runs

Section Scorecard Builder

Purpose Set the number of times the Scorecard Builder applies a method when optimizing a scorecard.

The Scorecard Builder uses the average value of all the runs.

Valid values A positive integer, by default 1

Note: You can override the setting of this preference by changing the number of runs [see To change the solver used to build a scorecard] in the Scorecard Solver dialog box.
Parent topic: Scorecard Builder


solver

Section Scorecard Builder

Purpose Set the solver method that the Scorecard Builder uses.

Valid values

Value | Description
direct (default) | Use direct matrix inversion to perform linear regression.
conjugate gradient | Use the conjugate gradient method.
levenberg-marquardt | Use the Levenberg — Marquardt method.
powell | Use the Powell method.
quasi newton | Use the quasi-Newton method.
simplex | Use the simplex method.
Note:

You can override the setting of this preference (for quality measures other than linear regression) by changing the method [see To change the solver used to build a scorecard] in the Scorecard Solver dialog box.

Parent topic: Scorecard Builder


tolerance

Section Scorecard Builder

Purpose Set a stopping condition for an iterative scorecard solver, in terms of fractional tolerance.

Valid values A real number, by default 0.0001

If the value of this preference is [image], the Scorecard Builder stops an iterative solver when successive values [image] and [image] of the quality measure satisfy the following:

Note: You can override the setting of this preference by changing the fractional tolerance [see To change the solver used to build a scorecard] in the Scorecard Solver dialog box.

See also

iterations
Parent topic: Scorecard Builder


Date formatting

  • Date formats
  • date write
  • default day index for incomplete dates
  • default month index for incomplete dates
  • full write
  • maximum future for two-digit years
  • read
  • time write
  • two-digit fixed pivot year
  • write in locale-specific format
  • x ordering
Parent topic: Portrait Miner preferences


Date formats

When working with flat files and FDL expressions, you can specify how Portrait Miner should interpret or export dates and times, using either a standard date format [see Standard date formats] or a customized date format [see Customized date formats].

See also

To set the display format for numeric and date values
Parent topic: Date formatting

Standard date formats

Name | Date format
American | MM/DD/YYYY:hh:mm:ss, for example, 12/31/2000:13:36:59
European | DD/MM/YYYY:hh:mm:ss, for example, 31/12/2000:13:36:59
YMD | YYYY/MM/DD:hh:mm:ss, for example, 2000/12/31:13:36:59
Note:
  • All three of the standard date formats also apply to dates without a time component and to pure times ("dates" with only a time component). For date-only and time-only dates, the time and date parts respectively are omitted.
  • American, European, and YMD formats also encompass data in the forms MMDDYYYY, DDMMYYYY, and YYYYMMDD respectively (for input only).

Customized date formats

You can specify a customized date format by using special character codes, each beginning with a percent sign %:
Code | Component of formatted date
%% | The percent sign itself: "%"
%? | Matches any single character
%* | Matches any number of characters; for example, to ignore trailing characters, use %Y/%m/%d%*
%a | The day name, in abbreviated form ("Mon," "Tue," ..., "Sun")
%A | The day name, in full ("Monday," "Tuesday," ..., "Sunday")
%b | The month name, in abbreviated form ("Jan," "Feb," ..., "Dec")
%B | The month name, in full ("January," "February," ..., "December")
%c | (Input) Equivalent to "%a %b %e %T %Y" (Output) The date and time in the standard representation for the current locale
%C | Equivalent to "%a %b %e %T %Z %Y"
%d | The day of the month, using two digits ("01," "02," ..., "31")
%D | Equivalent to "%m/%d/%y"
%e | The day of the month, with single digits preceded by a space (" 1," " 2," ..., "31")
%h | Equivalent to "%b"
%H | The hour of the day, using the 24-hour clock ("00," "02," ..., "23")
%I | The hour of the day, using the 12-hour clock ("01," "02," ..., "12")
%j | The day of the year, using three digits (Julian dates) ("001," "002," ..., "366")
%m | The month number, using two digits ("01," "02," ..., "12")
%M | The minute of the hour, using two digits ("00," "01," ..., "59")
%p | "AM" or "PM," according to the time of day
%r | Equivalent to "%I:%M:%S %p"
%R | Equivalent to "%H:%M"
%S | The second of the minute, using two digits ("00," "01," ..., "61")
%T | Equivalent to "%H:%M:%S"
%x | The date formatted according to the x ordering preference
%X | Equivalent to "%x"
%y | The year of the century, using two digits ("00," "01," ..., "99")
%Y | The year, using four digits
%Z | The name of the current locale's time zone
Note:
  • To use "%D" or "%y," you must also specify either a pivot year or a maximum future year (but not both).

    If you set a pivot equal to a valid year Y, Portrait Miner interprets two-digit years as years between Y - 99 and Y. For example, if you set the preference to 2077, Portrait Miner interprets the two-digit years 76, 77, and 78 as 2076, 2077, and 1978 respectively.

    If you set a maximum future year equal to a positive value n and the current year is Y, Portrait Miner interprets all two-digit years as years between Y + n - 99 and Y + n. For example, if you set the preference to 50 and the current year is 2002, Portrait Miner interprets the two-digit years 51, 52, and 53 as 2051, 2052, and 1953 respectively.

  • If you set the write in locale-specific format preference, the codes "%a," "%A," "%b," "%B," "%C," "%p," "%x," "%X," and "%Z" may produce different results when displaying dates (but not when interpreting them).
  • As well as /, any other character (except for the field separator or null marker) may be used as a separator within the date.
  • For a date format that lacks an explicit day or month component, you can specify a default by using the "day" or "month" qualifier.
  • The special character codes are those of the standard C library function strftime.

Example R–1: Date Formatting Strings

Date example | Date format string
02/04/2003 27/10/1940 | European
04/02/2003 10/27/1940 | American
2003/04/02 1940/10/27 | YMD
02-Apr-2003 27-Oct-1940 | %d-%b-%Y
02 Apr 2003 27 Oct 1940 | ((%d %b %Y))
2003-04-02 13:25 1940-10-27 08:23 | ((%Y-%m-%d %H:%M))
2003-04-02:13:25 1940-10-27:08:23 | %Y-%m-%d:%H:%M
2 Apr 2003 27 Oct 1940 | ((%e %b %Y))
April 2, 2003 | ((%B %e, %Y))
02/04/2003 13:25 27/10/1940 08:23 | ((%d/%m/%Y %H:%M))
2003-04-02 13:25:15000000 | ((%Y-%m-%d %H:%M:%S%*))
April 02, 2003 | ((%B %d, %Y))
2-Apr-2003 27-Oct-1940 | %e-%b-%Y
02/04/03 27/10/40 | (European pivot=2010)
04/02/03 10/27/40 | (American pivot=2010)
03/04/02 40/10/27 | (YMD pivot=2010)
02-Apr-03 27-Oct-40 | (%d-%b-%y pivot=2010)
April 02, 03 | ((%B %d, %y) pivot=2010)
2-Apr-03 27-Oct-03 | (%e-%b-%y pivot=2010)
April 2, 03 | ((%B %e, %y) pivot=2010)
01:25 PM 08:23 AM | ((%I:%M %p))
13:25 08:23 | %H:%M

See also

default day index for incomplete dates

default month index for incomplete dates

maximum future for two-digit years

two-digit fixed pivot year


date write

Section Date Format

Purpose Set the format to be used in flat files and FDL expressions for writing dates that have no time component.

Valid values

Value | Description
American | Write dates as MM/DD/YYYY.
European (default) | Write dates as DD/MM/YYYY.
YMD | Write dates as YYYY/MM/DD.
A date-format string [see Customized date formats] | Write dates in a custom format.
Note:

You should usually set the date write, full write and time write preferences to the same value.

See also

read
Parent topic: Date formatting


default day index for incomplete dates

Section Date Format

Purpose Set the day of month for dates, in flat files and FDL expressions, that lack an explicit day component.

Valid values An integer between 1 and 31 inclusive, by default 1

Note:
  • This setting applies when Portrait Miner converts text to a date according to a date format [see Customized date formats] such as "%Y%M."
  • For an individual flat file or field, you can override the setting by using the day keyword.

See also

default month index for incomplete dates
Parent topic: Date formatting


default month index for incomplete dates

Section Date Format

Purpose Set the month of year for dates, in flat files and FDL expressions, that lack an explicit month component.

Valid values An integer between 1 and 12 inclusive, by default 1

Note:
  • This setting applies when Portrait Miner converts text to a date according to a date format [see Customized date formats] such as "%Y."
  • For an individual flat file or field, you can override the setting by using the month keyword.

See also

default day index for incomplete dates
Parent topic: Date formatting


full write

Section Date Format

Purpose Set the format to be used in flat files and FDL expressions for formatting dates that include a time component.

Valid values

Value | Description
American | Format dates as MM/DD/YYYY:hh:mm:ss.
European (default) | Format dates as DD/MM/YYYY:hh:mm:ss.
YMD | Format dates as YYYY/MM/DD:hh:mm:ss.
A date-format string [see Customized date formats] | Format dates in a custom format.
Note:

You should usually set the full write, date write and time write preferences to the same value.

See also

read
Parent topic: Date formatting


maximum future for two-digit years

Section Date Format

Purpose Control the interpretation of two-digit years in flat files and FDL expressions, using a pivot year relative to the current year.

Valid values An integer between 0 and 99 inclusive, or (by default) -1

Note:
  • This setting applies to the "%D" and "%y" date-format codes [see Customized date formats].
  • For an individual flat file or field, you can override the setting by using the future keyword.

See also

two-digit fixed pivot year
Parent topic: Date formatting


read

Section Date Format

Purpose Set the default format used for interpreting dates in flat files and FDL expressions

Valid values

Value | Description
American | Interpret dates as MM/DD/YYYY:hh:mm:ss.
European (default) | Interpret dates as DD/MM/YYYY:hh:mm:ss.
YMD | Interpret dates as YYYY/MM/DD:hh:mm:ss.
A date-format string [see Customized date formats] | Interpret dates in a custom format.
Note:

When Portrait Miner reads a date from a flat file, it uses the format given by this preference setting, unless you include an explicit format specification in the flat-data description file.

See also

date write

full write

time write

Parent topic: Date formatting


time write

Section Date Format

Purpose Set the format to be used in flat files and FDL expressions for writing times (that is, dates with only hour, minute, and second components).

Valid values

Value | Description
American | Write times as hh:mm:ss.
European (default) | Write times as hh:mm:ss.
YMD | Write times as hh:mm:ss.
A date-format string [see Customized date formats] | Write times in a custom format.
Note:

You should usually set the time write, date write and full write preferences to the same value.

See also

read
Parent topic: Date formatting


two-digit fixed pivot year

Section Date Format

Purpose Control the interpretation of two-digit years in flat files and FDL expressions, using a fixed pivot year.

Valid values A positive integer (a year) or (by default) -1

Note:
  • This setting applies to the "%D" and "%y" date-format codes [see Customized date formats].
  • For an individual flat file or field, you can override the setting by using the pivot keyword.

See also

maximum future for two-digit years
Parent topic: Date formatting


write in locale-specific format

Section Date Format

Purpose Control the use of locale-specific date formatting, when using the date-formatting codes [see Customized date formats] "%a," "%A," "%b," "%B," "%C," "%h," "%p," "%x," "%X," and "%Z."

Valid values

Value | Description
true | Use locale-specific formatting, including localized day and month names.
false (default) | Use a standard date format, with English day and month names.
Note:

The default is false because Portrait Miner cannot currently interpret dates that involve non-English day and month names.

Parent topic: Date formatting


x ordering

Section Date Format

Purpose Set the format to be used for interpreting or displaying dates when using the "%x" or "%X" date-format code [see Customized date formats].

Valid values

Value | Description
American | Treat "%x" as month/day/year.
European (default) | Treat "%x" as day/month/year.
YMD | Treat "%x" as year/month/day.
Parent topic: Date formatting


File browsing

  • HOME
  • map load
  • qsexplorer home
Parent topic: Portrait Miner preferences


HOME

Section Environment

Purpose Set a "home" location that in turn sets the default value for various file-browsing preferences.

Valid values The location of a directory/folder (on the Portrait Miner server), by default unset (so it takes the value of the operating-system environment variable of the same name, if set)

Parent topic: File browsing


map load

Section Directories

Purpose Set the initial location that Portrait Miner shows when you browse to open a map (with filename extension .mif).

Valid values The location of a directory/folder (on the Portrait Miner server), by default ext/maps (on UNIX) or ext\maps (on Windows) in the Portrait Miner installation directory

Parent topic: File browsing


qsexplorer home

Section Directories

Purpose Set the initial location that Portrait Miner shows, and to which the [image] button in Portrait Miner and every Portrait Miner file browser leads.

Valid values The location of a directory/folder (on the Portrait Miner server), by default the setting of the HOME preference

Parent topic: File browsing


Flat files

  • coarse cutoff percentage
  • data format sample size
  • data sample size
  • empty lines
  • extraction max errors
  • extraction max warnings
  • ignore extraction warnings
  • maximum saved data file size in megabytes
  • permit data format errors
Parent topic: Portrait Miner preferences


coarse cutoff percentage

Section Flat File Database

Purpose Set the minimum proportion of sample records needed to assign a non-generic datatype [see Datatypes] to a field in a flat file.

Valid values A real number between 1 and 100, by default 99

If the datatypes of fields in a flat file are not specified, Portrait Miner reads sample records to assign them. For each field, if there is no numeric or date type that applies to at least the given percentage of sample records, a string datatype is assigned instead; for each field containing numeric data, if an integer type does not apply to at least the given percentage of sample records, a real datatype is assigned instead.

Note:

To ensure the assignment of datatypes that apply to every record in a flat file, set this preference and data sample size to their maximum values.

Parent topic: Flat files


data format sample size

Section Flat File Database

Purpose Set the number of sample records that Portrait Miner reads from a flat file to determine the field separator, string and date markers, and field names, during the initial phase of analysis of a flat file.
Note: The 'data format sample size' preference is only used in the absence of a flat file description (FDD) file.

Valid values An integer between 1 and 100,000 inclusive, by default 100

If the data format of a flat file is not specified, Portrait Miner reads sample records to determine it.

Parent topic: Flat files


data sample size

Section Flat File Database

Purpose Set the number of sample records that Portrait Miner reads from a flat file to determine the final datatypes [see Datatypes] of fields.
Note: The 'data sample size' preference is only used in the absence of a flat file description (FDD) file.

Valid values A positive integer, by default 1,000

Note:

If you are importing data directly from program output (that is, via a "pipe"), the sample records are those at the start of the data stream; otherwise Portrait Miner takes sample records that are distributed through the entire flat file.

See also

data format sample size
Parent topic: Flat files


empty lines

Section Flat File Database

Purpose Control how Portrait Miner treats a blank line when reading a flat file.

Valid values

Value | Description
ignore with warning (default) | Ignore the line, but generate a warning.
ignore silently | Ignore the line, without generating a warning.
null | Create a record for the line, containing the null [see The null value] value in every field.
Parent topic: Flat files


extraction max errors

Section Flat File Database

Purpose Set the maximum number of data-format errors that Portrait Miner allows when reading a flat file.

Valid values A positive integer, by default 1,000,000

If the number of errors exceeds this value, Portrait Miner rejects the flat file as unreadable and aborts the import.

Note:

If you are using the Portrait Miner data-build command qsimportflat, you can override this setting with the - maxerrors option.

See also

extraction max warnings

permit data format errors

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Flat files


extraction max warnings

Section Flat File Database

Purpose Set the maximum number of data-format warnings that Portrait Miner allows when reading a flat file.

Valid values A positive integer, by default 1,000,000

If the number of warnings exceeds this value, Portrait Miner rejects the flat file as unreadable and aborts the import.

Note:

If you are using the Portrait Miner data-build command qsimportflat, you can override this setting with the - maxwarnings option.

See also

extraction max errors

ignore extraction warnings

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Flat files


ignore extraction warnings

Section Flat File Database

Purpose Control whether Portrait Miner reports data-format warning messages (and compares the total number of warnings with the extraction max warnings preference) when reading a flat file.

Valid values

Value | Description
true | Don't report warning messages.
false (default) | Report warning messages.
Note:
  • Portrait Miner always reports error messages, and the total number of warning messages.
  • If you are using the Portrait Miner data-build command qsimportflat, you can override this setting with the - nowarnings option.

See also

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: Flat files


maximum saved data file size in megabytes

Section Flat File Database

Purpose Set the maximum quantity of data (in megabytes) that Portrait Miner writes to a single file when exporting as text using a flat-data description (FDD) file.

Valid values An integer greater than 1, by default 2048.

When the quantity of data written to a data file reaches this limit, Portrait Miner creates a new data file and adds an extra file reference in the FDD file.

Note:
  • Portrait Miner ignores the setting of this preference when exporting as text without using an FDD file.
  • To ensure that Portrait Miner only ever writes data to a single file, even when using an FDD file, change the value to $MAXLARGEFILESIZEMB.
Parent topic: Flat files


permit data format errors

Section Flat File Database

Purpose Control the behavior of Portrait Miner when it encounters data-format errors in flat files.

Valid values

Value | Description
true (default) | Treat data-format errors as warnings.
false | Treat data-format errors as errors.

See also

extraction max errors

extraction max warnings

Parent topic: Flat files


Databases

  • preserve numeric types on import
  • represent large integers as strings
Parent topic: Portrait Miner preferences


preserve numeric types on import

Section Database

Purpose Determine the datatype [see Datatypes] that Portrait Miner uses for a field when importing numeric values with greater than 15-digit precision from a database.

Valid values

Value | Description
true (default) | Use the real datatype, preserving the most significant 15 digits and discarding the remainder.
false | Use a string representation to preserve the full precision of the original (at least as far as the second-least significant digit).
Parent topic: Databases


represent large integers as strings

Section Database

Purpose Determine the datatype [see Datatypes] that Portrait Miner uses to represent an integer field that contains numbers too large to be represented as 32-bit integers (integers less than -2 147483647 or greater than 2 147483646) when importing from a database or flat file.

Valid values

Value | Description
true (default) | Use the string datatype.
false | Use the real datatype.
Parent topic: Databases


Audits and snapshots

  • backgroundcolor
  • backgroundtexture
  • barcolor
  • barstyle
  • errorbars
  • globalbarscale
  • globalpointscale
  • graph3deffect
  • graphshadow
  • imageheight
  • zoompointscale
Parent topic: Portrait Miner preferences


backgroundcolor

Section Audits and Snapshots

Purpose Control the color of the background for images in Profile and Audits and Model Snapshots.

Valid values A text string, by default "white"

You can specify an SVG-compliant color name http://www.w3.org (such as "firebrick") or a hex RGB value (such as "#2244FF").

See also

backgroundtexture

barcolor

barstyle

errorbars

globalbarscale

globalpointscale

graph3deffect

graphshadow

imageheight

zoompointscale

Parent topic: Audits and snapshots


backgroundtexture

Section Audits and Snapshots

Purpose Control the use of background texture for images in Profile and Audits and Model Snapshots (SVG format only).

Valid values

Value | Description
true | Use a background texture.
false (default) | Do not use a background texture.

See also

backgroundcolor

barcolor

barstyle

errorbars

globalbarscale

globalpointscale

graph3deffect

graphshadow

imageheight

zoompointscale

Parent topic: Audits and snapshots


barcolor

Section Audits and Snapshots

Purpose Control the color of bars in bar graphs in Profile and Audits and Model Snapshots.

Valid values A text string, by default "#9999FF" (lilac)

You can specify an SVG-compliant color name http://www.w3.org (such as "firebrick") or a hex RGB value (such as "#2244FF").

See also

backgroundcolor

backgroundtexture

barstyle

errorbars

globalbarscale

globalpointscale

graph3deffect

graphshadow

imageheight

zoompointscale

Parent topic: Audits and snapshots


barstyle

Section Audits and Snapshots

Purpose Control the style of bars in bar graphs and segments in decision trees for Profile and Audits and Model Snapshots.

Valid values

Value | Description
plain (default) | Give the bars or segments a flat, angular look.
curved | Give the bars or segments a curved look.
embossed | Give the bars or segments a raised, embossed look.

See also

backgroundcolor

backgroundtexture

barcolor

errorbars

globalbarscale

globalpointscale

graph3deffect

graphshadow

imageheight

zoompointscale

Parent topic: Audits and snapshots


errorbars

Section Audits and Snapshots

Purpose Control the use of error bars in bar graphs in Profile and Audits and Model Snapshots.

Valid values

Value | Description
true (default) | Place error bars on data points.
false | Do not place error bars on data points.

See also

backgroundcolor

backgroundtexture

barcolor

barstyle

globalbarscale

globalpointscale

graph3deffect

graphshadow

imageheight

zoompointscale

Parent topic: Audits and snapshots


globalbarscale

Section Audits and Snapshots

Purpose Control the relative scaling of the horizontal axes in bar graphs in Profile and Audits and Model Snapshots.

Valid values

Value | Description
true | Make the scale of the horizontal axes the same for all graphs in each Profile and Audit and Model Snapshot.
false (default) | Do not make the scale of the horizontal axes the same for all graphs in each Profile and Audit and Model Snapshot.

See also

backgroundcolor

backgroundtexture

barcolor

barstyle

errorbars

globalpointscale

graph3deffect

graphshadow

imageheight

zoompointscale

Parent topic: Audits and snapshots


globalpointscale

Section Audits and Snapshots

Purpose Control the relative scaling of the vertical axes in bar graphs in Profile and Audits and Model Snapshots.

Valid values

Value | Description
true (default) | Make the scale of the vertical axes the same for all graphs in each Profile and Audit and Model Snapshot.
false | Do not make the scale of the vertical axes the same for all graphs in each Profile and Audit and Model Snapshot.

See also

backgroundcolor

backgroundtexture

barcolor

barstyle

errorbars

globalbarscale

graph3deffect

graphshadow

imageheight

zoompointscale

Parent topic: Audits and snapshots


graph3deffect

Section Audits and Snapshots

Purpose Control the style of bars in bar graphs for Profile and Audits and Model Snapshots.

Valid values

Value | Description
true | Use three-dimensional bars.
false (default) | Use two-dimensional bars.

See also

backgroundcolor

backgroundtexture

barcolor

barstyle

errorbars

globalbarscale

globalpointscale

graphshadow

imageheight

zoompointscale

Parent topic: Audits and snapshots


graphshadow

Section Audits and Snapshots

Purpose Control the style of bars in bar graphs and segments in decision trees in Profile and Audits and Model Snapshots.

Valid values

Value | Description
true | Create a shadow effect.
false (default) | Do not create a shadow effect.

See also

backgroundcolor

backgroundtexture

barcolor

barstyle

errorbars

globalbarscale

globalpointscale

graph3deffect

imageheight

zoompointscale

Parent topic: Audits and snapshots


imageheight

Section Audits and Snapshots

Purpose Control the height (in pixels) of images created for Profile and Audits and Model Snapshots. The aspect ratio of the images is fixed.

Valid values A positive integer, by default 300

See also

backgroundcolor

backgroundtexture

barcolor

barstyle

errorbars

globalbarscale

globalpointscale

graph3deffect

graphshadow

zoompointscale

Parent topic: Audits and snapshots


zoompointscale

Section Audits and Snapshots

Purpose Control the range of the vertical axis for bar graphs in Profile and Audits and Model Snapshots.

Valid values

Value | Description
true | Set the range of the axis to that of the data points.
false (default) | Set the range of the axis to that of the data points augmented with zero.

See also

backgroundcolor

backgroundtexture

barcolor

barstyle

errorbars

globalbarscale

globalpointscale

graph3deffect

graphshadow

imageheight

Parent topic: Audits and snapshots


E-mail notification

  • emailaddress
  • emailserver
Parent topic: Portrait Miner preferences


emailaddress

Section Email

Purpose Set the e-mail address to which notification messages are sent.

Valid values A text string by default unset (so no e-mail is sent)

It should be a valid e-mail address or a comma-separated list of valid e-mail addresses; for example, me@mycompany.com.

Note:

To insert a literal comma into an e-mail address, use the text ${COMMA}.

See also

emailserver

Parent topic: E-mail notification


emailserver

Section Email

Purpose Set the e-mail server via which notification messages are sent.

Valid values A text string, by default unset (so no e-mail is sent)

It should be the address of an SMTP server, for example, smtp.mycompany.com.

See also

emailaddress

Parent topic: E-mail notification


System tuning and administration

  • derivation libraries
  • focus memory soft limit
  • maximum parallelism
  • parallelism
Parent topic: Portrait Miner preferences


derivation libraries

Section Functions

Purpose Specify locations of third-party or user-defined FDL function libraries (with filename extension .fdl).

Valid values A comma-separated list of file/directory/folder locations (on the Portrait Miner server), by default unset.

When Decision Studio starts, it opens function libraries that are explicitly listed as well as those contained in listed directories/folders (and all subfolders) making the functions defined within them available for use in the Table Viewer.

Note:

To insert a literal comma into a file/directory/folder name, use the text ${COMMA}.

Parent topic: System tuning and administration


focus memory soft limit

Changing this setting is not recommended

This limit is set dynamically by Portrait Miner; you should only make changes to this limit after consulting Portrait Miner Support.

Section System Tuning

Purpose Set a "soft" limit for memory usage (in megabytes).

Valid values An integer greater than or equal to 16, by default a value determined at runtime from the total physical memory available and the operating-system memory limits of Portrait Miner. If you run the 64-bit version of Portrait Miner, the maximum amount of memory available is limited only by the physical memory of the machine. If you run the 32-bit version of Portrait Miner, the maximum amount of memory available is restricted to 2GB.

Note:

The limit applies to Decision Studio and to certain data-build command s (along with their associated graphical user interfaces). It is a "soft" limit because it can be exceeded, although system performance may suffer in that case.

If the limit is exceeded by 20% or more in Decision Studio, a pop-up window warns the user that this has happened.

If the limit is exceeded by 20% or more during the execution of a data-build command, a warning is written to stderr (and also to a log file, if one is being used).

If you are using Portrait Miner Desktop, this limit is dynamically managed and should never require setting.

See also

parallelism

Parent topic: System tuning and administration


maximum parallelism

Section System Tuning

Purpose Specify the maximum number of processors used (on the Portrait Miner server) by a Decision Studio user session or a data-build command (and any Portrait Miner function that is implemented via a data-build command)

Valid values A positive integer, by default the number of available processors

See also

parallelism

Parent topic: System tuning and administration


parallelism

Section System Tuning

Purpose Specify the default number of processors used (on the Portrait Miner server) by a Decision Studio user session or a data-build command (and any Portrait Miner function that is implemented via a data-build command) In certain circumstances, users can choose to increase (or decrease) this number at runtime.

Valid values A positive integer, by default 1 The value cannot exceed the setting of the maximum parallelism preference.

Parent topic: System tuning and administration


Systems integration and RealTime

  • admin log file
  • cache refresh period
  • enable administration logging
  • enable evaluation logging
  • before ... read, after ... write
  • expired rule warning threshold
  • export XML menu item
  • external execution hook location
  • logging buffer flush period
  • logging buffer max memory usage
  • logging buffer size
  • rule store save
  • server state location
Parent topic: Portrait Miner preferences


admin log file

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Actionhouse RT

Purpose The pathname to the RealTime administration log file, which is used to log all server administration events. It is only used if enable administration logging is enabled.

Valid values The location of a directory/folder (on the Portrait Miner server), by default unset

Parent topic: Systems integration and RealTime


cache refresh period

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Actionhouse RT

Purpose The time in seconds between automatic rule refresh events from RealTime clients. A client queries the server periodically with this refresh period, to allow rule redefinitions or deletions to be copied across.

Valid values An integer, by default 3600

Parent topic: Systems integration and RealTime


enable administration logging

Section Actionhouse RT

Purpose Enable or disable RealTime administration logging.

Valid values

Value | Description
true | Enable administration logging
false (default) | Disable administration logging

See also

admin log file
Parent topic: Systems integration and RealTime


enable evaluation logging

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Actionhouse RT

Purpose Enable or disable RealTime rule evaluation logging.

Valid values

Value | Description
true (default) | Enable evaluation logging
false | Disable evaluation logging

See also

Parent topic: Systems integration and RealTime


before ... read, after ... write

Section External Execution Hooks

Purpose Specify a command that Portrait Miner always runs before reading from or writing to files of the given type.

Valid values A text string, by default unset

Portrait Miner runs the specified command before reading from or after writing to a file of the given type. The full pathname of the file is appended to the command as an argument.

Note:
A command in an execution hook runs in an environment that it inherits from Portrait Miner, except:
  • The path is augmented to include Portrait Miner command-line utilities.
  • You can override the inherited working directory/folder using the external execution hook location preference.

It is always safer to specify the full path to the executable or to set the external execution hook location. In particular, Windows searches the current directory for executables before searching the path, which can produce unexpected results.

File types with execution hooks

Name in preference | File type | Read | Write
binning | Decision Studio binning (.bng) file |  |
category hierarchy | .hrc file |  |
cluster | clustering model file |  |
configuration | Preference file (qs.ini) |  |
crosstab | Do not use. |  |
data | Do not use. |  |
database | A database table (specified as a DRL parameter to the command; see Scripting for qstml for information about DRLs) |  |
decision tree | .qsdt or .dt file |  |
derivation | FDL function-library (.fdl) file |  |
flat data description | .fdd file |  |
flat data | flat-data file |  |
flat file | flat file (specified as a flat-data description (FDD) filename parameter to the command, if you are writing a flat file and have asked that an FDD file be created; otherwise the parameter contains the flat-data filename instead). A flat file operation may involve several individual files (a flat-data description file and one or more flat-data files). The difference between this hook and the previous two is that the command is run only once per operation (before the first file is read or after the last file is written); the lower-level hooks are executed once per individual file. |  |
focus | .ftr file (note that when a focus is moved or removed in Portrait Miner or with qsremove or qsmove, the command is run for the old focus that no longer exists as well as being run for the new focus after it is created) |  |
HTML | HTML-formatted crosstab file |  |
log | .log file |  |
map | Decision Studio map (.mid or .mif) file |  |
model | TML model (.tml) file created by Decision Studio |  |
qmml | QMML model (.qmml) file created by Decision Studio |  |
scorecard | .qssc or .sc file |  |
text | Do not use. |  |
Parent topic: Systems integration and RealTime


expired rule warning threshold

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Actionhouse RT

Purpose The maximum number of rules on the RealTime server that may be marked as "expired" but not yet released by the clients. If this number is exceeded, a resource warning is written to the system event log (and, if enabled, to the RealTime administration log file). This is usually an indication of a mis-configured or crashed client.

Valid values An integer, by default 10

See also

admin log file
Parent topic: Systems integration and RealTime


export XML menu item

Section Actionhouse RT

Purpose Set the text that appears in the Table Viewer menu option for saving QMML models.

Valid values A text string, by default "Export as QMML..."

Parent topic: Systems integration and RealTime


external execution hook location

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Directories

Purpose Specify the working directory/folder for commands that Portrait Miner runs via execution hooks [see before ... read, after ... write].

Valid values The location of a directory/folder (on the Portrait Miner server), by default unset

If the location is unset, execution-hook commands inherit their working directory/folder from Decision Studio.

Parent topic: Systems integration and RealTime


logging buffer flush period

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Actionhouse RT

Purpose See RealTime integration and administration.

Valid values An integer, by default 5

Parent topic: Systems integration and RealTime


logging buffer max memory usage

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Actionhouse RT

Purpose See RealTime integration and administration.

Valid values An integer, by default 1024

Parent topic: Systems integration and RealTime


logging buffer size

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Actionhouse RT

Purpose See RealTime integration and administration.

Valid values An integer, by default 10

Parent topic: Systems integration and RealTime


rule store save

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Directories

Purpose Set the default location for saving QMML models (and enable this facility in Decision Studio).

Valid values The location of a directory/folder (on the Portrait Miner server), by default unset (so that the menu option defined by the preference export XML menu item does not appear in Decision Studio)

Parent topic: Systems integration and RealTime


server state location

This setting is for expert use, and should normally only be changed by the Portrait Miner administrator.

Section Actionhouse RT

Purpose The directory where the RealTime server stores its active state. When the server starts up, it loads state from this directory. The server maintains an on-disk copy of its current state here as it runs.

Valid values The location of a directory/folder (on the Portrait Miner server), by default shared/actionhouseRT (on UNIX) or shared\actionhouseRT (on Windows) in the Portrait Miner installation directory

Parent topic: Systems integration and RealTime


Aggregation functions

  • any
  • confintlower
  • confintupper
  • count
  • countnonnull/countnonnulls
  • countnull/countnulls
  • countunique
  • countuniquenonnull
  • expectedcount
  • expectedproportion
  • first
  • last
  • max (one argument)
  • mean (one argument)
  • median
  • min (one argument)
  • mode
  • moderatio
  • percentage
  • percentagerate
  • proportion
  • segindex
  • significance
  • stdev
  • sum (one argument)
  • variance


any

Purpose Pick an arbitrary non-null value from a field (possibly per group or segment).

Syntax any(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field from which to pick a value

Result

Type | Description
as input | An arbitrary non-null value from the field x (possibly per group or segment)
Note:

You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

first

last

Parent topic: Aggregation functions


confintlower

Purpose Calculate the lower bound of a 95% confidence interval for the mean of a field.

Syntax confintlower(x)

Arguments

Type | Name | Description
numeric | x | The field to be considered

Result

Type | Description
real | The lower bound of an interval within which the segment's population mean for the field x is expected to fall with 95% confidence
Note:

You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

confintupper

significance

Parent topic: Aggregation functions


confintupper

Purpose Calculate the upper bound of a 95% confidence interval for the mean of a field.

Syntax confintupper(x)

Arguments

Type | Name | Description
numeric | x | The field to be considered

Result

Type | Description
real | The upper bound of an interval within which the segment's population mean for the field x is expected to fall with 95% confidence
Note:

You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

confintlower

significance

Parent topic: Aggregation functions


count

Purpose Count the number of records (possibly per group or segment).

Syntax count()

Arguments None

Result

Type | Description
integer | The number of records (possibly per group or segment)

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

countnonnull/countnonnulls

countnull/countnulls

countunique

countuniquenonnull

Parent topic: Aggregation functions


countnonnull/countnonnulls

Purpose Count the number of records for which a field has non-null values (possibly per group or segment).

Syntax countnonnull(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field to be considered

Result

Type | Description
integer | The number of records for which the field x has non-null values (possibly per group or segment)
Note:

In Decision Studio crosstabs [see Aggregation functions for crosstabs] and in an measurement context [see Aggregation functions for measurements and derivations] this function is countnonnull, while in a derivation context it is countnonnulls.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

count

countnull/countnulls

countunique

countuniquenonnull

Parent topic: Aggregation functions


countnull/countnulls

Purpose Count the number of records for which a field contains the null value (possibly per group or segment).

Syntax countnull(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field to be considered

Result

Type | Description
integer | The number of records for which the field x is null (possibly per group or segment)
Note:

In Decision Studio crosstabs [see Aggregation functions for crosstabs] and in an measurement context [see Aggregation functions for measurements and derivations] this function is countnull, while in a derivation context it is countnulls.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

count

countnonnull/countnonnulls

countunique

countuniquenonnull

Parent topic: Aggregation functions


countunique

Purpose Count the number of unique values occurring in a field, potentially including the null value (possibly per group or segment).

Syntax countunique(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field to be considered

Result

Type | Description
integer | The number of unique values, including null, that occur in x (possibly per group or segment)
Note:

You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

count

countnonnull/countnonnulls

countnull/countnulls

countuniquenonnull

Parent topic: Aggregation functions


countuniquenonnull

Purpose Count the number of non-null unique values occurring in a field (possibly per group or segment).

Syntax countuniquenonnull(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field to be considered

Result

Type | Description
integer | The number of unique values, excluding null, that occur in x (possibly per group or segment)
Note:

You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

count

countnonnull/countnonnulls

countnull/countnulls

countunique

Parent topic: Aggregation functions


expectedcount

Purpose Calculate the "expected" population of a crosstab segment.

Syntax expectedcount()

Arguments None

Result

Type | Description
real | The record count that would be expected for a segment if the fields of the crosstab were independent of one another
Note:

You can only use this function in Decision Studio crosstabs [see Aggregation functions for crosstabs] for visualizing data.

See also

Aggregation functions for crosstabs

expectedproportion

Parent topic: Aggregation functions


expectedproportion

Purpose Calculate the "expected" population of a crosstab segment, as a proportion of the total population.

Syntax expectedproportion()

Arguments None

Result

Type | Description
real | The proportion of the population that would be expected in a segment if the fields of the crosstab were independent of one another
Note:

You can only use this function in Decision Studio crosstabs [see Aggregation functions for crosstabs] for visualizing data.

See also

Aggregation functions for crosstabs

expectedcount

Parent topic: Aggregation functions


first

Purpose Pick the first non-null value from a field (possibly per group or segment).

Syntax first(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field from which to pick a value

Result

Type | Description
as input | The first non-null value encountered in the field x (possibly per group or segment)
Note:

You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

any

last

Parent topic: Aggregation functions


last

Purpose Pick the last non-null value from a field (possibly per group or segment).

Syntax last(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field from which to pick a value

Result

Type | Description
as input | The last non-null value encountered in the field x (possibly per group or segment)
Note:

You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

any

first

Parent topic: Aggregation functions


max (one argument)

Purpose Calculate the maximum non-null value in a field (possibly per group or segment).

Syntax max(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field whose values are to be compared

Result

Type | Description
as input | The maximum non-null value in the field x (possibly per group or segment)
Note:
  • Be careful not to confuse this aggregation function with the multi-argument function [see max (two or more arguments), maxnonnull] of the same name.
  • In a derivation context, this function does not accept a string- or date-valued field as an argument.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

min (one argument)

Parent topic: Aggregation functions


mean (one argument)

Purpose Calculate the mean (common average) of the non-null values in a field (possibly per group or segment).

Syntax mean(x)

Arguments

Type | Name | Description
numeric | x | The field whose mean is to be calculated

Result

Type | Description
real | The mean of the non-null values in the field x (possibly per group or segment)
Note:

Be careful not to confuse this aggregation function with the multi-argument function [see mean (two or more arguments), meannonnull] of the same name.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

median

mode

Parent topic: Aggregation functions


median

Purpose Calculate the median (middle value) of the non-null values in a field (possibly per group or segment).

Syntax median(x)

Arguments

Type | Name | Description
integer, real, or string | x | The field whose median is to be calculated

Result

Type | Description
as input | The median value of the non-null values in the field x (possibly per group or segment)
Note:

You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

mean (one argument)

mode

Parent topic: Aggregation functions


min (one argument)

Purpose Calculate the minimum non-null value in a field (possibly per group or segment).

Syntax min(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field whose values are to be compared

Result

Type | Description
as input | The minimum non-null value in the field x (possibly per group or segment)
Note:
  • Be careful not to confuse this aggregation function with the multi-argument function [see min (two or more arguments), minnonnull] of the same name.
  • In a derivation context, this function does not accept a string- or date-valued field as an argument.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

max (one argument)

Parent topic: Aggregation functions


mode

Purpose Calculate the mode (most common value) of the non-null values in a field (possibly per group or segment).

Syntax mode(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field whose mode is to be calculated

Result

Type | Description
as input | The mode of the non-null values in the field x (possibly per group or segment)
Note:
  • In the event of a tie for the most common value, the function returns the least tying number, earliest tying date, or alphabetically earliest tying string.
  • You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

mean (one argument)

median

moderatio

Parent topic: Aggregation functions


moderatio

Purpose Calculate the proportion of non-null records containing the most common non-null value in a field (possibly per group or segment).

Syntax moderatio(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The field whose mode ratio is to be calculated

Result

Type | Description
real | The mode ratio of the field x (possibly per group or segment)
Note:

You cannot use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

mode

Parent topic: Aggregation functions


percentage

Syntax percentage()

Purpose Calculate the number of records in a crosstab segment, as a percentage of the total.

Arguments None

Result

Type | Description
real | The percentage of records (possibly per group or segment)
Note:

You can only use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

See also

Aggregation functions for measurements and derivations

Parent topic: Aggregation functions


percentagerate

Purpose For a binary (1/0) field, calculate the proportion of non-null records containing the value 1, as a percentage.

Syntax percentagerate(x)

Arguments

Type | Name | Description
numeric | x | The binary field to be considered

Result

Type | Description
real | The percentage of records in a binary field having the value 1 (possibly per group or segment)
Note:

You cannot use this function in an aggregations file [see Using aggregation functions and the where and default clauses] or statistics file [see Evaluating focus statistics: the calculate statement] for qsmeasure or the equivalent Aggregate Records window, or in a statistics file for qstrack.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

Parent topic: Aggregation functions


proportion

Purpose Calculate the number of records per customer or segment, as a proportion of the total number of records.

Syntax proportion()

Arguments None

Result

Type | Description
real | The number of records for a customer or in a crosstab segment, relative to the total number of records
Note:

You can only use this function in Decision Studio crosstabs [see Aggregation functions for crosstabs] for visualizing data.

See also

Aggregation functions for crosstabs
Parent topic: Aggregation functions


segindex

Purpose Generate an index number representing a segment.

Syntax segindex()

Arguments None

Result

Type | Description
integer | A positive number uniquely identifying a segment within a crosstab
Note:
  • If null, unclassified, or empty segments are hidden in a crosstab view, they still receive a segment index, so there may appear to be gaps in the sequence of visible indices.
  • You cannot use this function in an aggregations file [see Using aggregation functions and the where and default clauses] or statistics file [see Evaluating focus statistics: the calculate statement] for qsmeasure or the equivalent Aggregate Records window, or in a statistics file for qstrack.

Example R–2: Marking approximate deciles

You can bin a field "myfield" into ten equal-population bins and then derive a field "decile":

segindex() by myfield

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

bin

Parent topic: Aggregation functions


significance

Purpose Calculate the statistical significance of any discrepancy between the mean value of a field for a crosstab segment and the mean value of the same field for the whole population.

Syntax significance(x)

Arguments

Type | Name | Description
numeric | x | The field to be considered

Result

Type | Description
real | A value between -1 and 1, whose sign indicates the direction in which the segment mean of x deviates from the population mean of x and whose absolute value indicates the statistical significance of that deviation, taking segment size into account
Note:

You cannot use this function in an aggregations file [see Using aggregation functions and the where and default clauses] or statistics file [see Evaluating focus statistics: the calculate statement] for qsmeasure or the equivalent Aggregate Records window, or in a statistics file for qstrack.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

confintlower

confintupper

Parent topic: Aggregation functions


stdev

Purpose Calculate the standard deviation of the non-null values in a field (possibly per group or segment).

Syntax stdev(x)

Arguments

Type | Name | Description
numeric | x | The field whose standard deviation is to be computed

Result

Type | Description
real | The standard deviation of the non-null values in the field x (possibly per group or segment)

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

Parent topic: Aggregation functions


sum (one argument)

Purpose Calculate the sum of the non-null values in a field (possibly per group or segment).

Syntax sum(x)

Arguments

Type | Name | Description
numeric | x | The field whose values are to be summed

Result

Type | Description
as input | The sum of the non-null values in the field x (possibly per group or segment)
Note:
  • Be careful not to confuse this aggregation function with the multi-argument function [see sum (two or more arguments), sumnonnull] of the same name.
  • Note that when the sum aggregation function is applied to an empty set of records (for example, as a result of record filtering), the result is null. You should normally override this behavior, by setting the default value to 0.

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

Parent topic: Aggregation functions


variance

Purpose Calculate the statistical variance of the non-null values in a field (possibly per group or segment).

Syntax variance(x)

Arguments

Type | Name | Description
numeric | x | The field whose variance is to be computed

Result

Type | Description
real | The variance of the non-null values in the field x (possibly per group or segment)

See also

Aggregation functions for crosstabs

Aggregation functions for measurements and derivations

Parent topic: Aggregation functions


TransactionMeasurement Language (TML) reference

  • About Transaction Measurement Language
  • TML syntax
  • Field definition: the create statement
  • Using aggregation functions and the where and default clauses
  • Splitting aggregations: the by clause
  • Evaluating focus statistics: the calculate statement
  • Aggregation functions for measurements and derivations
  • Reserved words in TML


About Transaction Measurement Language

Transaction Measurement Language (TML) is a collection of lightweight syntactic wrappers around FDL expressions, used to specify field derivations and aggregations in conjunction with the Derive Fields [see To derive fields in a focus using Portrait Miner] and Aggregate Records [see To convert a transaction-oriented focus to a customer-oriented focus] wizards, and the Portrait Miner data-build commands qsderive, qsmeasure, qstrack and qsselect.

See also

About Field Derivation Language

TML syntax

Using Portrait Miner data-build commands for data import, processing, and export

Parent topic: TransactionMeasurement Language (TML) reference


TML syntax

A derivations, trackers, selections, or aggregations file contains one or more TML create statements, while a statistics file contains one or more TML calculate statements.
  • TML is a case-sensitive language:
    • TML keywords (create, by, string etc.) are written in lowercase letters, with the exception of STATISTIC.
    • The names of all aggregation functions [see Aggregation functions for measurements and derivations] are written in lowercase letters.
    • The names Average, average, and AVERAGE all refer to different fields or statistics.
  • Names for fields and statistics must begin with a letter ("A" — "Z" or "a" — "z"), contain only letters, digits, and underscore ("_"), and be no longer than 128 characters; optionally quoted in single quotation marks, for example, 'CustomerID'. You must enclose the name of a field or statistic in single quotation marks if it coincides with a TML or FDL reserved word, or differs from one only in case.
  • TML syntax is described using railroad diagrams like this:

    As long as you follow the arrows and don't backtrack, any path through a railroad diagram leads to syntactically valid (though not necessarily meaningful) TML:
    • Words in oval/circular boxes (like create) are TML keywords; you should type them exactly as they appear.
    • You should also type punctuation in oval boxes (like ":" and ":=") exactly as it appears (you can't have a space between ":" and "=" in ":=").
    • Don't forget the semicolon that ends each TML statement.
    • Terms in rectangular boxes (like expression) refer to other railroad diagrams or to forms described elsewhere in words; you should not type these literally.
  • TML is a freely formatted language: you can break lines or insert extra spaces between syntactic elements (in oval/circular boxes in railroad diagrams) without affecting the interpretation of a derivations, trackers, selections, aggregations, or statistics file.
  • As well as introducing spaces between syntactic elements, you can include comments, which begin with a double slash ("//") and continue to the end of the same line.
  • Wherever TML syntax requires an expression, you can use any FDL expression [see Expressions], except that an expression involving a TML reserved word, a semicolon, or braces {...} must be enclosed in parentheses (...).

See also

About Transaction Measurement Language

Evaluating focus statistics: the calculate statement

Field definition: the create statement

Reserved words in FDL

Reserved words in TML

Parent topic: TransactionMeasurement Language (TML) reference


Field definition: the create statement

The create statement defines a field by derivation or aggregation, depending on the context in which it appears.

Derivations The derivations file for qsderive or the equivalent Derive Fields window, the trackers file for qstrack, and the selections file for qsselect must contain create statements of the following form:

The aggregations file for qsmeasure or the equivalent Aggregate Records window can optionally contain create statements of the following form:

In both cases, the create statement defines a field called name in terms of an FDL expression [see Expressions]. The datatype of the field is the datatype of the expression, unless you override it by specifying a compatible type [see Datatypes].
  • For each successive create statement in the derivations file, qsderive or the Derive Fields window derives a field in the output focus using the given expression, which can refer both to fields in the source focus and to fields derived earlier in the derivations file.
  • For each successive create statement in the trackers file, qstrack derives a field using the given expression, which can refer to fields in the source focus and to fields derived earlier in the trackers file, as well as to focus statistics defined in any statistics file. The expression typically involves state variables [see Variables].
  • Given a selections file, qsselect derives a field corresponding by default to the first create statement and ignores any other statements in the file. The defining expression must be of boolean (or compatible) type.
  • For each successive create statement of this form in the aggregations file, qsmeasure or the Aggregate Records window derives a field in the output focus using the given expression, which can refer to fields derived earlier in the aggregations file, and to focus statistics defined in any statistics file.
  • A temporary statement has the same effect as a create statement, except that the field doesn't appear in the output focus. However you can still refer to the temporary field in subsequent expressions in the aggregations file.

Aggregations The aggregations file for qsmeasure or the equivalent Aggregate Records window can contain create statements of the following form:

For each create statement of this form in the aggregations file, qsmeasure or the Aggregate Records window effectively derives a virtual field corresponding to the expression following the aggregation function. This expression can refer to fields in the source focus.

After deriving the virtual field, qsmeasure or the Aggregate Records window applies the aggregation function [see Using aggregation functions and the where and default clauses].

The default datatype of the resulting field(s) depends on the aggregation function and the values, operators, and functions involved in the expression to which it applies, but you can override it by specifying a compatible type.

A temporary statement has the same effect as a create statement, except that the field doesn't appear in the output focus. However you can still refer to the temporary field in subsequent expressions in the aggregations file.

Note:
  • In qsderive or Derive Fields derivations files, qsselect selections files, and qstrack trackers files, the expression can involve field statistics, global variables, and functions defined in terms of these. These FDL features are not available in a qsmeasure or Aggregate Records aggregations file.
  • You must put extra parentheses around the expression if it contains a semicolon, braces, or a TML reserved word [see Reserved words in TML].
  • Each create statement must start on a new line.

Examples Given the derivations file, derivations-customer.tml, containing the following:

// Length of standing of customer in months
create CustMonths := countwholemonths(StartDate, today());
// A key field of extended length
create CustomerID_24 : string(24) := CustomerID;
Apply these derivations to the focus RetailCustApril.ftr to create a new focus RetailCustAprilDeriv.ftr: qsderive -derivations derivations-customer.tml\cmdlinecont -input RetailCustApril.ftr -output RetailCustAprilDeriv.ftr Given the selections file, selections-customer.tml, containing the following:
// Select male customers aged between 18 and 65 inclusive.
create Selection := Gender = 1 and Age >= 18 and Age <= 65;
Apply this selection to the focus RetailCustApril.ftr to create a new focus RetailCustAprilSelection.ftr:
qsselect -selections selections-customer.tml
         -input RetailCustApril.ftr%
         -output RetailCustAprilSelection.ftr
Given the aggregations file, aggregations-mostRecent.tml, containing the following:
temporary LastPurchase := max(PurchaseDate);
create AvgTransVal := mean(Amount - 0.01 * PointsRedeemed);
create NumTrans := count();
create MonthsSinceLastPurchase :=
       countwholemonths(LastPurchase, today());

Apply these aggregations to the focus RetailTransApril.ftr to create a customer-oriented focus RetailAggRecentApril:

qsmeasure -aggregations aggregations-mostRecent.tml
          -input RetailTransAprilSorted.ftr -output RetailAggRecentApril%
          -keys CustomerID

See also

Aggregation functions for measurements and derivations

Splitting aggregations: the by clause

To convert a transaction-oriented focus to a customer-oriented focus

Parent topic: TransactionMeasurement Language (TML) reference


Using aggregation functions and the where and default clauses

You can aggregate records using qsmeasure or the equivalent Aggregate Records window.

When you use a create statement in an aggregations file [see Field definition: the create statement], qsmeasure or the Aggregate Records window effectively derives a virtual field corresponding to the expression in parentheses following the aggregation function.

Conceptually, qsmeasure or the Aggregate Records window divides the records in the source focus — augmented by the virtual field — into groups of records with the same key-field value. For each group of records (corresponding to a single key-field value), qsmeasure or the Aggregate Records window applies the aggregation function to the values of the virtual field within those records, to produce a single result value.

The result values for all the groups taken together consitute a new field, with the name given in the create statement — unless the create statement contains a by clause [see Splitting aggregations: the by clause].

Within each group of records with a common key-field value, certain aggregation functions ignore records for which the virtual field contains null [see The null value].

If the create statement contains a where clause, the aggregation function ignores records for which the associated expression evaluates to 0 ("false"). This expression can refer to fields in the source focus.

Because aggregation functions can ignore some of the records in a group with a common key-field value, it's possible for all the records in the group to be skipped. Many aggregation functions return the null value in this case. By including a default clause, you can specify a constant expression to be evaluated instead of the aggregation in the event that it returns null.

Note:

When you use the sum aggregation function [see sum (one argument)], you should usually specify a default sum of 0. If you don't use a default clause, the sum over an empty record selection is null, which is unlikely to be what you want.

Examples Given the aggregations file, aggregations-purchaseSummary.tml, containing the following:

create firstPurchaseDate := first(PurchaseDate);
create commonPaymentMethod := mode(PaymentMethod);
create Spend := sum(Amount) default 0;
create SpendInStore800 := sum(Amount)
       where Store = "0800" default 0;
create proportionSpendInStore800 := SpendInStore800 / Spend;
create NumTransCRRedeemed := count()
       where PaymentMethod = "CR" and not isnull(PointsRedeemed);

Apply these aggregations to the focus RetailTransApril.ftr to create a customer-oriented focus RetailAggSummaryApril:

qsmeasure -aggregations aggregations-purchaseSummary.tml
          -input RetailTransAprilSorted.ftr -output RetailAggSummaryApril
          -keys CustomerID

See also

Aggregation functions for measurements and derivations

Expressions

Parent topic: TransactionMeasurement Language (TML) reference


Splitting aggregations: the by clause

The aggregations file for qsmeasure or the equivalent Aggregate Records window contains a sequence of create statements [see Field definition: the create statement]. As part of such a create statement, you can optionally include a by clause, to break your aggregation down according to the application of either a split function or the bin function to an expression derived from other fields.
For each possible integer i returned by the split function or bin function, qsmeasure or the Aggregate Records window creates a separate field, containing values aggregated from just those records for which the function application evaluates to i. The name of each of these related fields is formed from the name in the create statement together with a suffix that depends on the function used for splitting the aggregation.
  • The following built-in split functions are available (with given field-name suffixes corresponding to successive function values):
    Function | Field-name suffixes
    day | "_1," "_2," "_3," ..., "_31"
    dayofweek | "Sun," "Mon," "Tue," ..., "Sat"
    hour | "0000," "0100," "0200" ..., "2300"
    isnull | "NonNull," "Null"
    match | "MisMatch," "Match"
    member | "NotMember," "Member"
    minute | "0," "1," "2," ..., "59"
    month | "Jan," "Feb," "Mar," ..., "Dec"
    second | "0," "1," "2," ..., "59"
    sgn | "Negative," "Zero," "Positive"
    strmember | "NotMember," "Member"
    weekofyear | "_1," "_2," "_3," ..., "_53"
  • You can use the bin function to apply an FDL binning to an expression. Used as a split function, the bin function gives rise to field-name suffixes "_1," "_2," ..., "_n," "_null," and "_other" (where n depends on the number of bins in the binning).
  • You can also define your own split function [see User-defined functions]. The element_names attribute defines the field-name suffixes corresponding to the function return values.

Examples Given the aggregations file, aggregations-builtinSplit.tml, containing the following:

create numberPurchases := count();
create numberPurchasesOn_ := count() by dayofweek(PurchaseDate);
create proportionPurchases_Mon :=
       numberPurchasesOn_Mon / numberPurchases;
create purchaseAmountIn_ :=
       sum(Amount) by month(PurchaseDate) default 0;

Apply these aggregations to the focus RetailTransApril.ftr to create a customer-oriented focus RetailDateSplitsApril.ftr containing fields CustomerID, numberPurchases, numberPurchasesOn_Sun, numberPurchasesOn_Mon, ..., numberPurchasesOn_Sat, proportionPurchases_Mon, and purchaseAmountIn_Jan, purchaseAmountIn_Feb, ..., purchaseAmountIn_Dec:

qsmeasure -aggregations aggregations-builtinSplit.tml -keys CustomerID -input RetailTransApril.ftr -output RetailDateSplitsApril.ftr

Given the aggregations file, aggregations-binSplit.tml, containing the following:

create numberPurchasesAmountBand :=
       count() by bin(EqualRange(20,100,4),Amount);
create numberPurchasesDateBand := count() by
       bin(PrePost(todate(19990401), todate(19990501),
       todate(19990601)), PurchaseDate);
create ratioPrePost :=
       numberPurchasesDateBand_3 / numberPurchasesDateBand_2;

Apply these aggregations to the RetailTransApril.ftr focus to create a customer-oriented focus, RetailRangeSplitsApril.ftr, containing fields CustomerID, numberPurchasesAmountBand_1, numberPurchasesAmountBand_2, ..., numberPurchasesAmountBand_6, numberPurchasesAmountBand_null, numberPurchasesAmountBand_other (corresponding to two end bins, four internal bins and the null and unclassified bin), numberPurchasesDateBand_1, numberPurchasesDateBand_2, ..., numberPurchasesDateBand_4, numberPurchasesDateBand_null, numberPurchasesDateBand_other, and ratioPrePost:

qsmeasure -aggregations aggregations-binSplit.tml -keys CustomerID -input RetailTransApril.ftr -output RetailRangeSplitsApril.ftr

Given the FDL functions file, fdl-functions-storeGroups.fdl, containing the following:

function StoreGroupFunction( Store )
[
   element_names = "North, South, East, West"
]
{
case
    Store = "0000" or Store = "0800" : 1;
    Store = "0300" or Store = "0600" or Store = "0700" : 2;
    Store = "0100" or Store = "0400" : 3;
    default : 4;
}

Given the aggregations file, aggregations-userDefinedSplit.tml, containing the following:

create totalPurchases := sum(Amount);
create totalPurchasesByStore_ :=
       sum(Amount) by StoreGroupFunction( Store );
create proportionPurchases_North :=
       totalPurchasesByStore_North / totalPurchases;

Apply these aggregations to the RetailTransApril.ftr focus to create a customer-oriented focus, RetailGroupSplitsApril.ftr, containing fields CustomerID, totalPurchases, totalPurchasesByStore_North, totalPurchasesByStore_South, totalPurchasesByStore_East, totalPurchasesByStore_West, and proportionPurchases_North:

qsmeasure -aggregations aggregations-userDefinedSplit.tml
    -library fdl-functions-storeGroups.fdl
    -keys CustomerID
    -input RetailTransApril.ftr -output RetailGroupSplitsApril.ftr

See also

Aggregation functions for measurements and derivations

Expressions

Using aggregation functions and the where and default clauses

Parent topic: TransactionMeasurement Language (TML) reference


Evaluating focus statistics: the calculate statement

The statistics file for qsmeasure, the equivalent Aggregate Records window, or qstrack contains calculate statements of the following form:

The calculate statement defines a focus statistic called name in terms of an aggregation function applied to an FDL expression [see Expressions], which can refer to fields in the source focus.

As in the case of a measurement [see Using aggregation functions and the where and default clauses], qsmeasure, qstrack, or the Aggregate Records window effectively derives a virtual field corresponding to the expression in parentheses following the aggregation function.

The calculate statement gives rise to a single result value, obtained by applying the aggregation function to all the values in the virtual field. (In contrast, a create statement in an aggregations file gives rise to a field, in which each value is obtained by applying the aggregation function to the values in the virtual field for a group of records.)

The default datatype of a focus statistic depends on the aggregation function and the values, operators, and functions involved in the expression to which it applies, but you can override it by specifying a compatible type [see Datatypes].

If the calculate statement contains a where clause, the aggregation function ignores records for which the associated expression evaluates to 0 ("false"). This expression can refer to fields in the source focus.

Once you have defined a focus statistic in the statistics file, you can refer to it in expressions in the aggregations or trackers file using the special form STATISTIC.name. You can use this form anywhere that you can refer to a field in the source focus or trackers file.

Examples Given the statistics file, statistics-amount.tml, containing the following:

calculate averageAmount := mean(Amount);

Given the aggregations file, aggregations-statistic.tml, containing the following:

create averageSpend := mean(Amount);

create bigSpender := averageSpend > STATISTIC.averageAmount;

Apply these aggregations to the focus RetailTransApril.ftr to create a customer-oriented focus RetailAprilBigSpenders.ftr containing fields CustomerID, averageSpend, and bigSpender:

qsmeasure -statistics statistics-amount.tml

-aggregations aggregations-statistic.tml

-keys CustomerID

-input RetailTransApril.ftr -output RetailAprilBigSpenders.ftr

See also

Aggregation functions for measurements and derivations

Parent topic: TransactionMeasurement Language (TML) reference


Aggregation functions for measurements and derivations

There are a number of aggregation functions available for use in measurements and derivations.

To use a function in a measurement context means to use it \funccontextmeasure.

To use a function in a derivation context means to use it \funccontextderive.

Except where otherwise noted, an aggregation function takes a single numeric, string, or date field as an argument.

Aggregation functions for both measurements and derivations You can use the following aggregation functions in both measurement and derivation contexts:

Function | Result
count | The number of records in the group/segment (This function does not take an argument.)
max [see max (one argument)] | The maximum non-null value in the field for the group/segment (In a derivation context, this function does not accept a string-valued expression as an argument.)
mean [see mean (one argument)] | The mean (common average) of the non-null values in the field for the group/segment (This function requires a numeric expression as an argument.)
min [see min (one argument)] | The minimum non-null value in the field for the group/segment (In a derivation context, this function does not accept a string-valued expression as an argument.)
stdev | The standard deviation of the non-null values in the field for the group/segment (This function requires a numeric expression as an argument.)
sum [see sum (one argument)] | The sum of the non-null values in the field for the group/segment (This function requires a numeric expression as an argument.)
variance | The variance of the non-null values in the field for the group/segment (This function requires a numeric expression as an argument.)

Aggregation functions for measurements only You can use the following aggregation functions in a measurement context only:

Function | Result
any | A non-null value in the field, drawn from an arbitrary non-null record in the group/segment
confintlower | The lower bound of a 95% confidence interval for the mean of the field in the group
confintupper | The upper bound of a 95% confidence interval for the mean of the field in the group
countnonnull [see countnonnull/countnonnulls] | The number of records in the group for which the field has non-null values [see The null value] In derivations, use countnonnulls instead.
countnull [see countnull/countnulls] | The number of records in the group for which the field contains null [see The null value] In derivations, use countnulls instead.
countunique | The number of unique values that occur in the field, potentially including the null value
countuniquenonnull | The number of unique values, excluding the null value, that occur in the field
first | The first non-null value in the field for the group
last | The last non-null value in the field for the group
median | The median (middle value) of the non-null values in the field for the group (This function requires a numeric or string-valued expression as an argument.)
mode | The mode (most-common value) of the non-null values in the field for the group
moderatio | The proportion of non-null records in the group that contain the most-common non-null value in the field

Aggregation functions for derivations only You can use the following aggregation functions in a derivation context only:

Function | Result
countnonnulls [see countnonnull/countnonnulls] | The number of records in the segment for which the field has non-null values [see The null value] In measurements, use countnonnull instead.
countnulls [see countnull/countnulls] | The number of records in the segment for which the field contains null [see The null value] In measurements, use countnull instead.
percentage | The number of records in the segment, as a percentage of the total number of records (This function does not take an argument.)
percentagerate | The percentage of non-null records in the segment that contain the value 1 in the field The field must contain only the values 0 and 1.
segindex | A positive number uniquely identifying the segment within the crosstab formed by the breakdown fields (This function does not take an argument.)
significance | The statistical significance of any discrepancy between the mean value of the field in the segment and the mean value of the field for the whole population, with a sign indicating the direction of the deviation (This function requires a numeric expression as an argument.)
Parent topic: TransactionMeasurement Language (TML) reference


Reserved words in TML

The following tokens are reserved words in TML:

aggregation, all, and, as, auto, automatic, bin, binning, bool, boolean, by, calculate, constant, create, crosstab, date, default, description, dimension, double, drl, enum, except, fields, file, float, format, from, full, function, group, include, inplace, input, int, integer, join, left, long, merge, meta, modifiable, normal, on, open, outer, outfile, output, parameter, pragma, real, ref, reference, rename, right, separate_functions, short, show, show_empty_segments, show_summaries, sort, state, statistic, strbytes, string, suppress, table, temp, temporary, track, tracker, view, where

To use a reserved word, or a word that differs only in case from a reserved word, as a field or statistic name in TML, or as an identifier [see Expressions] in FDL, you must enclose it in single quotation marks — for example, 'Date'.

See also

About Transaction Measurement Language

Reserved words in FDL

Parent topic: TransactionMeasurement Language (TML) reference


Field Derivation Language (FDL) reference

  • About Field Derivation Language
  • Datatypes
  • Expressions
  • Conditional expressions
  • Variables
  • User-defined functions
  • Built-in functions
  • Reserved words in FDL
  • FDL operators
  • FDL functions
  • Binnings
  • FDL regular expressions


About Field Derivation Language

Field Derivation Language (FDL) is a simple language for specifying the creation of new fields in Portrait Miner foci. You can use FDL in the Table Viewer [see To derive a field using the Table Viewer] in Decision Studio, the Derive Fields [see To derive fields in a focus using Portrait Miner] and Aggregate Records [see To convert a transaction-oriented focus to a customer-oriented focus] wizards, and the Portrait Miner data-build commands % We won't mention its use with -records here. qsderive, qsmeasure, qstrack and qsselect.
You can employ FDL to:
  • Transform, combine, and perform a variety of other computations on existing fields in a focus
  • Partition a focus into a set of random samples.
  • Define segmentations and predictive models
  • Select records according to a criterion of your choice

You typically use it in simple, "one-line" expressions such as those described in Basic expressions, but you can also use it to construct scripts with complex, data-dependent execution paths.

FDL syntax includes:
  • Operators for arithmetic [see Arithmetic operators].
  • Operators for comparison [see Relational operators] and for combining logical expressions [see Logical operators].
  • Two alternative constructs for conditional evaluation of statements: if...then...else and case [see Conditional expressions].
  • A comprehensive set of built-in functions [see Built-in functions].
  • The ability to encapsulate common transformations as user-defined functions [see User-defined functions], for re-use and sharing.
  • Variables, to hold values for re-use within an FDL script, including (in some contexts) global "accumulator" variables [see Global variables in Decision Studio].
  • A facility for incorporating crosstabs into derivations .

See also

About Transaction Measurement Language

Expressions

Parent topic: Field Derivation Language (FDL) reference


Datatypes

The following basic datatypes are supported in FDL [see About Field Derivation Language]:

Type | Description | Examples (as FDL literals)
integer | A number without a fractional part (between -2 147 483 647 and 2 147 483 646) | 78004, -100
real | A number with a fractional part, represented internally as a "floating-point" number with 15-digit precision (between [image] and [image] , or 0) | 42.3, -0.56
date | A date/time between AD 1507 and AD 3015, to one-second precision | #2009/01/01, #2009/01/01:16:01:39
string | A character string, representing textual data | "hello"
smallinteger | A small number without a fractional part (between qsminsmallint and qsmaxsmallint) | 42, -1
Note:
  • If you use a literal integer value (such as 12345678910) that is too large for an integer datatype, you will get an overflow. You can often work around this by using a real value instead: (in this case, 12345678910.0).
  • The smallinteger type has limited applicability within Portrait Miner, and should only be used where absolutely necessary. In general, you should use the integer type instead.
Parent topic: Field Derivation Language (FDL) reference

The null value

In addition to the ordinary values for each of the basic datatypes, a field or expression of integer, real, date, or string type can take the special value null. The null value always represents an unknown value (due to missing data, because of an overflow in a calculation — such as division by zero — or for some other reason). It is distinct from both zero and the empty string "".

FDL functions and operators preserve the uncertainty introduced by a null argument or operand, often giving the null value as a result. There are, however, functions — notably isnull and some aggregation functions — that deal specially with the null value.

Examples

?

1 + null equals null.

1 != null equals null.

1 < null equals null.

null = null equals null.

null != null equals null.

false or null equals null.

true and null equals null.

true or null equals true.

false and null equals false.

See also

ifnull, nvl

Boolean data

There is no formal boolean (true/false) datatype in FDL. However, you can treat an integer field (or variable) containing only the values 0 and 1, or a logical expression such as Income < 10000, as though it were of boolean type.

Logical expressions evaluate to 1 when they are true and 0 when they are false. Conditional expressions use these values to determine which of two or more other expressions to evaluate. Logical operators also work with these values. A value of 0 in an integer field or variable is interpreted as "false" and any other (non-null) value is interpreted as "true."

Additionally, you can use the keywords true and false as boolean literals (which stand for 1 and 0 respectively).

Type-compatibility

The integer and real datatypes are said to be type-compatible, because you can use an integer value wherever a real value is required (but not vice versa), for example, as an argument to a function. Date and string datatypes are only type-compatible with themselves.

The operands of a binary arithmetic operator [see Arithmetic operators] or relational operator [see Relational operators] have to be type-compatible. Indeed, in the case of a binary arithmetic operator, both operands must be numeric; the result is real unless both operands are integers.

Likewise, the result expressions in an if or case expression [see Conditional expressions] have to be type-compatible, so that the type of the result can be determined before evaluation. If integer- and real-valued expressions are mixed, the result is real-valued.

Type conversion

As well as using implicit datatype conversion (which occurs when the datatype of an expression forces it), you can explicitly convert between datatypes with the tointeger, toreal, todate and tostring FDL functions.

Note: When converting from a string to a numeric, any trailing non-numeric characters are ignored.


Expressions

An FDL expression is one of the following:
  • A basic expression [see Basic expressions]
  • A conditional expression [see Conditional expressions]
  • A variable initialization or assignment [see Variables]
  • A semicolon-separated list of expressions (an expression list), enclosed in parentheses

Every expression has an associated datatype [see Datatypes] and can be evaluated.

To evaluate an expression list in a given context, evaluate each constituent expression in turn, from first to last; the value of the expression list as a whole is the last computed value.

Note:
  • The datatype is inferred automatically. You cannot specify it other than by using a local variable of the required type, or by using an expression that forces the type. For example, the following expression forces the type to be real:

    if false then 0.0 else ...

  • You typically use expression lists in combination with variable assignment.
Parent topic: Field Derivation Language (FDL) reference

Basic expressions

A basic expression is one of the following:
  • An identifier, optionally quoted in single quotation marks, for example, 'CustomerID'. You must enclose an identifier in single quotation marks if it does not begin with a letter ("A" — "Z" or "a" — "z"), contains characters other than letters, digits, and underscores, or coincides with a TML or FDL reserved word (or differs from one only in case). An identifier must be no longer than 128 characters.
  • A numeric literal, for example, 30, -3.28, or 3.1e8 (the last of these representing [image])
  • A string literal, enclosed in double quotation marks, for example, "A string"
  • A date literal, prefixed by "#," for example, #2004/03/16 or #2004/03/16:09:12:13
  • The keyword "null" (see The null value)
  • A function application, consisting of a function name (an identifier) followed by a comma-separated list of arguments (expressions) in parentheses; for example, mean(IncomeA + IncomeB, TotalEstIncome)
  • An arithmetic expression, consisting of numeric-valued expressions connected by arithmetic operators [see Arithmetic operators], for example, 365 / 52
  • A relation, consisting of numeric- or string-valued expressions connected by relational operators [see Relational operators], for example, Age > 30 or 'State' = "New York"
  • A logical expression, consisting of relations or other boolean-valued expressions connected by logical operators [see Logical operators], for example, (Income > 250000) and (MaritalStatus = "Single")
  • A statistic identifier, consisting of the TML keyword STATISTIC followed by a period followed by an identifier, for example, STATISTIC.AverageIncome (only in a TML aggregations file)
  • A field statistic — only in a Decision Studio derivation, a qsderive derivations file, or a qsselect selections file
Note:
  • FDL identifiers are case-significant. For example, the expressions CustomerID and CUSTOMERID refer to different fields, while the expressions isnull(Age) and IsNull(Age) involve different functions.
  • A numeric literal is evaluated as an integer if it contains no decimal point and doesn't use scientific notation. Otherwise it is evaluated as a real number.
  • A string literal can contain any characters other than double quotation marks (") and newline characters.
  • A date literal is initially evaluated in YMD [see Date formats] format; if this fails, it is evaluated according to the setting of your read preference [see read].
  • As well as introducing spaces between syntactic elements, you can include comments, which begin with a double slash ("//") and continue to the end of the line. For example,
    // This is a comment.
2 + 2 // This is a comment.

See also

Reserved words in FDL

Reserved words in TML


Conditional expressions

In FDL, there are two main ways of conditionally evaluating an expression: the if expression and the case expression.

See also

About Field Derivation Language

Expressions

Parent topic: Field Derivation Language (FDL) reference

The if expression

If the condition (an FDL expression returning a boolean [see Boolean data] value) is true, the expression following then is evaluated; otherwise, the expression following else is evaluated. The value of the if expression is the value of the evaluated expression.

Note:
  • The expressions following then and else must be type-compatible [see Datatypes].
  • If you omit the "else" part of an if expression and the condition is false, the value of the if expression is null [see The null value].
  • A null [see The null value] condition is treated by the if expression as though it were false. This is an exception to the general rule that the uncertainty introduced by the null value is preserved by FDL expressions. This can lead to unexpected results: for example, when Age is null, the following (at first sight equivalent) expressions generate the null value, 0 and 1 respectively:

    Age > 40

    if Age > 40 then 1 else 0

    if Age <= 40 then 0 else 1

  • You can test for multiple conditions using nested if expressions — if expressions in which the expression following then or else is itself an if expression. If the expression following then is an if expression, you should enclose it in parentheses to avoid ambiguity. Alternatively, you can use the case expression [see The case expression].
  • If your condition can be expressed as x = 0 (or [image]) for some number x, you can also use the built-in FDL function cond instead of an if expression.

Examples

if Age < 40 then "Young"

if Age < 40 then "Young" else "Senior"

if Age > 40 then "Young" else if Age < 60 then "MiddleAged" else "Senior"

if (Age >= 13 and Age < 20) then "Teenager"

if isnull(Age) then mean(Age) else Age

if Responder then RespondDate else StartDate

if match(Postcode, "^EH") then "Y" else "N"

if StartDate < #1998/09/08 then "Loyal" else "Recent"

The case expression

If the first condition (an FDL expression returning a boolean [see Boolean data] value) is true, the corresponding expression (to the right of the colon) is evaluated and returned as the value of the case expression. Otherwise, the next condition is tested; if it is true, the corresponding expression is evaluated and returned as the value of the case expression. Otherwise, the next condition is tested, and so on.

The special default keyword is interpreted as an always-true expression: you would normally use it as the last condition in a case expression (as any subsequent conditions would be ignored).

Note:
  • All the expressions occurring to the right of colons must be type-compatible [see Datatypes].
  • If none of the conditions is true (and there is no default keyword), the value of the case expression is null [see The null value].
  • A null [see The null value] condition is treated by the case expression as though it were false. This is an exception to the general rule that the uncertainty introduced by the null value is preserved by FDL expressions. For example, when Age is null, the following expression generates the value 3:

    case

    Age > 40 : 1;

    Age <= 40 : 2;

    default : 3;

  • If you use a case expression in an expression list or nest a case expression as a condition (inside an if expression or another case expression), you should enclose it in parentheses to avoid ambiguity.

Examples

case

Age < 40: "Young";

default: "NotYoung";

case

Response = "Exc": 7;

Response = "V. Sat": 6

Response = "Sat": 5;

Response = "F. Sat": 4;

Response = "Poor": 3;

Response = "Bad": 2;

default: 1;


Variables

A variable in FDL is a temporary storage location for a real, integer, string, or date value. You can use a local variable to evaluate a complicated subexpression% — particularly useful if the same subexpression occurs more than once% — or to evaluate an expression involving a random-number function, to avoid its value changing from one evaluation to the next. You can also use global variables in Decision Studio [see Global variables in Decision Studio] and state variables in TML trackers files [see State variables in Transaction Measurement Language] to carry information from one record to the next.

To assign a value to a variable, use the following syntax:

The first such assignment is an initialization and determines the class of the variable% — local (no keyword), global, or state. The keyword global or state is only used in conjunction with the first assignment to a global or state variable (the initialization).

The identifier [see Basic expressions] is the name of the variable (which must not coincide with a field name in the focus).

For any class of variable, its datatype [see Datatypes] is that of the first value that is assigned to it.

The value of an assignment expression is simply the value of the expression to the right of the ":=" sign.

For example, the following expression list randomly assigns the value 1 (to 20% of the records), 2 (to another 20% of the records), or 0 (to the remainder of the records):

x := rndUniform();

case

x < 0.2 : 1;

x < 0.4 : 2;

default : 0;

It could be written equivalently in this more compact form:

case

( x := rndUniform() ) < 0.2 : 1;

x < 0.4 : 2;

default : 0;

However, the following expression list generates a different (and probably unwanted) result:

case

rndUniform() < 0.2 : 1;

rndUniform() < 0.4 : 2;

default : 0;

Parent topic: Field Derivation Language (FDL) reference

Global variables in Decision Studio

Variables are local by default. A local variable is destroyed as soon as the last expression in the (outermost enclosing) expression list [see Expressions] is evaluated — The next time that the same variable is used, it is re-initialized. A local variable cannot carry information from one record to the next. For example, the following field-derivation expression list produces a field with 1 in every record:

i := 0;

i := i + 1

A global variable differs from a local variable in that it is not destroyed until Decision Studio or the data-build command has calculated the field values for all records. The initialization only happens once, for the first record in the focus. For example, the following field-derivation expression list produces an index field, with 1 in the first record, 2 in the second, and so on:

global i := 0;

i := i + 1

You can use a global variable in a field-derivation expression list in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in a trackers file for qstrack, or in a selections file for qsselect.

State variables in Transaction Measurement Language

You can use a state variable in a TML field definition in the qstrack trackers file.

A state variable differs from a local variable or a global variable in that it is not destroyed until qstrack has calculated all the field values for the current group (as defined by the key field). The initialization happens once for each group.

For example, the following field definition defines a running-balance field, assuming that the field "Deposit" contains an amount deposited in a transaction (or a negative value for a withdrawal) and the field "InitialBalance" contains the initial balance for the customer (perhaps from a previously joined customer table):

create Balance := (

state bal := InitialBalance;

bal := bal + Deposit

)


User-defined functions

To define an FDL function that you can use in the same way as a built-in function [see Built-in functions], use the following syntax:

The identifier [see Basic expressions] following the "function" keyword is the name of the function. The list of (formal) arguments comes next:

Each formal argument (other than one preceded by a "field" keyword) acts like a local variable [see Variables] that is initialized with the value of the corresponding actual argument when the function is applied. The type [see Datatypes] of a formal argument is the type specified in the function definition, if present; otherwise it is that of the actual argument used when the function is applied. Note that the enclosing parentheses are required even if there are no formal arguments.

Following the list of arguments comes an optional list of function attributes [see Function attributes], and then the defining body of the function. The expression list [see Expressions] is effectively prefixed with local variable assignments corresponding to the formal arguments (other than those preceded by a "field" keyword), before being evaluated to give the return value for the function. The type of the return value is that of the last expression.

Examples Define a function to replace zeros in the result of one expression (of any type) with the result of another expression:

function replaceZeros(expr1, expr2)

{

if expr1 = 0 then expr2 else expr1

}

A function which takes a string argument and returns it with the first letter capitalized:

function titleCase(string text)

{

concat(toupper(left(text, 1)), right(text, strlen(text) - 1));

}

Note:
  • When specifying the type of a function argument, use "real", "integer", "string" or "date."
  • You can include field statistics in a function definition, but each function argument that is used in a field statistic must be preceded by a "field" keyword. For example, to compare a value with a summary over the whole focus:

    function MyBand(real field x)

    {

    averageX := mean(x);

    stdevX := stdev(x);

    case

    x < averageX - stdevX : "Lower";

    x > averageX + stdevX : "Upper";

    default: "Mid";

    }

  • You can include function definitions at the beginning of the expression list that defines a derived field. Functions so defined are local to the field derivation.

    You can also define globally accessible functions by storing them in a file (or files) in a folder listed in the derivation libraries preference [see derivation libraries] . In Decision Studio, in the Function Family pane of the Derivation Functions dialog box in the Table Viewer, functions in a file named class.fdl appear in the class named class. For example, functions in a file named Conditional.fdl appear in the Conditional class. You can reuse an existing class name, to augment a class with your own user-defined functions, or create your own class by using a new name.

    When using the Portrait Miner data-build command qsmeasure, the equivalent Aggregate Records window, or the data-build command qstrack, you can specify a file containing additional global function definitions.

  • You cannot define aggregation functions in a measurement context, that is, \funccontextmeasure.
  • If the expression list ends with an alphabetic character, it must be separated from the closing brace by a semicolon or whitespace.
Parent topic: Field Derivation Language (FDL) reference

Function attributes

Specify function attributes as follows:

Useful attributes are:

synopsis and description. These attributes provide a standard way of making the function "self-documenting." If a function is installed in a folder listed in the derivation libraries preference [see derivation libraries] , the synopsis is shown when you highlight the function in the Functions pane of the Derivation Functions dialog box in the Table Viewer. When you click on the Details button, the description is shown. The synopsis text should be short, but the description text can be longer.

For example:

function nvl(testNull, replaceValue)

[

synopsis = "Replace null values"

description = "The nvl() function replaces null values...strings."

]

(Note that the description attribute must all be on the same line.)

element_names. In an aggregations file, you can use a function with the element_names attribute to split an aggregation to create multiple fields [see Splitting aggregations: the by clause].

The value of this attribute is a string containing a comma-separated list of names, which are associated with function return values 1, 2, ..., in the order that they are listed.

For example, the element_names attribute of the following function associates the names "Low", "Medium" and "High" with return values 1, 2, and 3 respectively:

function band(x)

[ element_names = "Low,Medium,High" ]

{

clamp(floor(x / 1000), 0, 2) + 1

}

The element_names attribute of the following function associates the names "North", "South", "East" and "West" with return values 1, 2, 3 and 4 respectively:

function StoreGroupFunction( Store )

[

element_names = "North, South, East, West"

]

{

case

Store = "0000" or Store = "0800" : 1;

Store = "0300" or Store = "0600" or Store = "0700" : 2;

Store = "0100" or Store = "0400" : 3;

default : 4;

}


Built-in functions

FDL includes a comprehensive set of built-in functions.

Conditional functions

Function | Description
clamp | Constrain a number to lie within a given interval.
cond | Produce one of two results depending on whether an expression is zero or non-zero.
iff | Produce one of two results depending on whether an expression is zero or non-zero.
ifnull, nvl | Replace the null value.
isnull | Test whether a value is null.
isselected | Flag the records that are currently selected.
replace | Replace a number if it does not lie within a given interval.

Datatype-conversion functions

Function | Purpose
todate | Convert a value to a date.
tointeger | Convert a value to an integer.
toreal | Convert a value to a real number.
tostring | Convert a value to a string.

Functions for working with dates

Function | Purpose
addcenturies, addcenturiescountbackwards | Calculate a date from another date using an offset in centuries.
adddays | Calculate a date from another date using an offset in days.
addhours | Calculate a date from another date using an offset in hours.
addminutes | Calculate a date from another date using an offset in minutes.
addmonths, addmonthscountbackwards | Calculate a date from another date using an offset in months.
addseconds | Calculate a date from another date using an offset in seconds.
addweeks | Calculate a date from another date using an offset in weeks.
addyears, addyearscountbackwards | Calculate a date from another date using an offset in years.
countcenturies | Calculate the period between two dates in centuries.
countdays | Calculate the period between two dates in days.
counthours | Calculate the period between two dates in hours.
countminutes | Calculate the period between two dates in minutes.
countseconds | Count the number of seconds between two dates.
countweeks | Calculate the period between two dates in weeks.
countwholecenturies, countwholecenturiesbackwards | Count the number of complete centuries between two dates.
countwholedays | Count the number of complete days between two dates.
countwholehours | Count the number of complete hours between two dates.
countwholeminutes | Count the number of complete minutes between two dates.
countwholemonths, countwholemonthsbackwards | Count the number of complete months between two dates.
countwholeseconds | Count the number of seconds between two dates.
countwholeweeks | Count the number of complete weeks between two dates.
countwholeyears, countwholeyearsbackwards | Count the number of complete years between two dates.
countyears | Calculate the period between two dates in years.
day | Obtain the day-of-month part of a date.
dayofweek | Obtain a number representing the day-of-week of a date.
gmt2edt | Convert a Greenwich Mean Time (GMT) date to Eastern Daylight Time (EDT).
hour | Obtain the hours part of a date.
minute | Obtain the minutes part of a date.
month | Obtain the month part of a date.
now | Obtain the current date and time.
second | Obtain the seconds part of a date.
today | Obtain the current date.
weekofyear | Calculate the week-of-year of a date, relative to a specified start date.
year | Obtain the year part of a date.

Functions for working with strings

Function | Purpose
concat | Concatenate two or more strings.
endswith | Test whether one string ends with another.
find | Test whether one string is contained within another.
left | Return a substring of specified length from the beginning of a string.
mid | Return a substring of specified length from the middle of a string.
right | Return a substring of specified length from the end of a string.
soundex | Reduce each word to a four-character string for indexing purposes.
startswith | Test whether one string starts with another.
strlen | Obtain the length of a string.
strmember | Determine set membership.
substitute | Replace one string with another.
substr | Obtain a substring from a string.
tolower | Convert a string to lowercase text.
toupper | Convert a string to uppercase text.
trim | Remove all spaces from a string except for single spaces between words.

Regular expressions and associated functions

Function | Purpose
match | Test a string for a regular expression match [see Regular expressions].
replaceall | Replace all substrings that match a regular expression [see Regular expressions].
replacefirst | Replace the first substring that matches a regular expression [see Regular expressions].

Mathematical and statistical functions

Type | Description
abs | Calculate the absolute value of a number.
ceil | Round a number up to the nearest integer.
cos | Calculate the cosine of an angle.
exp | Calculate the exponential of a number.
floor | Round a number down to the nearest integer.
log | Calculate the natural (base-e) logarithm of a number.
log10 | Calculate the base-10 logarithm of a number.
logbase | Calculate the logarithm of a number, to a specified base.
max (two or more arguments), maxnonnull | Calculate the maximum of two or more numbers, or the latest of two or more dates, or the alphabetically latest of two or more strings.
mean (two or more arguments), meannonnull | Calculate the mean (common average) of two or more numbers.
min (two or more arguments), minnonnull | Calculate the minimum of two or more numbers, or the earliest of two or more dates, or the alphabetically earliest of two or more strings.
normalize | Normalize field values to lie in the interval [0,1].
pow | Calculate the result of raising one number to the power of another number.
product, productnonnull | Calculate the product of two or more numbers.
round | Round a number to the nearest integer.
sgn | Calculate the signum (sign) of a number.
sin | Calculate the sine of an angle.
sqrt | Calculate the square root of a number.
sum (two or more arguments), sumnonnull | Calculate the sum of two or more numbers.
tan | Calculate the tangent of an angle.

Data-sampling functions

Function | Purpose
numericTestTrainSplit | Create a test/training segmentation for use in model validation.
numericTestTrainValidateSplit | Create a test/training/validation segmentation for use in model validation.
sampleEqualSize | Create, at random, a segmentation index for groups of equal size.
sampleExactNumber | Flag, at random, an exact number of customers from a selected population.
sampleExactPercentage | Flag, at random, an exact percentage of customers from a selected population.
sampleStratified | Flag, at random, a specified number of customers from a segment and the rest of the population.
testTrainSplit | Create a test/training segmentation for use in model validation.
testTrainValidateSplit | Create a test/training/validation segmentation for use in model validation.

Random-number functions

Function | Purpose
rndBinomial | Generate a random integer based on a binomial distribution.
rndBool | Generate either 0 or 1 randomly (with equal probability).
rndExp | Generate a random positive number based on an exponential distribution.
rndGamma | Generate a random positive number based on a gamma distribution.
rndNormal | Generate a random number based on a normal distribution.
rndPoisson | Generate a random non-negative integer based on a discrete Poisson distribution.
rndUniform | Generate a random number between 0 and 1 based on a uniform distribution.

Return-on-investment functions

Function | Purpose
ActionROI | Estimate the (money) per-customer return on investment contribution from taking action designed to generate a definite response.
ActionROIAnnualized | Estimate the annualized per-customer return on investment multiple from taking action designed to generate a definite response from a customer.
OfferROI | Estimate the per-customer return on investment contribution from making an offer designed to generate a definite response.
OfferROIAnnualized | Estimate the annualized per-customer return on investment multiple from making an offer designed to generate a definite response from a customer.
RetentionActionROI | Estimate the per-customer (money) return on investment contribution from taking action designed to prevent attrition.
RetentionActionROIAnnualized | Estimate the annualized per-customer return on investment contribution from taking action designed to prevent attrition.
RetentionOfferROI | Estimate the per-customer return on investment from making an offer designed to prevent attrition.
RetentionOfferROIAnnualized | Estimate the annualized per-customer return on investment from making an offer designed to prevent attrition.

Miscellaneous functions

Function | Purpose
dblookup | Look up values in a reference table (stored as a focus).
member | Determine set membership.
rankOrder, rankOrderApprox | Identify the rank of a value within a list of values.
rankOrderMean, rankOrderApproxMean | Identify the rank of a value within a list of values.
rownum | Generate the number of each row in the table.

Binnings

Function | Purpose
bin | Obtain a bin index corresponding to a value.

See also

User-defined functions
Parent topic: Field Derivation Language (FDL) reference


Reserved words in FDL

The following tokens are reserved words in \fdl: accum, agg, aggregate, aggregation, and, by, case, date, default, div, double, else, eq, false, field, float, function, global, if, int, integer, long, mod, not, null, number, numeric, or, real, short, state, string, then, true, where, and while

To use a reserved word, or a word that differs only in case from a reserved word, as an identifier [see Expressions] in FDL, or as a field or statistic name in TML, you must enclose it in single quotation marks — for example, 'State'.

Note: Although identifiers in FDL are case-significant (fred and Fred are distinct), the reserved words are not case-significant and are therefore reserved in any case combination: for example, if, If, iF, and IF are all representations of the same token; all such combinations are reserved and may not be used as identifiers.

See also

About Field Derivation Language

Reserved words in TML

Parent topic: Field Derivation Language (FDL) reference


FDL operators

  • Arithmetic operators
  • Relational operators
  • Logical operators
  • Operator precedence
Parent topic: Field Derivation Language (FDL) reference


Arithmetic operators

Except for unary minus, which prefixes its single operand, all FDL arithmetic operators are infix binary operators, that is, they are written between their two operands.

Operator | Operands | Result
+ (addition) | numeric | The sum of the operands
- (subtraction) | numeric | The result of subtracting the second operand from the first
- (unary minus) | numeric | The negative of the operand
* (multiplication) | numeric | The product of the operands
/ (division) | numeric | The (real) result of dividing the first operand by the second
div (integer division) | integer | The (integer) result of dividing the first operand by the second, ignoring any remainder
mod (modulo) | integer | The remainder on integer-dividing the first operand by the second (the modulus), with the same sign as the first operand — for example, 9 % 7 returns 2 but -9 % 7 returns -2

Examples 2 + 5 equals 7.

2 - 5 equals -3.

- (2 + 5) equals -7.

2 * 5 equals 10.

2 / 5 equals 0.4.

2 div 5 equals 0.

2 mod 5 equals 2.

5 % 2 equals 1.

Note:
  • The addition, subtraction, unary minus, and multiplication operators preserve the type of their operands (which are type-compatible [see Type-compatibility]). If one operand is an integer and the other is a real number, the result is real.
  • If the second operand of the division, integer-division, or modulo operator is zero, the result is null [see The null value], as division by zero is undefined.
  • mod requires integer operands.
  • You can also use % instead of mod.

See also

Logical operators

Operator precedence

Relational operators

Parent topic: FDL operators


Relational operators

All FDL relational operators are infix binary operators, that is, they are written between their two operands.

Operator | Operands | Result
< (less than) | integer, real, date, or string | True if the first operand is less than the second; false if the first operand is greater than or equal to the second
<= (less than or equal to) | integer, real, date, or string | True if the first operand is less than or equal to the second; false if the first operand is greater than the second
> (greater than) | integer, real, date, or string | True if the first operand is greater than the second; false if the first operand is less than or equal to the second
>= (greater than or equal to) | integer, real, date, or string | True if the first operand is greater than or equal to the second; false if the first operand is less than the second
= (equality) | integer, real, date, or string | True if both operands have the same value; false if the operands have distinct values. For string types, the comparison ignores trailing space characters in both operands.
!= (inequality) | integer, real, date, or string | True if the operands have distinct values; false if both operands have the same value. For string types, the comparison ignores trailing space characters in both operands.

Examples 2 < 5 equals 1 (TRUE).

5 < 5 equals 0 (FALSE).

"A" < "B" equals 1 (TRUE).

5 <= 5 equals 1 (TRUE).

5 > 5 equals 0 (FALSE).

7 > 5 equals 1 (TRUE).

#2003/12/31 > #2003/11/30 equals 1 (TRUE).

5 >= 5 equals 1 (TRUE).

"A" = "A" equals 1 (TRUE).

"A" = "a" equals 0 (FALSE).

"A" != "A" equals 0 (FALSE).

"A" != "a" equals 1 (TRUE).

Note:
  • The operands of a binary relational operator must be type-compatible [see Type-compatibility].
  • When comparing dates, "less than" means earlier. When comparing strings, "less than" means earlier in the alphabet (or more specifically, earlier in the underlying character representation). Likewise for "greater than" etc.
  • You can also use == or eq instead of = and <> instead of !=.

See also

Arithmetic operators

Boolean data

Logical operators

Parent topic: FDL operators


Logical operators

The logical negation operator prefixes its single operand, while the logical conjunction and disjunction operators are infix binary operators, that is, they are written between their two operands.
Operator | Operands | Result
and (logical conjunction) | boolean | True if both operands are true; false if either operand is false
or (logical disjunction) | boolean | True if either operand is true; false if both operands are false
not (logical negation) | boolean | True if the operand is false; false if the operand is true

Examples ("A" = "A") and (5 = 5) equals 1 (TRUE).

("A" = "B") and (5 = 5) equals 0 (FALSE).

("A" = "B") and (5 = 2) equals 0 (FALSE).

("A" = "A") or (5 = 5) equals 1 (TRUE).

("A" = "B") || (5 = 5) equals 1 (TRUE).

("A" = "B") or (5 = 2) equals 0 (FALSE).

not ("A" = "A") equals 0 (FALSE).

!(("A" = "B") or (5 = 2)) equals 1 (TRUE).

Note:
  • There is currently no boolean [see Boolean data] datatype in FDL, so the operands for logical operators are actually integers. You should not, however, apply these operators to arbitrary integers.
  • You can also use and instead of and, || instead of or, and ! instead of not.

See also

Arithmetic operators

Operator precedence

Relational operators

Parent topic: FDL operators


Operator precedence

In the absence of parentheses, FDL operations in an expression are carried out in order of operator precedence, from highest to lowest:
Class | Operators
Unary minus | -
Multiplication-style operators | * / div mod
Addition-style operators | + -
Relational operators | < <= > >= != =
Logical negation | not
Binary logical operators | and or

If there is a tie for precedence, operations are carried out from left to right.

Subexpressions in parentheses are always evaluated first.

Examples -5 + 12 / 4 * 2 + 20 * 3 equals 61.

that is, the expression is evaluated as: -5 + ((12 / 4) * 2) + (20 * 3)

Moving the parentheses:

-(5 + 12 / (4 * 2) + 20) * 3 equals -79.5.

See also

Arithmetic operators

Logical operators

Relational operators

Parent topic: FDL operators


FDL functions

  • Aggregation functions (multi-argument)
  • Conditional functions
  • Datatype-conversion functions
  • Functions for working with dates
  • Mathematical and statistical functions
  • Other functions
  • Return-on-investment functions
  • Random-number functions
  • Rank functions
  • Data-sampling functions
  • Functions for working with strings
Parent topic: Field Derivation Language (FDL) reference


Aggregation functions (multi-argument)

  • max (two or more arguments), maxnonnull
  • mean (two or more arguments), meannonnull
  • min (two or more arguments), minnonnull
  • product, productnonnull
  • sum (two or more arguments), sumnonnull
Parent topic: FDL functions


max (two or more arguments), maxnonnull

Purpose Calculate the maximum of two or more numbers, or the latest of two or more dates, or the alphabetically latest of two or more strings. The max variant returns the null value if any of its arguments is null; the maxnonnull variant ignores null arguments (but still returns the null value if all of its arguments are null).

Syntax

max( [image], [image], ...)

maxnonnull( [image], [image], ...)

Arguments

Type | Name | Description
integer, real, date, or string (all the same type) | , [image] , ... | The values to be compared

Result

Type | Description
as input | The maximum of [image] , [image] , ...
Note:
  • Be careful not to confuse this multi-argument max function with the aggregation function [see max (one argument)] of the same name.
  • For strings, "alphabetically latest" means "latest in the underlying character representation."

Examples max(5.5, -3, 7, -8.5) equals 7.

max(5.5, -3, null, -8.5) equals null.

maxnonnull(5.5, -3, 7, -8.5) equals 7.

maxnonnull(5.5, -3, null, -8.5) equals 5.5.

To determine the next best action for a customer based on different ROI measures:

maxvalue := max (ROI1, ROI2, ROI3);

case

maxvalue = ROI1: "Product1";

maxvalue = ROI2: "Product2";

maxvalue = ROI3: "Product3";

Parent topic: Aggregation functions (multi-argument)


mean (two or more arguments), meannonnull

Purpose Calculate the mean (common average) of two or more numbers. The mean variant returns the null value if any of its arguments is null; the meannonnull variant ignores null arguments (but still returns the null value if all of its arguments are null).

Syntax

mean( [image], [image], ...)

meannonnull( [image], [image], ...)

Arguments

Type | Name | Description
numeric | , [image] , ... | The numbers to average

Result

Type | Description
real | The mean of [image] , [image] , ...
Note:

Be careful not to confuse this multi-argument mean function with the aggregation function [see mean (one argument)] of the same name.

Examples mean(5.5, -3, 7, -8.5) equals 0.25.

mean(5.5, -3, null, -8.5) equals null.

meannonnull(5.5, -3, 7, -8.5) equals 0.25.

meannonnull(5.5, -3, null, -8.5) equals -2.

To calculate the average yearly spend from four separate quarter spend fields:

mean(SpendQtr1, SpendQtr2, SpendQtr3, SpendQtr4)

Parent topic: Aggregation functions (multi-argument)


min (two or more arguments), minnonnull

Purpose Calculate the minimum of two or more numbers, or the earliest of two or more dates, or the alphabetically earliest of two or more strings. The min variant returns the null value if any of its arguments is null; the minnonnull variant ignores null arguments (but still returns the null value if all of its arguments are null).

Syntax

min( [image], [image], ...)

minnonnull( [image], [image], ...)

Arguments

Type | Name | Description
integer, real, date, or string (all the same type) | , [image] , ... | The values to be compared

Result

Type | Description
as input | The minimum of [image] , [image] , ...
Note:
  • Be careful not to confuse this multi-argument min function with the aggregation function [see min (one argument)] of the same name.
  • For strings, "alphabetically earliest" means "earliest in the underlying character representation."

Examples min(5.5, -3, 7, -8.5) equals -8.5.

min(5.5, -3, null, -8.5) equals null.

minnonnull(5.5, -3, 7, -8.5) equals -8.5.

minnonnull(5.5, -3, null, -8.5) equals -8.5.

Parent topic: Aggregation functions (multi-argument)


product, productnonnull

Purpose Calculate the product of two or more numbers. The product variant returns the null value if any of its arguments is null; the productnonnull variant ignores null arguments (but still returns the null value if all of its arguments are null).

Syntax

product( [image], [image], ...)

productnonnull( [image], [image], ...)

Arguments

Type | Name | Description
numeric | , [image] , ... | The numbers to be multiplied

Result

Type | Description
as input | The product of [image] , [image] , ...

Examples product(5.5, -3, 7, -8.5) equals 981.75.

product(5.5, -3, null, -8.5) equals null.

productnonnull(5.5, -3, 7, -8.5) equals 981.75.

productnonnull(5.5, -3, null, -8.5) equals 140.25.

Parent topic: Aggregation functions (multi-argument)


sum (two or more arguments), sumnonnull

Purpose Calculate the sum of two or more numbers. The sum variant returns the null value if any of its arguments is null; the sumnonnull variant ignores null arguments (but still returns the null value if all of its arguments are null).

Syntax

sum( [image], [image], ...)

sumnonnull( [image], [image], ...)

Arguments

Type | Name | Description
numeric | , [image] , ... | The numbers to be added

Result

Type | Description
as input | The sum of [image] , [image] , ...
Note:

Be careful not to confuse this multi-argument sum function with the aggregation function [see sum (one argument)] of the same name.

Examples sum(5.5, -3, 7, -8.5) equals 1.

sum(5.5, -3, null, -8.5) equals null.

sumnonnull(5.5, -3, 7, -8.5) equals 1.

sumnonnull(5.5, -3, null, -8.5) equals -6.

To derive the total spend from six weekly spend fields:

sum(SpendWk1, SpendWk2, SpendWk3, SpendWk4, SpendWk5, SpendWk6)

Parent topic: Aggregation functions (multi-argument)


Conditional functions

  • clamp
  • cond
  • iff
  • ifnull, nvl
  • isnull
  • isselected
  • replace
Parent topic: FDL functions


clamp

Purpose Constrain a number to lie within a given interval.

Syntax clamp(x, min, max)

Arguments

Type | Name | Description
numeric | x | The number to be clamped
as x | min | The lower bound of the interval
as x | max | The upper bound of the interval

Result

Type | Description
as input | x if [image] ; min if x < min; max if x > max

Examples To clamp values within a range from 18 to 65 inclusive, replacing values outside the range with the appropriate range boundaries:

CustomerAge | clamp(CustomerAge,18,65)
9 | 18
18 | 18
66 | 65
43 | 43

See also

replace
Parent topic: Conditional functions


cond

Purpose Produce one of two results depending on whether an expression is zero or non-zero.

Syntax cond(cond, trueExpr, falseExpr)

Arguments

Type | Name | Description
integer | cond | The expression to test
integer, real, date, or string | trueExpr | "True" (non-zero) branch
as trueExpr | falseExpr | "False" (zero) branch

Result

Type | Description
as trueExpr, falseExpr | trueExpr if cond [image] 0; falseExpr if cond = 0
Note:

Unlike an if expression [see The if expression] or case expression [see The case expression], both branches are evaluated by the cond function.

More significantly, cond preserves the uncertainty of a null value [see The null value] in the condition.

If you don't need this behavior, use an if or case expression for speed.

Examples To target customers with a zero spend in Quarter 2 for a mailing campaign:

SpendQtr2 | cond(SpendQtr2, "Don't Mail", "Mail")
100.39 | Don't Mail
0 | Mail
-5.72 | Mail
null | null

See also

clamp

iff

ifnull, nvl

replace

Parent topic: Conditional functions


iff

Purpose Produce one of two results depending on whether an expression is zero or non-zero.

Syntax iff(logical_text, value_if_true, value_if_false)

Arguments

Type | Name | Description
real | logical_text | The expression to test
integer, real, date, or string | value_if_true | "True" (non-zero) branch
as value_if_true | value_if_false | "False" (zero or null) branch

Result

Type | Description
as value_if_true, value_if_false | value_if_true if logical_text [image] 0; value_if_false if logical_text = 0 or logical_text is null

Examples iff(Score > 650, "Mail", "No Mail")

See also

cond
Parent topic: Conditional functions


ifnull, nvl

Purpose Replace the null value. You can use nvl as an alias for ifnull.

Syntax ifnull(testNull, replaceValue)

nvl(testNull, replaceValue)

Arguments

Type | Name | Description
integer, real, date, or string | testNull | The value to be tested
as testNull | replaceValue | The replacement for the null value

Result

Type | Description
as input | A copy of the value testNull with replaceValue replacing the null value

Examples To replace missing values with a value derived from another field:

SpendQtr1 | AnnualSpend | ifnull(SpendQtr1, AnnualSpend/4)
45.21 | 178.97 | 45.21
null | 150.56 | 37.64
null | 784.27 | 196.07
59.05 | 274.18 | 59.05

See also

cond

isnull

Parent topic: Conditional functions


isnull

Purpose Test whether a value is null.

Syntax isnull(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | The value to be tested

Result

Type | Description
integer | 1 if x is null; 0 otherwise

Examples To replace null value entries in a field with that field's mean value:

Age | if isnull(Age) then mean(Age) else Age
32 | 32
null | 44
59 | 59
27 | 27

See also

Splitting aggregations: the by clause
Parent topic: Conditional functions


isselected

Purpose Flag the records that are currently selected.

Syntax isselected()

Arguments None

Result

Type | Description
integer | 1 if the record is currently selected, otherwise 0
Note:

The Table Viewer has special support for immediate expansion [see Assisted function entry in the Table Viewer] of this function.

Examples if isselected() then "LowRisk" else "HighRisk"

Parent topic: Conditional functions


replace

Purpose Replace a number if it does not lie within a given interval.

Syntax replace(x, min, max, y)

Arguments

Type | Name | Description
numeric | x | The number to be tested
as x | min | The lower bound of the interval
as x | max | The upper bound of the interval
as x | y | The replacement value

Result

Type | Description
as input | x if [image] ; y otherwise

Examples To clamp values within a range from 18 to 65 inclusive, replacing values outside the range with the mean value:

CustomerAge | replace (CustomerAge, 18, 65, mean(CustomerAge))
9 | 38
18 | 18
66 | 38
43 | 43

See also

clamp
Parent topic: Conditional functions


Datatype-conversion functions

  • todate
  • tointeger
  • toreal
  • tostring
Parent topic: FDL functions


todate

Purpose Convert a value to a date.

Syntax todate(x [, format] )

Arguments

Type | Name | Description
integer, real, date, or string | x | A value to convert
string | format | A date format [see Date formats] to use for the conversion (optional and only allowed if x is of string type)

Result

Type | Description
date | x, as a date
Note:
  • If the argument is of integer type, it is assumed to represent the date as YYYYMMDD.
  • If the argument is of real type, it is assumed to represent the date as YYYYMMDD.HHMMSS.
  • If the argument is of string type, and no date format argument is provided, the string is converted according to the setting of your read preference [see read].

Examples (Date values shown with European date format.)

todate(20040109) equals 09/01/2004:00:00:00.

todate(20040109.122853) equals 09/01/2004:12:08:52.

todate("09/01/2004") equals 09/01/2004:00:00:00.

todate("09-Jan-2004","%d-%b-%Y") equals 09/01/2004:00:00:00.

todate(#09/01/2004:12:28:53) equals 09/01/2004:12:28:53.

See also

tointeger

toreal

tostring

Type conversion

Parent topic: Datatype-conversion functions


tointeger

Purpose Convert a value to an integer.

Syntax tointeger(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | A value to convert

Result

Type | Description
integer | x, as an integer
Note:
  • If the argument is of real type, digits after the decimal point are ignored.
  • If the argument is of date type, the result is of the form YYYYMMDD (the time component is ignored).
  • If the argument is of string type, any trailing non-numeric characters are ignored.

Examples tointeger(100) equals 100.

tointeger(100.65) equals 100.

tointeger("100.65") equals 100.

tointeger(#09/01/2004:12:28:53) equals 20040109.

See also

todate

toreal

tostring

Type conversion

Parent topic: Datatype-conversion functions


toreal

Purpose Convert a value to a real number.

Syntax toreal(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | A value to convert

Result

Type | Description
real | x, as a real number
Note:
  • If the argument is of date type, the result is of the form YYYYMMDD.HHMMSS.
  • If the argument is of string type, any trailing non-numeric characters are ignored.

Examples toreal(100) equals 100.0.

toreal(100.65) equals 100.65.

toreal("100.65") equals 100.65.

toreal(#09/01/2004:12:28:53) equals 20040109.122853.

See also

todate

tointeger

tostring

Type conversion

Parent topic: Datatype-conversion functions


tostring

Purpose Convert a value to a string.

Syntax tostring(x)

Arguments

Type | Name | Description
integer, real, date, or string | x | A value to convert

Result

Type | Description
string | x, as a string
Note:
  • If the argument is of real type, the result is in ordinary decimal (not scientific) format.
  • If the argument is of date type, the result is formatted according to the setting of your date write preference [see date write].

Examples tostring(100) equals "100".

tostring(1.0065e2) equals "100.650000".

tostring("100.65") equals "100.65".

tostring(#09/01/2004:12:28:53) equals "09/01/2004:12:28:53".

See also

todate

tointeger

toreal

Type conversion

Parent topic: Datatype-conversion functions


Functions for working with dates

  • addcenturies, addcenturiescountbackwards
  • adddays
  • addhours
  • addminutes
  • addmonths, addmonthscountbackwards
  • addseconds
  • addweeks
  • addyears, addyearscountbackwards
  • countcenturies
  • countdays
  • counthours
  • countminutes
  • countseconds
  • countweeks
  • countwholecenturies, countwholecenturiesbackwards
  • countwholedays
  • countwholehours
  • countwholeminutes
  • countwholemonths, countwholemonthsbackwards
  • countwholeseconds
  • countwholeweeks
  • countwholeyears, countwholeyearsbackwards
  • countyears
  • day
  • dayofweek
  • gmt2edt
  • hour
  • minute
  • month
  • now
  • second
  • today
  • weekofyear
  • year
Parent topic: FDL functions


addcenturies, addcenturiescountbackwards

Purpose Calculate a date from another date using an offset in centuries.

Syntax addcenturies(date, n)

addcenturiescountbackwards(date, n)

Arguments

Type | Name | Description
date | date | The starting date
integer | n | The number of centuries to add (which can be negative)

Result

Type | Description
date | The date n calendar centuries after the date date (interpreted as |n| centuries before date if n < 0). The time part of the result is the same as the time part of date. See addmonths, addmonthscountbackwards for an explanation of the two variants.
Note:

The result of adding n centuries using the addcenturies (respectively addcenturiescountbackwards) function is defined to be the result of adding 1200n months with the addmonths (respectively addmonthscountbackwards) function.

Examples To calculate a date one century later than d, showing the difference between the addcenturies and addcenturiescountbackwards variants (YMD date format):

d | addcenturies(d,1) | addcenturiescountbackwards(d,1)
1900/02/14 | 2000/02/14 | 2000/02/15
See also

countcenturies

countwholecenturies, countwholecenturiesbackwards

Date formats

Parent topic: Functions for working with dates


adddays

Purpose Calculate a date from another date using an offset in days.

Syntax adddays(date, n)

Arguments

Type | Name | Description
date | date | The starting date
integer | n | The number of days to add (which can be negative)

Result

Type | Description
date | The date n days after the date date (interpreted as |n| days before date if n < 0). The time part of the result is the same as the time part of date.

Examples European date format: adddays(#09/01/2004, 25) equals 03/02/2004.

European date format: adddays(#09/01/2004:11:43:46, 25) equals 03/02/2004:11:43:46.

American date format: adddays(#01/09/2004, 25) equals 02/03/2004.

American date format: adddays(#01/09/2004:11:43:46, 25) equals 02/03/2004:11:43:46.

YMD date format: adddays(#2004/01/09, 25) equals 2004/02/03.

YMD date format: adddays(#2004/01/09:11:43:46, 25) equals 2004/02/03:11:43:46.

See also

countdays

countwholedays

Date formats

Parent topic: Functions for working with dates


addhours

Purpose Calculate a date from another date using an offset in hours.

Syntax addhours(date, n)

Arguments

Type | Name | Description
date | date | The starting date
integer | n | The number of hours to add (which can be negative)

Result

Type | Description
date | The date n hours after the date date (interpreted as |n| hours before date if n < 0)
Note:

All dates in FDL include a time component.

Examples European date format: addhours(#09/01/2004:12:28:53, 25) equals 10/01/2004:13:28:53.

American date format: addhours(#01/09/2004:12:28:53, 25) equals 01/10/2004:13:28:53.

YMD date format: addhours(#2004/01/09:12:28:53, 25) equals 2004/01/10:13:28:53.

See also

counthours

countwholehours

Date formats

Parent topic: Functions for working with dates


addminutes

Purpose Calculate a date from another date using an offset in minutes.

Syntax addminutes(date, n)

Arguments

Type | Name | Description
date | date | The starting date
integer | n | The number of minutes to add (which can be negative)

Result

Type | Description
date | The date n minutes after the date date (interpreted as |n| minutes before date if n < 0)
Note:

All dates in FDL include a time component.

Examples European date format: addminutes(#09/01/2004:12:28:53, 25) equals 09/01/2004:12:53:53.

American date format: addminutes(#01/09/2004:12:28:53, 25) equals 01/09/2004:12:53:53.

YMD date format: addminutes(#2004/01/09:12:28:53, 25) equals 2004/01/09:12:53:53.

See also

countminutes

countwholeminutes

Date formats

Parent topic: Functions for working with dates


addmonths, addmonthscountbackwards

Purpose Calculate a date from another date using an offset in months.

Syntax addmonths(date, n)

addmonthscountbackwards(date, n)

Arguments

Type | Name | Description
date | date | The starting date
integer | n | The number of months to add (which can be negative)
Result
Type Description
date The date n calendar months after the date date (interpreted as |n| months before date if n < 0).

The month and year parts of the result are determined by the offset n.

Then the day of month of the result is set to be the same as it is in the date date (for addmonths) or the same number of days from the end of the month as it is in the date date (for addmonthscountbackwards).

If the day of month would end up being before the beginning or after the end of the month (because the result month is a shorter month than the month containing date), it is clamped to the first or last day of the month as appropriate.

The time part of the result is the same as the time part of date.

Note:
  • If you add n months using addmonths (or addmonthscountbackwards), you won't necessarily get the same result as you would get by adding one month n times, as the day of month might be constrained by an intermediate short month in the latter case.
  • The results of adding to a date with addmonths and addmonthscountbackwards may differ if the month part of the date and the month part of the result contain different numbers of days.

Examples To calculate a date one month later than d, showing the propagation of time parts (YMD date format):

d | addmonths(d,1)
2007/08/14:00:00:00 | 2007/09/14:00:00:00
2007/08/14:12:34:56 | 2007/09/14:12:34:56

To calculate a date one month later than d, showing the difference between the addmonths and addmonthscountbackwards variants (YMD date format):

d | addmonths(d,1) | addmonthscountbackwards(d,1)
2007/08/14 | 2007/09/14 | 2007/09/13

To calculate a date one month later than d, showing the clamping behavior of addmonths at the end of a month (YMD date format):

d | addmonths(d,1)
2007/08/31 | 2007/09/30

To calculate a date one month later than d, showing the clamping behavior of addmonthscountbackwards at the start of the month (YMD date format):

d | addmonthscountbackwards(d,1)
2007/08/02 | 2007/09/01
2007/08/01 | 2007/09/01

To calculate the six-month anniversary of each customer's acquisition, using the customer acquisition date field StartDate:

addmonths(StartDate, 6)

See also

countwholemonths, countwholemonthsbackwards

Date formats

Parent topic: Functions for working with dates


addseconds

Purpose Calculate a date from another date using an offset in seconds.

Syntax addseconds(date, n)

Arguments

Type | Name | Description
date | date | The starting date
integer | n | The number of seconds to add (which can be negative)

Result

Type | Description
date | The date n seconds after the date date (interpreted as |n| seconds before date if n < 0)
Note:

All dates in FDL include a time component.

Examples European date format: addseconds(#09/01/2004:12:28:53, 25) equals 09/01/2004:12:54:18.

American date format: addseconds(#01/09/2004:12:28:53, 25) equals 01/09/2004:12:54:18.

YMD date format: addseconds(#2004/01/09:12:28:53, 25) equals 2004/01/09:12:54:18.

See also

countseconds

countwholeseconds

Date formats

Parent topic: Functions for working with dates


addweeks

Purpose Calculate a date from another date using an offset in weeks.

Syntax addweeks(date, n)

Arguments

Type | Name | Description
date | date | The starting date
integer | n | The number of weeks to add (which can be negative)

Result

Type | Description
date | The date n weeks after the date date (interpreted as |n| weeks before date if n < 0). The time part of the result is the same as the time part of date.

Examples European date format: addweeks(#09/01/2004, 8) equals 05/03/2004.

American date format: addweeks(#01/09/2004, 8) equals 03/05/2004.

YMD date format: addweeks(#2004/01/09, 8) equals 2004/03/05.

See also

countweeks

countwholeweeks

Date formats

Parent topic: Functions for working with dates


addyears, addyearscountbackwards

Purpose Calculate a date from another date using an offset in years.

Syntax addyears(date, n)

addyearscountbackwards(date, n)

Arguments

Type | Name | Description
date | date | The starting date
integer | n | The number of years to add (which can be negative)

Result

Type | Description
date | The date n calendar years after the date date (interpreted as |n| years before date if n < 0). The time part of the result is the same as the time part of date. See addmonths, addmonthscountbackwards for an explanation of the two variants.
Note:

The result of adding n years using the addyears (respectively addyearscountbackwards) function is defined to be the result of adding 12n months with the addmonths (respectively addmonthscountbackwards) function.

Examples To calculate a date one year later than d, showing the difference between the addyears and addyearscountbackwards variants (YMD date format):

d | addyears(d,1) | addyearscountbackwards(d,1)
2007/02/14 | 2008/02/14 | 2008/02/15

To calculate the one-year anniversary of each customer's acquisition, using the customer acquisition date field StartDate:

addyears(StartDate, 1)

See also

countwholeyears, countwholeyearsbackwards

countyears

Date formats

Parent topic: Functions for working with dates


countcenturies

Purpose Calculate the period between two dates in centuries.

Syntax countcenturies(date1, date2)

Arguments

Type | Name | Description
date | date1 | the first date
date | date2 | the second date

Result

Type | Description
real | The period between date1 and date2 in centuries (a negative number if date1 is later than date2)
Note:
  • If the number is not an exact multiple of 100 years (taking time parts of dates into account), the result includes a fractional part.
  • The result of the countcenturies function is defined to be the result of the countyears function, divided by 100.

Examples European date format: countcenturies(#09/01/2004, #09/01/2054) equals 0.5.

American date format: countcenturies(#01/09/2004, #01/09/2054) equals 0.5.

YMD date format: countcenturies(#2004/01/09, #2054/01/09) equals 0.5.

See also

countwholecenturies, countwholecenturiesbackwards

Date formats

Parent topic: Functions for working with dates


countdays

Purpose Calculate the period between two dates in days.

Syntax countdays(date1, date2)

Arguments

Type | Name | Description
date | date1 | the first date
date | date2 | the second date

Result

Type | Description
real | The period between date1 and date2 in days (a negative number if date1 is later than date2)
Note:

If the time parts of the two dates differ, the result includes a fractional part.

Examples European date format: countdays(#09/01/2004, #03/02/2004) equals 25.

countdays(#09/01/2004:10:00:00, #03/02/2004:11:00:00) equals 25.04.

countdays(#09/01/2004:11:00:00, #03/02/2004:10:00:00) equals 24.96.

American date format: countdays(#01/09/2004, #02/03/2004) equals 25.

countdays(#01/09/2004:10:00:00, #02/03/2004:11:00:00) equals 25.04.

countdays(#01/09/2004:11:00:00, #02/03/2004:10:00:00) equals 24.96.

YMD date format: countdays(#2004/01/09, #2004/02/03) equals 25.

countdays(#2004/01/09:10:00:00, #2004/02/03:11:00:00) equals 25.04.

countdays(#2004/01/09:11:00:00, #2004/02/03:10:00:00) equals 24.96.

See also

adddays

countwholedays

Date formats

Parent topic: Functions for working with dates


counthours

Purpose Calculate the period between two dates in hours.

Syntax counthours(time1, time2)

Arguments

Type | Name | Description
date | time1 | the first date/time
date | time2 | the second date/time

Result

Type | Description
real | The period between time1 and time2 in hours (a negative number if time1 is later than time2)
Note:

If the minutes or seconds parts of the two dates differ, the result includes a fractional part.

Examples European date format: counthours(#09/01/2004:12:28:53, #10/01/2004:13:28:53) equals 25.

American date format: counthours(#01/09/2004:12:28:53, #01/10/2004:13:28:53) equals 25.

YMD date format: counthours(#2004/01/09:12:28:53, #2004/01/10:13:28:53) equals 25.

See also

countwholehours

Date formats

Parent topic: Functions for working with dates


countminutes

Purpose Calculate the period between two dates in minutes.

Syntax countminutes(time1, time2)

Arguments

Type | Name | Description
date | time1 | the first date/time
date | time2 | the second date/time

Result

Type | Description
real | The period between time1 and time2 in minutes (a negative number if time1 is later than time2)
Note:

If the seconds parts of the two dates differ, the result includes a fractional part.

Examples European date format: countminutes(#09/01/2004:12:28:53, #09/01/2004:12:53:53) equals 25.

American date format: countminutes(#01/09/2004:12:28:53, #01/09/2004:12:53:53) equals 25.

YMD date format: countminutes(#2004/01/09:12:28:53, #2004/01/09:12:53:53) equals 25.

See also

countwholeminutes

Date formats

Parent topic: Functions for working with dates


countseconds

Purpose Count the number of seconds between two dates.

Syntax countseconds(time1, time2)

Arguments

Type | Name | Description
date | time1 | the first date/time
date | time2 | the second date/time

Result

Type | Description
real | The number of seconds between time1 and time2 (a negative number if time1 is later than time2)
Note:

The only difference between this function and countwholeseconds is that the result of the latter is of type integer.

Examples European date format: countseconds(#09/01/2004:12:28:53, #09/01/2004:12:29:18) equals 25.

American date format: countseconds(#01/09/2004:12:28:53, #01/09/2004:12:29:18) equals 25.

YMD date format: countseconds(#2004/01/09:12:28:53, #2004/01/09:12:29:18) equals 25.

See also

Date formats
Parent topic: Functions for working with dates


countweeks

Purpose Calculate the period between two dates in weeks.

Syntax countweeks(date1, date2)

Arguments

Type | Name | Description
date | date1 | the first date
date | date2 | the second date

Result

Type | Description
real | The period between date1 and date2 in weeks (a negative number if date1 is later than date2)
Note:

If the period is not an exact multiple of seven days (taking time parts of dates into account), the result includes a fractional part.

Examples European date format: countweeks(#09/01/2004, #05/03/2004) equals 8.

American date format: countweeks(#01/09/2004, #03/05/2004) equals 8.

YMD date format: countweeks(#2004/01/09, #2004/03/05) equals 8.

See also

countwholeweeks

Date formats

Parent topic: Functions for working with dates


countwholecenturies, countwholecenturiesbackwards

Purpose Count the number of complete centuries between two dates.

Syntax countwholecenturies(date1, date2) countwholecenturiesbackwards(date1, date2)

Arguments

Type | Name | Description
date | date1 | the first date
date | date2 | the second date

Result

Type | Description
integer | The number of complete centuries elapsed between date1 and date2 (a negative number if date1 is later than date2). See countwholemonths, countwholemonthsbackwards for an explanation of the two variants.
Note:
  • The result of the countwholecenturies (respectively countwholecenturiesbackwards) function is defined as the result of the countwholemonths (respectively countwholemonthsbackwards) function divided by 1200, ignoring any remainder.
  • The results of comparing two dates with countwholecenturies and countwholecenturiesbackwards may differ, but only when both dates lie in February, one date lies in a year divisible by 400, and the other lies in a year divisible by 100 but not divisible by 400.

Examples To count the number of complete centuries between d1 and d2, showing the difference between the countwholecenturies and countwholecenturiesbackwards variants (YMD date format):

d1 | d2 | countwholecenturies(d1,d2) | countwholecenturiesbackwards(d1,d2)
1900/02/14 | 2000/02/13 | 0 | 0
1900/02/14 | 2000/02/14 | 1 | 0
1900/02/14 | 2000/02/15 | 1 | 1

See also

addcenturies, addcenturiescountbackwards

countcenturies

Date formats

Parent topic: Functions for working with dates


countwholedays

Purpose Count the number of complete days between two dates.

Syntax countwholedays(date1, date2)

Arguments

Type | Name | Description
date | date1 | the first date
date | date2 | the second date

Result

Type | Description
integer | The number of complete 24-hour periods elapsed between date1 and date2 (a negative number if date1 is later than date2)

Examples European date format: countdays(#09/01/2004, #03/02/2004) equals 25.

countdays(#09/01/2004:10:00:00, #03/02/2004:11:00:00) equals 25.

countdays(#09/01/2004:11:00:00, #03/02/2004:10:00:00) equals 24.

American date format: countdays(#01/09/2004, #02/03/2004) equals 25.

countdays(#01/09/2004:10:00:00, #02/03/2004:11:00:00) equals 25.

countdays(#01/09/2004:11:00:00, #02/03/2004:10:00:00) equals 24.

YMD date format: countdays(#2004/01/09, #2004/02/03) equals 25.

countdays(#2004/01/09:10:00:00, #2004/02/03:11:00:00) equals 25.

countdays(#2004/01/09:11:00:00, #2004/02/03:10:00:00) equals 24.

See also

adddays

countdays

Date formats

Parent topic: Functions for working with dates


countwholehours

Purpose Count the number of complete hours between two dates.

Syntax countwholehours(time1, time2)

Arguments

Type | Name | Description
date | time1 | the first date/time
date | time2 | the second date/time

Result

Type | Description
integer | The number of complete hours elapsed between time1 and time2 (a negative number if time1 is later than time2)

Examples European date format: countwholehours(#09/01/2004:12:28:53, #10/01/2004:13:28:53) equals 24.

American date format: countwholehours(#01/09/2004:12:28:53, #01/10/2004:13:28:53) equals 24.

YMD date format: countwholehours(#2004/01/09:12:28:53, #2004/01/10:13:28:53) equals 24.

See also

counthours

Date formats

Parent topic: Functions for working with dates


countwholeminutes

Purpose Count the number of complete minutes between two dates.

Syntax countwholeminutes(time1, time2)

Arguments

Type | Name | Description
date | time1 | the first date/time
date | time2 | the second date/time

Result

Type | Description
integer | The number of complete minutes elapsed between time1 and time2 (a negative number if time1 is later than time2)

Examples European date format: countwholeminutes(#09/01/2004:12:28:53, #09/01/2004:12:53:53) equals 24.

American date format: countwholeminutes(#01/09/2004:12:28:53, #01/09/2004:12:53:53) equals 24.

YMD date format: countwholeminutes(#2004/01/09:12:28:53, #2004/01/09:12:53:53) equals 24.

See also

countminutes

Date formats

Parent topic: Functions for working with dates


countwholemonths, countwholemonthsbackwards

Purpose Count the number of complete months between two dates.

Syntax countwholemonths(date1, date2) countwholemonthsbackwards(date1, date2)

Arguments

Type | Name | Description
date | date1 | the first date
date | date2 | the second date

Result

Type | Description
integer | The number of complete months elapsed between date1 and date2 (a negative number if date1 is later than date2)
Note:
  • The time parts of date1 and date2 are ignored.
  • The number of complete months between two dates is the greatest number of months that can be added to the first date (truncating time parts, and using addmonths in the case of countwholemonths, and addmonthscountbackwards in the case of countwholemonthsbackwards) such that if the second date is later than the first date, the result is no later than the second date, and if the second date is earlier than the first date, the result is no earlier than the second date.
  • The results of comparing two dates with countwholemonths and countwholemonthsbackwards may differ when the dates lie in months of different lengths.
  • Because of the clamping behavior of addmonths (and addmonthscountbackwards), the absolute value of the results of comparing two dates with countwholemonths (or countwholemonthsbackwards) may depend on the order of the arguments when the dates lie in months of different lengths.

Examples To count the number of complete months between d1 and d2, showing the truncation of time parts (YMD date format):

d1 | d2 | countwholemonths(d1,d2)
2007/08/14:00:00:00 | 2007/09/14:00:00:00 | 1
2007/08/14:12:34:56 | 2007/09/14:00:00:00 | 1

To count the number of complete months between d1 and d2, showing the difference between the countwholemonths and countwholemonthsbackwards variants (YMD date format):

d1 | d2 | countwholemonths(d1,d2) | countwholemonthsbackwards(d1,d2)
2007/08/14 | 2007/09/12 | 0 | 0
2007/08/14 | 2007/09/13 | 0 | 1
2007/08/14 | 2007/09/14 | 1 | 1

To count the number of complete months between d1 and d2, showing the clamping behavior of countwholemonths at the end of the month (YMD date format):

d1 | d2 | countwholemonths(d1,d2) | countwholemonths(d2,d1)
2007/08/31 | 2007/09/30 | 1 | 0

To count the number of complete months between d1 and d2, showing the clamping behavior of countwholemonths at the start of the month (YMD date format):

d1 | d2 | countwholemonthsbackwards(d1,d2) | countwholemonthsbackwards(d2,d1)
2007/07/01 | 2007/06/01 | -1 | 0

To count the number of monthly e-mail communications each customer has received, where communications are sent on the fifth day of each month (the final communication having been sent on March 5th 2006), and using the customer acquisition date field StartDate:

-countwholemonths(#2006/03/05, StartDate)

To count the number of monthly statements each customer has received, where statement are sent seven days before the end of each month (the final statement having been sent on March 24th 2006), and using the customer acquisition date field StartDate:

-countwholemonthsbackwards(#2006/03/24, StartDate)

See also

addmonths, addmonthscountbackwards

Date formats

Parent topic: Functions for working with dates


countwholeseconds

Purpose Count the number of seconds between two dates.

Syntax countwholeseconds(time1, time2)

Arguments

Type | Name | Description
date | time1 | the first date/time
date | time2 | the second date/time

Result

Type | Description
integer | The number of seconds between time1 and time2 (a negative number if time1 is later than time2)
Note:

The only difference between this function and countseconds is that the result of the latter is of type real.

Examples European date format: countwholeseconds(#09/01/2004:12:28:53, #09/01/2004:12:29:18) equals 25.

American date format: countwholeseconds(#01/09/2004:12:28:53, #01/09/2004:12:29:18) equals 25.

YMD date format: countwholeseconds(#2004/01/09:12:28:53, #2004/01/09:12:29:18) equals 25.

See also

Date formats
Parent topic: Functions for working with dates


countwholeweeks

Purpose Count the number of complete weeks between two dates.

Syntax countwholeweeks(date1, date2)

Arguments

Type | Name | Description
date | date1 | the first date
date | date2 | the second date

Result

Type | Description
integer | The number of complete weeks elapsed between date1 and date2 (a negative number if date1 is later than date2)

Examples European date format: countwholeweeks(#09/01/2004, #09/03/2004) equals 8.

American date format: countwholeweeks(#01/09/2004, #03/09/2004) equals 8.

YMD date format: countwholeweeks(#2004/01/09, #2004/03/09) equals 8.

See also

countweeks

Date formats

Parent topic: Functions for working with dates


countwholeyears, countwholeyearsbackwards

Purpose Count the number of complete years between two dates.

Syntax countwholeyears(date1, date2)

countwholeyearsbackwards(date1, date2)

Arguments

Type | Name | Description
date | date1 | the first date
date | date2 | the second date

Result

Type | Description
integer | The number of complete years elapsed between date1 and date2 (a negative number if date1 is later than date2). See countwholemonths, countwholemonthsbackwards for an explanation of the two variants.
Note:
  • The result of the countwholeyears (respectively countwholeyearsbackwards) function is defined as the result of the countwholemonths (respectively countwholemonthsbackwards) function divided by 12, ignoring any remainder.
  • The results of comparing two dates with countwholeyears and countwholeyearsbackwards may differ, but only when both dates lie in February, one date lies in a leap year, and the other does not.

Examples To count the number of complete years between d1 and d2, showing the difference between the countwholeyears and countwholeyearsbackwards variants (YMD date format):

d1 | d2 | countwholeyears(d1,d2) | countwholeyearsbackwards(d1,d2)
2007/02/14 | 2008/02/13 | 0 | 0
2007/02/14 | 2008/02/14 | 1 | 0
2007/02/14 | 2008/02/15 | 1 | 1
To compute the age of each customer at March 1st 2007 from a date-of-birth field DOB (YMD date format):

countwholeyears(DOB, #2007/03/01)

See also

addyears, addyearscountbackwards

countyears

Date formats

Parent topic: Functions for working with dates


countyears

Purpose Calculate the period between two dates in years.

Syntax countyears(date1, date2)

Arguments

Type | Name | Description
date | date1 | the first date
date | date2 | the second date

Result

Type | Description
real | The period between date1 and date2 in years (a negative number if date1 is later than date2)
Note:
  • If the month, day, or time parts of the two dates differ, the result includes a fractional part, counting the incomplete year as a fraction of the number of days (365 or 366) in the year of the later of the two dates.

Examples European date format: countyears(#09/01/2004, #09/01/1994) equals -10.

American date format: countyears(#01/09/2004, #01/09/1994) equals -10.

YMD date format: countyears(#2004/01/09, #1994/01/09) equals -10.

See also

countwholeyears, countwholeyearsbackwards

Date formats

Parent topic: Functions for working with dates


day

Purpose Obtain the day-of-month part of a date.

Syntax day(date)

Arguments

Type | Name | Description
date | date | A date

Result

Type | Description
integer | The day-of-month part of date

Examples European date format: day(#09/01/2004) equals 9.

American date format: day(#01/09/2004) equals 9.

YMD date format: day(#2004/01/09) equals 9.

See also

Date formats

Splitting aggregations: the by clause

Parent topic: Functions for working with dates


dayofweek

Purpose Obtain a number representing the day-of-week of a date.

Syntax dayofweek(date)

Arguments

Type | Name | Description
date | date | A date

Result

Type | Description
integer | The day-of-week of date (a number between 0 and 6, with 0 representing Sunday)

Examples European date format: dayofweek(#09/01/2004) equals 5 (that is, Friday).

American date format: dayofweek(#01/09/2004) equals 5 (that is, Friday).

YMD date format: dayofweek(#2004/01/09) equals 5 (that is, Friday).

See also

Date formats

Splitting aggregations: the by clause

Parent topic: Functions for working with dates


gmt2edt

Purpose Convert a Greenwhich Mean Time (GMT) date to Eastern Daylight Time (EDT).

Syntax gmt2edt(datetimeGMT)

Arguments

Type | Name | Description
date | datetimeGMT | The GMT date to be converted

Result

Type | Description
date | The EDT date, accounting for daylight savings

Examples Winter: GMT2EDT(#09/01/2004:12:28:53) equals 09/01/2004:07:28:53.

Summer: GMT2EDT(#09/07/2004:12:28:53) equals 09/07/2004:08:28:53.

Parent topic: Functions for working with dates


hour

Purpose Obtain the hours part of a date.

Syntax hour(time)

Arguments

Type | Name | Description
date | time | A date/time

Result

Type | Description
integer | The hours part of time

Examples European date format: hour(#09/01/2004:12:28:53) equals 12.

American date format: hour(#01/09/2004:12:28:53) equals 12.

YMD date format: hour(#2004/01/09:12:28:53) equals 12.

See also

Date formats

Splitting aggregations: the by clause

Parent topic: Functions for working with dates


minute

Purpose Obtain the minutes part of a date.

Syntax minute(time)

Arguments

Type | Name | Description
date | time | A date/time
Result
Type | Description
integer | The minutes part of time

Examples European date format: minute(#09/01/2004:12:28:53) equals 28.

American date format: minute(#01/09/2004:12:28:53) equals 28.

YMD date format: minute(#2004/01/09:12:28:53 equals 28.

See also

Date formats

Splitting aggregations: the by clause

Parent topic: Functions for working with dates


month

Purpose Obtain the month part of a date.

Syntax month(date)

Arguments

Type | Name | Description
date | date | A date
Result
Type | Description
integer | The month part of date

Examples European date format: month(#09/01/2004) equals 1.

American date format: month(#01/09/2004) equals 1.

YMD date format: month(#2004/01/09) equals 1.

See also

Date formats

Splitting aggregations: the by clause

Parent topic: Functions for working with dates


now

Purpose Obtain the current date and time.

Syntax now()

Arguments None

Result

Type | Description
date | The current date (including time), obtained from the system clock
Examples European date format: now() equals 09/01/2004:12:28:53.

American date format: now() equals 01/09/2004:12:28:53.

YMD date format: now() equals 2004/01/09:12:28:53.

See also

Date formats

today

Parent topic: Functions for working with dates


second

Purpose Obtain the seconds part of a date.

Syntax second(time)

Arguments

Type | Name | Description
date | time | A date/time
Result
Type | Description
integer | The seconds part of time

Examples European date format: second(#09/01/2004:12:28:53) equals 53.

American date format: second(#01/09/2004:12:28:53) equals 53.

YMD date format: second(#2004/01/09:12:28:53) equals 53.

See also

Date formats

Splitting aggregations: the by clause

Parent topic: Functions for working with dates


today

Purpose Obtain the current date.

Syntax today()

Arguments None

Result

Type | Description
date | The current date obtained from the system clock, with the time part set to 00:00:00
Examples European date format: today() equals 09/01/2004:00:00:00.

American date format: today() equals 01/09/2004:00:00:00.

YMD date format: today() equals 2004/01/09:00:00:00.

See also

Date formats

now

Parent topic: Functions for working with dates


weekofyear

Purpose Calculate the week-of-year of a date, relative to a specified start date.

Syntax weekofyear(date, yearStart)

Arguments

Type | Name | Description
date | date | The date whose week-of-year is to be obtained
date | yearStart | The start date (for example, of a financial year)
Result
Type | Description
integer | The week-of-year of date, relative to yearStart
Note:

Only the month and day parts of the start date are used.

Examples European date format: weekofyear(#09/07/2004, #01/04/2004) equals 14.

American date format: weekofyear(#07/09/2004, #04/01/2004) equals 14.

YMD date format: weekofyear(#2004/07/09, #2004/04/01) equals 14.

See also

Date formats

Splitting aggregations: the by clause

Parent topic: Functions for working with dates


year

Purpose Obtain the year part of a date.

Syntax year(date)

Arguments

Type | Name | Description
date | date | A date

Result

Type | Description
integer | The year part of date

Examples European date format: year(#09/01/2004) equals 2004.

American date format: year(#01/09/2004) equals 2004.

YMD date format: year(#2004/01/09) equals 2004.

See also

Date formats
Parent topic: Functions for working with dates


Mathematical and statistical functions

  • abs
  • ceil
  • cos
  • exp
  • floor
  • log
  • log10
  • logbase
  • normalize
  • pow
  • round
  • sgn
  • sin
  • sqrt
  • tan
Parent topic: FDL functions


abs

Purpose Calculate the absolute value of a number.

Syntax abs(x)

Arguments

Type | Name | Description
numeric | x | A signed number

Result

Type | Description
as input | , the absolute value, or magnitude, of x

Examples abs(10000) equals 10000.

abs(-25000) equals 25000.

To calculate the absolute error between a predicted value and a historical value: abs(Value - PredictedValue)

See also

sgn
Parent topic: Mathematical and statistical functions


ceil

Purpose Round a number up to the nearest integer.

Syntax ceil(x)

Arguments

Type | Name | Description
numeric | x | The number to be rounded
Result
Type | Description
integer | , the integer such that

Examples ceil(1.25) equals 2.

ceil(-1.25) equals -1.

To generate a random integer between 1 and 10 inclusive: ceil(rndUniform()*10)

See also

floor

round

Parent topic: Mathematical and statistical functions


cos

Purpose Calculate the cosine of an angle.

Syntax cos(x)

Arguments

Type | Name | Description
numeric | x | An angle in radians
Result
Type | Description
real | cos x, the cosine of x

Examples cos(0) equals 1.

Parent topic: Mathematical and statistical functions


exp

Purpose Calculate the exponential of a number.

Syntax exp(x)

Arguments

Type | Name | Description
numeric | x | The number whose exponential is to be computed
Result
Type | Description
real | , the exponential of x

Examples exp(0) equals 1.

Parent topic: Mathematical and statistical functions


floor

Purpose Round a number down to the nearest integer.

Syntax floor(x)

Arguments

Type | Name | Description
numeric | x | The number to be rounded
Result
Type | Description
integer | , the integer such that

Examples floor(1.25) equals 1.

floor(-1.25) equals -2.

To generate a random integer between 0 and 9 inclusive: floor(rndUniform()*10)

See also

ceil

round

Parent topic: Mathematical and statistical functions


log

Purpose Calculate the natural (base-e) logarithm of a number.

Syntax log(x)

Arguments

Type | Name | Description
numeric | x | A positive number
Result
Type | Description
real | , the natural logarithm of x

Examples log(1) equals 0.

Parent topic: Mathematical and statistical functions


log10

Purpose Calculate the base-10 logarithm of a number.

Syntax log10(x)

Arguments

Type | Name | Description
numeric | x | A positive number
Result
Type | Description
real | , the base-10 logarithm of x

Examples log10(100) equals 2.

Parent topic: Mathematical and statistical functions


logbase

Purpose Calculate the logarithm of a number, to a specified base.

Syntax logbase(x, base)

Arguments

Type | Name | Description
numeric | x | The positive number whose logarithm is to be computed
numeric | base | The base to be used
Result
Type | Description
real | , the base-base logarithm of x

Examples logbase(100,10) equals 2.

Parent topic: Mathematical and statistical functions


normalize

Purpose Normalize field values to lie in the interval [0,1].

Syntax normalize(x)

Arguments

Type | Name | Description
numeric | x | The number to be normalized
Result
Type | Description
real | Value between 0 and 1 given by
Note:

You can only use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

Parent topic: Mathematical and statistical functions


pow

Purpose Calculate the result of raising one number to the power of another number.

Syntax pow(x, exponent)

Arguments

Type | Name | Description
numeric | x | The number to be raised to a power
numeric | exponent | The exponent
Result
Type | Description
real | , x raised to the power exponent

Examples pow(10, 2) equals 100.

Parent topic: Mathematical and statistical functions


round

Purpose Round a number to the nearest integer.

Syntax round(x)

Arguments

Type | Name | Description
numeric | x | The number to be rounded
Result
Type | Description
integer | the nearest integer to x, or, in the event of a tie, the greater of the two nearest integers (in absolute value)

Examples round(1.25) equals 1.

round(-1.25) equals -1.

round(1.5) equals 2.

round(-1.5) equals -2.

See also

ceil

floor

Parent topic: Mathematical and statistical functions


sgn

Purpose Calculate the signum (sign) of a number.

Syntax sgn(x)

Arguments

Type | Name | Description
numeric | x | A signed number
Result
Type | Description
as input | A number representing the sign of x:

Examples sgn(25) equals 1.

sgn(-25) equals -1.

See also

abs

Splitting aggregations: the by clause

Parent topic: Mathematical and statistical functions


sin

Purpose Calculate the sine of an angle.

Syntax sin(x)

Arguments

Type | Name | Description
numeric | x | An angle in radians
Result
Type | Description
real | sin x, the sine of x

Examples sin(3.14159/2) equals 1.

Parent topic: Mathematical and statistical functions


sqrt

Purpose Calculate the square root of a number.

Syntax sqrt(x)

Arguments

Type | Name | Description
numeric | x | A non-negative number
Result
Type | Description
real | , the square root of x

Examples sqrt(25) equals 5.

sqrt(-25) equals null.

Parent topic: Mathematical and statistical functions


tan

Purpose Calculate the tangent of an angle.

Syntax tan(x)

Arguments

Type | Name | Description
numeric | x | An angle in radians
Result
Type | Description
real | tan x, the tangent of x
Note:

If x is of the form [image] for some integer n, tan x is undefined. In that case, the FDL function returns null.

Examples tan(3.14159/4) equals 1.

Parent topic: Mathematical and statistical functions


Other functions

  • bin
  • dblookup
  • member
  • rownum
Parent topic: FDL functions


bin

Purpose Obtain a bin index corresponding to a value.

Syntax bin(binning, x)

Arguments

Type | Name | Description
binning | binning | A named binning, with parameter values (which must be literal values) in parentheses if required
integer, real, date, or string | x | A value compatible with the binning
Result
Type | Description
integer | The bin index of the bin in which x lies
Note:
  • Bin indices are positive integers. For a numeric binning with n nominal bins (numbered 2 to n + 1), the lower and upper end bins [see End bins] are numbered 1 and n + 2 respectively, while the null and unclassified bins are numbered n + 3 and n + 4.
  • This function is not available in Decision Studio. However, if x is a field and b is the primary binning associated with x, you can achieve the same result using segindex:

    segindex() by x

Examples Split aggregations using the equal-range binning EqualRange on the Amount field, resulting in an eight-way segmented aggregation (four internal bins between amount values 20 and 100 plus two end bins, a null bin and an unclassified bin):

create totalPointsByAmountBands :=

sum(PointsRedeemed) by bin(EqualRange(20, 100, 4), Amount);

Split aggregations into eight segments based on the campaign binning PrePost, starting on the [image] May 1999, and with aggregates from the month before and after the campaign:

create totalSpendPrePostMayCampaign_ := sum(Amount) by

bin(PrePost(todate(19990401), todate(19990501),

todate(19990601)), PurchaseDate);

See also

Boolean

DayFrom, WeekFrom, MonthFrom, YearFrom

DayMultipleFrom, WeekMultipleFrom, MonthMultipleFrom, YearMultipleFrom

DayMultipleNumBins, WeekMultipleNumBins, MonthMultipleNumBins, YearMultipleNumBins

DayMultiplePrePost, WeekMultiplePrePost, MonthMultiplePrePost, YearMultiplePrePost

DayMultipleTo, WeekMultipleTo, MonthMultipleTo, YearMultipleTo

DayMultipleWidth, WeekMultipleWidth, MonthMultipleWidth, YearMultipleWidth

DayPrePost, WeekPrePost, MonthPrePost, YearPrePost

DayRange, WeekRange, MonthRange, YearRange

DayTo, WeekTo, MonthTo, YearTo

EqualRange

EqualRangeWidth

NegativeNonNegative

PreDuringPost

PrePost

Sign

Splitting aggregations: the by clause

Parent topic: Other functions


dblookup

Purpose Look up values in a reference table (stored as a focus).

Syntax dblookup(d, k, f, x)

Arguments

Type | Name | Description
string | d | The pathname of the lookup table
string | k | The name of the key field in the lookup table
string | f | The name of another field in the lookup table
as field k | x | The lookup value

Result

Type | Description
as field f | The value y in the field f of table d, for the record indexed by the value x occurring in the key field k

Note:
  • You should only use this function for small lookup tables. If the lookup table is comparable in size to a customer or transaction table, you should consider performing a join instead.
  • If the lookup value doesn't occur in the key field, the null value is returned.
  • If the lookup value occurs more than once in the key field, the first value is used.
  • Trailing whitespace is stripped from the lookup value, but not from the values of the key field in the lookup table. This may produce unexpected behavior if the key field in the lookup table contains values with trailing whitespace.
  • For backwards compatibility, you can prefix the pathname of the lookup table with the string focus:.

Example In a focus, the store at which a customer most frequently shops is recorded in the field PopularShop. Another focus stores.ftr comprises a lookup table that describes facilities at each store: in this focus, StoreCode is the key field, and the field HasFuel indicates whether each store has a gas station. Store 105 has a gas station, stores 299 and 204 do not, and so on; store 189 is not in the lookup table. To derive a field that flags whether each customer's favorite store has a gas station:

PopularShop | dblookup("focus:stores.ftr", "StoreCode", "HasFuel", PopularShop)
105 | 1
299 | 0
204 | 0
189 | null

See also

About combining foci
Parent topic: Other functions


member

Purpose Determine set membership.

Syntax

member(x, [image], [image], ...)

Arguments

Type | Name | Description
integer, real, date, or string | x | The value to be tested
as x | , [image] , ... | The elements of the set

Result

Type | Description
integer | 1 (true) if x is in the set [image] ; 0 (false) otherwise
Note:
  • You can only use literal values (numbers, strings, or dates) for the list of set elements.
  • It is in general more efficient to use the member function than a disjunction of equality tests. For example, the expression strmember(F, "a", "b", "c") is quicker to evaluate than F = "a" or F = "b" or F = "c".
  • For backwards compatibility, you can use strmember instead of member when the arguments are strings.
  • Trailing whitespace in string values is not ignored.

Examples To use the first two characters of a StateCode field to identify West-coast customers:

StateCode | member (substr (StateCode, 0, 1), "CA", "OR", WA")
OR009 | 1
CA043 | 1
UT005 | 0
WA027 | 1

To flag customers whose 10-digit numeric phone numbers have Edinburgh (131) or Glasgow (141) area codes (by determining the first three digits using the div [see Arithmetic operators] operator):

TelNo | if member (TelNo div 10000000, 131, 141) then "Edin/Glas" else null
1312204491 | Edin/Glas
1753833999 | null
1611234567 | null
1417654321 | Edin/Glas

See also

Splitting aggregations: the by clause
Parent topic: Other functions


rownum

Purpose Generate the number of each row in the table.

Syntax rownum()

Arguments None

Result

Type | Description
integer | An index number from 1 to the number of records in the table
Note:

You can only use this function in a Decision Studio derivation, in the derivations file for qsderive or the equivalent Derive Fields window, in the trackers file for qstrack, or in a selections file for qsselect.

Examples To add an index column to an N-record dataset, with values [image]:

ID | rownum()
AZ195 | 1
DI539 | 2
JD974 | 3
BY643 | 4
Parent topic: Other functions


Return-on-investment functions

  • ActionROI
  • ActionROIAnnualized
  • OfferROI
  • OfferROIAnnualized
  • RetentionActionROI
  • RetentionActionROIAnnualized
  • RetentionOfferROI
  • RetentionOfferROIAnnualized
Parent topic: FDL functions


ActionROI

Purpose Estimate the per-customer (money) return on investment contribution from taking action designed to generate a definite response. The action happens whether or not the customer responds, so there is only a cost of action, not of fulfillment.

Syntax ActionROI(ResponseProbability, ValueOfResponse, CostOfAction)

Arguments

Type | Name | Description
numeric | ResponseProbability | The estimated probability that the customer will respond to the action by exhibiting some response behavior
numeric | ValueOfResponse | The estimated value of the customer's response to the marketing action (if it occurs)
numeric | CostOfAction | The estimated cost of the action (whether or not the customer responds)
Result
Type | Description
numeric | The estimated per-customer (money) return on investment contribution from taking action
Note:
  • The response probability should be an "uplift," that is, the probability that the customer will exhibit that behavior when they would not otherwise have done so. If there is any possibility of the customer's exhibiting the desired behavior without the action being taken, you should model this by using an uplift model or, failing that, by subtracting the likelihood of response given the action from the likelihood without the action.
  • The value of response should be a net revenue that ignores the cost of the marketing action.

See also

ActionROIAnnualized

OfferROI

OfferROIAnnualized

RetentionActionROI

RetentionActionROIAnnualized

RetentionOfferROI

RetentionOfferROIAnnualized

Parent topic: Return-on-investment functions


ActionROIAnnualized

Purpose Estimate the annualized per-customer return on investment multiple from taking action designed to generate a definite response from a customer. The action happens whether or not the customer responds, so there is only a cost of action, not of fulfillment.

Syntax ActionROIAnnualized(ResponseProbability, ValueOfResponse, CostOfAction, DaysToROI)

Arguments

Type | Name | Description
numeric | ResponseProbability | The estimated probability that the customer will respond to the action by exhibiting some response behavior
numeric | ValueOfResponse | The estimated value of the customer's response to the marketing action (if it occurs)
numeric | CostOfAction | The estimated cost of the action (whether or not the customer responds)
numeric | DaysToROI | The number of days expected to be required to achieve the given return on investment
Result
Type | Description
numeric | The estimated annualized per-customer return on investment multiple from taking action
Note:
  • The response probability should be an "uplift," that is, the probability that the customer will exhibit that behavior when they would not otherwise have done so. If there is any possibility of the customer's exhibiting the desired behavior without the action being taken, you should model this by using an uplift model or, failing that, by subtracting the likelihood of response given the action from the likelihood without the action.
  • The value of response should be a net revenue that ignores the cost of the marketing action.

See also

ActionROI

OfferROI

OfferROIAnnualized

RetentionActionROI

RetentionActionROIAnnualized

RetentionOfferROI

RetentionOfferROIAnnualized

Parent topic: Return-on-investment functions


OfferROI

Purpose Estimate the per-customer return on investment contribution from making an offer designed to generate a definite response.

Syntax OfferROI(ResponseProbability, ValueOfResponse, CostOfOffer, CostOfFulfilment)

Arguments

Type | Name | Description
numeric | ResponseProbability | The estimated probability that the customer will respond to the action by exhibiting some response behavior
numeric | ValueOfResponse | The estimated value of the customer's response to the marketing action (if it occurs)
numeric | CostOfOffer | The estimated cost of the action (whether or not the customer responds)
numeric | CostOfFulfilment | The estimated cost of a fulfilling a positive response (zero if there is no (additional) cost of fulfillment)
Result
Type | Description
numeric | The estimated per-customer return on investment from making an offer
Note:
  • The response probability should be an "uplift," that is, the probability that the customer will exhibit that behavior when they would not otherwise have done so. If there is any possibility of the customer's exhibiting the desired behavior without the action being taken, you should model this by using an uplift model or, failing that, by subtracting the likelihood of response given the action from the likelihood without the action.
  • The value of response should be a net revenue that ignores the cost of the marketing action and the cost of fulfillment to the customer's response.

See also

ActionROI

ActionROIAnnualized

OfferROIAnnualized

RetentionActionROI

RetentionActionROIAnnualized

RetentionOfferROI

RetentionOfferROIAnnualized

Parent topic: Return-on-investment functions


OfferROIAnnualized

Purpose Estimate the annualized per-customer return on investment multiple from making an offer designed to generate a definite response from a customer.

Syntax OfferROIAnnualized(ResponseProbability, ValueOfResponse, CostOfOffer, CostOfFulfilment, DaysToROI)

Arguments

Type | Name | Description
numeric | ResponseProbability | The estimated probability that the customer will respond to the action by exhibiting some response behavior
numeric | ValueOfResponse | The estimated value of the customer's response to the marketing action (if it occurs)
numeric | CostOfOffer | The estimated cost of the action (whether or not the customer responds)
numeric | CostOfFulfilment | The estimated cost of a fulfilling a positive response (zero if there is no (additional) cost of fulfillment)
numeric | DaysToROI | The number of days expected to be required to achieve the given return on investment
Result
Type | Description
numeric | The estimated per-customer annualized return on investment multiple from making an offer
Note:
  • The response probability should be an "uplift," that is, the probability that the customer will exhibit that behavior when they would not otherwise have done so. If there is any possibility of the customer's exhibiting the desired behavior without the action being taken, you should model this by using an uplift model or, failing that, by subtracting the likelihood of response given the action from the likelihood without the action.
  • The value of response should be a net revenue that ignores the cost of the marketing action and the cost of fulfillment to the customer's response.

See also

ActionROI

ActionROIAnnualized

OfferROI

RetentionActionROI

RetentionActionROIAnnualized

RetentionOfferROI

RetentionOfferROIAnnualized

Parent topic: Return-on-investment functions


RetentionActionROI

Purpose Estimate the per-customer (money) return on investment contribution from taking action designed to prevent attrition. The action is assumed to have a fixed cost, regardless of whether the customer is saved or not, and whether or not a customer "accepts" the offer.

Syntax RetentionActionROI(SaveProbability, NetRevenueAtRisk, CostOfAction)

Arguments

Type | Name | Description
numeric | SaveProbability | The estimated probability that the customer will be "saved" (for the period under consideration) as a result of the action taken
numeric | NetRevenueAtRisk | The estimated net revenue that will be lost if the customer undergoes attrition over the period under consideration
numeric | CostOfAction | The estimated cost of the action (whether or not the customer responds)
Result
Type | Description
numeric | The estimated per-customer (money) return on investment contribution from action designed to prevent attrition
Note:
  • To say a customer is "saved" means "caused not to leave when the customer otherwise would have done so." This value is the negative of the uplift in attrition rate produced by an uplift model. Alternatively, it can be calculated as P(attrition|no action) - P(attrition|action).
  • Net revenue at risk should be a net revenue that ignores the cost of the action designed to prevent attrition.

See also

ActionROI

ActionROIAnnualized

OfferROI

OfferROIAnnualized

RetentionActionROIAnnualized

RetentionOfferROI

RetentionOfferROIAnnualized

Parent topic: Return-on-investment functions


RetentionActionROIAnnualized

Purpose Estimate the annualized per-customer return on investment contribution from taking action designed to prevent attrition. The action is assumed to have a fixed cost, regardless of whether the customer is saved or not, and whether or not a customer "accepts" the offer.

Syntax RetentionActionROIAnnualized(SaveProbability, NetRevenueAtRisk, CostOfAction, DaysToROI)

Arguments

Type | Name | Description
numeric | SaveProbability | The estimated probability that the customer will be "saved" (for the period under consideration) as a result of the action taken
numeric | NetRevenueAtRisk | The estimated net revenue that will be lost if the customer undergoes attrition over the period under consideration
numeric | CostOfAction | The estimated cost of the action (whether or not the customer responds)
numeric | DaysToROI | The number of days expected to be required to achieve the given return on investment
Result
Type | Description
numeric | The estimated annualized per-customer return on investment contribution from action designed to prevent attrition
Note:
  • To say a customer is "saved" means "caused not to leave when the customer otherwise would have done so." This value is the negative of the uplift in attrition rate produced by an uplift model. Alternatively, it can be calculated as P(attrition|no action) - P(attrition|action).
  • Net revenue at risk should be a net revenue that ignores the cost of the action designed to prevent attrition.

See also

ActionROI

ActionROIAnnualized

OfferROI

OfferROIAnnualized

RetentionActionROI

RetentionOfferROI

RetentionOfferROIAnnualized

Parent topic: Return-on-investment functions


RetentionOfferROI

Purpose Estimate the per-customer return on investment from making an offer designed to prevent attrition. An offer, as distinct from an action, has a different cost according to whether or not it is accepted by the customer.

Syntax RetentionOfferROI(SaveProbability, ResponseProbability, NetRevenueAtRisk, CostOfOffer, CostOfFulfilment)

Arguments

Type | Name | Description
numeric | SaveProbability | The estimated probability that the customer will be "saved" (for the period under consideration) as a result of the action taken
numeric | ResponseProbability | The estimated probability that the customer will respond to the offer
numeric | NetRevenueAtRisk | The estimated net revenue that will be lost if the customer undergoes attrition over the period under consideration
numeric | CostOfOffer | The estimated cost of the offer (whether or not the customer responds)
numeric | CostOfFulfilment | The estimated cost of fulfilling a positive response to the offer

Result

Type | Description
numeric | The estimated per-customer return on investment from an offer designed to prevent attrition
Note:
  • To say a customer is "saved" means "caused not to leave when the customer otherwise would have done so". This value is minus the uplift in attrition rate produced by an uplift model. Alternatively, it can be calculated as P(attrition|no action) - P(attrition|action).
  • Net revenue at risk should be a net revenue ignoring the cost of the action designed to prevent attrition.

See also

ActionROI

ActionROIAnnualized

OfferROI

OfferROIAnnualized

RetentionActionROI

RetentionActionROIAnnualized

RetentionOfferROIAnnualized

Parent topic: Return-on-investment functions


RetentionOfferROIAnnualized

Purpose Estimate the annualized per-customer return on investment from making an offer designed to prevent attrition. An offer, as distinct from an action, has a different cost according to whether or not it is accepted by the customer.

Syntax RetentionOfferROIAnnualized(SaveProbability, ResponseProbability, NetRevenueAtRisk, CostOfOffer, CostOfFulfilment, DaysToROI)

Arguments

Type | Name | Description
numeric | SaveProbability | The estimated probability that the customer will be "saved" (for the period under consideration) as a result of the action taken
numeric | ResponseProbability | The estimated probability that the customer will respond to the offer
numeric | NetRevenueAtRisk | The estimated net revenue that will be lost if the customer undergoes attrition over the period under consideration
numeric | CostOfOffer | The estimated cost of the offer (whether or not the customer responds)
numeric | CostOfFulfilment | The estimated cost of fulfilling a positive response to the offer
numeric | DaysToROI | The number of days expected to be required to achieve the given return on investment
Result
Type | Description
numeric | The estimated annualized per-customer return on investment from an offer designed to prevent attrition
Note:
  • To say a customer is "saved" means "caused not to leave when the customer otherwise would have done so". This value is minus the uplift in attrition rate produced by an uplift model. Alternatively, it can be calculated as P(attrition|no action) - P(attrition|action).
  • Net revenue at risk should be a net revenue ignoring the cost of the action designed to prevent attrition.

See also

ActionROI

ActionROIAnnualized

OfferROI

OfferROIAnnualized

RetentionActionROI

RetentionActionROIAnnualized

RetentionOfferROI

Parent topic: Return-on-investment functions


Random-number functions

  • About random-number functions in FDL
  • rndBinomial
  • rndBool
  • rndExp
  • rndGamma
  • rndNormal
  • rndPoisson
  • rndUniform
Parent topic: FDL functions


About random-number functions in FDL

When evaluating an FDL expression involving a random number function (numericTestTrainSplit, numericTestTrainValidateSplit, rndBinomial, rndBool, rndExp, rndGamma, rndNormal, rndPoisson, or rndUniform sampleEqualSize, sampleExactNumber, sampleExactPercentage, sampleStratified, testTrainSplit, and testTrainValidateSplit), Portrait Miner needs an integer "seed" to initialize its sequence of random numbers. With the same seed, the same expression will always produce the same sequence of results.
Note:
  • The seed is stored as part of the field information.
  • The (pseudo)random number generation is based on that of Marsaglia, Zaman, and Tsang (1990).
Parent topic: Random-number functions


rndBinomial

Purpose Generate a random integer based on a binomial distribution.

Syntax rndBinomial(N, p)

Arguments

Type | Name | Description
integer | N | The (positive) number of trials
numeric | p | The probability of success for each trial (between 0 and 1)

Result

Type | Description
integer | A random non-negative integer sampled from the binomial distribution, with probability given by
Note:

The expectation and variance of the binomial distribution are [image] and [image] respectively.

Examples rndBinomial (50, 0.05)

See also

About random-number functions in FDL
Parent topic: Random-number functions


rndBool

Purpose Generate either 0 or 1 randomly (with equal probability).

Syntax rndBool()

Arguments None

Result

Type | Description
integer | Either 0 or 1, with probabilities

Examples To derive a field that allocates the value 0 to approximately 50% of the records (chosen randomly) and the value 1 to the remainder: rndBool()

See also

About random-number functions in FDL
Parent topic: Random-number functions


rndExp

Purpose Generate a random positive number based on an exponential distribution.

Syntax rndExp(b)

Arguments

Type | Name | Description
numeric | b | The (positive) scale parameter

Result

Type | Description
real | A positive random number sampled from the exponential distribution, with probability density function given by [image] (x > 0)
Note:

The expectation and variance of the exponential distribution are [image] and [image] respectively.

Examples rndExp(10)

See also

About random-number functions in FDL
Parent topic: Random-number functions


rndGamma

Purpose Generate a random positive number based on a gamma distribution.

Syntax rndGamma(a, b)

Arguments

Type | Name | Description
integer | a | The (positive) number of independent events
numeric | b | The (positive) event rate

Result

Type | Description
real | A positive random number sampled from the gamma distribution [image] , with probability density function given by
Note:

The expectation and variance of the gamma distribution are [image] and [image] respectively.

Examples rndGamma (50, 0.05)

See also

About random-number functions in FDL
Parent topic: Random-number functions


rndNormal

Purpose Generate a random number based on a normal distribution.

Syntax

rndNormal( [image], ef="../../../../images/img344.gif"/>h>

Arguments

Type | Name | Description
numeric |  | The mean of the distribution
numeric |  | The standard deviation of the distribution

Result

Type | Description
real | A random number sampled from the normal distribution [image] , with probability density function given by
Note:

The expectation and variance of the normal distribution are [image] and [image] respectively.

Examples To derive a Gaussian distribution with zero mean and unit standard deviation: rndNormal(0,1)

See also

About random-number functions in FDL
Parent topic: Random-number functions


rndPoisson

Purpose Generate a random non-negative integer based on a discrete Poisson distribution.

Syntax rndPoisson(mean)

Arguments

Type | Name | Description
numeric |  | The (positive) mean of the distribution

Result

Type | Description
integer | A random non-negative integer sampled from the discrete Poisson distribution, with probability given by [image] ( [image] )
Note:

The expectation and variance of the discrete Poisson distribution are both equal to the mean, [image].

Examples rndPoisson(10)

See also

About random-number functions in FDL
Parent topic: Random-number functions


rndUniform

Purpose Generate a random number between 0 and 1 based on a uniform distribution.

Syntax rndUniform()

Arguments None

Result

Type | Description
real | A random number sampled from a uniform distribution over [0, 1)

Examples To generate a random real number in the range [0,10): rndUniform() * 10

See also

About random-number functions in FDL
Parent topic: Random-number functions


Rank functions

  • rankOrder, rankOrderApprox
  • rankOrderMean, rankOrderApproxMean
Parent topic: FDL functions


rankOrder, rankOrderApprox

Purpose Identify the rank of a value within a list of values.

Syntax

rankOrder(x, [image], [image], ...)

rankOrderApprox(x, [image], [image], ...)

Arguments

Type | Name | Description
integer, real, date, or string | x | The value to be ranked
as x | , [image] , ... | The list of values for comparison

Result

Type | Description
integer | The position of the first occurrence of x within the list of values obtained by sorting [image] , [image] , ... in descending order (latest to earliest for dates; reverse alphabetical order for strings) If x doesn't occur in the list, rankOrder returns null, while rankOrderApprox returns the position of x within the list of values obtained by sorting x, [image] , [image] , ... in descending order.
Note:
  • When the value to be ranked occurs exactly once in the list of values, rankOrder, rankOrderApprox, rankOrderMean, and rankOrderApproxMean all give the same result.
  • When the value to be ranked occurs more than once in the list of values, rankOrderApprox gives the same result as rankOrder.
  • When the value to be ranked doesn't occur in the list of values, rankOrderApprox gives the same result as rankOrderApproxMean.
  • For strings, "alphabetical order" means the natural order of the underlying character representation.

Examples rankOrder(6.74, 6.74, 1.99, 0.00, 9.27) equals 2.

rankOrderApprox(6.74, 1.99, 0.00, 9.27) equals 2.

To check where a customer's number of phone calls in Quarter 4 ranks in a year:

rankOrder(CallsQ4, CallsQ1, CallsQ2, CallsQ3, CallsQ4)

To check where a customer's number of phone calls in month 5 ranks with the previous four:

RankOrderApprox(CallsM5, CallsM1, CallsM2, CallsM3, CallsM4)

See also

rankOrderMean, rankOrderApproxMean
Parent topic: Rank functions


rankOrderMean, rankOrderApproxMean

Purpose Identify the rank of a value within a list of values, or its average rank if it occurs more than once.

Syntax

rankOrderMean(x, [image], [image], ...)

rankOrderApproxMean(x, [image], [image], ...)

Arguments

Type | Name | Description
integer, real, date, or string | x | The value to be ranked
as x | , [image] , ... | The list of values for comparison

Result

Type | Description
real | The mean rank of x within the list of values obtained by sorting [image] , [image] , ... in descending order (latest to earliest for dates; reverse alphabetical order for strings) If x doesn't occur in the list, rankOrderMean returns null, while rankOrderApproxMean returns the position of x within the list of values obtained by sorting x, [image] , [image] , ... in descending order.
Note:
  • When the value to be ranked occurs exactly once in the list of values, rankOrder, rankOrderApprox, rankOrderMean, and rankOrderApproxMean all give the same result.
  • When the value to be ranked occurs more than once in the list of values, rankOrderApproxMean gives the same result as rankOrderMean.
  • When the value to be ranked doesn't occur in the list of values, rankOrderApproxMean gives the same result as rankOrderApprox.
  • For strings, "alphabetical order" means the natural order of the underlying character representation.

Examples rankOrderMean(6.74, 6.74, 1.99, 6.74, 9.27) equals 2.5.

rankOrderApproxMean(6.74, 1.99, 6.74, 9.27, 6.74) equals 2.5.

See also

rankOrder, rankOrderApprox
Parent topic: Rank functions


Data-sampling functions

  • numericTestTrainSplit
  • numericTestTrainValidateSplit
  • sampleEqualSize
  • sampleExactNumber
  • sampleExactPercentage
  • sampleStratified
  • testTrainSplit
  • testTrainValidateSplit
Parent topic: FDL functions


numericTestTrainSplit

Purpose Create a test/training segmentation for use in model validation.

Syntax numericTestTrainSplit(testFraction)

Arguments

Type | Name | Description
real | testFraction | The fraction of the data to be used as the test set
Result
Type | Description
integer | Values 0 for the training set or 1 for the test set

Examples To derive a field that allocates the value 0 to approximately 70% of the records (chosen randomly) and the value 1 to the remainder: numericTestTrainSplit(0.3)

See also

numericTestTrainValidateSplit

sampleEqualSize

testTrainSplit

testTrainValidateSplit

To partition a focus into sample subpopulations

Parent topic: Data-sampling functions


numericTestTrainValidateSplit

Purpose Create a test/training/validation segmentation for use in model validation.

Syntax numericTestTrainValidateSplit(testFraction, validateFraction)

Arguments

Type | Name | Description
real | testFraction | The fraction of the data to be used as the test set
real | validateFraction | The fraction of the data to be used as the hold-out set
Result
Type | Description
integer | Values 0 for the training set, 1 for the test set or 2 for the validation set

Examples To derive a field that allocates the value 0 to approximately 50% of the records (chosen randomly), the value 1 to approximately 30% of the records (again chosen randomly), and the value 2 to the remainder: numericTestTrainValidateSplit(0.3, 0.2)

See also

numericTestTrainSplit

sampleEqualSize

testTrainSplit

testTrainValidateSplit

To partition a focus into sample subpopulations

Parent topic: Data-sampling functions


sampleEqualSize

Purpose Create a segmentation index that randomly assigns records to segments of approximately equal size.

Syntax sampleEqualSize(NumberOfSegments)

Arguments

Type | Name | Description
integer | NumberOfSegments | The number of segments to create
Result
Type | Description
integer | A number between 1 and NumberOfSegments (inclusive)

Examples To derive a field enumerating five (approximately) equal-sized populations: sampleEqualSize(5)

See also

numericTestTrainSplit

numericTestTrainValidateSplit

testTrainSplit

testTrainValidateSplit

To partition a focus into sample subpopulations

Parent topic: Data-sampling functions


sampleExactNumber

Purpose Create a random sample of an exact size, specified as a number of records.

Syntax sampleExactNumber(NumberToSelect)

Arguments

Type | Name | Description
integer | NumberToSelect | The size of sample to create, as a number of records

Result

Type | Description
integer | 1 if a record is chosen for the sample; 0 otherwise
Note:
  • Records that are not currently selected in the focus are assigned the null value.
  • You can only use this function in a Decision Studio derivation, in the derivations ?le for qsderive or the equivalent Derive Fields window, in the trackers ?le for qstrack, or in a selections ?le for qsselect.

Examples To choose 1,250 records for a sample: sampleExactNumber(1250)

See also

sampleExactPercentage

sampleStratified

To partition a focus into sample subpopulations

Parent topic: Data-sampling functions


sampleExactPercentage

Purpose Create a random sample of an exact size, specified as a percentage of the size of the currently-selected population.

Syntax sampleExactPercentage(PercentageToSelect)

Arguments

Type | Name | Description
integer | PercentageToSelect | The size of sample to create, as a percentage of the size of the current population

Result

Type | Description
integer | 1 if a record is chosen for the sample; 0 otherwise
Note:
  • Records that are not currently selected in the focus are assigned the null value.
  • If PercentageToSelect multiplied by the population size is not a whole number, the number chosen will be the nearest whole number above or below PercentageToSelect multiplied by the population size, and will on average give the specified percentage.
  • You can only use this function in a Decision Studio derivation, in the derivations ?le for qsderive or the equivalent Derive Fields window, in the trackers ?le for qstrack, or in a selections ?le for qsselect.

Examples To choose 25% of the population for a sample: sampleExactPercentage(25)

See also

sampleExactNumber

sampleStratified

To partition a focus into sample subpopulations

Parent topic: Data-sampling functions


sampleStratified

Purpose Create a random sample that contains an exact number of records from a specified segment, together with an exact number of records from the remainder of the currently-selected population.

Syntax sampleStratified(NumberFromSegmentToSelect, SegmentTotalSize, NumberOutsideSegmentToSelect, OutsideSegmentTotalSize, InSegmentExpression)

Arguments

Type | Name | Description
integer | NumberFromSegmentToSelect | The number of records in the sample to be chosen from the specified segment
integer | SegmentTotalSize | The total number of records in the specified segment
integer | NumberOutsideSegmentToSelect | The number of records in the sample to be chosen from the remainder of the population
integer | OutsideSegmentTotalSize | The total number of records in the remainder of the population
integer | InSegmentExpression | The (boolean) expression that determines whether or not a record is in the specified segment

Result

Type | Description
integer | 1 if a record is chosen for the sample; 0 otherwise
Note:
  • Records that are not currently selected in the focus are assigned the null value.
  • You can only use this function in a Decision Studio derivation, in the derivations ?le for qsderive or the equivalent Derive Fields window, in the trackers ?le for qstrack, or in a selections ?le for qsselect.

Examples To create a sample comprising 2,500 records from a total of 25,000 females, and 5,000 records from a total of 75,000 non-females: sampleStratified(2500, 25000, 5000, 75000, Gender = "F")

See also

sampleExactNumber

sampleExactPercentage

To partition a focus into sample subpopulations

Parent topic: Data-sampling functions


testTrainSplit

Purpose Create a test/training segmentation for use in model validation.

Syntax testTrainSplit(testFraction)

Arguments

Type | Name | Description
real | testFraction | The fraction of the data to be used as the test set
Result
Type | Description
string | String values TestSet or TrainingSet

Examples To derive a field that allocates the value "TrainingSet" to approximately 70% of the records (chosen randomly) and the value "TestSet" to the remainder:

testTrainSplit(0.3)

See also

numericTestTrainSplit

numericTestTrainValidateSplit

sampleEqualSize

testTrainValidateSplit

To partition a focus into sample subpopulations

Parent topic: Data-sampling functions


testTrainValidateSplit

Purpose Create a test/training/validation segmentation for use in model validation.

Syntax testTrainValidateSplit(testFraction, validateFraction)

Arguments

Type | Name | Description
real | testFraction | The fraction of the data to be used as the test set
real | validateFraction | The fraction of the data to be used as the hold-out set

Result

Type | Description
string | String values TestSet, TrainingSet or ValidationSet

Examples To derive a field that allocates the value "TrainingSet" to approximately 50% of the records (chosen randomly), the value "TestSet" to approximately 30% of the records (again chosen randomly), and the value "ValidationSet" to the remainder:

testTrainValidateSplit(0.3, 0.2)

See also

numericTestTrainSplit

numericTestTrainValidateSplit

sampleEqualSize

testTrainSplit

To partition a focus into sample subpopulations

Parent topic: Data-sampling functions


Functions for working with strings

  • concat
  • endswith
  • find
  • left
  • match
  • mid
  • replaceall
  • replacefirst
  • right
  • soundex
  • startswith
  • strlen
  • strmember
  • substitute
  • substr
  • tolower
  • toupper
  • trim
Parent topic: FDL functions


concat

Purpose Concatenate two or more strings.

Syntax

concat( [image], [image], ...)

Arguments

Type | Name | Description
string | , [image] , ... | Strings to be concatenated
Result
Type | Description
string | The string obtained by writing the characters of [image] , followed by the characters of [image] , etc.

Examples Derive a customer's complete name from two fields FirstName and Surname:

FirstName | Surname | concat(FirstName," ",Surname)
John | Brown | John Brown
David | Smith | David Smith

Derive a customer's complete name, but using only their initial:

FirstName | Surname | concat(substr(FirstName,0,0),". ",Surname)
John | Brown | J. Brown
David | Smith | D. Smith
Parent topic: Functions for working with strings


endswith

Purpose Test whether one string ends with another.

Syntax endswith(find_text, within_text)

Arguments

Type | Name | Description
string | find_text | The string to be found at the end
string | within_text | The string to be tested
Result
Type | Description
integer | 1 (true) if find_text is found at the end of within_text; 0 (false) otherwise
Note:

The endswith function is based on the match function. It appends a $ character to find_text before treating the result as a regular expression [see Regular expressions].

Examples To derive a field that flags e-mail addresses from .net domains:

EmailAddress | endswith(".net", EmailAddress)
J.Brown@glob.net | 1
D.Smith@portraitsoftware.com | 0

See also

find

startswith

Parent topic: Functions for working with strings


find

Purpose Test whether one string is contained within another.

Syntax find(find_text, within_text)

Arguments

Type | Name | Description
string | find_text | The string to be found
string | within_text | The string to be tested

Result

Type | Description
integer | 1 (true) if find_text is found in within_text; 0 (false) otherwise
Note:

The find function is based on the match function, and it treats find_text as a regular expression [see Regular expressions].

Examples To flag e-mail addresses containing the text "portraitsoftware" in upper, lower, or mixed case:

EmailAddress | find("portraitsoftware", tolower(EmailAddress))
J.BROWN@PORTRAITSOFTWARE.COM | 1
J.Brown@glob.net | 0
D.Smith@portraitsoftware.com | 1

See also

endswith

startswith

Parent topic: Functions for working with strings


left

Purpose Return a substring of specified length from the start of a string.

Syntax left(text, num_chars)

Arguments

Type | Name | Description
string | text | The string to extract from
integer | num_chars | The number of characters
Result
Type | Description
string | The substring formed by num_chars characters at the start of text
Note:

The left function is based on the substr function.

Examples To use the first two characters of a StateCode field to identify west-coast customers:

StateCode | member (left (StateCode, 2), "CA", "OR", WA")
OR009 | 1
CA043 | 1
UT005 | 0
WA027 | 1

See also

mid

right

trim

Parent topic: Functions for working with strings


match

Purpose Test a string for a regular expression match [see Regular expressions].

Syntax match(regexp, string)

Arguments

Type | Name | Description
string | regexp | The regular expression
string | string | The string to be tested
Result
Type | Description
integer | 1 (true) if regexp matches string; 0 (false) otherwise

Examples To flag customers whose home postcode and bank branch postcode match in the first two characters (using the substr function):

HomePostcode | BranchPostCode | match(substr(HomePostcode, 0, 1), substr(BranchPostcode,0,1))
NE25 0AY | NE30 1QX | 1
SW3 | NG18 1HT | 0
CF36 | CF31 1HY | 1
EH9 0NJ | E10 8AJ | 0

To look in a company name field for the first three characters from a first-name field, followed by any text and then the contents of a family name field (ignoring case):

FirstName | FamilyName | CompanyName | rx := concat( substr(toupper(FirstName),0,2), "[[:print:]]*", toupper(FamilyName); match(rx,toupper(CompanyName))
Patrick | Smith | 1234 Pat Smith Ltd | 1
Patrick | Smith | 1234 Pat J Smith Ltd | 1

To do the same, but with only some letters or digits and a single space between the first name and family name:

FirstName | FamilyName | CompanyName | rx := concat( substr(toupper(FirstName),0,2), "[[:alnum:]]* ", toupper(FamilyName); match(rx,toupper(CompanyName))
Patrick | Smith | 1234 Pat Smith Ltd | 1
Patrick | Smith | 1234 Pat J Smith Ltd | 0

See also

replaceall

replacefirst

Splitting aggregations: the by clause

Parent topic: Functions for working with strings


mid

Purpose Return a substring of specified length from the middle of a string.

Syntax mid(text, start_num, num_chars)

Arguments

Type | Name | Description
string | text | The string to extract from
string | start_num | The first index
string | num_chars | The number of characters
Result
Type | Description
string | The substring formed by the num_chars characters from character position start_num (inclusive) of text, where the character position are numbered starting from 1
Note:

The mid function is based on the substr function.

Examples To derive a location from the fifth through seventh characters of a store code:

StoreCode | mid(StoreCode, 5, 3)
0114EDI256 | EDI
1863LON836 | LON
9326EDI039 | EDI
0387BOS041 | BOS

See also

left

right

trim

Parent topic: Functions for working with strings


replaceall

Purpose Replace all substrings that match a regular expression [see Regular expressions].

Syntax replaceall(regexp, replacement, string)

Arguments

Type | Name | Description
string | regexp | The regular expression
string | replacement | The replacement string
string | string | The string to be searched
Result
Type | Description
string | A copy of the string string with replacement replacing each non-overlapping portion that regexp matches
Note:

The first matching portion of the string to be searched is the leftmost, longest portion that the regular expression matches. The next search applies to the remainder of the string to be searched, and so on. For example,

replaceall("i..", "X", "initiation")

yields the string "XtXX" (rather than, say, "inXatX"). And

replaceall("i.*i", "X", "initiation")

gives the result "Xon" (rather than, say, "XtXon").

Examples To detect and remove whitespace from a PostalCode field using a regular expression match:

PostalCode | replaceall("[[:blank:]]","",PostalCode))
ND 069 | ND069
IN 099 | IN099
UT 0 0 5 | UT005
O R 009 | OR009

See also

match

replacefirst

Parent topic: Functions for working with strings


replacefirst

Purpose Replace the first substring that matches a regular expression [see Regular expressions].

Syntax replacefirst(regexp, replacement, string)

Arguments

Type | Name | Description
string | regexp | The regular expression
string | replacement | The replacement string
string | string | The string to be searched
Result
Type | Description
string | A copy of the string string with replacement replacing the first portion that regexp matches (if any)

Examples To extract a customer's name from an e-mail address field in the format "Firstname.Surname@company.com", by removing everything from the "@" onwards and replacing the "." with a space:

Email | replacefirst("@.*", "", (replacefirst ("\.", " ", Email)))
John.Brown@myco.com | John Brown
Angela.Smith@yourco.com | Angela Smith

See also

match

replaceall

Parent topic: Functions for working with strings


right

Purpose Return a substring of specified length from the end of a string.

Syntax right(text, num_chars)

Arguments

Type | Name | Description
string | text | The string to extract from
integer | num_chars | The number of characters
Result
Type | Description
string | The substring formed by num_chars characters at the end of text
Note:

The right function is based on the substr function.

Examples To return the house/street component of a UK postcode field, that is, the last three characters:

Postcode | right(Postcode, 3)
NE25 0AY | 0AY
EH3 7RA | 7RA
SL4 1QX | 1QX
EH9 0NJ | 0NJ

See also

left

mid

trim

Parent topic: Functions for working with strings


soundex

Purpose Reduce each word to a four-character string for indexing purposes.

Syntax soundex(text)

Arguments

Type | Name | Description
string | text | The text to reduce
Result
Type | Description
string | A four-character reduced index coding
Examples To derive the soundex code for a family name:
Surname | soundex(Surname)
Brown | B650
Smythe | S530
Smith | S530
Bruno | B650
Note: The Soundex function is not defined for non ascii characters.
Parent topic: Functions for working with strings


startswith

Purpose Test whether one string starts with another.

Syntax startswith(find_text, within_text)

Arguments

Type | Name | Description
string | find_text | The string to look for at the start
string | within_text | The string to be tested
Result
Type | Description
integer | 1 if find_text is found at the start of within_text; 0 otherwise
Note:

The startswith function is based on the match function. It prepends a ^ character to find_text before treating the result as a regular expression [see Regular expressions].

Examples To derive the type of credit card used in a transaction, such as "Discover", "AmEx", "Visa" or "MasterCard", based on the card prefix numbers:

case

startswith ("6011", CC_Number): "Discover";

startswith ("4", CC_Number): "Visa";

startswith ("5", CC_Number): "MasterCard";

startswith ("34",CC_Number) or startswith ("37", CC_Number): "AmEx";

default: null;

CC_Number | CC_Type
4111-1111-1111-1111 | Visa
5431-1111-1111-1111 | MasterCard
341-1111-1111-1111 | AmEx
6011-6011-6011-6611 | Discover
See also

endswith

find

Parent topic: Functions for working with strings


strlen

Purpose Obtain the length of a string.

Syntax strlen(string)

Arguments

Type | Name | Description
string | string | The string whose length is to be determined
Result
Type | Description
integer | The number of characters in string

Examples To derive a string field of exactly four characters, by padding a shorter string field with leading zeros:

case

strlen(AccountID) = 1: concat("000", AccountID);

strlen(AccountID) = 2: concat("00", AccountID);

strlen(AccountID) = 3: concat("0", AccountID);

default: AccountID;

AccountID | Account
1 | 0001
22 | 0022
333 | 0333
4444 | 4444
Parent topic: Functions for working with strings


strmember

Purpose Determine set membership.

Syntax

strmember(x, [image], [image], ...)

Arguments

Type | Name | Description
string | x | The value to be tested
as x | , [image] , ... | The elements of the set

Result

Type | Description
integer | 1 (true) if x is in the set [image] ; 0 (false) otherwise
Note:
  • You can only use string literal values for the list of set elements.
  • Trailing whitespace in the values is not ignored.
  • This function is deprecated in favor of the more general member function.

See also

Splitting aggregations: the by clause
Parent topic: Functions for working with strings


substitute

Purpose Replace one string with another.

Syntax substitute(text, old_text, new_text)

Arguments

Type | Name | Description
string | text | The string to be searched
string | old_text | The string to be replaced
string | new_text | The replacement string

Result

Type | Description
string | A copy of the string text with new_text replacing each non-overlapping instance of old_text
Note:

The substitute function is based on the replaceall function, and it treats old_text as a regular expression [see Regular expressions].

Examples To remove whitespace from a field named PostalCode:

PostalCode | substitute(PostalCode, "[[:blank:]]", "")
ND 069 | ND069
IN 099 | IN099
UT 0 0 5 | UT005
O R 009 | OR009

See also

replacefirst
Parent topic: Functions for working with strings


substr

Purpose Obtain a substring from a string.

Syntax substr(string, start, end)

Arguments

Type | Name | Description
string | string | The initial string
integer | start | The first index
integer | end | The second index

Result

Type | Description
string | The substring formed from characters start through end (inclusive) of string, where the characters are numbered starting from 0. Positive index values count from the start of the string, and negative index values count from the end of the string.

Examples To select the first two and last three characters of a PostalCode field to give the state code:

PostalCode | substr(PostalCode, 0, 1) | substr(PostalCode, -3, -1)
MA015 | MA | 015
WA055 | WA | 055
UT005 | UT | 005
MN119 | MN | 119

To derive the type of credit card used in a transaction, such as "Discover", "AmEx", "Visa" or "MasterCard", based on the card prefix numbers:

case

substr(CC_Number, 0, 3) = "6011": "Discover";

substr(CC_Number, 0, 0) = "4": "Visa";

substr(CC_Number, 0, 0) = "5": "MasterCard";

substr(CC_Number, 0, 1) = "34" or substr(CC_Number, 0, 1) = "37": "AmEx";

default: null;

CC_Number | CC_Type
4111-1111-1111-1111 | Visa
5431-1111-1111-1111 | MasterCard
341-1111-1111-1111 | AmEx
6011-6011-6011-6611 | Discover
Parent topic: Functions for working with strings


tolower

Purpose Convert a string to lowercase text.

Syntax tolower(string)

Arguments

Type | Name | Description
string | string | A string to be converted

Result

Type | Description
string | The string obtained from string by replacing every uppercase letter in string with the corresponding lowercase letter

Examples tolower("ZYXWV") equals "zyxwv"

See also

toupper
Parent topic: Functions for working with strings


toupper

Purpose Convert a string to uppercase text.

Syntax toupper(string)

Arguments

Type | Name | Description
string | string | A string to be converted

Result

Type | Description
string | The string obtained from string by replacing every lowercase letter in string with the corresponding uppercase letter

Examples toupper("abcde") equals "ABCDE"

See also

tolower
Parent topic: Functions for working with strings


trim

Purpose Remove all spaces from a string except for single spaces between words.

Syntax trim(text)

Arguments

Type | Name | Description
string | text | The string to be trimmed

Result

Type | Description
string | The string formed from text removing all spaces except for single spaces between words
Note:

The trim function is based on the replaceall function.

Examples To derive a field that replace multiple whitespace characters with a single space:

CommentField | trim(CommentField)
Returned faulty goods | Returned faulty goods
Missed appointment | Missed appointment
Engineer to visit: Monday | Engineer to visit: Monday
Resolved | Resolved
Parent topic: Functions for working with strings


Binnings

  • Boolean
  • DayFrom, WeekFrom, MonthFrom, YearFrom
  • DayMultipleFrom, WeekMultipleFrom, MonthMultipleFrom, YearMultipleFrom
  • DayMultipleNumBins, WeekMultipleNumBins, MonthMultipleNumBins, YearMultipleNumBins
  • DayMultiplePrePost, WeekMultiplePrePost, MonthMultiplePrePost, YearMultiplePrePost
  • DayMultipleTo, WeekMultipleTo, MonthMultipleTo, YearMultipleTo
  • DayMultipleWidth, WeekMultipleWidth, MonthMultipleWidth, YearMultipleWidth
  • DayPrePost, WeekPrePost, MonthPrePost, YearPrePost
  • DayRange, WeekRange, MonthRange, YearRange
  • DayTo, WeekTo, MonthTo, YearTo
  • EqualRange
  • EqualRangeWidth
  • NegativeNonNegative
  • PreDuringPost
  • PrePost
  • Sign
Parent topic: Field Derivation Language (FDL) reference


Boolean

Purpose Bin boolean [see Boolean data] values.

Parameters None

Result

Bin index | Values
1 | false
2 | true
3 | null [see The null value]
4 | unclassified
Parent topic: Binnings


DayFrom, WeekFrom, MonthFrom, YearFrom

Purpose Bin date values into a specified number of periods (days, weeks, months, or years) following a given date.

Parameters

Type | Name | Description
date | a ("start_date") | The start of the periodic portion of the binning
integer | n ("num_bins") | The number of periods (days, weeks, months, or years) in the periodic portion of the binning
Result
Bin index | Values
1 | dates earlier than a; the lower end bin [see End bins]
2, ..., n + 1 | the n consecutive periods following a
n + 2 | dates n periods after a and later; the upper end bin [see End bins]
n + 3 | null [see The null value]
n + 4 | unclassified

See also

DayRange, WeekRange, MonthRange, YearRange

DayTo, WeekTo, MonthTo, YearTo

Parent topic: Binnings


DayMultipleFrom, WeekMultipleFrom, MonthMultipleFrom, YearMultipleFrom

Purpose Bin date values into a specified number of periods following a given date, where a period is a specified number of days, weeks, months, or years.

Parameters

Type | Name | Description
date | a ("start_date") | The start of the periodic portion of the binning
integer | m ("width") | The number of units (days, weeks, months, or years) in a period
integer | n ("num_bins") | The number of bins in the periodic portion of the binning
Result
Bin index | Values
1 | dates earlier than a; the lower end bin [see End bins]
2, ..., n + 1 | the n consecutive periods (each of m units) following a
n + 2 | dates n x m units after a and later; the upper end bin [see End bins]
n + 3 | null [see The null value]
n + 4 | unclassified

See also

DayMultiplePrePost, WeekMultiplePrePost, MonthMultiplePrePost, YearMultiplePrePost

DayMultipleTo, WeekMultipleTo, MonthMultipleTo, YearMultipleTo

Parent topic: Binnings


DayMultipleNumBins, WeekMultipleNumBins, MonthMultipleNumBins, YearMultipleNumBins

Purpose Bin date values into approximately the specified number of periods between two given dates, where the period is a fixed multiple of the unit (day, week, month, or year).

Parameters

Type | Name | Description
date | a ("start_date") | The start of the periodic portion of the binning
date | b ("end_date") | The end of the periodic portion of the binning
integer | n ("num_bins") | The target number of periods (multiples of a day, week, month, or year) in the periodic portion of the binning

Result

Bin index | Values
1 | dates earlier than a; the lower end bin [see End bins]
2, ..., N - 3 | periods between a and b
N - 2 | dates b and later; the upper end bin [see End bins]
N - 1 | null [see The null value]
N | unclassified
Note:
  • These binnings are like the DayRange, WeekRange, MonthRange, and YearRange [see DayRange, WeekRange, MonthRange, YearRange] binnings, except that the period may be two or more units (days, weeks, months, or years), to yield approximately the target number of bins.
  • When the period is two or more units, bin N - 3 can be shorter than bins 2 to N - 4.

See also

DayMultipleWidth, WeekMultipleWidth, MonthMultipleWidth, YearMultipleWidth
Parent topic: Binnings


DayMultiplePrePost, WeekMultiplePrePost, MonthMultiplePrePost, YearMultiplePrePost

Purpose Bin date values into specified numbers of bins before and after a given reference date, where each bin is a given multiple of the unit (day, week, month, or year).

Parameters

Type | Name | Description
date | a ("ref_date") | The reference date for the binning
integer | m ("width") | The number of bins before and after the reference date
integer | n ("num_bins") | The number of units (days, weeks, months, or years) in each bin

Result

Bin index | Values
1 | dates earlier than n x m units before a; the lower end bin [see End bins]
2, ..., n + 1 | the n consecutive periods (each of m units) preceding a
n + 2, ..., 2n + 1 | the n consecutive periods (each of m units) following a
2n + 2 | dates n x m units after a and later; the upper end bin [see End bins]
2n + 3 | null [see The null value]
2n + 4 | unclassified

See also

DayMultipleFrom, WeekMultipleFrom, MonthMultipleFrom, YearMultipleFrom

DayMultipleTo, WeekMultipleTo, MonthMultipleTo, YearMultipleTo

DayPrePost, WeekPrePost, MonthPrePost, YearPrePost

PreDuringPost

PrePost

Parent topic: Binnings


DayMultipleTo, WeekMultipleTo, MonthMultipleTo, YearMultipleTo

Purpose Bin date values into a specified number of periods preceding a given date, where a period is a specified number of days, weeks, months, or years.

Parameters

Type | Name | Description
date | b ("end_date") | The end of the periodic portion of the binning
integer | m ("width") | The number of units (days, weeks, months, or years) in a period
integer | n ("num_bins") | The number of bins in the periodic portion of the binning
Result
Bin index | Values
1 | dates earlier than n x m units before a; the lower end bin [see End bins]
2, ..., n + 1 | the n consecutive periods (each of m units) preceding a
n + 2 | dates a and later; the upper end bin [see End bins]
n + 3 | null [see The null value]
n + 4 | unclassified

See also

DayMultipleFrom, WeekMultipleFrom, MonthMultipleFrom, YearMultipleFrom

DayMultiplePrePost, WeekMultiplePrePost, MonthMultiplePrePost, YearMultiplePrePost

Parent topic: Binnings


DayMultipleWidth, WeekMultipleWidth, MonthMultipleWidth, YearMultipleWidth

Purpose Bin date values into periods between two given dates, where the period is a specified multiple of the unit (day, week, month, or year).

Parameters

Type | Name | Description
date | a ("start_date") | The start of the periodic portion of the binning
date | b ("end_date") | The end of the periodic portion of the binning
integer | m ("width") | The number of units (days, weeks, months, or years) in a period

Result

Bin index | Values
1 | dates earlier than a; the lower end bin [see End bins]
2, ..., N - 3 | periods between a and b
N - 2 | dates b and later; the upper end bin [see End bins]
N - 1 | null [see The null value]
N | unclassified
Note:
  • These binnings are like the DayRange, WeekRange, MonthRange, and YearRange [see DayRange, WeekRange, MonthRange, YearRange] binnings, except that the period may be two or more units (days, weeks, months, or years).
  • When the period is two or more units, bin N - 3 can be shorter than bins 2 to N - 4.

See also

DayMultipleNumBins, WeekMultipleNumBins, MonthMultipleNumBins, YearMultipleNumBins
Parent topic: Binnings


DayPrePost, WeekPrePost, MonthPrePost, YearPrePost

Purpose Bin date values into specified numbers of periods (days, weeks, months, or years) preceding and following a given reference date.

Parameters

Type | Name | Description
date | a ("ref_date") | The reference date for the binning
integer | m ("before") | The number of periods (days, weeks, months, or years) to bin before the reference date
integer | n ("after") | The number of periods to bin after the reference date

Result

Bin index | Values
1 | dates earlier than m periods before a; the lower end bin [see End bins]
2, ..., m + 1 | the mconsecutive periods preceding a
m + 2, ..., m + n + 1 | the n consecutive periods following a
m + n + 2 | dates n periods after a and later; the upper end bin [see End bins]
m + n + 3 | null [see The null value]
m + n + 4 | unclassified

See also

DayMultiplePrePost, WeekMultiplePrePost, MonthMultiplePrePost, YearMultiplePrePost

PreDuringPost

PrePost

Parent topic: Binnings


DayRange, WeekRange, MonthRange, YearRange

Purpose Bin date values into periods (days, weeks, months, or years) between two given dates.

Parameters

Type | Name | Description
date | a ("start_date") | The start of the periodic portion of the binning
date | b ("end_date") | The end of the periodic portion of the binning
Result
Bin index | Values
1 | dates earlier than a; the lower end bin [see End bins]
2, ..., N - 3 | periods (days, weeks, months, or years) between a and b
N - 2 | dates b and later; the upper end bin [see End bins]
N - 1 | null [see The null value]
N | unclassified
Note:
  • If there is less than a complete period between a and b, bin 2 contains dates between a (inclusive) and b (exclusive).
  • If there is not an exact number of periods between a and b (but there is at least one complete period), the bin immediately preceding b is lengthened to accommodate the excess.

See also

DayFrom, WeekFrom, MonthFrom, YearFrom

DayTo, WeekTo, MonthTo, YearTo

Parent topic: Binnings


DayTo, WeekTo, MonthTo, YearTo

Purpose Bin date values into a specified number of periods (days, weeks, months, or years) preceding a given date.

Parameters

Type | Name | Description
date | b ("end_date") | The end of the periodic portion of the binning
integer | n ("num_bins") | The number of periods (days, weeks, months, or years) in the periodic portion of the binning
Result
Bin index | Values
1 | dates earlier than n periods before b; the lower end bin [see End bins]
2, ..., n + 1 | the n consecutive periods preceding b
n + 2 | dates b and later; the upper end bin [see End bins]
n + 3 | null [see The null value]
n + 4 | unclassified

See also

DayFrom, WeekFrom, MonthFrom, YearFrom

DayRange, WeekRange, MonthRange, YearRange

Parent topic: Binnings


EqualRange

Purpose Bin numeric values into a specified number of equal-width intervals.

Parameters

Type | Name | Description
real | a ("from") | The lower end of the equal-range portion of the binning
real | b ("to") | The upper end of the equal-range portion of the binning
integer | n ("num_bins") | The number of bins in the equal-range portion of the binning

Result

Bin index | Values
1 | ; the lower end bin [see End bins]
2, ..., n + 1 | [a, a + (b - a)/n), ..., [b - (b - a)/n, b)
n + 2 | ; the upper end bin [see End bins]
n + 3 | null [see The null value]
n + 4 | unclassified

See also

EqualRangeWidth
Parent topic: Binnings


EqualRangeWidth

Purpose Bin numeric values into intervals of a specified width.

Parameters

Type | Name | Description
real | a ("from") | The lower end of the equal-range portion of the binning
real | b ("to") | The upper end of the equal-range portion of the binning
real | r ("width") | The width of bins in the equal-range portion of the binning

Result

Bin index | Values
1 | ; the lower end bin [see End bins]
2, ..., N - 3 | equal-width bins of approximate width r
N - 2 | the upper end bin [see End bins]
N - 1 | null [see The null value]
N | unclassified
Note:

If a - b isn't an exact multiple of r, an approximation to r is used, so that the bins between a and b are of equal width.

See also

EqualRange
Parent topic: Binnings


NegativeNonNegative

Purpose Bin numeric values according to sign, grouping 0 with positive values.

Parameters None

Result

Bin index | Values
1 | ; that is, negative values
2 | ; that is, non-negative values
3 | null [see The null value]
4 | unclassified

See also

Sign
Parent topic: Binnings


PreDuringPost

Purpose Bin date values into pre-campaign, during-campaign, and post-campaign periods.

Parameters

Type | Name | Description
date | a ("pre_date") | The start of the pre-campaign period
date | b ("campaign_start_date") | The start of the campaign
date | c ("campaign_end_date") | The end of the campaign
date | d ("post_date") | The end of the post-campaign period
Result
Bin index | Values
1 | dates earlier than a; the lower end bin [see End bins]
2 | dates between a (inclusive) and b (exclusive)
3 | dates between b (inclusive) and c (exclusive)
4 | dates between c (inclusive) and d (exclusive)
5 | dates d and later; the upper end bin [see End bins]
6 | null [see The null value]
7 | unclassified

See also

DayMultiplePrePost, WeekMultiplePrePost, MonthMultiplePrePost, YearMultiplePrePost

DayPrePost, WeekPrePost, MonthPrePost, YearPrePost

PrePost

Parent topic: Binnings


PrePost

Purpose Bin date values into pre-campaign and post-campaign periods.

Parameters

Type | Name | Description
date | a ("pre_date") | The start of the pre-campaign period
date | b ("campaign_date") | The campaign date
date | c ("post_date") | The end of the post-campaign period

Result

Bin index | Values
1 | dates earlier than a; the lower end bin [see End bins]
2 | dates between a (inclusive) and b (exclusive)
3 | dates between b (inclusive) and c (exclusive)
4 | dates c and later; the upper end bin [see End bins]
5 | null [see The null value]
6 | unclassified

See also

DayMultiplePrePost, WeekMultiplePrePost, MonthMultiplePrePost, YearMultiplePrePost

DayPrePost, WeekPrePost, MonthPrePost, YearPrePost

PreDuringPost

Parent topic: Binnings


Sign

Purpose Bin numeric values according to sign.

Parameters None

Result

Bin index | Values
1 | ; that is, negative values
2 | 0
3 | ; that is, positive values
4 | null [see The null value]
5 | unclassified

See also

NegativeNonNegative
Parent topic: Binnings


FDL regular expressions

  • Regular expressions
  • Basic components of a regular expression
  • Regular-expression operators
Parent topic: Field Derivation Language (FDL) reference


Regular expressions

Regular expressions are for matching patterns in strings [see Datatypes]. A regular expression is a specially formatted string that represents a pattern of characters. For example, the regular expression "ar{1,2}y?$" represents "the letter 'a,' followed by one or two 'r's, possibly followed by 'y,' followed by the end of a string." (That pattern occurs in strings like "marry" and "jar" - but not in "may" or "jars.")

A regular expression consists of basic components [see Basic components of a regular expression] combined using operators [see Regular-expression operators].

If a regular expression (other than a subexpression) could match more than one portion of a string, it always matches the leftmost, longest candidate portion. For example, the regular expression "a[^ad]+" (representing "the letter 'a', followed by one or more letters other than 'a' or 'd'") matches "adaptationally." The matched portion is not "ation," as there are candidate portions further to the left. Neither is it "ap," because, although there are no candidates further to the left, there is a longer candidate portion starting at the same character.
  • To test a string for a regular expression match, use the match function.
  • To replace matched portions of a string with another string, use the replacefirst or replaceall function.
Note:
  • Regular expressions are typically (but not necessarily) literals, in which case they must be enclosed in double quotation marks, for example, "ar{1,2}y?$".

  • Miner/FDL uses Regular expression provided by the ICU library. We can link to http://userguide.icu-project.org/strings/regexp).

  • ICU Regular Expressions conform to Unicode Technical Standard #18 , Unicode Regular Expressions, level 1, and in addition include Default Word boundaries and Name Properties from level 2.

Parent topic: FDL regular expressions


Basic components of a regular expression

The basic components of a regular expression [see Regular expressions] are atoms, anchors, and back-references.

Atoms

An atom matches exactly one of a specified set of characters:
Atom | Character matched
. (match-any) | Any character
[...] (match-list) | Any one of the specified characters
[^...] (non-match-list) | Any character other than one of the specified characters
A character other than ., ^, $, \, [, ], or *, occurring outside a match-list or non-match-list | The character itself
., ^, $, \, [, ], or *, occurring outside a match-list or non-match-list | The character itself

A match-list or non-match-list can include simple characters, character ranges, and character classes. You cannot use character ranges or character classes except in a match-list or non-match-list.

A character range is a pair of characters separated by a hyphen and is equivalent to a list of all the characters in that range (within the character set). For example, "a-e" is equivalent to "abcde" in a match-list.

A character class is one of the following pre-defined tokens (where the enclosing brackets are additional to those enclosing the match-list or non-match-list):

Token | Matches
[:alnum:] | An alphanumeric character, that is an alphabetic character or decimal digit
[:alpha:] | An alphabetic character, that is, "A" — "Z" and "a" — "z"
[:blank:] | A tab or space character
[:cntrl:] | A control character
[:digit:] | A decimal digit, that is, "0" — "9"
[:graph:] | A printable character other than space
[:lower:] | A lowercase letter
[:print:] | A printable character or space
[:punct:] | A punctuation character
[:space:] | A whitespace character
[:upper:] | An uppercase character
[:xdigit:] | A hexadecimal digit, that is, "0" — "9," "A" — "F," and "a" — "f"
Note:
  • You can include a mixture of simple characters, character ranges, and character classes in a single match-list or non-match-list. For example, the match-list "[a-ex[:digit:]]" matches the lowercase letters "a" — "e" and "x," as well as decimal digits ("0" — "9").
  • A hyphen in a match-list or non-match-list stands for itself when it is (a) at the end of a range, (b) at the start of the match-list or non-match-list (in which case it can also serve as the start of a range), or (c) at the end of the match-list or non-match-list.

Anchors

The characters ^ and $ are anchors; they match the beginning and end of a string respectively.

For example, to match "The" occurring at the start of a string and nowhere else, you could use the regular expression "^The."

Parent topic: FDL regular expressions

Back-references

A back-reference is a backslash followed by a single digit n (other than 0). It matches exactly the same characters as the nth subexpression enclosed in \(...\).

For example,to match "yoyo," "dodo," etc. — but not "dojo" — you could use the regular expression "\(.o\)$1."

Note:
  • The nth back-referenced subexpression is always the subexpression beginning with the nth opening backslash/parenthesis (even if subexpressions are nested).
  • The empty subexpression "\(\)" can be useful in regular expressions involving alternation [see The alternation operator]. For example,

    \(fish\(\)\|profit\(\)\)-and-\(chips$2\|loss$3\)

    matches both "fish-and-chips" and "profit-and-loss," but not "fish-and-loss" or "profit-and-chips."


Regular-expression operators

An operator acts on one or two regular expressions [see Regular expressions] to create a new regular expression. The operators, from highest to lowest precedence, are the repetition operators [see Repetition operators], the concatenation operator [see The concatenation operator], and the alternation operator [see The alternation operator].

If there is a tie for precedence, operations are carried out from left to right.

Subexpressions enclosed in (...) are always evaluated first.

Parent topic: FDL regular expressions

Repetition operators

The repetition operators are unary and are written following their single operand.

Operator | Description
* (zero-or-more) | If a regular expression a matches one or more adjacent portions of a string, the regular expression a* matches the concatenation of those portions. It also matches any empty substring.
\+ (one-or-more) | If a regular expression a matches one or more adjacent portions of a string, the regular expression a\+ matches the concatenation of those portions.
\{m,n\} (0 [image] m [image] n) | If a regular expression a matches at least m and no more than n adjacent portions of a string, the regular expression a\{m,n\} matches the concatenation of those portions. If m=0, it also matches any empty substring.
\? (optional) | Equivalent to a\{0,1}, the regular expression a\? matches any empty substring, or any portion of a string that the regular expression a matches.
Note:

The "adjacent portions" mentioned in the definitions of *, \+, and \{...} are not necessarily identical strings. If you need to match exact repetitions, use back-references [see Back-references].

The concatenation operator

The concatenation operator is not actually written, but is implied whenever you write two regular expressions next to each other.

If regular expressions a and b match adjacent portions x and y of a string z (with x preceding y), the concatenation of a and b (written as a followed by b) matches the portion of z containing x and y.

Note:

Any string of non-special characters, that is, characters with no special meaning in a regular expression, serves as a regular expression that matches that string, because of the implicit concatenation operator.

In practice, most regular expressions consist of simple character strings, interspersed with a few special characters. For example, the regular expression "[SsDd]imple" matches the strings "Simple," "simple," "Dimple," and "dimple."

The alternation operator

The alternation operator "|" is a binary operator, written between its operands.

If either of the regular expressions a and b matches a portion of a string, the alternation a|b also matches that portion.


XML in Portrait Miner

  • XML in Portrait Miner


XML in Portrait Miner

To allow easy interchange of results with other applications, XML is used throughout Portrait Miner, according to the Portrait Miner XML schema definition,http://www.portraitsoftware.com

All XML inputs to the Portrait Miner data-build commands (and any Portrait Miner function that is implemented via a Portrait Miner data-build command) must be in the Portrait Miner namespace, http://support.portraitsoftware.com. The easiest way to ensure this is to include the attribute xmlns=" http://support.portraitsoftware.com " in the root element of the XML document.

XML files created by Portrait Miner automatically include an optional schemaLocation attribute that points to schemas at http://www.portraitsoftware.com/xml/qs7.1. If you use a schema-aware editor to create XML files, you can access these schemas directly from your Portrait Miner installation at:

<pmhome>/server/qs7.1/integration/schemas

(where <pmhome> is the Portrait Miner installation directory). You can also find examples of how to process these XML files at:

<pmhome>/server/qs7.1/etc/xslt

Parent topic: XML in Portrait Miner


Troubleshooting

  • "Why can't I open a focus?"
  • "Why are the axes in my graph unevenly subdivided?"
  • "Why is 'Keep Highlighted Segments' always grayed out?"
  • "Why does my text look different than when I typed it?"


"Why can't I open a focus?"

Possible reason | Solution
You already have a focus open. Decision Studio can only work with one focus at a time. | Before you can open a focus or create a new focus from a flat file or database table, you need to close your currently open focus: choose File>Close in the Decision Studio window.
Parent topic: Troubleshooting


"Why are the axes in my graph unevenly subdivided?"

Possible reason | Solution
Each axis in a crossdistribution or profile graph is subdivided according to the primary binning on the field that corresponds to the axis. Whether bins are shown with equal width is a property of this binning. (The exception is where the extent of a block in a given direction conveys information: in this case, the Binning Editor display setting has no effect, so as not to mislead.) | In the Binning Editor, select the required field and uncheck View>Histogram.
Parent topic: Troubleshooting


"Why is 'Keep Highlighted Segments' always grayed out?"

Possible reason | Solution
You are trying to keep highlighted segments in the Table Viewer, Crosstab Viewer, or Scorecard Builder. When a tool is linked [see Tool relationships] to follow one of these tools, the two tools share the same data source, regardless of whether anything is highlighted in the leading tool. | Try highlighting the same segments in a graphical visualization tool instead.
Parent topic: Troubleshooting


"Why does my text look different than when I typed it?"

Possible reason | Solution
There are characters in your text that cannot be translated into the ISO-8859-1 (Latin-1) character set. | Avoid text containing characters that cannot be translated into the ISO-8859-1 character set.
Parent topic: Troubleshooting


Copyright notices

  • Copyright notices


Copyright notices

Portrait Miner may contain the following software:

ANTLR

http://www.antlr.org

Apache Batik

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Copyright © 2000 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.
  4. The names "Batik" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.
  5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see http://www.apache.org.

Apriori algorithm implementation

Christian Borgelt, http://www.borgelt.net/apriori.html.

Open software redistributed under the terms of the GNU Lesser General Public License.

DOM4J

The DOM4J Project, http://www.dom4j.org.
Redistribution and use of this software and associated documentation ("Software"), with or without modification, are permitted provided that the following conditions are met:
  1. Redistributions of source code must retain copyright statements and notices. Redistributions must also contain a copy of this document.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. The name "DOM4J" must not be used to endorse or promote products derived from this Software without prior written permission of MetaStuff, Ltd. For written permission, please contact dom4j-info@metastuff.com.
  4. Products derived from this Software may not be called "DOM4J" nor may "DOM4J" appear in their names without prior written permission of MetaStuff, Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
  5. Due credit should be given to the DOM4J Project — http://www.dom4j.org

THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Copyright 2001 — 2004 © MetaStuff, Ltd. All Rights Reserved.

fmt

and http://www.cs.princeton.edu/software/cii/} String formatting library from the book C Interfaces and Implementations, Techniques for Creating Reusable Software by David R. Hanson.

The author of this software is David R. Hanson.

Copyright © 1994, 1995, 1996, 1997 by David R. Hanson. All Rights Reserved.

Permission to use, copy, modify, and distribute this software for any purpose, subject to the provisions described below, without fee is hereby granted, provided that this entire notice is included in all copies of any software that is or includes a copy or modification of this software and in all copies of the supporting documentation for such software.

THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, THE AUTHOR DOES MAKE ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.

David Hanson, drh@microsoft.com, http://www.research.microsoft.com/~drh/.

FreeTDS

http://www.freetds.org/.

Free software redistributed under Subsection 6b of the GNU Library General Public License.

getopt

This product (Portrait Miner) may include software developed by the University of California, Berkeley and its contributors, subject to the following permission notice:
Copyright © 1987, 1993, 1994 The Regents of the University of California. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. All advertising materials mentioning features or use of this software must display the following acknowledgement: This product includes software developed by the University of California, Berkeley and its contributors.
  4. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MemoryClassLoader from OpenEJB.org

Redistribution and use of this software and associated documentation ("Software"), with or without modification, are permitted provided that the following conditions are met:
  1. Redistributions of source code must retain copyright statements and notices. Redistributions must also contain a copy of this document.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. The name "OpenEJB" must not be used to endorse or promote products derived from this Software without prior written permission of The OpenEJB Group. For written permission, please contact info@openejb.org.
  4. Products derived from this Software may not be called "OpenEJB" nor may "OpenEJB" appear in their names without prior written permission of The OpenEJB Group. OpenEJB is a registered trademark of The OpenEJB Group.
  5. Due credit should be given to the OpenEJB Project (http://www.openejb.org/).

THIS SOFTWARE IS PROVIDED BY THE OPENEJB GROUP AND CONTRIBUTORS "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OPENEJB GROUP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Copyright 2001 — 2005 © The OpenEJB Group. All Rights Reserved.

Numerical Recipes

This product contains procedures based on routines in Numerical Recipes: The Art of Scientific Computing, published by Cambridge University Press, and are used by permission.

pthreads-win32

A POSIX threads library for Windowslong. Copyright © 2001 Ross P. Johnson. All rights reserved.

Open software redistributed under the terms of the GNU Lesser General Public License.

RPC/XDR

Copyright © 1986, Sun Microsystems, Inc. subject to the following permission notice:

Sun RPC is a product of Sun Microsystems, Inc. and is provided for unrestricted use provided that this legend is included on all tape media and as a part of the software program in whole or part. Users may copy or modify Sun RPC without charge, but are not authorized to license or distribute it to anyone else except as part of a product or program developed by the user.

SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.

Sun RPC is provided with no support and without any obligation on the part of Sun Microsystems, Inc. to assist in its use, correction, modification or enhancement.

SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC OR ANY PART THEREOF.

In no event will Sun Microsystems, Inc. be liable for any lost revenue or profits or other special, indirect and consequential damages, even if Sun has been advised of the possibility of such damages.

Sun Microsystems, Inc.

2550 Garcia Avenue

Mountain View, California 94043

Rx

Copyright © 1996 Tom Lord, Berkeley, CA USA, except portions of "POSIX Regex Functions" which are Copyright © 1995 Free Software Foundation, Inc.

Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.

Free software redistributed under Subsection 6b of the GNU Library General Public License.

Stat/Transfer

Copyright © 2003 Circle Systems, Inc.

Trang

Multi-format schema converter based on \rng. Copyright © 2002, 2003 Thai Open Source Software Center Ltd. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of the Thai Open Source Software Center Ltd nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

unixODBC

Open Source ODBC sub-system and an ODBC SDK for Linux, Mac OSX, and UNIX. unixODBC, http://www.unixodbc.org/.

Free software redistributed under Subsection 6b of the GNU Library General Public License.

Xerces Java Parser

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Copyright © 1999 — 2002 The Apache Software Foundation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.
  4. The names "Xerces" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.
  5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright © 1999, International Business Machines, Inc., http://www.ibm.com. For more information on the Apache Software Foundation, please see http://www.apache.org.

Xerces Java Parser

Copyright © 1995 — 1998 Jean-loup Gailly and Mark Adler.
Parent topic: Copyright notices

GNU LIBRARY GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright © 1991 Free Software Foundation, Inc.

59 Temple Place — Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software — to make sure the software is free for all its users.

This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it.

For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights.

Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library.

Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license.

The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such.

Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better.

However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries.

The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library.

Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  • 0. This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you".

    A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.

    The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".)

    "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.

  • 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  • 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    • a) The modified work must itself be a software library.
    • b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.
    • c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.
    • d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.

    In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  • 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.

    Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.

    This option is useful when you wish to copy part of the code of the Library into a program that is not a library.

  • 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.

    If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.

  • 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.

    However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.

    When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.

    If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)

    Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.

  • 6. As an exception to the Sections above, you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications.
    You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:
    • a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)
    • b) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution.
    • c) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.
    • d) Verify that the user has already received a copy of these materials or that you have already sent this user a copy.

    For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.

  • 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:
    • a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above.
    • b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.
  • 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  • 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.
  • 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  • 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  • 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  • 13. The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.

  • 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

    NO WARRANTY

  • 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  • 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Libraries

If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).

To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

    one line to give the library's name and an idea of what it does.
    Copyright (C) year name of author

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public
    License along with this library; if not, write to the
    Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA  02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names:
    Yoyodyne, Inc., hereby disclaims all copyright interest in
    the library 'Frob' (a library for tweaking knobs) written
    by James Random Hacker.

    signature of Ty Coon, 1 April 1990
    Ty Coon, President of Vice
That's all there is to it!

GNU LESSER GENERAL PUBLIC LICENSE

Version 2.1, February 1999

Copyright © 1991, 1999 Free Software Foundation, Inc.

59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software — to make sure the software is free for all its users.

This license, the Lesser General Public License, applies to some specially designated software packages — typically libraries — of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below.

When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things.

To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it.

For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights.

We protect your rights with a two-step method: (1) we copyright the library, and (2) we offer you this license, which gives you legal permission to copy, distribute and/or modify the library.

To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others.

Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license.

Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs.

When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library.

We call this license the "Lesser" General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances.

For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License.

In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system.

Although the Lesser General Public License is Less protective of the users' freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library.

The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, whereas the latter must be combined with the library in order to run.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  • 0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called "this License"). Each licensee is addressed as "you".

    A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.

    The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".)

    "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.

  • 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  • 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    • a) The modified work must itself be a software library.
    • b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.
    • c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.
    • d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.

    In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  • 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.

    Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.

    This option is useful when you wish to copy part of the code of the Library into a program that is not a library.

  • 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.

    If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.

  • 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.

    However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.

    When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.

    If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)

    Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.

  • 6. As an exception to the Sections above, you may also combine or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications.
    You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:
    • a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)
    • b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with.
    • c) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution.
    • d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.
    • e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy.

    For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.

  • 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:
    • a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above.
    • b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.
  • 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  • 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.
  • 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License.
  • 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  • 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  • 13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.

  • 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

    NO WARRANTY

  • 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  • 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Libraries

If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).

To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

    one line to give the library's name and an idea of what it does.
    Copyright (C) year name of author

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names:
    Yoyodyne, Inc., hereby disclaims all copyright interest in
    the library 'Frob' (a library for tweaking knobs) written
    by James Random Hacker.

    signature of Ty Coon, 1 April 1990
    Ty Coon, President of Vice
That's all there is to it!


Copyright

© 2016 Pitney Bowes Software Inc. All rights reserved.

This document may contain confidential and proprietary information belonging to Pitney Bowes Inc. and/or its subsidiaries and associated companies.

Portrait Software, the Portrait Software logo, Portrait, and Portrait Software's Portrait brand are the trademarks of Portrait Software International Limited and may not be used or exploited in any way without the prior express written authorization of Portrait Software International Limited.

Acknowledgement of trademarks

Other product names, company names, marks, logos and symbols referenced herein may be the trademarks or registered trademarks of their registered owners.

Portrait Software Support

If you need help with something that is not covered by this documentation, try the Knowledge Base on our web site. http://support.portraitsoftware.com and follow the links to your product.

You can also download other Portrait Software documentation from the site. If you do not have a username and password—or you have forgotten them—please contact us through one of the channels below.

If you find a problem with the use, installation, or documentation of this product, please contact us using any of the following methods:

Email:support@portraitsoftware.com

Phone

  • USA/Canada 1-800-335-3860 (toll-free)
  • Rest of world +44 800 840 0001

When you report a problem, it helps if you can tell us:

  • The name of the software application
  • The circumstances in which the problem arose
  • What error messages you saw (if any);
  • The version of the software that you were using.

Pitney Bowes Software Inc.

February 23, 2016


Online Help