Python command: Retrieval

The Retrieval commands in Python can be used for two separate functions:

 

Contents  [Hide]

 

Retrieve stored data

Note: The recommended method of setting options for a basic SPC or DMS retrieval is to use a Set Retrieval SPC or DMS action (rather than writing your own Python code - or using a Custom Code action - with the commands listed below). These recommended Set Retrieval actions are easier to use and help you to avoid coding errors.

 

There are 3 basic steps to retrieve data that is stored in GainSeeker:

    1. Specify the DMS or SPC standard - or the DMS process - that you want to analyze:

      • To retrieve DMS data, use the retrdms commands.

        • The minimum information needed to retrieve stored data is a DMS process, set by the retrdms.process command. You can only specify one DMS process for the retrieval.

        • If you want to analyze data for a specific DMS standard, you must additionally specify the DMS part number, set by the retrdms.partno command. You can only specify one DMS part number for the retrieval.

      • To retrieve SPC data, use the retrspc commands.

        • The minimum information needed to retrieve stored data is an SPC standard, set by the retrspc.partno command. You can only specify one SPC part number for the retrieval.

        • As with other GainSeeker analysis tools, bypassed data is not included by default.

    1. (optional) Use commands in the table below to set other retrieval settings such as date period, filter, or SPC data count.

    2. Work with the retrieval you have specified above:

      • (optional) Verify that the retrieval you have specified is valid, using the retrdms.validretrieval or retrspc.validretrieval command.

      • Retrieve data and statistics for the retrieval, using the Python statistics commands.

      • (optional) Perform the data retrieval again, using the retrdms.refresh() or retrspc.refresh() command.

Syntax

Example

Description/Remarks

retrspc.count

retrspc.partno = 1000

Get/Set the maximum number of data points for retrieving SPC data stored in GainSeeker.

Does not apply to external data.

retrdms.filter

retrspc.filter

retrdms.filter = "UDL3 = 'MOLDING'"

retrspc.filter = "Molding Dept"

Get/Set the filter for retrieving data stored in GainSeeker.:

  • You can specify a saved SPC or DMS filter using the filter name.

  • You can set a quick filter by using SQL query syntax.

Does not apply to external data.

retrdms.partno

retrspc.partno

retrdms.partno = "B-75 INSERT"

retrspc.partno = "D-34KW Diameter Z"

Get/Set the part number for retrieving data stored in GainSeeker.

Does not apply to external data.

retrdms.process

retrdms.process = "M-CUT OFF"

Get/Set the DMS process for retrieving data stored in GainSeeker.

If retrdms.partno is not set, all data for the process is retrieved.

Does not apply to external data.

retrdms.periodstr

retrspc.periodstr

retrdms.periodstr = '17'

Sets the date period for retrieval to 'One month ending today'.

 

retrspc.periodstr = '36'

Sets the date period for retrieval to 'One day ending now'.

Gets/Sets the date period for retrieving data stored in GainSeeker.

The default (None) is the configuration setting for the current user.

Other valid options include the numbers below, which must be specified as a string:

Today

1

Last n hours ending now

35

One day ending now

36

One week ending today

16

One month ending today

17

One quarter ending today

18

One year ending today

19

Today to default low

32

Current week

4

Current month

5

Current quarter

6

Current year

7

All dates

3

To specify a date period not on this list, use the Set Retrieval DMS or SPC actions to set the desired date period.

Does not apply to external data.

retrdms.refresh()

retrspc.refresh()

retrspc.refresh()

Force a new retrieval of stored GainSeeker data to get most recent data.

Does not apply to external data.

retrdms.useexternal

retrspc.useexternal

if retrdms.useexternal == True:

   print "retrieving external data."

Gets/Sets whether the retrieval will be loaded with an external dataset or with data stored in GainSeeker.

If False (the default), the retrieval is loaded using data stored in GainSeeker.

If True, the retrieval is loaded using an external dataset. Executing retrdms.external.addrow() automatically sets retrdms.useexternal = True , and executing retrspc.external.addrow() automatically sets retrspc.useexternal = True

retrdms.validretrieval

retrspc.validretrieval

isvalid = retrdms.validretrieval

If True, the information required for a retrieval is present:

  • For stored DMS data (retrdms.useexternal = False), a DMS process must be specified with retrdms.process

  • For stored SPC data (retrspc.useexternal = False), an SPC standard must be specified with retrspc.partno

  • For external DMS data, the only requirement is that  retrdms.useexternal = True

  • For external SPC data, the only requirement is that  retrspc.useexternal = True

This does not guarantee that data is returned.

Retrieve external data

