Metadata-Version: 2.4
Name: memeh-coder
Version: 1.0.0
Summary: Administrative identity infrastructure for generating persistent ISO-aligned codes for public locations, facilities, assets, and services.
Home-page: https://github.com/memeh-trust/memeh-coder
Author: David Moinina Sengeh, Mohamed James, Mosses TF Vibbe
Author-email: dsengeh@gmail.com, mohamedjames21@gmail.com, vbmo2007@gmail.com
Maintainer: David Moinina Sengeh, Mohamed James, Mosses TF Vibbe
Maintainer-email: dsengeh@gmail.com, mohamedjames21@gmail.com, vbmo2007@gmail.com
License: MIT
Project-URL: Documentation, https://github.com/memeh-trust/memeh-coder/tree/main/docs
Project-URL: Source, https://github.com/memeh-trust/memeh-coder
Project-URL: Bug Tracker, https://github.com/memeh-trust/memeh-coder/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.3
Requires-Dist: openpyxl>=3.0
Requires-Dist: xlrd>=2.0
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn>=0.29; extra == "api"
Dynamic: license-file

# Memeh Coder

Memeh Coder is an open digital public good for administrative and entity
identity. It turns an ordered spreadsheet into persistent, reproducible codes
for schools, health facilities, assets, service points, and other public
records.

* Unique school identity for an education management information system.
* Unique health facility identity for a health management information system.
* Standard administrative level geocode for country planning.
* Administrative level identity generation in a digital addressing system.

## The problem

Public records are often identified by names or by IDs that only work inside
one database. Names vary by spelling, language, abbreviations, punctuation, and
administrative reform. Internal IDs cannot be understood by another ministry,
partner, country, or information system.

Without a shared identity key, datasets cannot be joined safely. The result is
duplicate facilities and assets, broken historical continuity, incorrect
counts, and codes that collide when records are exchanged.

Memeh Coder addresses this question:

> How can an authority give one administrative unit or public entity a
> persistent, reproducible, and verifiable identity using data it already owns,
> without depending on a proprietary central registry?

## Why ISO is used

ISO 3166-1 provides a shared international reference for countries. ISO 3166-2
may provide the principal subdivision of a country. Memeh Coder uses that
reference as the start of an identifier, then extends it with nationally
governed administrative levels and an entity sequence.

The generated district, chiefdom, ward, school, facility, or asset components
are local codes, not official ISO assignments. This distinction lets national
systems keep local authority while remaining understandable across borders and
partner systems.

## The methodology

1. Load one ordered CSV or Excel master list.
2. Normalise administrative and category values.
3. Anchor the record to an ISO country and, where available, ISO 3166-2.
4. Assign deterministic child codes under each complete parent path.
5. Assign a positional entity identifier independent of the DataFrame index.
6. Reject administrative and final identifier collisions.
7. Optionally append a Damm check digit to detect common transcription errors.
8. Export the coded data and preserve the configuration as provenance.

## Dependencies

The Python package uses pandas and can be used from scripts or Jupyter
notebooks. The browser coder requires no Python installation.

##  Installation
Install memeh_coder with pip3

```python
pip3 install memeh-coder
```
      
##   Usage/Examples
The package has two modules: `iso` provides country and subdivision reference
helpers, while `geo` generates administrative levels, entity identifiers,
collision checks, and optional Damm check digits. Public releases include ISO
reference tables and synthetic examples only. Country operational datasets are
configured separately and are never silently bundled into the PyPI package.
   

   **GEO Examples**:
   
   Generating a unique school identity for an EMIS system
      
```python
from  memeh_coder import geo
```
```python
schools_df = geo.data('sl_school_list.csv')
```
```python
#columns
schools_df.columns 
#output
Index(['idregion', 'iddistrict', 'idchiefdom', 'idsection', 'sch_type',
       'idschool_name'],
      dtype='object')
Region = geo.level1(schools_df,'idregion')
Region
District = geo.level2(schools_df,Region,'iddistrict')
District
Chiefdom = geo.level3(schools_df,District,'idchiefdom')
Chiefdom
Section = geo.level4(schools_df,Chiefdom,'idsection')
Section
Schools = geo.uniqueid(schools_df,Section,'idschool_name')
Schools
School_Type = geo.categorical(schools_df,'sch_type',encoding_type='integer')
School_Type
school_masterlist = geo.gencode(Section,Schools,cat_df=School_Type,level_column='idchiefdom',uniqueid_column='idschool_name_edited_code',title='emis_code',sep='-',checksum='damm')
school_masterlist
```

## Use Memeh Coder from any system

Applications that do not run Python can call the versioned REST API. Install the optional API service with `python -m pip install "memeh_coder[api]"`, start it with `memeh-coder-api`, and open `/docs` for its interactive OpenAPI documentation.

The main generation endpoint is `POST /v1/identities/generate`. It accepts an ISO country name or alpha code plus governed administrative codes, an entity code, and a stable source-system ID. See [REST API documentation](docs/REST_API.md).

ISO 3166 covers the country and principal subdivision identity. Lower administrative and entity codes remain governed national or organizational data; Memeh Coder links them into one collision-checked identity.

Generating administrative level coding in digital addressing system


```python
from  memeh_coder import geo
```
```python
schools_df = geo.data('sl_school_list.csv')
```
```python
#columns
schools_df.columns 
#output
Index(['idregion', 'iddistrict', 'idchiefdom', 'idsection', 'sch_type',
       'idschool_name'],
      dtype='object')
Region = geo.level1(schools_df,'idregion')
Region
District = geo.level2(schools_df,Region,'iddistrict')
District
Chiefdom = geo.level3(schools_df,District,'idchiefdom')
Chiefdom
Section = geo.level4(schools_df,Chiefdom,'idsection')
Section
Region_Alpha = geo.alpha_coder(Region,column='idregion',clen=2)
District_alpha = geo.alpha_coder(District,column='iddistrict',clen=3,add_char='D')
Alpha_df = geo.alpha_merger(region_alpha,district_alpha,'idregion',sufixs=['Reg','Dis'],level=1,sep='-')
Chiefdom_level = Chiefdom[['iddistrict_code','idchiefdom','idchiefdom_code']]
Chiefdom_Alpha= geo.alpha_merger_l3(alpha_df,Chiefdom_level,'idchiefdom_code','iddistrict_code',2,sep='-')
Section_level =   Section[['idchiefdom_code','idsection','idsection_code']]
digital_addressing = geo.alpha_merger_l4(l3,Section_level,'idsection_code','idchiefdom_code',4,sep='-')
digital_addressing
```

**ISO Example**:

```python
import pandas as pd
from  memeh_coder import iso
continents_df = pd.read_csv(iso.countries_data())
subdivision_df = pd.read_csv(iso.subdiv_data())
iso.continents(continents_df)
dataframe of subregions in a continent
iso.subregions(continents_df,'Africa',level=1,sep='-')
iso.countries(continents_df,'Africa',level=2,sep='-')
iso.country(subdivision_df,'Sierra Leone')

```

## Documentation 

Documentation is available  [here](https://github.com/memeh-trust/memeh-coder/blob/gh-pages/documentation.md) 

## Contributing

PR requests are highly welcome, fork and commit your changes 

## Maintainers

- David Moinina Sengeh ([moinina](https://github.com/moinina))
- Mohamed James ([mjames21](https://github.com/mjames21))
- Mosses TF Vibbe ([Mosesvb](https://github.com/Mosesvb))

 
## License

[MIT](https://choosealicense.com/licenses/mit/)  
       
