This repository has been archived by the owner. It is now read-only.
A cancer staging library for Windows applications.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
DirectTNMStaging_APP
Install
SupportFiles
SupportFilesx64
TNMStagingDLL
TNMStagingTests
TNMStgIntegrationTests
ZipUtils
gtest/gtest-1.7.0
jsoncpp
zlib_library
.gitattributes
.gitignore
README.md
TNMStaging.sln

README.md

Announcement

The C++ Staging Library will not be updated for the upcoming EOD staging algorithm and any TNM version beyond 1.6. A new staging library, written in C#, is now available. It is highly recommended that you switch to the C# library. The C# library currently supports the Collaborative Stage, TNM stage, and EOD staging algorithms.

The new C# library can be found here: https://github.com/imsweb/staging-client-csharp.

staging-client-cpp

A cancer staging library created using C++.

Supported Staging Algorithms

TNM

TNM is a widely accepted system of cancer staging. TNM stands for Tumor, Nodes, and Metastasis. T is assigned based on the extent of involvement at the primary tumor site, N for the extent of involvement in regional lymph nodes, and M for distant spread. Clinical TNM is assigned prior to treatment and pathologic TNM is assigned based on clinical information plus information from surgery. The clinical TNM and the pathologic TNM values are summarized as clinical stage group or pathologic stage group.

For each cancer site, or schema, valid values, definitions, and registrar notes are provided for clinical TNM and stage group, pathologic TNM and stage group, and relevant Site-Specific Factors (SSFs).

TNM categories, stage groups, and definitions are based on the Union for International Cancer Control (UICC) TNM 7th edition classification. UICC 7th edition and AJCC 7th edition TNM categories and stage groups are very similar; however, there are some differences.

WARNING: SEER Primary Tumor, SEER Regional Nodes, and SEER Mets not used in 2016!!

In 2016, SEER Summary Stage 2000 will continue to be used. For those schemas and site/histology combinations that are not defined in TNM, SEER Summary Stage 2000 should be collected manually.

NCI will be developing SEER Summary Stage 2017, which will be effective for diagnosis year 2017. In preparation for SEER Summary Stage 2017, three data fields have been defined, SEER Primary Tumor, SEER Regional Nodes and SEER Mets. Some work has been done to define these fields, but they do NOT apply in 2016 and should be ignored. Do not utilize these fields for data collection in 2016. Only use the SEER Summary Stage 2000 directly coded field.

Versions supported:

  • 1.6 (released February 2018)

Collaborative Staging

Collaborative Stage is a unified data collection system designed to provide a common data set to meet the needs of all three staging systems (TNM, SEER EOD, and SEER SS). It provides a comprehensive system to improve data quality by standardizing rules for timing, clinical and pathologic assessments, and compatibility across all of the systems for all cancer sites.

Versions supported:

  • 02.05.50 (originally released October 2013)

Download

To download the latest 64-bit staging library.

To download the latest 32-bit staging library.

Each download zip file contains the TNM Staging DLL and associated files. A Stage Viewer Windows program is also included. For more information, please reference the accompanying readme.txt file. Detailed documentation on how to use the DLL can be found in the wiki.

Usage

The staging library was written in C++ but has a C-style interface. The generic interface style was selected in order to be able to reach the widest audience possible.

More detailed documentation can be found in the Wiki

Reporting a Problem

If you encounter a discrepancy with either the staging library or the Windows Stage Viewer, please report it via the issues link at the top of this page.

Loading a Staging algorithm

Everything starts with loading a Staging algorithm into memory. After an algorithm is loaded into memory, then all library APIs that retrieve algorithm information or stage cases can be used on that specific algorithm. All previously mentioned algorithms have been embedded into the library so there are no extraneous files.

For example, to load the TNM version 1.5 algorithm:

int iResult = TNMStage_LoadAlgorithm("tnm", "1.5");

Schemas

Schemas represent sets of specific staging instructions. Determining the schema to use for staging is based on primary site, histology and sometimes additional discriminator values. Schemas include the following information:

  • schema identifier (i.e. "prostate")
  • algorithm identifier (i.e. "tnm")
  • algorithm version (i.e. "1.5")
  • name
  • title, subtitle, description and notes
  • schema selection criteria
  • input definitions describing the data needed for staging
  • list of table identifiers involved in the schema
  • a list of initial output values set at the start of staging
  • a list of mappings which represent the logic used to calculate staging output

To get a list of all schema identifiers from the TNM version 1.5 algorithm:

const char *sSchemaId;
int iNumSchemas = TNMStage_get_total_num_schemas("tnm", "1.5");
for (int iSchemaOffset = 0; iSchemaOffset < iNumSchemas; iSchemaOffset++)
    sSchemaId = TNMStage_get_schema_id_using_offset("tnm", "1.5", iSchemaOffset); 

Tables

Tables represent the building blocks of the staging instructions specified in schemas. Tables are used to define schema selection criteria, input validation and staging logic.

Tables include the following information:

  • table identifier (i.e. "extension_bar")
  • algorithm identifier (i.e. "tnm")
  • algorithm version (i.e. "1.5")
  • name
  • title, subtitle, description, notes and footnotes
  • list of column definitions
  • list of table data

To get a list of all table identifiers in the TNM version 1.5 algorithm:

const char *sTableId;
int iNumTables = TNMStage_get_total_num_tables("tnm", "1.5");
for (int iTableOffset = 0; iTableOffset < iNumTables; iTableOffset++)
    sTableId = TNMStage_get_table_id_using_offset("tnm", "1.5", iTableOffset);