For information on launching scripted external data analysis in the GainSeeker Charts module, see Charting External Data

For information on using a Python script to create a dataset for dashboard analysis, see Retrievals for dashboard controls.


There are two basic steps to writing a Python script that builds a dataset for GainSeeker analysis as external data:

    1. In your Python script, use standard Python commands to connect to your external data source and extract the data to analyze in GainSeeker.

      • While looping through the data in your external data source, use the GainSeeker Python commands below to translate that data into discrete GainSeeker data records. After building each record, add it to the external dataset using the retrdms.external.addrow() or retrspc.external.addrow() command.

      • When creating the external dataset, there are no separate Python commands to specify a date period, filter, or maximum number of data points. The external dataset created by your Python script should specify only the data you want to analyze.

      • Example scripts are provided below.

    2. (optional) In your Python script, retrieve data and statistics for the external dataset you have built, using the Python statistics commands. This can be especially helpful when testing and debugging your script.

DMS external data commands

Syntax

Example

Description/Remarks

retrdms.external.adddefect(description, count)

retrdms.external.adddefect("Scratch", 3)

Adds a defect entry for this record. You can add up to 20 defect entries per record.

Each defect entry specifies a brief description of the defect and a count of how many times this defect was found.

You can specify a defect description that does not already exist in DMS, unless you are performing cost analysis based on defect cost. (If defect cost is needed, you must specify a defect description that already exists in DMS.) If you save this external dataset in GainSeeker, any defect description that does not already exist in DMS will be added to GainSeeker.

retrdms.external.addrow()

retrdms.external.addrow()

Stores the fields as a record in the external dataset.

  • If no fields are set, default values will be used.

  • Duplicate DateTimes are automatically incremented (based on the Show time to configuration setting).

Retrieves information for the first standard and process.

Clears the following fields in preparation for the next record to be built:

  • retrdms.external.adddefect

  • retrdms.external.ncu

  • retrdms.external.note

  • retrdms.external.event

All other fields and properties for the external dataset are left unchanged (retrdms.external.autosumncu, retrdms.external.datetime, retrdms.external.partno, retrdms.external.process, retrdms.external.samplesize, and retrdms.external.settrace).

Sets retrdms.useexternal = True.

Resets the statistics for the external dataset to include this record.

retrdms.external.autosumncu

retrdms.external.autosumncu = True

If True, executing retrdms.external.adddefect will automatically update the sum of nonconforming units for the record (retrdms.external.ncu) with the count of the new defect being added.

The default for this property is determined in configuration settings.

retrdms.external.clear()

retrdms.external.clear()

Clears all records and statistics for the external dataset.

retrdms.external.datetime

retrdms.external.datetime = "10/30/2017 16:10:32"

retrdms.external.datetime = hsidate.dbdatetimestr()

Gets/Sets the DateTime field for this record (either in GainSeeker database format or international format).

If not set:

  • for the first record in the external dataset, the computer date and time will be used.

  • for any other record, the previous record's DateTime will be incremented (based on the Show time to configuration setting) and used.

There are three typical strategies for setting DateTimes in the external dataset:

  • Strategy 1:  Don't set the DateTime.

    • GainSeeker will apply the computer date and time to the first record and increment it for the other records in the dataset.

  • Strategy 2:  Only set the DateTime for the first record.

    • GainSeeker will increment that DateTime for the other records in the dataset.

  • Strategy 3:  Set the DateTime for each record.

    • When your source data already specifies a Date/Time for each sample, it makes sense to show that in your external dataset.

retrdms.external.event

retrdms.external.event = "Broken"

Gets/Sets the Event field for this record.

Defaults to an empty string.

You can specify a DMS Event that does not already exist in GainSeeker. If you save this external dataset in GainSeeker, any DMS Event that does not already exist in GainSeeker will be removed from this data record.

retrdms.external.ncu

retrdms.external.ncu = 2

Gets/Sets the NCU field (number of NonConforming Units) for this record.

Defaults to zero and cannot be greater than the sample size for the record.

If retrdms.external.autosumncu is True, do not use this command to manually set the number of nonconforming units. (Manually setting the NCU when autosumncu is True can produce unexpected results.)

retrdms.external.note

retrdms.external.note = "Halted 10 minutes for fire drill."

Gets/Sets the Note field for this record.

Defaults to an empty string.

retrdms.external.partno

retrdms.external.partno = "Prototype 17"

Gets/Sets the Part Number field for this record.

If left blank, will be set to "External Data".

You should only specify one Part Number for the dataset. (Specifying multiple Part Numbers can produce unexpected results.)

