pyDMNrules

https://pydmnrules.readthedocs.io/en/latest/
Admin
pyDMNrules is a Python rules engine that builds decision logic from DMN (Decision Model and...
Tokens:8,343
Snippets:61
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Execute DMN tests with test()

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

Demonstrates loading a DMN model from an Excel file and running the test suite, followed by iterating through results to identify passed or failed tests.

```python
import pyDMNrules
dmnRules = pyDMNrules.DMN()
status = dmnRules.load('ExampleHPV.xlsx')
if 'errors' in status:
    print('ExampleHPV.xlsx has errors', status['errors'])
    sys.exit(0)
else:
    print('ExampleHPV.xlsx loaded')
(testStatus, results) = dmnRules.test()
for test in range(len(results)):
    if 'Mismatches' not in results[test]:
        print('Test ID', results[test]['Test ID'], 'passed')
    else:
        print('Test ID', results[test]['Test ID'], 'failed')
        for failure in range(len(results[test]['Mismatches'])):
            print(results[test]['Mismatches'][failure])
    if 'errors' in testStatus[test]:
        print('Failed')
```

--------------------------------

### Load DMN Rules and Make Decisions

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

Loads a DMN file and makes decisions using a dictionary for input data. Ensure the DMN file is accessible and the input data keys match the DMN expected inputs.

```python
import pyDMNrules
dmnRules = pyDMNrules.DMN()
status = dmnRules.load('Example1.xlsx')
if 'errors' in status:
    print('Example1.xlsx has errors', status['errors'])
    sys.exit(0)
else:
    print('Example1.xlsx loaded')

data = {}
data['Applicant Age'] = 63
data['Medical History'] = 'bad'
(status, newData) = dmnRules.decide(data)
if 'errors' in status:
    print('Failed')

```

--------------------------------

### DMN Class Methods

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

Methods for loading and interacting with DMN rulesbooks and XML files.

```APIDOC
## DMN.load

### Description
Loads a rulesBook from an Excel workbook. The workbook can contain a 'Glossary' sheet, a 'Decision' sheet, and other sheets with DMN rules tables.

### Method
`load`

### Parameters
#### Path Parameters
- **rulesBook** (str) - Required - The name of the Excel workbook (including path if not in the current working directory).

### Returns
- **status** (dict) - A dictionary containing status information. If the key 'error' is present, it lists encountered errors.

### Notes
- If no 'Glossary' sheet is supplied, one will be created from input and output headings in the DMN rules tables.
- Every input 'Variable' must be named in an input or output column. Dummy columns may be needed for variables used only in calculations.

## DMN.use

### Description
Uses an already loaded Excel workbook. The workbook can contain a 'Glossary' sheet, a 'Decision' sheet, and other sheets with DMN rules tables.

### Method
`use`

### Parameters
#### Path Parameters
- **workbook** (openpyxl.workbook) - Required - An openpyxl workbook object.

### Returns
- **status** (dict) - A dictionary containing status information. If the key 'error' is present, it lists encountered errors.

### Notes
- If no 'Glossary' sheet is supplied, one will be created from input and output headings in the DMN rules tables.
- Every input 'Variable' must be named in an input or output column. Dummy columns may be needed for variables used only in calculations.

## DMN.loadXML

### Description
Loads a DMN compliant XML file (.xml or .dmn) and builds a rules engine.

### Method
`loadXML`

### Parameters
#### Path Parameters
- **DMNxmlFile** (str) - Required - The name of the DMN compliant file (including path if not in the current working directory).

### Returns
- **status** (dict) - A dictionary containing status information. If the key 'error' is present, it lists encountered errors.

## DMN.useXML

### Description
Uses a DMN XML compliant string to build a rules engine.

### Method
`useXML`

### Parameters
#### Path Parameters
- **text** (str) - Required - A string containing a DMN compliant XML structure.

### Returns
- **status** (dict) - A dictionary containing status information. If the key 'error' is present, it lists encountered errors.

## DMN.getGlossaryNames

### Description
Returns the names of the Glossary and its annotation headings.

### Method
`getGlossaryNames`

### Parameters
- **None**

### Returns
- **str** - The Glossary Name.

## DMN.getGlossary

### Description
Returns the Glossary, including each Variable within each Business Concept, along with their FEEL names, current values, and annotations.

### Method
`getGlossary`

### Parameters
- **None**

### Returns
- **dict** - A dictionary where keys are Business Concept names and values are dictionaries. These inner dictionaries have Variable names as keys and tuples of (FEELname, current value, [annotations]) as values.

## DMN.getDecisionName

### Description
Returns the name of the Decision table, which is the heading for the Decision table or the 'name' from the <definitions> root element in the DMN.xml file.

### Method
`getDecisionName`

### Parameters
- **None**

### Returns
- **str** - The Decision Name.

## DMN.getDecision

### Description
Returns the Decision table, representing the order of execution of the Decision tables.

### Method
`getDecision`

### Parameters
- **None**

### Returns
- **list** - A list of lists (2D array) representing the Decision table. Row 0 contains the headings. Subsequent rows include input tests, Decisions, Execute Decision Tables, and Annotations.

## DMN.getSheets

### Description
Returns the Decision Tables formatted as though they were sheets in an Excel workbook (as XHTML).

### Method
`getSheets`

### Parameters
- **None**

### Returns
- **XHTML** - The Decision Tables as XHTML.

```

--------------------------------

### loadTest Function

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

Loads an Excel workbook for unit testing.

```APIDOC
## loadTest(testBook)

### Description
Loads an Excel workbook that must contain a 'Test' worksheet to define unit tests.

### Parameters
#### Path Parameters
- **testBook** (str) - Required - The name or path of the Excel workbook.
```

--------------------------------

### pyDMNrules.DMN Methods

Source: https://pydmnrules.readthedocs.io/en/latest/genindex.html

This section details the various methods available for the DMN class in the pyDMNrules library.

```APIDOC
## DMN Methods

### `decide()`

*   **Description**: Executes a decision based on the loaded DMN model.
*   **Method**: N/A (Method of the DMN class)

### `decidePandas()`

*   **Description**: Executes a decision using pandas DataFrames as input.
*   **Method**: N/A (Method of the DMN class)

### `getDecision()`

*   **Description**: Retrieves a specific decision from the DMN model.
*   **Method**: N/A (Method of the DMN class)

### `getDecisionName()`

*   **Description**: Gets the name of a decision.
*   **Method**: N/A (Method of the DMN class)

### `getGlossary()`

*   **Description**: Retrieves the glossary associated with the DMN model.
*   **Method**: N/A (Method of the DMN class)

### `getGlossaryNames()`

*   **Description**: Gets the names of all available glossaries.
*   **Method**: N/A (Method of the DMN class)

### `getSheets()`

*   **Description**: Retrieves the names of all decision tables (sheets) within the DMN model.
*   **Method**: N/A (Method of the DMN class)

### `load()`

*   **Description**: Loads a DMN model from a file path.
*   **Method**: N/A (Method of the DMN class)

### `loadTest()`

*   **Description**: Loads a DMN model from a test file.
*   **Method**: N/A (Method of the DMN class)

### `loadXML()`

*   **Description**: Loads a DMN model from an XML string.
*   **Method**: N/A (Method of the DMN class)

### `test()`

*   **Description**: Performs tests on the loaded DMN model.
*   **Method**: N/A (Method of the DMN class)

### `use()`

*   **Description**: Uses the DMN model for decision making.
*   **Method**: N/A (Method of the DMN class)

### `useTest()`

*   **Description**: Uses the DMN model with test data.
*   **Method**: N/A (Method of the DMN class)

### `useXML()`

*   **Description**: Uses the DMN model loaded from an XML string.
*   **Method**: N/A (Method of the DMN class)
```

--------------------------------

### Load DMN Rules and Make Decisions with Pandas

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

Loads a DMN file and makes decisions using a Pandas DataFrame for input. This method is suitable for batch processing and requires careful data type and date parsing configuration. Column mappings are used to align input DataFrame columns with DMN expected inputs.

```python
import pyDMNrules
import pandas as pd
import sys
dmnRules = pyDMNrules.DMN()
status = dmnRules.load('AN-SNAP rules (DMN).xlsx')
if 'errors' in status:
   print('AN-SNAP rules (DMN).xlsx has errors', status['errors'])
   sys.exit(0)
else:
     print('AN-SNAP rules (DMN).xlsx loaded')
dataTypes = {'Patient_Age':int, 'Episode_Length_of_stay':int, 'Phase_Length_of_stay':int,
   'Phase_FIM_Motor_Score':int, 'Phase_FIM_Cognition_Score':int, 'Phase_RUG_ADL_Score':int,
   'Phase_w01':float, 'Phase_NWAU21':float,
   'Indigenous_Status':str, 'Care_Type':str, 'Funding_Source':str, 'Phase_Impairment_Code':str,
   'AROC_code':str, 'Phase_AN_SNAP_V4_0_code':str,
   'Same_day_addmitted_care':bool, 'Delerium_or_Dimentia':bool, 'RadioTherapy_Flag':bool, 'Dialysis_Flag':bool}
dates = ['BirthDate', 'Admission_Date', 'Discharge_Date', 'Phase_Start_Date', 'Phase_End_Date']
dfInput = pd.read_csv('subAcuteExtract.csv', dtype=dataTypes, parse_dates=dates)
dfInput['Multidisciplinary'] = True
dfInput['Admitted_Flag'] = True
dfInput['Length_of_Stay'] = dfInput['Phase_Length_of_Stay']
dfInput['Long_term_care'] = False
dfInput.loc[dfInput['Length_of_Stay'] > 92, 'Long_term_care'] = True
dfInput['Same_day_admitted_care'] = False
dfInput['GEM_clinic'] = None
dfInput['Patient_Age_Type'] = None
dfInput['First_Phase'] = False
grouped = dfInput.groupby(['Patient_UR', 'Admission_Date'])
for index in grouped.head(1).index:
   if dfInput.loc[index]['Phase_Type'] == 'Unstable':
      dfInput.loc[index, 'First_Phase'] = True
columns = {'Admitted_Flag':'Admitted Flag', 'Care_Type':'Care Type', 'Length_of_Stay':'Length of Stay', 'Long_term_care':'Long term care',
   'Same_day_admitted_care':'Same-day admitted care', 'GEM_clinic':'GEM clinic', 'Patient_Age':'Patient Age', 'Patient_Age_Type':'Patient Age Type',
   'AROC_code':'AROC code', 'Delirium_of_Dimentia':'Delirium or Dimentia', 'Phase_Type':'Phase Type', 'First_Phase':'First Phase', 'Phase_FIM_Motor_Score':'FIM Motor score',
   'Phase_FIM_Cognition_Score':'FIM Cognition score', 'Phase_RUG_ADL_Score':'RUG-ADL', 'Delirium_or_Dimentia':'Delirium or Dimentia',
   'Problem_Severity_Scrore':'Problem Severity Score'}
(dfStatus, dfResults, dfDecision) = dmnRules.decidePandas(dfInput, headings=columns)
if dfStatus.where(dfStatus != 'no errors').count() > 0:
   print('has errors', dfStatus.loc['status' != 'no errors'])
   sys.exit(0)
for index in dfResults.index:
   print(index, dfResults.loc[index, 'AN_SNAP_V4_code'])

```

--------------------------------

### useTest() Function

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

This function uses a workbook containing a 'Test' worksheet to define unit tests for pyDMNrules.test(). It requires an already loaded Excel workbook with a 'Test' sheet.

```APIDOC
## useTest(workbook)

### Description
Uses a workbook containing a 'Test' worksheet to define unit tests for pyDMNrules.test(). Requires an already loaded Excel workbook with a 'Test' sheet.

### Method
N/A (Function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **status** (dict) - A dictionary containing status information. Currently, only 'status["error"]' is implemented. If the key 'error' is present, it contains a list of errors encountered during loading.

#### Response Example
```json
{
  "status": {
    "error": [
      "Error message 1",
      "Error message 2"
    ]
  }
}
```
```

--------------------------------

### decide() - Make a Decision

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

Runs provided data through loaded DMN rules to return a decision. It handles complex data structures and variable matching within the DMN glossary.

```APIDOC
## decide() - Make a Decision

### Description
Make a decision by running the passed data through the loaded DMN rules.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **data** (dict) - Required - The dictionary of data about which a decision is being made. 
  * Each key in ‘data’ must match a ‘Variable’ in the Glossary or a ‘Business Concept’.
  * If key is a ‘Business Concept’, the value must be a dictionary (or list of dictionaries) where the construct of ‘Business Concept’.key must match a ‘Variable’ in the Glossary.
  * The matching ‘Variable’ in the Glossary will be set to the matching value for this key from the ‘data’ dictionary.
  * Any entry in the Glossary which does not have a key in the ‘data’ dictionary will be set to the value ‘None’.
  * The values associated with each ‘Variable’ in the Glossary will be the input values, for the input columns, in the first DMN rules table in the ‘Decision’.
  * Subsequently, the input values for the input columns in subsequent DMN rules tables will come from ‘data’, unless those input ‘Variables’ are also output ‘Variables’ in a preceding, executed, DMN rules table. In which case, those output values will be used as the input values for the current DMN rules table.

### Request Example
```json
{
  "data": {
    "customer_age": 30,
    "loan_amount": 50000
  }
}
```

### Response
#### Success Response (200)
* **status** (dict) - Dictionary of different status information. Currently only status[‘error’] is implemented. If the key ‘error’ is present, then decide() encountered one or more errors and status[‘error’] is the list of those errors.
* **newData** (dict or list) - The decision result.
  * For a Single Hit Policy, single DMN rules table executed, newData will be a decision dictionary of the decision.
  * For a Multi Hit Policy DMN rules table, newData will be a list of decision dictionaries; one for each matched rule.
  * If more than one DMN rules table is selected and executed, newData will be a list of decision dictionaries.

**Keys within each decision dictionary:**
* **'Result'** (dict or list) - For a Single Hit Policy DMN rules table, this will be a dictionary where all keys will be ‘Variables’ from the Glossary and the matching value will be the value of that ‘Variable’ after the decision was made. For a Multi Hit Policy DMN rules table this will be a list of decision dictionaries, one for each matched rule.
* **'Executed Rule'** (tuple or list) - For a Single Hit Policy DMN rules table, this will be a tuple of the Decision Table Description, DMN rules table name, and the Rule number for the rule that matched. For a Multi Hit Policy DMN rules table this will be a list of tuples, being the Decision Table Description, DMN rules table name, and matched Rule number for each matching rule.
* **'DecisionAnnotations'** (optional, list of tuples) - List of tuples (heading, value) of the annotations from the ‘Decision’ table named in the ‘Executed Rule’ tuple.
* **'RuleAnnotations'** (optional, list of tuples or list of lists) - For a Single Hit Policy DMN rules table, this will be a list of tuples (heading, value) of the annotations for the matching rule. For a Multi Hit Policy DMN rules table this will be a list of the lists of any annotations for each matching rule.

### Response Example
```json
{
  "status": {},
  "newData": {
    "Result": {
      "loan_eligibility": "Approved",
      "interest_rate": 5.5
    },
    "Executed Rule": "Loan Application Rules - Table 1 - Rule 3"
  }
}
```
```

--------------------------------

### pyDMNrules Module

Source: https://pydmnrules.readthedocs.io/en/latest/genindex.html

Information about the top-level pyDMNrules module.

```APIDOC
## pyDMNrules Module

### Description

The `pyDMNrules` module is the main entry point for the library, providing access to the `DMN` class and other functionalities.
```

--------------------------------

### test Function

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

Runs unit tests defined in the 'Test' worksheet.

```APIDOC
## test()

### Description
Reads Unit Test data and DMNrulesTests from the 'Test' worksheet and runs the data through the decide() function, returning any mismatches.

### Response
#### Success Response (200)
- **testStatus** (list) - List of status dictionaries returned by decide().
- **results** (list) - List of dictionaries containing test IDs, data, and mismatch reports.
```

--------------------------------

### Glossary Tab

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

The optional 'Glossary' tab in an Excel workbook provides documentation and clarification for input and output data. It must contain a table headed 'Glossary' with three columns: 'Variable', 'Business Concept', and 'Attribute'.

```APIDOC
## Glossary Tab

### Description
An optional tab in the Excel workbook that provides documentation and clarification for input and output data. It must contain a table headed 'Glossary'.

### Columns
- **Variable** (string) - Any text used to pass data to and from pyDMNrules. The name 'Execute' is reserved.
- **Business Concept** (string) - Must be a valid FEEL name. Used to group 'Variable'/'Attribute' pairs.
- **Attribute** (string) - Must be a valid FEEL name. Combined with 'Business Concept' (using a period) to form a Glossary item (e.g., 'Order.orderSize').

### Annotations
The 'Glossary' tab can include additional columns for annotations, such as data types or valid values.

### Default Glossary Creation
If no 'Glossary' tab is present, pyDMNrules creates one using input and output headings. It uses a single 'Business Concept' called 'Data', and attributes are derived from headings by replacing spaces with underscores and removing invalid FEEL characters. Ambiguities are resolved by appending digits.
```

--------------------------------

### decidePandas() - Process DataFrame

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

Processes a Pandas DataFrame, making a decision for each row based on the input data. Returns status and results DataFrames.

```APIDOC
## decidePandas() - Process DataFrame

### Description
Process a Pandas DataFrame and make a decision for each row, based upon the input data in each row. This routine runs each row of data in a Pandas dataframe through the decide() function and returns a Pandas Series (dfStatus) of the status of each decision, and a Pandas Dataframe (dfResults), being the Results of the last Decision Table processed by the decide() function.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **dfInput** (dataframe) - Required - The Pandas dataframe of rows of data about which decisions need to be made. 
  * Some of the column names in the dataframe (or a mapping of them) must match a ‘Variable’ name in the Glossary.
  * Each matching ‘Variable’ in the Glossary will be set to the value from this matching column for each row in the dataframe.
  * decide() will then be called to make a decision about this row of data.
* **kwargs** (optional) - Additional keyword arguments to pass to the decide() function.

### Request Example
```python
import pandas as pd

data = {'customer_age': [30, 45, 22], 'loan_amount': [50000, 10000, 75000]}
df = pd.DataFrame(data)

dfStatus, dfResults = decidePandas(df)
```

### Response
#### Success Response (200)
* **dfStatus** (Pandas Series) - A Pandas Series containing the status of each decision for each row.
* **dfResults** (Pandas DataFrame) - A Pandas DataFrame containing the results of the last Decision Table processed by the decide() function for each row.

#### Response Example
```python
# dfStatus example:
# 0    {}
# 1    {}
# 2    {}
# dtype: object

# dfResults example:
#   loan_eligibility  interest_rate
# 0        Approved            5.5
# 1        Approved            4.0
# 2        Rejected            NaN
```
```

--------------------------------

### decidePandas Function

Source: https://pydmnrules.readthedocs.io/en/latest/index.html

Processes a Pandas DataFrame through the decision engine.

```APIDOC
## decidePandas(param1, headings=None, strict=True)

### Description
Processes a Pandas DataFrame through the decision engine using defined headings and strict mode settings.

### Parameters
#### Path Parameters
- **param1** (Pandas DataFrame) - Required - The input dataframe to process.

#### Query Parameters
- **headings** (dict) - Optional - Dictionary mapping column names from dfInput to Glossary variables.
- **strict** (bool) - Optional - If true, converts Glossary names to valid Pandas column headings.

### Response
#### Success Response (200)
- **dfStatus** (Pandas Series) - Status of each row processing.
- **dfResults** (Pandas DataFrame) - Decisions returned by the decide() function.
- **dfDecision** (Pandas DataFrame) - Details about the last rule executed.
```
Tokens:
Raw