Metadata-Version: 2.4
Name: Ayoub-Allali-HCP-Data
Version: 1.0.0
Summary: Easy access to Morocco's official demographic data (HCP – RGPH 2024) for data scientists and analysts.
Author: Ayoub Allali
License: MIT
Project-URL: Homepage, https://github.com/AyoubAllali/Ayoub_Allali_HCP_Data
Project-URL: Bug Tracker, https://github.com/AyoubAllali/Ayoub_Allali_HCP_Data/issues
Project-URL: Data Source, https://www.hcp.ma
Keywords: morocco,maroc,hcp,rgph,census,demographics,population,data,open-data,urbanisation,statistics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Sociology
Classifier: Natural Language :: French
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3

# Ayoub_Allali_HCP_Data

[![PyPI version](https://badge.fury.io/py/Ayoub-Allali-HCP-Data.svg)](https://pypi.org/project/Ayoub-Allali-HCP-Data/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A Python library that gives **data scientists and analysts** instant access to Morocco's official demographic data published by the **Haut-Commissariat au Plan (HCP)** – General Population and Housing Census **RGPH 2024**.

> **Data source:** [hcp.ma](https://www.hcp.ma) – Recensement Général de la Population et de l'Habitat 2024.

---

## Installation

```bash
pip install Ayoub-Allali-HCP-Data
```

---

## Quick Start

```python
import ayoub_allali_hcp_data as hcp

# Discover all datasets
hcp.info()

# --- Scalar values ---
print(hcp.get_population_legale())     # 36828330
print(hcp.get_nombre_menages())        # 9275038
print(hcp.get_taux_urbanisation())     # 0.628

# --- DataFrames ---
df = hcp.get_population_historique()
print(df)
```

---

## Available Datasets

| Function | Description |
|---|---|
| `get_population_legale()` | Official legal population – 2024 (int) |
| `get_nombre_menages()` | Total number of households – 2024 (int) |
| `get_taux_urbanisation()` | Urbanisation rate – 2024 (float, e.g. 0.628) |
| `get_population_historique()` | Population & growth rate per census (1960–2024) |
| `get_population_urbaine_rurale()` | Urban / Rural counts & urbanisation rate (1960–2024) |
| `get_structure_age()` | Age-group distribution % – Ensemble / Urban / Rural (2024) |
| `get_fecondite()` | Total Fertility Rate by milieu (2024) |
| `get_acces_reseaux_publics()` | % HH with access to water, electricity, sanitation (2024) |
| `get_taille_menage()` | Average household size – Ensemble / Urban / Rural (2004–2024) |

You can also use the generic `load()` function:

```python
df = hcp.load("structure_age")
```

And list all dataset names:

```python
hcp.list_datasets()
# ['acces_reseaux_publics', 'fecondite', 'nombre_menages', ...]
```

---

## Detailed Examples

### Population history

```python
import ayoub_allali_hcp_data as hcp
import matplotlib.pyplot as plt

df = hcp.get_population_historique()
print(df)
#    Année    Population  Taux d'accroissement
# 0   1960  1.162647e+07                   NaN
# 1   1971  1.537926e+07                  2.58
# 2   1982  2.041956e+07                  2.61
# 3   1994  2.607372e+07                  2.06
# 4   2004  2.989171e+07                  1.38
# 5   2014  3.384824e+07                  1.25
# 6   2024  3.682833e+07                  0.85

plt.plot(df["Année"], df["Population"] / 1e6, marker="o")
plt.title("Population du Maroc (millions)")
plt.xlabel("Année"); plt.ylabel("Population (M)")
plt.show()
```

### Urban vs Rural breakdown

```python
df = hcp.get_population_urbaine_rurale()
print(df)
#    Année    Urbain     Rural   Ensemble  Taux d'urbanisation (%)
# 0   1960   3389613   8236857  11626470                      29.2
# ...
# 6   2024  23110108  13718222  36828330                      62.8
```

### Access to public utilities

```python
df = hcp.get_acces_reseaux_publics()
print(df)
#        Réseaux publics  Urbain  Rural  Ensemble
# 0         Eau courante    97.1   54.6      82.9
# 1          Electricité    98.6   91.8      96.3
# 2       Assainissement    93.4    9.6      65.4
```

### Fertility rate

```python
df = hcp.get_fecondite()
print(df)
#       Milieu  Indice synthétique de fécondité
# 0   Ensemble                              2.0
# 1     Urbain                              1.8
# 2      Rural                              2.4
```

---

## License

MIT © Ayoub Allali

Data is published by **HCP Morocco** and is used here for educational and research purposes.