You can specify a DMS standard (combination of this Part Number and retrdms.external.process) that does not already exist in GainSeeker. If you save this external dataset in GainSeeker and the DMS standard does not exist, GainSeeker will offer to create the standard for you.

The first time you use retrdms.external.addrow() to add a record to the external dataset, GainSeeker will retrieve the standard you specify (if it exists).

retrdms.external.process

retrdms.external.process = "Drying"

Gets/Sets the Process field for this record.

If left blank, will be set to "External Data".

You should only specify one Process for the dataset. (Specifying multiple Processes can produce unexpected results.)

You can specify a Process that does not already exist in GainSeeker. If you save this external dataset in GainSeeker and the Process does not exist, GainSeeker will offer to create the DMS standard for you (including the Process).

The first time you use retrdms.external.addrow() to add a record to the external dataset, GainSeeker will retrieve the process you specify (if it exists).

retrdms.external.samplesize

retrdms.external.samplesize = 25

Gets/Sets the Sample Size field for this record.

Defaults to zero.

There are two typical strategies for setting the Sample Sizes in the external dataset:

  • Strategy 1:  Only set the Sample Size for the first record.

    • If you don't change the Sample Size, subsequent records in the dataset will use the same value.

  • Strategy 2:  Set the Sample Size for each record.

    • When your source data already specifies a Sample Size for each sample, it makes sense to use that in your external dataset.

retrdms.external.settrace(index, value)

retrdms.external.settrace(4, "Dryer 3")

Sets a traceability field value for this record.

The index specifies which traceability field you are setting and must be an integer from 1 to 48.

Traceability fields are empty by default.

For any one traceability field, there are two typical strategies for setting the traceability values in the external dataset:

  • Strategy 1:  Only set the traceability value for the first record.

    • If you don't change the value for this traceability field, subsequent records in the dataset will use the same value.

  • Strategy 2:  Set the traceability value for each record.

    • When your source data already specifies a traceability value for each sample, it makes sense to use that in your external dataset.

Example DMS script

#These will be applied to the entire dataset

retrdms.external.partno =
"14861"
retrdms.external.process =
"Shipping"
retrdms.external.settrace(
1, "Lot 45173") #Lot traceability
retrdms.external.samplesize =
10
retrdms.external.autosumncu =
False

#Individual records

retrdms.external.datetime =
"8/30/2017 07:30:00"
retrdms.external.settrace(
2, "1") #Shift traceability, shift 1
retrdms.external.ncu =
2
retrdms.external.adddefect(
"Wrong Label", 2)
retrdms.external.adddefect(
"Postage Error", 1)
retrdms.external.addrow()

retrdms.external.datetime =
"8/30/2017 15:30:00"
retrdms.external.settrace(
2, "2") #Shift traceability, shift 2
#no defects or nonconforming units in this sample
retrdms.external.addrow() 

retrdms.external.datetime =
"8/30/2017 23:30:00"
retrdms.external.settrace(
2, "3") #Shift traceability, shift 3
retrdms.external.ncu =
4
retrdms.external.adddefect(
"Postage Error", 4)
retrdms.external.event =
"New staff"
retrdms.external.note =
"Training new personnel"
retrdms.external.addrow()

#Debug script to show external dataset
mypartnos = statdms.data.partno()
myprocesses = statdms.data.process()
mylots = statdms.data.trace(
1)
mysmplsizes = statdms.data.samplesize()
mydatetimes = statdms.data.datetimedisp()
myshifts = statdms.data.trace(
2)
myncus = statdms.data.ncu()
mynumgood = statdms.data.numgood()
mydefect01 = statdms.data.defect(
1)
mydefctcount01 = statdms.data.defectcnt(
1)
mydefect02 = statdms.data.defect(
2)
mydefctcount02 = statdms.data.defectcnt(
2)
myevents = statdms.data.eventdms()

SPC external data commands

Syntax

Example

Description/Remarks

retrspc.external.adddata(value)

retrspc.external.adddata(23.526)

Sets the measurement value in the next Data field for this record. Also increments the value of the Subgroup Size for this record (see retrspc.external.subgroupsize).

Value can be either a number or None (for a measurement that is missing from the subgroup).

GainSeeker does not check for real-time failures in external SPC data, but you can perform your own checks and manually flag this record with real-time failure codes. See retrspc.external.rtf .

For a different method of setting measurement values for this record, see retrspc.external.setdata .

retrspc.external.addrow()

retrspc.external.addrow()

Stores the fields as a record in the external dataset.

  • If no fields are set, default values will be used.

  • Duplicate DateTimes are automatically incremented (based on the Show time to configuration setting).

Retrieves information for the first standard.

