Skip to content

Commit 19b31b4

Browse files
emjay0921emjay0921
committed
fix(spp_graduation): add web_icon to Graduation menu and fix pre-existing README diffs
- Added web_icon attribute to Graduation root menu to display the existing openspp-graduation-menu-icons.png icon - Regenerated READMEs for spp_aggregation, spp_metrics_core, and spp_metrics_services to match updated DESCRIPTION.md content
1 parent 31cf2d2 commit 19b31b4

4 files changed

Lines changed: 173 additions & 127 deletions

File tree

‎spp_aggregation/README.rst‎

Lines changed: 65 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -22,84 +22,87 @@ OpenSPP Aggregation Engine
2222

2323
|badge1| |badge2| |badge3|
2424

25-
Unified aggregation engine for computing statistics, breakdowns, and
26-
fairness metrics over scoped registrant populations. Supports multiple
27-
scope types (CEL expressions, areas, spatial queries, explicit IDs) with
28-
access control, caching, and privacy enforcement.
25+
Unified aggregation service that all consumers (simulation API, GIS API,
26+
dashboards) use to compute population statistics with demographic
27+
breakdowns and privacy enforcement. Resolves a scope (CEL expression,
28+
area, polygon, explicit IDs) to registrant IDs, computes requested
29+
statistics, applies k-anonymity suppression, and caches results.
2930

3031
Key Capabilities
3132
~~~~~~~~~~~~~~~~
3233

33-
- Define reusable aggregation scopes: CEL expression, area, area tag,
34-
spatial polygon/buffer, or explicit registrant IDs
35-
- Resolve scopes to registrant sets with union and intersection
36-
operations
37-
- Compute statistics (count, Gini) with extensible statistic registry
38-
supporting CEL variables
39-
- Role-based access control with per-user scope type restrictions,
40-
dimension limits, and area constraints
41-
- Result caching with configurable TTL per scope type and automatic
42-
cleanup
43-
- Privacy enforcement via k-anonymity suppression on computed results
44-
- Convenience methods for area-based, expression-based, fairness, and
45-
distribution queries
34+
- Single entry point (``spp.aggregation.service.compute_aggregation``)
35+
for all analytics queries
36+
- Scope resolution: CEL expressions, admin areas, area tags, spatial
37+
polygons/buffers, explicit IDs
38+
- Multi-dimensional breakdown (up to 3 dimensions) using demographic
39+
dimensions
40+
- Result caching with configurable TTL and manual invalidation
41+
- Per-user access rules controlling scope types, dimensions, and
42+
k-anonymity thresholds
4643

4744
Key Models
4845
~~~~~~~~~~
4946

50-
+----------------------------+----------+----------------------------+
51-
| Model | Type | Description |
52-
+============================+==========+============================+
53-
| ``spp.aggregation.scope`` | Concrete | Configurable aggregation |
54-
| | | scope definitions |
55-
+----------------------------+----------+----------------------------+
56-
| ``spp | Concrete | Per-user/group access |
57-
| .aggregation.access.rule`` | | control rules |
58-
+----------------------------+----------+----------------------------+
59-
| ``spp | Concrete | Persistent cache entries |
60-
| .aggregation.cache.entry`` | | with TTL |
61-
+----------------------------+----------+----------------------------+
62-
| ``spp.ag | Abstract | Strategy-based scope |
63-
| gregation.scope.resolver`` | | resolution service |
64-
+----------------------------+----------+----------------------------+
65-
| ``spp.aggregation.cache`` | Abstract | Cache service with TTL and |
66-
| | | cleanup |
67-
+----------------------------+----------+----------------------------+
68-
| ``spp.aggreg | Abstract | Statistic computation |
69-
| ation.statistic.registry`` | | registry (builtins + CEL) |
70-
+----------------------------+----------+----------------------------+
71-
| ` | Abstract | Main aggregation entry |
72-
| `spp.aggregation.service`` | | point |
73-
+----------------------------+----------+----------------------------+
47+
+----------------------------------+----------------------------------+
48+
| Model | Description |
49+
+==================================+==================================+
50+
| ``spp.aggregation.scope`` | Defines what to aggregate (CEL, |
51+
| | area, polygon, explicit IDs) |
52+
+----------------------------------+----------------------------------+
53+
| ``spp.aggregation.access.rule`` | Per-user/group access level, |
54+
| | scope restrictions, k-threshold |
55+
+----------------------------------+----------------------------------+
56+
| ``spp.aggregation.cache.entry`` | Cached aggregation results |
57+
+----------------------------------+----------------------------------+
58+
| ``spp.aggregation.service`` | Abstract service: main |
59+
| | aggregation entry point |
60+
+----------------------------------+----------------------------------+
61+
| `` | Abstract service: resolves |
62+
| spp.aggregation.scope.resolver`` | scopes to registrant IDs |
63+
+----------------------------------+----------------------------------+
64+
| ``spp. | Abstract service: dispatches |
65+
| aggregation.statistic.registry`` | statistic computation |
66+
+----------------------------------+----------------------------------+
7467

