# Rule Language Documentation
## Overview
The Rule Language is a domain-specific language (DSL) designed for defining soft logic constraints in mammography classification. It allows you to replace hard-coded constraint logic with flexible, interpretable rule scripts that can be modified without changing Python code.
## Syntax Reference
### Comments
Comments start with `#` and continue to the end of the line:
```
# This is a comment
define findings_L = mass_L | mc_L # Inline comment
```
### Variable Definitions
Define new variables using logical combinations of existing features:
```
define variable_name = expression
```
### Constant Definitions
Define constants for reusable literal values:
```
const constant_name = value
```
### Variable Expectations
Declare which variables (features) the script expects to be provided:
```
expect variable_name
expect variable1, variable2, variable3
```
Examples:
```
# Declare expected variables at the beginning of the script
expect left_birads, right_birads, mass_L, mc_L
# Or declare them individually
expect comp
expect risk_score
# Define constants for thresholds
const high_threshold = 0.8
const low_threshold = 0.2
const birads_cutoff = 4
# Basic logical operations with literals
define findings_L = mass_L | mc_L
define high_risk = risk_score > 0.7 # Using literal number
define moderate_risk = risk_score > low_threshold # Using constant
# Function calls with mixed literals and variables
define high_birads = sum(birads_L, [4, 5, 6])
define threshold_check = risk_score >= high_threshold
```
### Constraints
Define constraints that will be enforced during training:
```
constraint expression [weight=value] [transform="type"] [param=value ...]
```
Examples:
```
# Basic constraint
constraint exactly_one(birads_L)
# Constraint with weight and transform
constraint findings_L >> high_birads weight=0.7 transform="logbarrier"
# Constraint with multiple parameters
constraint exactly_one(comp) weight=1.5 transform="hinge" alpha=2.0
```
## Operators
### Logical Operators (in order of precedence, lowest to highest)
1. **Implication (`>>`)**: A >> B (if A then B)
```
constraint findings_L >> high_birads_L
```
2. **OR (`|`)**: A | B (A or B)
```
define findings = mass_L | mc_L
```
3. **XOR (`^`)**: A ^ B (A exclusive or B)
```
define exclusive = mass_L ^ mc_L
```
4. **Comparison Operators**: `>`, `<`, `==`, `>=`, `<=`
```
define high_risk = risk_score > threshold_value
define similar_scores = score_a == score_b
define within_range = score >= min_val & score <= max_val
```
5. **AND (`&`)**: A & B (A and B)
```
define strict_findings = mass_L & high_confidence
```
6. **AND_n (`& variable`)**: AND across all elements in a tensor
```
# All radiologists must agree (consensus)
define consensus = & radiologist_assessments
# All imaging modalities must show findings
define all_modalities_positive = & imaging_results
```
7. **OR_n (`| variable`)**: OR across all elements in a tensor
```
# Any radiologist found something
define any_concern = | radiologist_assessments
# Any imaging modality shows findings
define any_positive = | imaging_results
```
8. **NOT (`~`)**: ~A (not A)
```
define no_findings = ~findings_L
```
9. **Indexing (`variable[...]`)**: Access tensor elements using numpy/pytorch syntax
```
# Integer indexing
define first_patient = patient_data[0]
define specific_element = matrix[1, 2]
define last_radiologist = assessments[2]
# Slice indexing
define first_two_patients = patient_data[:2]
define middle_columns = matrix[:, 1:3]
define every_other = data[::2]
define specific_range = tensor[1:4]
# Multi-dimensional indexing
define patient_features = batch_data[0, :, 2]
define view_subset = assessments[:, 1, :]
```
### Parentheses
Use parentheses to override operator precedence:
```
define complex = (mass_L | mc_L) & ~(birads_L >> findings_L)
```
## Statement Separation
### Semicolons
You can use semicolons (`;`) to separate multiple statements on a single line, similar to Python:
```
# Multiple statements on one line
expect a, b; define c = a | b; constraint c
# Mix of semicolons and newlines
const threshold = 0.5; expect risk_score
define high_risk = risk_score > threshold
constraint high_risk weight=0.8
# Multiple constants and definitions
const low = 0.2; const high = 0.8; define range_check = value >= low & value <= high
```
### Line-based Separation
Statements can also be separated by newlines (traditional approach):
```
expect findings_L, findings_R
define bilateral = findings_L & findings_R
constraint bilateral weight=0.6
```
### Trailing Semicolons
Trailing semicolons are optional and ignored:
```
expect variables;
define result = expression;
constraint result;
```
## Built-in Functions
### `sum(probabilities, indices)`
Sum probabilities for specified class indices:
```
define high_birads_L = sum(birads_L, [4, 5, 6])
define very_high_birads = sum(birads_L, [5, 6])
```
### `exactly_one(probabilities)`
Create exactly-one constraint for categorical probabilities:
```
constraint exactly_one(birads_L) weight=1.0
```
### `mutual_exclusion(...probabilities)`
Create mutual exclusion constraint between multiple probabilities:
```
constraint mutual_exclusion(mass_L, mc_L) weight=0.5
```
### `at_least_k(probabilities, k)`
Create constraint that at least k elements must be true:
```
define min_two_findings = at_least_k(findings_combined, 2)
constraint min_two_findings weight=0.6
```
### `at_most_k(probabilities, k)`
Create constraint that at most k elements can be true:
```
define max_one_high_birads = at_most_k(high_birads_indicators, 1)
constraint max_one_high_birads weight=0.7
```
### `exactly_k(probabilities, k)`
Create constraint that exactly k elements must be true:
```
define exactly_two_radiologists = exactly_k(radiologist_agreement, 2)
constraint exactly_two_radiologists weight=0.8
```
### `threshold_implication(antecedent, consequent, threshold)`
Create threshold-based implication constraint:
```
define strong_implication = threshold_implication(high_risk_L, findings_L, 0.7)
constraint strong_implication weight=0.9
```
### `conditional_probability(condition, event, target_prob)`
Create conditional probability constraint:
```
define conditional_findings = conditional_probability(high_birads_L, findings_L, 0.85)
constraint conditional_findings weight=0.8
```
### `clamp(tensor, min_val, max_val)`
Clamp tensor values to specified range:
```
define clamped_mass = clamp(mass_L, 0.1, 0.9)
```
### `threshold(tensor, threshold)`
Apply threshold to tensor:
```
define binary_mass = threshold(mass_L, 0.5)
```
### `greater_than(left, right)`
Create soft greater than comparison between two tensors:
```
define high_confidence = greater_than(confidence, baseline)
```
### `less_than(left, right)`
Create soft less than comparison between two tensors:
```
define low_risk = less_than(risk_score, threshold_low)
```
### `equals(left, right)`
Create soft equality comparison between two tensors:
```
define similar_scores = equals(score_a, score_b)
```
### `threshold_constraint(tensor, threshold, operator)`
Create threshold constraint with specified comparison operator:
```
define high_birads = threshold_constraint(birads_score, 0.7, ">")
define exact_match = threshold_constraint(prediction, 0.5, "==")
define within_bounds = threshold_constraint(value, 0.3, ">=")
```
## Data Types
### Numbers
Integer or floating-point numbers can be used directly in expressions:
```
define high_risk = risk_score > 0.8
define moderate = value >= 0.3 & value <= 0.7
constraint threshold_check weight=1.5 # Literal number as parameter
```
### Strings
Text values enclosed in quotes:
```
transform="logbarrier"
transform='hinge'
const model_type = "transformer"
```
### Lists
Arrays of values:
```
[1, 2, 3]
[4, 5, 6]
const important_classes = [4, 5, 6] # Can store list constants
```
### Mixed Type Expressions
The rule language automatically handles mixed types in expressions:
```
# Tensor compared with literal number
define high_values = predictions > 0.5
# Tensor compared with constant
const threshold = 0.7
define above_threshold = scores >= threshold
# Combining constants and variables
const low_cut = 0.2
const high_cut = 0.8
define in_range = (values >= low_cut) & (values <= high_cut)
```
## Constraint Parameters
### `weight` (float)
Relative importance of the constraint:
```
constraint exactly_one(birads_L) weight=2.0 # Higher weight = more important
```
### `transform` (string)
Loss transformation method:
- `"logbarrier"`: Logarithmic barrier (default, smooth penalties)
- `"hinge"`: Hinge loss (softer penalties)
- `"linear"`: Linear loss (proportional penalties)
```
constraint findings >> high_birads transform="hinge"
```
### Custom Parameters
Additional parameters specific to constraint types:
```
constraint exactly_one(birads_L) weight=1.0 alpha=2.0 beta=0.5
```
## Complete Example
```
# Mammography Constraint Rules
# ============================
# Declare expected variables from model output
expect mass_L, mass_R, mc_L, mc_R
expect birads_L, birads_R, birads_score_L, birads_score_R
expect comp
# Define constants for reusable thresholds
const high_risk_threshold = 0.7
const low_risk_threshold = 0.3
const birads_high_cutoff = 4
const birads_very_high_cutoff = 5
# Feature definitions - combine findings per breast
define findings_L = mass_L | mc_L
define findings_R = mass_R | mc_R
# BI-RADS probability groups using constants
define high_birads_L = sum(birads_L, [4, 5, 6])
define high_birads_R = sum(birads_R, [4, 5, 6])
define very_high_birads_L = sum(birads_L, [5, 6])
define very_high_birads_R = sum(birads_R, [5, 6])
define low_birads_L = sum(birads_L, [1, 2])
define low_birads_R = sum(birads_R, [1, 2])
# Threshold-based risk assessments using literals and constants
define high_risk_L = birads_score_L > high_risk_threshold
define high_risk_R = birads_score_R > high_risk_threshold
define very_low_risk_L = birads_score_L < low_risk_threshold
define very_low_risk_R = birads_score_R < low_risk_threshold
define balanced_assessment = equals(risk_L, risk_R)
# Range constraints using multiple comparisons with literals
define valid_risk_range_L = (birads_score_L >= 0.0) & (birads_score_L <= 1.0)
define valid_risk_range_R = (birads_score_R >= 0.0) & (birads_score_R <= 1.0)
# No findings (negation of findings)
define no_findings_L = ~findings_L
define no_findings_R = ~findings_R
# Categorical exclusivity constraints
constraint exactly_one(birads_L) weight=1.0 transform="logbarrier"
constraint exactly_one(birads_R) weight=1.0 transform="logbarrier"
constraint exactly_one(comp) weight=0.7 transform="logbarrier"
# Logical implication constraints using threshold variables
constraint high_risk_L >> findings_L weight=0.8 transform="logbarrier"
constraint high_risk_R >> findings_R weight=0.8 transform="logbarrier"
# Very High BI-RADS (5-6) -> Findings
constraint very_high_birads_L >> findings_L weight=0.7 transform="logbarrier"
constraint very_high_birads_R >> findings_R weight=0.7 transform="logbarrier"
# Low BI-RADS with literal thresholds -> No findings (gentle constraint)
constraint very_low_risk_L >> no_findings_L weight=0.3 transform="logbarrier"
constraint very_low_risk_R >> no_findings_R weight=0.3 transform="logbarrier"
# Range validation constraints
constraint valid_risk_range_L weight=2.0 transform="logbarrier"
constraint valid_risk_range_R weight=2.0 transform="logbarrier"
# Comparison-based constraints using constants
constraint balanced_assessment weight=0.4 transform="hinge"
```
## Usage Patterns
### 1. Variable Expectations
Declare required variables at the beginning of scripts for better error handling:
```
# Declare all expected model outputs in one line
expect left_mass_prob, right_mass_prob, left_birads, right_birads, composition
# Now use these variables with confidence
define findings_L = left_mass_prob > 0.5
constraint exactly_one(left_birads)
```
### 2. Categorical Constraints
Ensure exactly one category is selected:
```
constraint exactly_one(birads_L) weight=1.0
constraint exactly_one(composition) weight=0.8
```
### 2. Implication Rules
Model domain knowledge as if-then relationships:
```
# If findings present, then high BI-RADS likely
constraint findings_L >> high_birads_L weight=0.7
# If very high BI-RADS, then findings must be present
constraint very_high_birads_L >> findings_L weight=0.8
```
### 3. Mutual Exclusion
Prevent conflicting classifications:
```
constraint mutual_exclusion(mass_L, calc_L) weight=0.5
```
### 4. Threshold Rules
Apply domain-specific thresholds:
```
define suspicious = threshold(combined_score, 0.7)
constraint suspicious >> high_birads weight=0.6
```
### 5. Comparison Constraints
Use soft comparison operators for ordinal and threshold relationships:
```
# Risk stratification with thresholds
define high_risk = risk_score > 0.8
define low_risk = risk_score < 0.2
constraint high_risk >> findings weight=0.7
```
### 6. Consensus and Agreement (AND_n)
Model situations where all elements must be true:
```
# All radiologists must agree for high confidence
define consensus = & radiologist_assessments
constraint consensus > 0.7 >> definitive_diagnosis weight=0.9
# All imaging modalities must show findings
define multi_modal_positive = & imaging_results
constraint multi_modal_positive >> high_confidence weight=0.8
```
### 7. Any Evidence Detection (OR_n)
Model situations where any element being true is significant:
```
# Any radiologist expressing concern triggers review
define any_concern = | radiologist_assessments
constraint any_concern > 0.5 >> requires_review weight=0.6
# Any modality showing findings suggests pathology
define any_positive = | imaging_modalities
constraint any_positive >> potential_pathology weight=0.7
```
### 8. Tensor Indexing and Slicing
Access specific elements, patients, or subsets of multi-dimensional data:
```
# Patient-specific analysis
define patient_0_risk = patient_risks[0]
define patient_1_findings = findings[1, :]
constraint patient_0_risk > 0.8 >> patient_0_findings weight=1.0
# View-specific mammography analysis
define cc_assessments = assessments[:, 0, :] # CC view for all patients
define mlo_assessments = assessments[:, 1, :] # MLO view for all patients
define cc_consensus = & cc_assessments
define mlo_consensus = & mlo_assessments
constraint cc_consensus & mlo_consensus >> high_confidence weight=0.9
# Radiologist-specific consistency
define senior_opinions = assessments[:, :, 0] # Senior across all views
define resident_opinions = assessments[:, :, 1] # Resident across all views
define senior_consistency = & senior_opinions
constraint senior_consistency weight=0.8
# Subset analysis
define high_risk_patients = patient_data[:3] # First 3 patients
define feature_subset = features[:, 2:5] # Specific feature range
define consensus_subset = & high_risk_patients
constraint consensus_subset >> intensive_monitoring weight=1.0
# Equality constraints for consistency
define balanced_breasts = equals(risk_L, risk_R)
constraint balanced_breasts weight=0.3 transform="hinge"
# Range constraints using multiple comparisons
define valid_range = (score >= 0.1) & (score <= 0.9)
constraint valid_range weight=1.0
```
### 9. Ordinal Relationships
Model ordered classifications with comparison operators:
```
# BI-RADS ordering constraints
define birads_3_higher = birads_3 >= birads_2
define birads_4_higher = birads_4 >= birads_3
constraint birads_3_higher & birads_4_higher weight=0.8
```
## Error Handling
The rule language provides helpful error messages for common issues:
### Syntax Errors
```
define x = mass_L | # Error: Missing right operand
```
### Undefined Variables
```
define x = undefined_var # Error: Variable 'undefined_var' is not defined
```
### Type Mismatches
```
constraint exactly_one(5) # Error: Expected Truth object, got number
```
### Invalid Functions
```
define x = unknown_func() # Error: Unknown function 'unknown_func'
```
## Advanced Features
### Custom Functions
Add domain-specific functions to the interpreter:
```python
def custom_risk_score(mass_prob, calc_prob, birads_prob):
# Custom risk calculation
return combined_risk
interpreter.add_builtin_function('risk_score', custom_risk_score)
```
### Dynamic Rule Updates
Modify rules at runtime:
```python
loss_fn.update_rules(new_rules_string)
```
### Multiple Semantics
Choose different logical semantics:
- **Gödel**: min/max operations (sharp decisions)
- **Łukasiewicz**: bounded sum operations (smoother)
- **Product**: multiplication operations (independent probabilities)
```python
loss_fn = RuleBasedMammoConstraintsLoss(
feature_indices=indices,
rules=rules,
semantics="lukasiewicz" # or "godel", "product"
)
```
## Best Practices
1. **Start Simple**: Begin with basic constraints and add complexity gradually
2. **Use Comments**: Document the medical reasoning behind each constraint
3. **Test Incrementally**: Add constraints one at a time and validate behavior
4. **Meaningful Names**: Use descriptive variable names that reflect medical concepts
5. **Balanced Weights**: Start with equal weights and adjust based on domain importance
6. **Appropriate Transforms**: Use "logbarrier" for strict constraints, "hinge" for softer ones
## Migration from Hard-coded Constraints
To convert existing hard-coded constraints to rule language:
1. **Identify logical patterns** in your constraint code
2. **Extract variable definitions** for reused expressions
3. **Convert constraints** to rule language syntax
4. **Test equivalence** with the original implementation
5. **Refine and optimize** weights and transforms
Raw data
{
"_id": null,
"home_page": null,
"name": "logic-lang",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "logic, constraints, dsl, medical-imaging, soft-logic, rule-based, soft-constraints",
"author": null,
"author_email": "Mahbod Issaiy <mahbodissaiy2@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/78/fd0686d37ccfad4391806507a4ab668e963ae992a8af10a767c8a39881a1/logic_lang-0.1.1.tar.gz",
"platform": null,
"description": "# Rule Language Documentation\r\n\r\n## Overview\r\n\r\nThe Rule Language is a domain-specific language (DSL) designed for defining soft logic constraints in mammography classification. It allows you to replace hard-coded constraint logic with flexible, interpretable rule scripts that can be modified without changing Python code.\r\n\r\n## Syntax Reference\r\n\r\n### Comments\r\n\r\nComments start with `#` and continue to the end of the line:\r\n```\r\n# This is a comment\r\ndefine findings_L = mass_L | mc_L # Inline comment\r\n```\r\n\r\n### Variable Definitions\r\n\r\nDefine new variables using logical combinations of existing features:\r\n```\r\ndefine variable_name = expression\r\n```\r\n\r\n### Constant Definitions\r\n\r\nDefine constants for reusable literal values:\r\n```\r\nconst constant_name = value\r\n```\r\n\r\n### Variable Expectations\r\n\r\nDeclare which variables (features) the script expects to be provided:\r\n```\r\nexpect variable_name\r\nexpect variable1, variable2, variable3\r\n```\r\n\r\nExamples:\r\n```\r\n# Declare expected variables at the beginning of the script\r\nexpect left_birads, right_birads, mass_L, mc_L\r\n\r\n# Or declare them individually\r\nexpect comp\r\nexpect risk_score\r\n\r\n# Define constants for thresholds\r\nconst high_threshold = 0.8\r\nconst low_threshold = 0.2\r\nconst birads_cutoff = 4\r\n\r\n# Basic logical operations with literals\r\ndefine findings_L = mass_L | mc_L\r\ndefine high_risk = risk_score > 0.7 # Using literal number\r\ndefine moderate_risk = risk_score > low_threshold # Using constant\r\n\r\n# Function calls with mixed literals and variables\r\ndefine high_birads = sum(birads_L, [4, 5, 6])\r\ndefine threshold_check = risk_score >= high_threshold\r\n```\r\n\r\n### Constraints\r\n\r\nDefine constraints that will be enforced during training:\r\n```\r\nconstraint expression [weight=value] [transform=\"type\"] [param=value ...]\r\n```\r\n\r\nExamples:\r\n```\r\n# Basic constraint\r\nconstraint exactly_one(birads_L)\r\n\r\n# Constraint with weight and transform\r\nconstraint findings_L >> high_birads weight=0.7 transform=\"logbarrier\"\r\n\r\n# Constraint with multiple parameters\r\nconstraint exactly_one(comp) weight=1.5 transform=\"hinge\" alpha=2.0\r\n```\r\n\r\n## Operators\r\n\r\n### Logical Operators (in order of precedence, lowest to highest)\r\n\r\n1. **Implication (`>>`)**: A >> B (if A then B)\r\n ```\r\n constraint findings_L >> high_birads_L\r\n ```\r\n\r\n2. **OR (`|`)**: A | B (A or B)\r\n ```\r\n define findings = mass_L | mc_L\r\n ```\r\n\r\n3. **XOR (`^`)**: A ^ B (A exclusive or B)\r\n ```\r\n define exclusive = mass_L ^ mc_L\r\n ```\r\n\r\n4. **Comparison Operators**: `>`, `<`, `==`, `>=`, `<=`\r\n ```\r\n define high_risk = risk_score > threshold_value\r\n define similar_scores = score_a == score_b\r\n define within_range = score >= min_val & score <= max_val\r\n ```\r\n\r\n5. **AND (`&`)**: A & B (A and B)\r\n ```\r\n define strict_findings = mass_L & high_confidence\r\n ```\r\n\r\n6. **AND_n (`& variable`)**: AND across all elements in a tensor\r\n ```\r\n # All radiologists must agree (consensus)\r\n define consensus = & radiologist_assessments\r\n \r\n # All imaging modalities must show findings\r\n define all_modalities_positive = & imaging_results\r\n ```\r\n\r\n7. **OR_n (`| variable`)**: OR across all elements in a tensor \r\n ```\r\n # Any radiologist found something\r\n define any_concern = | radiologist_assessments\r\n \r\n # Any imaging modality shows findings\r\n define any_positive = | imaging_results\r\n ```\r\n\r\n8. **NOT (`~`)**: ~A (not A)\r\n ```\r\n define no_findings = ~findings_L\r\n ```\r\n\r\n9. **Indexing (`variable[...]`)**: Access tensor elements using numpy/pytorch syntax\r\n ```\r\n # Integer indexing\r\n define first_patient = patient_data[0]\r\n define specific_element = matrix[1, 2]\r\n define last_radiologist = assessments[2]\r\n \r\n # Slice indexing\r\n define first_two_patients = patient_data[:2]\r\n define middle_columns = matrix[:, 1:3]\r\n define every_other = data[::2]\r\n define specific_range = tensor[1:4]\r\n \r\n # Multi-dimensional indexing\r\n define patient_features = batch_data[0, :, 2]\r\n define view_subset = assessments[:, 1, :]\r\n ```\r\n\r\n### Parentheses\r\n\r\nUse parentheses to override operator precedence:\r\n```\r\ndefine complex = (mass_L | mc_L) & ~(birads_L >> findings_L)\r\n```\r\n\r\n## Statement Separation\r\n\r\n### Semicolons\r\n\r\nYou can use semicolons (`;`) to separate multiple statements on a single line, similar to Python:\r\n\r\n```\r\n# Multiple statements on one line\r\nexpect a, b; define c = a | b; constraint c\r\n\r\n# Mix of semicolons and newlines\r\nconst threshold = 0.5; expect risk_score\r\ndefine high_risk = risk_score > threshold\r\nconstraint high_risk weight=0.8\r\n\r\n# Multiple constants and definitions\r\nconst low = 0.2; const high = 0.8; define range_check = value >= low & value <= high\r\n```\r\n\r\n### Line-based Separation\r\n\r\nStatements can also be separated by newlines (traditional approach):\r\n```\r\nexpect findings_L, findings_R\r\ndefine bilateral = findings_L & findings_R\r\nconstraint bilateral weight=0.6\r\n```\r\n\r\n### Trailing Semicolons\r\n\r\nTrailing semicolons are optional and ignored:\r\n```\r\nexpect variables;\r\ndefine result = expression;\r\nconstraint result;\r\n```\r\n\r\n## Built-in Functions\r\n\r\n### `sum(probabilities, indices)`\r\n\r\nSum probabilities for specified class indices:\r\n```\r\ndefine high_birads_L = sum(birads_L, [4, 5, 6])\r\ndefine very_high_birads = sum(birads_L, [5, 6])\r\n```\r\n\r\n### `exactly_one(probabilities)`\r\n\r\nCreate exactly-one constraint for categorical probabilities:\r\n```\r\nconstraint exactly_one(birads_L) weight=1.0\r\n```\r\n\r\n### `mutual_exclusion(...probabilities)`\r\n\r\nCreate mutual exclusion constraint between multiple probabilities:\r\n```\r\nconstraint mutual_exclusion(mass_L, mc_L) weight=0.5\r\n```\r\n\r\n### `at_least_k(probabilities, k)`\r\n\r\nCreate constraint that at least k elements must be true:\r\n```\r\ndefine min_two_findings = at_least_k(findings_combined, 2)\r\nconstraint min_two_findings weight=0.6\r\n```\r\n\r\n### `at_most_k(probabilities, k)`\r\n\r\nCreate constraint that at most k elements can be true:\r\n```\r\ndefine max_one_high_birads = at_most_k(high_birads_indicators, 1)\r\nconstraint max_one_high_birads weight=0.7\r\n```\r\n\r\n### `exactly_k(probabilities, k)`\r\n\r\nCreate constraint that exactly k elements must be true:\r\n```\r\ndefine exactly_two_radiologists = exactly_k(radiologist_agreement, 2)\r\nconstraint exactly_two_radiologists weight=0.8\r\n```\r\n\r\n### `threshold_implication(antecedent, consequent, threshold)`\r\n\r\nCreate threshold-based implication constraint:\r\n```\r\ndefine strong_implication = threshold_implication(high_risk_L, findings_L, 0.7)\r\nconstraint strong_implication weight=0.9\r\n```\r\n\r\n### `conditional_probability(condition, event, target_prob)`\r\n\r\nCreate conditional probability constraint:\r\n```\r\ndefine conditional_findings = conditional_probability(high_birads_L, findings_L, 0.85)\r\nconstraint conditional_findings weight=0.8\r\n```\r\n\r\n### `clamp(tensor, min_val, max_val)`\r\n\r\nClamp tensor values to specified range:\r\n```\r\ndefine clamped_mass = clamp(mass_L, 0.1, 0.9)\r\n```\r\n\r\n### `threshold(tensor, threshold)`\r\n\r\nApply threshold to tensor:\r\n```\r\ndefine binary_mass = threshold(mass_L, 0.5)\r\n```\r\n\r\n### `greater_than(left, right)`\r\n\r\nCreate soft greater than comparison between two tensors:\r\n```\r\ndefine high_confidence = greater_than(confidence, baseline)\r\n```\r\n\r\n### `less_than(left, right)`\r\n\r\nCreate soft less than comparison between two tensors:\r\n```\r\ndefine low_risk = less_than(risk_score, threshold_low)\r\n```\r\n\r\n### `equals(left, right)`\r\n\r\nCreate soft equality comparison between two tensors:\r\n```\r\ndefine similar_scores = equals(score_a, score_b)\r\n```\r\n\r\n### `threshold_constraint(tensor, threshold, operator)`\r\n\r\nCreate threshold constraint with specified comparison operator:\r\n```\r\ndefine high_birads = threshold_constraint(birads_score, 0.7, \">\")\r\ndefine exact_match = threshold_constraint(prediction, 0.5, \"==\")\r\ndefine within_bounds = threshold_constraint(value, 0.3, \">=\")\r\n```\r\n\r\n## Data Types\r\n\r\n### Numbers\r\n\r\nInteger or floating-point numbers can be used directly in expressions:\r\n```\r\ndefine high_risk = risk_score > 0.8\r\ndefine moderate = value >= 0.3 & value <= 0.7\r\nconstraint threshold_check weight=1.5 # Literal number as parameter\r\n```\r\n\r\n### Strings\r\n\r\nText values enclosed in quotes:\r\n```\r\ntransform=\"logbarrier\"\r\ntransform='hinge'\r\nconst model_type = \"transformer\"\r\n```\r\n\r\n### Lists\r\n\r\nArrays of values:\r\n```\r\n[1, 2, 3]\r\n[4, 5, 6]\r\nconst important_classes = [4, 5, 6] # Can store list constants\r\n```\r\n\r\n### Mixed Type Expressions\r\n\r\nThe rule language automatically handles mixed types in expressions:\r\n```\r\n# Tensor compared with literal number\r\ndefine high_values = predictions > 0.5\r\n\r\n# Tensor compared with constant\r\nconst threshold = 0.7\r\ndefine above_threshold = scores >= threshold\r\n\r\n# Combining constants and variables\r\nconst low_cut = 0.2\r\nconst high_cut = 0.8\r\ndefine in_range = (values >= low_cut) & (values <= high_cut)\r\n```\r\n\r\n## Constraint Parameters\r\n\r\n### `weight` (float)\r\n\r\nRelative importance of the constraint:\r\n```\r\nconstraint exactly_one(birads_L) weight=2.0 # Higher weight = more important\r\n```\r\n\r\n### `transform` (string)\r\n\r\nLoss transformation method:\r\n- `\"logbarrier\"`: Logarithmic barrier (default, smooth penalties)\r\n- `\"hinge\"`: Hinge loss (softer penalties)\r\n- `\"linear\"`: Linear loss (proportional penalties)\r\n\r\n```\r\nconstraint findings >> high_birads transform=\"hinge\"\r\n```\r\n\r\n### Custom Parameters\r\n\r\nAdditional parameters specific to constraint types:\r\n```\r\nconstraint exactly_one(birads_L) weight=1.0 alpha=2.0 beta=0.5\r\n```\r\n\r\n## Complete Example\r\n\r\n```\r\n# Mammography Constraint Rules\r\n# ============================\r\n\r\n# Declare expected variables from model output\r\nexpect mass_L, mass_R, mc_L, mc_R\r\nexpect birads_L, birads_R, birads_score_L, birads_score_R\r\nexpect comp\r\n\r\n# Define constants for reusable thresholds\r\nconst high_risk_threshold = 0.7\r\nconst low_risk_threshold = 0.3\r\nconst birads_high_cutoff = 4\r\nconst birads_very_high_cutoff = 5\r\n\r\n# Feature definitions - combine findings per breast\r\ndefine findings_L = mass_L | mc_L\r\ndefine findings_R = mass_R | mc_R\r\n\r\n# BI-RADS probability groups using constants\r\ndefine high_birads_L = sum(birads_L, [4, 5, 6])\r\ndefine high_birads_R = sum(birads_R, [4, 5, 6])\r\ndefine very_high_birads_L = sum(birads_L, [5, 6])\r\ndefine very_high_birads_R = sum(birads_R, [5, 6])\r\ndefine low_birads_L = sum(birads_L, [1, 2])\r\ndefine low_birads_R = sum(birads_R, [1, 2])\r\n\r\n# Threshold-based risk assessments using literals and constants\r\ndefine high_risk_L = birads_score_L > high_risk_threshold\r\ndefine high_risk_R = birads_score_R > high_risk_threshold \r\ndefine very_low_risk_L = birads_score_L < low_risk_threshold\r\ndefine very_low_risk_R = birads_score_R < low_risk_threshold\r\ndefine balanced_assessment = equals(risk_L, risk_R)\r\n\r\n# Range constraints using multiple comparisons with literals\r\ndefine valid_risk_range_L = (birads_score_L >= 0.0) & (birads_score_L <= 1.0)\r\ndefine valid_risk_range_R = (birads_score_R >= 0.0) & (birads_score_R <= 1.0)\r\n\r\n# No findings (negation of findings)\r\ndefine no_findings_L = ~findings_L\r\ndefine no_findings_R = ~findings_R\r\n\r\n# Categorical exclusivity constraints\r\nconstraint exactly_one(birads_L) weight=1.0 transform=\"logbarrier\"\r\nconstraint exactly_one(birads_R) weight=1.0 transform=\"logbarrier\"\r\nconstraint exactly_one(comp) weight=0.7 transform=\"logbarrier\"\r\n\r\n# Logical implication constraints using threshold variables\r\nconstraint high_risk_L >> findings_L weight=0.8 transform=\"logbarrier\"\r\nconstraint high_risk_R >> findings_R weight=0.8 transform=\"logbarrier\"\r\n\r\n# Very High BI-RADS (5-6) -> Findings \r\nconstraint very_high_birads_L >> findings_L weight=0.7 transform=\"logbarrier\"\r\nconstraint very_high_birads_R >> findings_R weight=0.7 transform=\"logbarrier\"\r\n\r\n# Low BI-RADS with literal thresholds -> No findings (gentle constraint)\r\nconstraint very_low_risk_L >> no_findings_L weight=0.3 transform=\"logbarrier\"\r\nconstraint very_low_risk_R >> no_findings_R weight=0.3 transform=\"logbarrier\"\r\n\r\n# Range validation constraints\r\nconstraint valid_risk_range_L weight=2.0 transform=\"logbarrier\"\r\nconstraint valid_risk_range_R weight=2.0 transform=\"logbarrier\"\r\n\r\n# Comparison-based constraints using constants\r\nconstraint balanced_assessment weight=0.4 transform=\"hinge\"\r\n```\r\n\r\n## Usage Patterns\r\n\r\n### 1. Variable Expectations\r\n\r\nDeclare required variables at the beginning of scripts for better error handling:\r\n```\r\n# Declare all expected model outputs in one line\r\nexpect left_mass_prob, right_mass_prob, left_birads, right_birads, composition\r\n\r\n# Now use these variables with confidence\r\ndefine findings_L = left_mass_prob > 0.5\r\nconstraint exactly_one(left_birads)\r\n```\r\n\r\n### 2. Categorical Constraints\r\n\r\nEnsure exactly one category is selected:\r\n```\r\nconstraint exactly_one(birads_L) weight=1.0\r\nconstraint exactly_one(composition) weight=0.8\r\n```\r\n\r\n### 2. Implication Rules\r\n\r\nModel domain knowledge as if-then relationships:\r\n```\r\n# If findings present, then high BI-RADS likely\r\nconstraint findings_L >> high_birads_L weight=0.7\r\n\r\n# If very high BI-RADS, then findings must be present\r\nconstraint very_high_birads_L >> findings_L weight=0.8\r\n```\r\n\r\n### 3. Mutual Exclusion\r\n\r\nPrevent conflicting classifications:\r\n```\r\nconstraint mutual_exclusion(mass_L, calc_L) weight=0.5\r\n```\r\n\r\n### 4. Threshold Rules\r\n\r\nApply domain-specific thresholds:\r\n```\r\ndefine suspicious = threshold(combined_score, 0.7)\r\nconstraint suspicious >> high_birads weight=0.6\r\n```\r\n\r\n### 5. Comparison Constraints\r\n\r\nUse soft comparison operators for ordinal and threshold relationships:\r\n```\r\n# Risk stratification with thresholds\r\ndefine high_risk = risk_score > 0.8\r\ndefine low_risk = risk_score < 0.2\r\nconstraint high_risk >> findings weight=0.7\r\n```\r\n\r\n### 6. Consensus and Agreement (AND_n)\r\n\r\nModel situations where all elements must be true:\r\n```\r\n# All radiologists must agree for high confidence\r\ndefine consensus = & radiologist_assessments\r\nconstraint consensus > 0.7 >> definitive_diagnosis weight=0.9\r\n\r\n# All imaging modalities must show findings\r\ndefine multi_modal_positive = & imaging_results\r\nconstraint multi_modal_positive >> high_confidence weight=0.8\r\n```\r\n\r\n### 7. Any Evidence Detection (OR_n)\r\n\r\nModel situations where any element being true is significant:\r\n```\r\n# Any radiologist expressing concern triggers review\r\ndefine any_concern = | radiologist_assessments \r\nconstraint any_concern > 0.5 >> requires_review weight=0.6\r\n\r\n# Any modality showing findings suggests pathology\r\ndefine any_positive = | imaging_modalities\r\nconstraint any_positive >> potential_pathology weight=0.7\r\n```\r\n\r\n### 8. Tensor Indexing and Slicing\r\n\r\nAccess specific elements, patients, or subsets of multi-dimensional data:\r\n```\r\n# Patient-specific analysis\r\ndefine patient_0_risk = patient_risks[0]\r\ndefine patient_1_findings = findings[1, :]\r\nconstraint patient_0_risk > 0.8 >> patient_0_findings weight=1.0\r\n\r\n# View-specific mammography analysis\r\ndefine cc_assessments = assessments[:, 0, :] # CC view for all patients\r\ndefine mlo_assessments = assessments[:, 1, :] # MLO view for all patients\r\ndefine cc_consensus = & cc_assessments\r\ndefine mlo_consensus = & mlo_assessments\r\nconstraint cc_consensus & mlo_consensus >> high_confidence weight=0.9\r\n\r\n# Radiologist-specific consistency\r\ndefine senior_opinions = assessments[:, :, 0] # Senior across all views\r\ndefine resident_opinions = assessments[:, :, 1] # Resident across all views\r\ndefine senior_consistency = & senior_opinions\r\nconstraint senior_consistency weight=0.8\r\n\r\n# Subset analysis\r\ndefine high_risk_patients = patient_data[:3] # First 3 patients\r\ndefine feature_subset = features[:, 2:5] # Specific feature range\r\ndefine consensus_subset = & high_risk_patients\r\nconstraint consensus_subset >> intensive_monitoring weight=1.0\r\n\r\n\r\n# Equality constraints for consistency\r\ndefine balanced_breasts = equals(risk_L, risk_R)\r\nconstraint balanced_breasts weight=0.3 transform=\"hinge\"\r\n\r\n# Range constraints using multiple comparisons\r\ndefine valid_range = (score >= 0.1) & (score <= 0.9)\r\nconstraint valid_range weight=1.0\r\n```\r\n\r\n### 9. Ordinal Relationships\r\n\r\nModel ordered classifications with comparison operators:\r\n```\r\n# BI-RADS ordering constraints\r\ndefine birads_3_higher = birads_3 >= birads_2\r\ndefine birads_4_higher = birads_4 >= birads_3\r\nconstraint birads_3_higher & birads_4_higher weight=0.8\r\n```\r\n\r\n## Error Handling\r\n\r\nThe rule language provides helpful error messages for common issues:\r\n\r\n### Syntax Errors\r\n\r\n```\r\ndefine x = mass_L | # Error: Missing right operand\r\n```\r\n\r\n### Undefined Variables\r\n\r\n```\r\ndefine x = undefined_var # Error: Variable 'undefined_var' is not defined\r\n```\r\n\r\n### Type Mismatches\r\n\r\n```\r\nconstraint exactly_one(5) # Error: Expected Truth object, got number\r\n```\r\n\r\n### Invalid Functions\r\n\r\n```\r\ndefine x = unknown_func() # Error: Unknown function 'unknown_func'\r\n```\r\n\r\n## Advanced Features\r\n\r\n### Custom Functions\r\n\r\nAdd domain-specific functions to the interpreter:\r\n```python\r\ndef custom_risk_score(mass_prob, calc_prob, birads_prob):\r\n # Custom risk calculation\r\n return combined_risk\r\n\r\ninterpreter.add_builtin_function('risk_score', custom_risk_score)\r\n```\r\n\r\n### Dynamic Rule Updates\r\n\r\nModify rules at runtime:\r\n```python\r\nloss_fn.update_rules(new_rules_string)\r\n```\r\n\r\n### Multiple Semantics\r\n\r\nChoose different logical semantics:\r\n- **G\u00f6del**: min/max operations (sharp decisions)\r\n- **\u0141ukasiewicz**: bounded sum operations (smoother)\r\n- **Product**: multiplication operations (independent probabilities)\r\n\r\n```python\r\nloss_fn = RuleBasedMammoConstraintsLoss(\r\n feature_indices=indices,\r\n rules=rules,\r\n semantics=\"lukasiewicz\" # or \"godel\", \"product\"\r\n)\r\n```\r\n\r\n## Best Practices\r\n\r\n1. **Start Simple**: Begin with basic constraints and add complexity gradually\r\n2. **Use Comments**: Document the medical reasoning behind each constraint\r\n3. **Test Incrementally**: Add constraints one at a time and validate behavior\r\n4. **Meaningful Names**: Use descriptive variable names that reflect medical concepts\r\n5. **Balanced Weights**: Start with equal weights and adjust based on domain importance\r\n6. **Appropriate Transforms**: Use \"logbarrier\" for strict constraints, \"hinge\" for softer ones\r\n\r\n## Migration from Hard-coded Constraints\r\n\r\nTo convert existing hard-coded constraints to rule language:\r\n\r\n1. **Identify logical patterns** in your constraint code\r\n2. **Extract variable definitions** for reused expressions\r\n3. **Convert constraints** to rule language syntax\r\n4. **Test equivalence** with the original implementation\r\n5. **Refine and optimize** weights and transforms\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A domain-specific language for defining soft logic constraints in medical/general domains",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/mahbodez/logic-lang-package/issues",
"Documentation": "https://github.com/mahbodez/logic-lang-package#readme",
"Homepage": "https://github.com/mahbodez/logic-lang-package",
"Repository": "https://github.com/mahbodez/logic-lang-package.git"
},
"split_keywords": [
"logic",
" constraints",
" dsl",
" medical-imaging",
" soft-logic",
" rule-based",
" soft-constraints"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2e09e5ffc326fef50948b44067fe7a1558f6a1b250410fc7c7b53012e33a7dc6",
"md5": "2b52c91057dd062dc16abce45784a9da",
"sha256": "163c01375b3078bd812c9fab8b52a624bebb0c03c357e3784b97f795bbf05d2f"
},
"downloads": -1,
"filename": "logic_lang-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b52c91057dd062dc16abce45784a9da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 37465,
"upload_time": "2025-08-18T05:55:05",
"upload_time_iso_8601": "2025-08-18T05:55:05.191130Z",
"url": "https://files.pythonhosted.org/packages/2e/09/e5ffc326fef50948b44067fe7a1558f6a1b250410fc7c7b53012e33a7dc6/logic_lang-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c278fd0686d37ccfad4391806507a4ab668e963ae992a8af10a767c8a39881a1",
"md5": "25b688d6e8284bd31a1fa39e32286ec9",
"sha256": "5d2f6f1b42feb14936b0354461054781aca9283b08a8b8614f7e2315d4692893"
},
"downloads": -1,
"filename": "logic_lang-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "25b688d6e8284bd31a1fa39e32286ec9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 41394,
"upload_time": "2025-08-18T05:55:06",
"upload_time_iso_8601": "2025-08-18T05:55:06.335584Z",
"url": "https://files.pythonhosted.org/packages/c2/78/fd0686d37ccfad4391806507a4ab668e963ae992a8af10a767c8a39881a1/logic_lang-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 05:55:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mahbodez",
"github_project": "logic-lang-package",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "logic-lang"
}
JSON