Clears the following fields in preparation for the next record to be built:

  • retrspc.external.adddata / retrspc.external.setdata

  • retrspc.external.anchorpoint

  • retrspc.external.note

  • retrspc.external.rtf

  • retrspc.external.setactiontaken

  • retrspc.external.setcause

  • retrspc.external.setevent

  • retrspc.external.subgroupsize

All other fields and properties for the external dataset are left unchanged (retrspc.external.datetime, retrspc.external.partno, and retrspc.external.settrace).

Sets retrspc.useexternal = True.

Resets the statistics for the external dataset to include this record.

All other fields and properties for the external dataset are left unchanged.

retrspc.external.anchorpoint

retrspc.external.anchorpoint = True

Gets/Sets if the record is an anchor point.

Defaults to False.

Possible values are True or False.

retrspc.external.clear()

retrspc.external.clear()

Clears all records and statistics for the external dataset.

retrspc.external.datetime

retrspc.external.datetime = "10/30/2017 16:10:32"

retrspc.external.datetime = hsidate.dbdatetimestr()

Gets/Sets the DateTime field for this record (either in GainSeeker database format or international format).

If not set:

  • for the first record in the external dataset, the computer date and time will be used.

  • for any other record, the previous record's DateTime will be incremented (based on the Show time to configuration setting) and used.

There are three typical strategies for setting DateTimes in the external dataset:

  • Strategy 1:  Don't set the DateTime.

    • GainSeeker will apply the computer date and time to the first record and increment it for the other records in the dataset.

  • Strategy 2:  Only set the DateTime for the first record.

    • GainSeeker will increment that DateTime for the other records in the dataset.

  • Strategy 3:  Set the DateTime for each record.

    • When your source data already specifies a Date/Time for each sample, it makes sense to show that in your external dataset.

retrspc.external.note

retrspc.external.note = "Halted 10 minutes for fire drill."

Gets/Sets the Note field for this record.

Defaults to an empty string.

retrspc.external.partno

retrspc.external.partno = "Prototype 17"

Gets/Sets the Part Number field (the name of the SPC standard) for this record.

If left blank, will be set to "External Data".

You should only specify one Part Number for the dataset. (Specifying multiple Part Numbers can produce unexpected results.)

You can specify an SPC standard that does not already exist in GainSeeker. If you save this external dataset in GainSeeker and the SPC standard does not exist, GainSeeker will offer to create the standard for you.

The first time you use retrspc.external.addrow() to add a record to the external dataset, GainSeeker will retrieve the standard you specify (if it exists).

retrspc.external.rtf

retrspc.external.rtf = 16386

retrspc.external.note = "X-bar below control limit | Range run above mean"

Flags this data record with real-time failure codes 2 (X-bar below control limit) and 16384 (Range run above mean), and sets meaningful descriptions of the failures in the note for this record.

Gets/Sets the real-time failure value for this record.

Defaults to zero (no failures).

GainSeeker does not check for real-time failures when external data is added, but you can perform your own checks* and manually flag this record with real-time failure codes. For a reference of the failures and their associated code numbers, see Real-time Failure codes. These codes are used when displaying real-time failure colors on the dashboard grid and on the Monitor Table.

Please note that flagging a record with real-time failure codes does not automatically set a failure note for the record. If you flag this record with real-time failure codes, you should also add to the failure note using retrspc.external.note :

  • When one data record has both a real-time failure flag and a note, it will be displayed on a Control Chart using the "Failure Note" symbol. With the failure flag but no note, this record will be displayed like "normal" data with no real-time failures.

  • The failure note should briefly describe the failure(s) for the record, so that the user can understand why it has been flagged with real-time failures.

* As an alternative to programming your own real-time checks, you could use the following strategy to let GainSeeker do this work for you:

  1. Manually create an SPC standard for this data, and set the real-time checks that GainSeeker should perform for you.
  2. Write a Python script that:
    1. first deletes all data for this new SPC standard,
    2. then reads only the data you want to analyze now
    3. and uses the dataspc commands (instead of the retrspc.external commands) to store that data in GainSeeker.
  3. Use the GainSeeker Inspections module to execute this script as a standalone script.
    (This data that you just imported will only exist temporarily in GainSeeker, because the script will delete this data the next time you run it.)
  4. Use the GainSeeker Charts module to analyze this stored data.

retrspc.external.setactiontaken(description, shortcode)

retrspc.external.setactiontaken("Replaced Filter", "RF")

Sets the Action Taken field for this record.

Both arguments default to empty strings.

The shortcode is used for display on a Control chart. It must be 1-4 characters long.