That list will be quite large. To get a list of table indentifiers involved in a particular schema:

const char *sTableId;
int iInvolvedTables = TNMStage_get_schema_num_involved_tables("tnm", "1.5", "rectum"); 
for (int iTableOffset = 0; iTableOffset < iInvolvedTables; iTableOffset++)
   sTableId = TNMStage_get_schema_involved_table_id("tnm", "1.5", "rectum", iTableOffset);

To obtain information on a single table by identifer,

const char *sTableName = TNMStage_get_table_name("tnm", "1.5", "extension_bar");
const char *sTableTitle = TNMStage_get_table_title("tnm", "1.5", "extension_bar");
etc..

Lookup a schema

A common operation is to lookup a schema based on primary site, histology and optionally one or more discriminators.

Using TNM Staging as an example, here is a lookup based on site and histology.

int iNumSchemas = TNMStage_get_num_schemas("tnm", "1.5", "C629", "9231");
const char *sSchemaId = TNMStage_get_schema_id("tnm", "1.5", "C629", "9231", "");
EXPECT_EQ(1, iNumSchemas);
EXPECT_STREQ("testis", sSchemaId);

If the TNMStage_get_num_schemas call returns a 1, then the site-histology combination went to one schema. If it indicates more than one schema, then it needs a discriminator. In the TNM Staging example, the fields ssf25 and sex are discriminators. Other staging algorithms may use different sets of discriminators that can be determined based on the result.

int iNumSchemas = TNMStage_get_num_schemas("tnm", "1.5, "C111", "8200");
EXPECT_EQ(2, iNumSchemas);

const char *sDiscriminatorKey = TNMStage_get_discrim_key("tnm", "1.5", "C111", "8200");
EXPECT_STREQ("ssf25", sDiscriminatorKey);

// To obtain the table id that the discriminator applies to, the following API may be used.
// Once the table id is obtained, a list of possible discriminator values can be displayed.
const char *sDiscriminatorTableId = TNMStage_get_discriminator_table_id("tnm", "1.5", "C111", "8200");

// Once a discriminator value is selected you can supply the selected discriminator value to the API call
const char *sSchemaId = TNMStage_get_schema_id("tnm", "1.5", "C111", "8200", "010");
EXPECT_STREQ("nasopharynx", sSchemaId);

If you want to know the specific schemas that site C111 and histology 8200 apply to, then you can use the following calls:

const char *pSchemaId;
int iNumSchemas = TNMStage_get_schema_id("tnm", "1.5", "C111", "8200");
for (int iSchemaIndex = 0; iSchemaIndex < iNumSchemas; iSchemaIndex++)
    pSchemaId = TNMStage_get_app_schema_ids("tnm", "1.5", "C111", "8200", iSchemaIndex);

Calculate stage

Staging a case requires first knowing which schema you are working with. Once you have the schema, you can then obtain a list of fields (keys) that are required for staging the specific schema.

A tnm_datacard structure is used to hold input values to make TNM staging calls. All inputs to staging should be set in the tnm_datacard structure. The structure can then be passed to that staging API. All staging results are added to the structure. The results include:

  • output - all output values resulting from the calculation
  • errors - a list of errors and their descriptions
  • staging path - an ordered list of the tables that were used in the calculation

Each algorithm has a specific datacard structure which contains the associated inputs and outputs for the algorithm staging. For Collaborative Staging, use cs_datacard. For TNM, use the tnm_datacard.

tnm_datacard_v1 *tnm_dc = new tnm_datacard_v1;
TNMStage_clear_tnm_datacard(tnm_dc);

TNMStage_update_tnm_datacard("tnm", "1.5", "site", "C510", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "hist", "8093", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "year_dx", "2016", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "behavior", "3", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "nodes_pos", "00", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "systemic_surg_seq", "0", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "radiation_surg_seq", "0", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "clin_t", "c1", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "clin_n", "c0", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "clin_m", "c0", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "path_t", "p1", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "path_n", "p0", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "path_m", "c0", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "clin_stage_group_direct", "1", tnm_dc);
TNMStage_update_tnm_datacard("tnm", "1.5", "path_stage_group_direct", "1", tnm_dc);

// stage the case
TNMStage_stage_tnm_dc("tnm", "1.5", tnm_dc);

EXPECT_STREQ("1.5",TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "derived_version", tnm_dc));
EXPECT_STREQ("p1", TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "combined_t", tnm_dc));
EXPECT_STREQ("c0", TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "combined_m", tnm_dc));
EXPECT_STREQ("p0", TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "combined_n", tnm_dc));
EXPECT_STREQ("1",  TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "combined_stage_group", tnm_dc));
EXPECT_STREQ("1",  TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "clin_stage_group", tnm_dc));
EXPECT_STREQ("1",  TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "path_stage_group", tnm_dc));
EXPECT_STREQ("2",  TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "source_t", tnm_dc));
EXPECT_STREQ("2",  TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "source_n", tnm_dc));
EXPECT_STREQ("1",  TNMStage_get_tnm_datacard_output_field_value("tnm", "1.5", "source_m", tnm_dc));

delete tnm_dc;

About SEER

The Surveillance, Epidemiology and End Results (SEER) Program is a premier source for cancer statistics in the United States. The SEER Program collects information on incidence, prevalence and survival from specific geographic areas representing 28 percent of the US population and reports on all these data plus cancer mortality data for the entire country.