7568
Configuration
7669
~~~~~~~~~~~~~
7770

78-
- Aggregation scopes: **Settings > Aggregation > Aggregation Scopes**
79-
- Access rules: **Settings > Aggregation > Access Rules**
80-
- Cache cleanup runs daily via scheduled action
71+
After installing:
72+
73+
1. Navigate to **Settings > Aggregation > Configuration > Scopes** to
74+
define reusable scopes
75+
2. Configure **Access Rules** to set per-user/group privacy levels and
76+
scope restrictions
77+
3. Verify the **Cache Cleanup** scheduled action is active under
78+
**Settings > Technical > Scheduled Actions**
79+
80+
UI Location
81+
~~~~~~~~~~~
82+
83+
- **Menu**: Settings > Aggregation > Configuration > Scopes
84+
- **Menu**: Settings > Aggregation > Configuration > Demographic
85+
Dimensions
86+
- **Menu**: Settings > Aggregation > Configuration > Access Rules
8187

8288
Security
8389
~~~~~~~~
8490

85-
+----------------------------------+----------------------------------+
86-
| Group | Access |
87-
+==================================+==================================+
88-
| ``spp_aggr | Read-only access to scopes and |
89-
| egation.group_aggregation_read`` | cache |
90-
+----------------------------------+----------------------------------+
91-
| ``spp_aggre | Read/write scopes and access |
92-
| gation.group_aggregation_write`` | rules |
93-
+----------------------------------+----------------------------------+
94-
| ``spp_aggreg | Implied by write group |
95-
| ation.group_aggregation_viewer`` | |
96-
+----------------------------------+----------------------------------+
97-
| ``spp_aggrega | Implied by viewer group |
98-
| tion.group_aggregation_officer`` | |
99-
+----------------------------------+----------------------------------+
100-
| ``spp_aggrega | Full access, implied by admin |
101-
| tion.group_aggregation_manager`` | |
102-
+----------------------------------+----------------------------------+
91+
============================= =============================
92+
Group Access
93+
============================= =============================
94+
``group_aggregation_read`` Read scopes and cache entries
95+
``group_aggregation_write`` Full CRUD on scopes and cache
96+
``group_aggregation_manager`` Full CRUD on access rules
97+
============================= =============================
98+
99+
Extension Points
100+
~~~~~~~~~~~~~~~~
101+
102+
- Add new scope types by extending ``spp.aggregation.scope`` and
103+
``spp.aggregation.scope.resolver``
104+
- Register custom statistics via ``spp.aggregation.statistic.registry``
105+
- Override ``_compute_single_statistic()`` for custom computation logic
103106

104107
Dependencies
105108
~~~~~~~~~~~~

‎spp_graduation/views/graduation_menus.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
id="menu_graduation_root"
66
name="Graduation"
77
sequence="60"
8+
web_icon="spp_graduation,static/description/openspp-graduation-menu-icons.png"
89
groups="group_spp_graduation_user"
910
/>
1011

‎spp_metrics_core/README.rst‎

Lines changed: 45 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -22,38 +22,63 @@ OpenSPP Metrics Core
2222

2323
|badge1| |badge2| |badge3|
2424

25-
Unified metric foundation providing abstract base models for statistics,
26-
simulations, and reporting across OpenSPP modules.
25+
Shared foundation for all metric types in OpenSPP (statistics,
26+
simulation metrics, and custom domain metrics). Provides an abstract
27+
base model with identity, presentation, and categorization fields, plus
28+
a hierarchical category system. Concrete metric modules inherit from the
29+
base and add their own computation fields.
2730

