Indicators

The PyGranta BoM Analytics API can be used to determine compliance against one or more indicators. An indicator essentially represents a legislation with a threshold. If a substance appears in a certain item, either directly or indirectly, in a quantity that exceeds that threshold, the item is non-compliant with that indicator. In cases where the legislation defines a per-substance threshold (for example, RoHS), then this per-substance threshold is used instead.

Indicators can include a list of legislations, in which case a substance is impacted by the indicator if it is impacted by one or more legislations included in that indicator.

There are two different types of indicator, and they compute compliance in slightly different ways. It is therefore important to understand the differences between them. For more information, see the Restricted Substances Reports User Guide supplied with Granta MI Restricted Substances Reports.

RoHS indicator

class RoHSIndicator(*, name, legislation_ids, default_threshold_percentage=None, ignore_exemptions=False)

Provides the indicator object that represents RoHS-type compliance of a BoM object against one or more legislations.

Other RoHSIndicator objects with results can be compared, with ‘less compliant’ indicators being greater than ‘more compliant’ indicators.

Parameters:

namestr

Name of the indicator that is to identify the indicator in the query result.

legislation_idslist[str]

New in version 2.0.

Legislations against which compliance will be determined. Legislations are identified based on their Legislation ID attribute value.

Important

This argument replaces legislation_names, which has been removed in version 2.0.

When updating scripts from version 1.x, replace the legislation_names argument with the legislation_ids argument and ensure the value provided is a list of Legislation ID attribute values.

default_threshold_percentagefloat, optional

Concentration of substance that is to be determined to be non-compliant. The default is None. This parameter is only used if the legislation doesn’t define a specific threshold for the substance.

ignore_exemptionsbool, optional

Whether to consider exemptions added to parts when determining compliance against this indicator. The default is True.

Raises:

TypeError

Error to raise if two indicators of different types are compared.

ValueError

Error to raise if two indicators are compared and both don’t have a result flag.

Notes

The RoHS indicator is designed to be used with RoHS-type legislations such as RoHS and RoHS China. However, usage is not enforced. Substances marked as Process Chemicals [1] are always ignored, and exceptions are supported (unless explicitly ignored by specifying ignore_exemptions=True when creating the indicator). The possible result flags for the indicator distinguish between an item being compliant, compliant with exemptions, or non-compliant.

Examples

>>> indicator = RoHSIndicator(name='RoHS substances',
...                           legislation_ids=["RoHS"],
...                           default_threshold_percentage=0.1,
...                           ignore_exemptions=True)
>>> indicator
<RoHSIndicator, name: Tracked substances>

>>> query = MaterialComplianceQuery.with_indicators([indicator])...
>>> result: MaterialComplianceQueryResult  # Perform a compliance query
>>> indicator_result = result.compliance_by_indicator['Tracked substances']
>>> indicator_result
<RoHSIndicator, name: Tracked substances, flag: RoHSFlag.RohsNonCompliant>

>>> indicator_result <= indicator.available_flags['RohsCompliantWithExemptions']
False  # The material is not compliant with the legislations in the Indicator

Attributes:

available_flagsType[RoHSFlag]

Provides permitted RoHS flag states.

enum RoHSFlag(value)

Provides permitted RoHS flag states.

A larger value means that the item is less compliant. The further down the list the compliance result appears, the worse it is.

For more information, see the Restricted Substances Reports User Guide.

Valid values are as follows:

RohsNotImpacted = <RoHSFlag.RohsNotImpacted: 1>

This substance is not impacted by the specified legislations. Substance is not impacted.

RohsBelowThreshold = <RoHSFlag.RohsBelowThreshold: 2>

This substance is impacted by the specified legislations, but it appears in the parent item in a quantity below that specified by the indicator. Substance is below threshold.

RohsCompliant = <RoHSFlag.RohsCompliant: 3>

This item either does not contain any substances impacted by the specified legislations or contains no substances above the specified threshold. Item is compliant.

RohsCompliantWithExemptions = <RoHSFlag.RohsCompliantWithExemptions: 4>

This item contains substances impacted by the specified legislations, but an exemption has been declared either on itself or a child item. Item is compliant with exemptions.

RohsAboveThreshold = <RoHSFlag.RohsAboveThreshold: 5>

This substance is impacted by the specified legislations and is present in a quantity above that specified by the indicator. Exemption for use required.

RohsNonCompliant = <RoHSFlag.RohsNonCompliant: 6>