You can specify an Action Taken that does not already exist in GainSeeker. If you save this external dataset in GainSeeker, any Action Taken that does not already exist in GainSeeker will be removed from this data record.

retrspc.external.setcause(description, shortcode)

retrspc.external.setcause("Clogged Filter", "CF")

Sets the Cause field for this record.

Both arguments default to empty strings.

The shortcode is used for display on a Control chart. It must be 1-4 characters long.

You can specify a Cause that does not already exist in GainSeeker. If you save this external dataset in GainSeeker, any Cause that does not already exist in GainSeeker will be removed from this data record.

retrspc.external.setdata(index, value)

retrspc.external.setdata(4, 23.526)

Sets the fourth measurement in this subgroup to 23.526 . If Subgroup Size field is less than four, raises it to four.

Sets the measurement value for the Data field specified by index.

Index must be an integer from 1 to 72. It tells GainSeeker which of the Data fields in the subgroup should be filled with the measurement value.

If the index is greater than the Subgroup Size for this record (see retrspc.external.subgroupsize), this also raises the Subgroup Size.

Data fields are empty by default.

Value can be either a number or None (for a measurement that is missing from the subgroup).

GainSeeker does not check for real-time failures in external SPC data, but you can perform your own checks and manually flag this record with real-time failure codes. See retrspc.external.rtf .

For a different method of setting measurement values for this record, see retrspc.external.adddata .

retrspc.external.setevent(description, shortcode)

retrspc.external.setevent("Insufficient Oxygen", "O2")

Sets the Event field for this record.

Both arguments default to empty strings.

The shortcode is used for display on a Control chart. It must be 1-4 characters long.

You can specify an Event that does not already exist in GainSeeker. If you save this external dataset in GainSeeker, any Event that does not already exist in GainSeeker will be removed from this data record.

retrspc.external.settrace(index, value)

retrspc.external.settrace(4, "Dryer 3")

Sets a traceability field value for this record.

The index specifies which traceability field you are setting and must be an integer from 1 to 48.

Traceability fields are empty by default.

For any one traceability field, there are two typical strategies for setting the traceability values in the external dataset:

  • Strategy 1:  Only set the traceability value for the first record.

    • If you don't change the value for this traceability field, subsequent records in the dataset will use the same value.

  • Strategy 2:  Set the traceability value for each record.

    • When your source data already specifies a traceability value for each sample, it makes sense to use that in your external dataset.

retrspc.external.subgroupsize

mysubsize = retrspc.external.subgroupsize

Gets the Subgroup Size of this record.

The Subgroup Size is incremented automatically when adding data values with retrspc.external.adddata or retrspc.external.setdata .

Example SPC script

#These will be applied to the entire dataset

retrspc.external.partno =
"14861 weight"
retrspc.external.settrace(
1, "Lot 45173") #Lot traceability

#Individual records

retrspc.external.datetime =
"8/30/2017 07:30:00"
retrspc.external.settrace(
2, "1") #Shift traceability, shift 1
retrspc.external.adddata(
13.17) #use adddata command
retrspc.external.adddata(
13.16)
retrspc.external.adddata(
13.21)
retrspc.external.addrow()

retrspc.external.datetime =
"8/30/2017 15:30:00"
retrspc.external.settrace(
2, "2") #Shift traceability, shift 2
retrspc.external.setdata(
1, 13.15) #use setdata command
retrspc.external.setdata(
2, 13.13)
retrspc.external.setdata(
3, 13.22)
retrspc.external.setevent(
"Power Outage", "PWR")
retrspc.external.addrow()

retrspc.external.datetime =
"8/30/2017 23:30:00"
retrspc.external.settrace(
2, "3") #Shift traceability, shift 3
retrspc.external.setdata(
1, 13.29
retrspc.external.setdata(
2, 13.75)
retrspc.external.setdata(
3, 13.24)
retrspc.external.rtf =
1024
retrspc.external.note =
"Sample #2 violates Upper spec limit"
retrspc.external.addrow()

retrspc.external.datetime =
"8/31/2017 07:30:00"
retrspc.external.settrace(
2, "1") #Shift traceability, shift 1
retrspc.external.setdata(
1, 13.27
retrspc.external.setdata(
3, 13.24)
retrspc.external.note =
"Sample #2 removed from lab before weight checks could be performed."
retrspc.external.addrow()

#Debug script to show external dataset
mypartnos = statspc.data.partno()
mylots = statspc.data.trace(
1)
mydatetimes = statspc.data.datetimedisp()
myshifts = statspc.data.trace(
2)
mydata = statspc.data.datapts()
myevents = statspc.data.eventspc()
myrtfs = statspc.data.rtfstr()