2831
Key Capabilities
2932
~~~~~~~~~~~~~~~~
3033

31-
- Abstract base model for defining reusable metrics with label, unit,
32-
and decimal precision
33-
- Hierarchical metric categories with unique code constraints
34-
- Category tree with parent-child recursion prevention
35-
- Default metric categories for population, coverage, targeting, and
36-
distribution
34+
- Abstract base model (``spp.metric.base``) with shared identity,
35+
presentation, and metadata fields
36+
- Hierarchical metric category system with unique codes
37+
- Default categories: Demographics, Vulnerability, Programs, Geographic,
38+
Economic, Fairness
3739

3840
Key Models
3941
~~~~~~~~~~
4042

41-
+-------------------------+----------+----------------------------+
42-
| Model | Type | Description |
43-
+=========================+==========+============================+
44-
| ``spp.metric.base`` | Abstract | Base fields and logic |
45-
| | | inherited by concrete |
46-
| | | metrics |
47-
+-------------------------+----------+----------------------------+
48-
| ``spp.metric.category`` | Concrete | Hierarchical grouping of |
49-
| | | metrics by domain |
50-
+-------------------------+----------+----------------------------+
43+
+-------------------------+-------------------------------------------+
44+
| Model | Description |
45+
+=========================+===========================================+
46+
| ``spp.metric.base`` | Abstract model inherited by all concrete |
47+
| | metric types |
48+
+-------------------------+-------------------------------------------+
49+
| ``spp.metric.category`` | Hierarchical categorization for |
50+
| | organizing metrics |
51+
+-------------------------+-------------------------------------------+
5152

5253
Configuration
5354
~~~~~~~~~~~~~
5455

55-
No configuration required. Default categories are created via data files
56-
on install.
56+
After installing, default metric categories are created automatically.
57+
Add custom categories via **Settings > Technical > Metric Categories**
58+
or in XML data files.
59+
60+
UI Location
61+
~~~~~~~~~~~
62+
63+
No standalone menu; library module consumed by ``spp_statistic``,
64+
``spp_simulation``, and other metric modules.
65+
66+
Security
67+
~~~~~~~~
68+
69+
===================== =======================
70+
Group Access
71+
===================== =======================
72+
``base.group_user`` Read categories
73+
``base.group_system`` Full CRUD on categories
74+
===================== =======================
75+
76+
Extension Points
77+
~~~~~~~~~~~~~~~~
78+
79+
- Inherit ``spp.metric.base`` to create domain-specific metric models
80+
- Add custom categories via XML data records referencing
81+
``spp.metric.category``
5782

5883
Dependencies
5984
~~~~~~~~~~~~

‎spp_metrics_services/README.rst‎

Lines changed: 62 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -22,68 +22,85 @@ OpenSPP Metrics Services
2222

2323
|badge1| |badge2| |badge3|
2424

25-
Shared service layer providing demographic dimensions, fairness
26-
analysis, distribution statistics, privacy enforcement, and breakdown
27-
computation for OpenSPP aggregation and reporting modules.
25+
Shared computation services for fairness analysis, distribution
26+
statistics, demographic breakdowns, privacy enforcement, and dimension
27+
caching. These abstract services are consumed by ``spp_aggregation``,
28+
``spp_simulation``, GIS APIs, and dashboards. No standalone UI; provides
29+
only programmatic service models.
2830

2931
Key Capabilities
3032
~~~~~~~~~~~~~~~~
3133

32-
- Define demographic dimensions (gender, age group, disability) as
33-
field-based or CEL expression-based
34-
- Compute fairness metrics with disparity ratios and equity scores
35-
- Calculate distribution statistics including Gini coefficient, Lorenz
36-
curve, percentiles, and standard deviation
37-
- Enforce k-anonymity privacy with complementary suppression to prevent
38-
differencing attacks
39-
- Compute multi-dimensional breakdowns of registrant populations
40-
- Cache dimension evaluations using Odoo ORM cache for performance
34+
- Fairness analysis: compute equity scores and disparity ratios across
35+
demographic dimensions
36+
- Distribution statistics: Gini coefficient, Lorenz curve, percentiles,
37+
descriptive stats
38+
- Demographic breakdowns: multi-dimensional grouping with cached CEL
39+
evaluations
40+
- Privacy enforcement: k-anonymity with complementary suppression to
41+
prevent differencing attacks
42+
- Configurable demographic dimensions: field-based or CEL
43+
expression-based
4144