This item contains one or more substances impacted by the specified legislations. Item is non-compliant.

RohsUnknown = <RoHSFlag.RohsUnknown: 7>

One or more declarations are missing, so there is not enough information to determine compliance. Compliance is unknown.

Watch list indicator

class WatchListIndicator(*, name, legislation_ids, default_threshold_percentage=None, ignore_process_chemicals=False)

Provides the indicator object that represents watch list-type compliance of a BoM object against one or more legislations.

Other WatchListIndicator objects with results can be compared, with ‘less compliant’ indicator flags being greater than ‘more compliant’ indicator flags.

Parameters:

namestr

Name of the indicator that is used to identify the indicator in the query result.

legislation_idslist[str]

New in version 2.0.

Legislations against which compliance will be determined. Legislations are identified based on their Legislation ID attribute value.

Important

This argument replaces legislation_names, which has been removed in version 2.0.

When updating scripts from version 1.x, replace the legislation_names argument with the legislation_ids argument and ensure the value provided is a list of Legislation ID attribute values.

default_threshold_percentagefloat, optional

Percentage of substance concentration that is to be determined to be non-compliant. The default is None. This parameter is only used if the legislation doesn’t define a specific threshold for the substance.

ignore_process_chemicalsbool, optional

Whether to ignore substances flagged as process chemicals when determining compliance against this indicator. The default is False.

Raises:

TypeError

Error to raise if two indicators of different types are compared.

ValueError

Error to raise if two indicators are compared and both don’t have a result flag.

Notes

The watch list indicator is designed to be used with REACH legislations or internal watch lists. However, usage is not enforced. Substances marked as Process Chemicals [1] are usually included, but they can be ignored by specifying ignore_process_chemicals=True when creating the indicator. Exemptions are always ignored. The possible result flags for the indicator distinguish between an item being compliant, compliant but with substances below the threshold, or non-compliant.

Examples

>>> indicator = RoHSIndicator(name='Tracked substances',
...                           legislation_ids=["SINList"],
...                           default_threshold_percentage=0.1,
...                           ignore_process_chemicals=True)
>>> indicator
<WatchListIndicator, name: Tracked substances>

>>> query = MaterialComplianceQuery.with_indicators([indicator])...
>>> result: MaterialComplianceQueryResult  # Perform a compliance query
>>> indicator_result = result.compliance_by_indicator['Tracked substances']
>>> indicator_result
<WatchListIndicator, name: Tracked substances,
flag: WatchListFlag.WatchListHasSubstanceAboveThreshold>

>>> indicator_result <= indicator.available_flags['WatchListAllSubstancesBelowThreshold']
False  # The material is not compliant with the legislations in the indicator

Attributes:

available_flagsType[WatchListFlag]

Provides permitted watch list flag states.

enum WatchListFlag(value)

Provides permitted watch list flag states.

An increasing value means less compliance. The further down the list the compliance result appears, the worse it is.

For more information, see the Restricted Substances Reports User Guide.

Valid values are as follows:

WatchListNotImpacted = <WatchListFlag.WatchListNotImpacted: 1>

This substance is not impacted by the specified legislations. Substance is not impacted.

WatchListCompliant = <WatchListFlag.WatchListCompliant: 2>

This item does not contain any substances impacted by the specified legislations. Item is compliant.

WatchListBelowThreshold = <WatchListFlag.WatchListBelowThreshold: 3>

This substance is impacted by the specified legislations, but appears in the parent item in a quantity below that specified by the indicator. Substance is below threshold.

WatchListAllSubstancesBelowThreshold = <WatchListFlag.WatchListAllSubstancesBelowThreshold: 4>

This item contains no substances above the specified threshold. Item is compliant.

WatchListAboveThreshold = <WatchListFlag.WatchListAboveThreshold: 5>

This substance is impacted by the specified legislations and appears in the parent item in a quantity above that specified by the indicator. Substance is impacted.

WatchListHasSubstanceAboveThreshold = <WatchListFlag.WatchListHasSubstanceAboveThreshold: 6>

This item contains one or more substances impacted by the specified legislations. Item is non-compliant.

WatchListUnknown = <WatchListFlag.WatchListUnknown: 7>

There is not enough information to determine compliance. Compliance is unknown.

[1] (1,2)

A substance is determined to be a process chemical if either the substance category is set as ‘Used in production’ or ‘May be used in production’ in the tabular row where it is referenced, or if the substance is included in a material and the material type is set as ‘Process’ in the tabular row that links the material to a specification.