4245
Key Models
4346
~~~~~~~~~~
4447

45-
+----------------------------+----------+----------------------------+
46-
| Model | Type | Description |
47-
+============================+==========+============================+
48-
| ``s | Concrete | Configurable demographic |
49-
| pp.demographic.dimension`` | | dimensions for breakdowns |
50-
+----------------------------+----------+----------------------------+
51-
| ``spp | Abstract | ORM-cached dimension |
52-
| .metrics.dimension.cache`` | | evaluation service |
53-
+----------------------------+----------+----------------------------+
54-
| ``spp.metrics.fairness`` | Abstract | Fairness and equity |
55-
| | | analysis service |
56-
+----------------------------+----------+----------------------------+
57-
| `` | Abstract | Distribution statistics |
58-
| spp.metrics.distribution`` | | (Gini, Lorenz, |
59-
| | | percentiles) |
60-
+----------------------------+----------+----------------------------+
61-
| ``spp.metrics.privacy`` | Abstract | K-anonymity enforcement |
62-
| | | with complementary |
63-
| | | suppression |
64-
+----------------------------+----------+----------------------------+
65-
| ``spp.metrics.breakdown`` | Abstract | Multi-dimensional |
66-
| | | population breakdown |
67-
| | | service |
68-
+----------------------------+----------+----------------------------+
48+
+---------------------------------+-----------------------------------+
49+
| Model | Description |
50+
+=================================+===================================+
51+
| ``spp.demographic.dimension`` | Configurable dimension for |
52+
| | breakdowns (field or CEL) |
53+
+---------------------------------+-----------------------------------+
54+
| ``spp.metrics.fairness`` | Abstract service: equity/parity |
55+
| | analysis |
56+
+---------------------------------+-----------------------------------+
57+
| ``spp.metrics.distribution`` | Abstract service: distribution |
58+
| | statistics |
59+
+---------------------------------+-----------------------------------+
60+
| ``spp.metrics.breakdown`` | Abstract service: |
61+
| | multi-dimensional grouping |
62+
+---------------------------------+-----------------------------------+
63+
| ``spp.metrics.privacy`` | Abstract service: k-anonymity |
64+
| | enforcement |
65+
+---------------------------------+-----------------------------------+
66+
| ``spp.metrics.dimension.cache`` | Abstract service: dimension |
67+
| | evaluation cache |
68+
+---------------------------------+-----------------------------------+
6969

7070
Configuration
7171
~~~~~~~~~~~~~
7272

73-
- Demographic dimensions are managed via **Settings > Aggregation >
74-
Demographic Dimensions**
75-
- Default dimensions for gender and age group are created on install
76-
- K-anonymity threshold defaults to 5 (configurable per access rule)
73+
After installing:
74+
75+
1. Default demographic dimensions (gender, disability, age group) are
76+
created via data file
77+
2. Add custom dimensions at **Settings > Aggregation > Configuration >
78+
Demographic Dimensions** (menu provided by ``spp_aggregation``)
79+
80+
UI Location
81+
~~~~~~~~~~~
82+
83+
No standalone menu; extends existing views. Dimension management UI
84+
provided by ``spp_aggregation``.
7785

7886
Security
7987
~~~~~~~~
8088

81-
===================== ==========================================
89+
===================== ===================================
8290
Group Access
83-
===================== ==========================================
84-
``base.group_user`` Read-only access to demographic dimensions
85-
``base.group_system`` Full CRUD access to demographic dimensions
86-
===================== ==========================================
91+
===================== ===================================
92+
``base.group_user`` Read demographic dimensions
93+
``base.group_system`` Full CRUD on demographic dimensions
94+
===================== ===================================
95+
96+
Extension Points
97+
~~~~~~~~~~~~~~~~
98+
99+
- Override ``_analyze_dimension()`` in ``spp.metrics.fairness`` for
100+
custom analysis logic
101+
- Add new dimension types by extending ``spp.demographic.dimension``
102+
- Override ``enforce()`` in ``spp.metrics.privacy`` for custom
103+
suppression strategies
87104

88105
Dependencies
89106
~~~~~~~~~~~~

0 commit comments

Comments
 (0)