📚 Documentation Complète

Documentation Cartograpy

Guide complet pour maîtriser la cartographie en Python avec Cartograpy

1

Présentation

Cartograpy est un package Python conçu pour faciliter la manipulation de données géographiques et la création de cartes de manière simple et intuitive. Grâce à ses nombreuses fonctionnalités, il permet aussi bien aux débutants qu'aux experts de visualiser, analyser et mettre en valeur des données spatiales en quelques lignes de code.

Cartograpy Demo

And you have all you need !

2

Fonctionnalités

Voici ce que vous pouvez faire avec cartograpy :

2.1 Téléchargement et accès rapide aux données géographiques

  • Découpages administratifs : Téléchargez en une ligne les limites administratives de n'importe quel pays, région ou commune.
  • Données de continents : Récupérez facilement les frontières vectorielles des continents ou sous-continents.
  • Réseaux hydrographiques : Accédez à des couches de rivières, fleuves ou plans d'eau.
  • Géocodage des localités : Enrichissez vos jeux de données en retrouvant des zones géographiques associées à des adresses ou des noms de lieux.

2.2 Pre-processing et processing des données

  • Importez tout type de données vectorielles ou matricielles : Shapefile, GeoJSON, KML, GPX, GPKG, CSV, Parquet, etc.
  • Exportez vos analyses dans le format de votre choix, prêt pour QGIS, ArcGIS ou le web.
  • Listing automatique : Repérez en un coup d'œil tous les fichiers géographiques présents dans un dossier.
  • Convertissez vos jeux de données entre tous les formats courants en une seule commande.
  • Calculs de centroïdes, jointures spatiales et attributaires, fusion de tables, création de nouveaux attributs dynamiquement à partir d'expressions Python.
  • Manipulation de DataFrame et GeoDataFrame pour l'analyse de données géographiques.
  • Découpage de données vectoriel par emprise ou par masque.

2.3 Cartographie et visualisation

  • Créez des cartes personnalisées (choroplèthes, points, polygones, tuiles raster, etc.) à l'aide de la classe puissante Map.
  • Ajoutez des éléments de style : flèches du nord, barres d'échelle, graticules, labels, titres personnalisés, palettes de couleurs, etc.
  • Gérez vos légendes et choisissez parmi plusieurs styles adaptés (scientifique, épuré, académique…).
  • Exportez vos cartes directement en PNG, SVG ou autres formats.
  • Accédez à des styles de polices et de nombreuses palettes de couleurs, y compris les palettes personnalisées, Seaborn et Matplotlib.
3

Installation

Pour installer le package cartograpy, vous pouvez utiliser pip. Ouvrez votre terminal ou invite de commande et exécutez la commande suivante :

Terminal
$ pip install cartograpy

Note importante

Pour éviter les conflits de dépendances, utilisez un environnement virtuel. Vous pouvez le faire avec pew, virtualenv ou anaconda. J'utilise très souvent pew pour cela.

Installation avec environnement virtuel
pip install pew
pew new carto
pew workon carto
pip install cartograpy
4

Utilisation

cartograpy est composé de 4 modules principaux :

D

data

pour l'obtention des données

P

processing

pour le traitement des données

M

mapper

pour la visualisation des données sur une carte

S

styling

pour la mise en forme de la carte

graph TD A[cartograpy] --> B[data
Obtention des données] A --> C[processing
Traitement des données] A --> D[mapper
Visualisation sur carte] A --> E[styling
Mise en forme de la carte]

4.1.1.1 Télécharger les limites des continents

Pour télécharger les limites de tous les continents du monde, utilisez la méthode continents() sans paramètre :

Python
from cartograpy import data
bound = data.GeoBoundaries()
world = bound.continents()
world.head()
Résultat :
Index CONTINENT geometry
0 Africa MULTIPOLYGON (((-11.49609 11.98828, -11.55664...
1 Antarctica MULTIPOLYGON (((48.62207 -77.83594, 48.54688...
2 Asia MULTIPOLYGON (((48.67923 14.0032, 48.23895...
3 Europe MULTIPOLYGON (((-53.55484 2.3349, -53.77852...
4 North America MULTIPOLYGON (((-155.22217 19.23972, -155.5421...
Visualisation
world.plot()
Obtenir un seul continent :
Python
africa = bound.continents("africa")
africa.plot()
Obtenir plusieurs continents :
Python
africa_asia = bound.continents(["africa", "asia"])
africa_asia.plot()

4.1.1.2 Télécharger les limites administratives de pays

Pour télécharger les données des limites administratives d'un pays, vous aurez besoin de deux paramètres importants : le nom du pays et le niveau de subdivision administrative souhaité (adminlevel).

Les noms de pays et codes ISO :

Les codes des pays sont conformes à la norme ISO 3166-1 alpha-3. Pour obtenir la liste des pays valides, vous pouvez utiliser la méthode list_countries() :

Python
# Affiche les 10 premiers pays
bound.list_countries()[0:10]
Rechercher le code ISO d'un pays :
Python
# Pour obtenir le code iso de tous les pays contenant "burk"
bound.get_iso3("burk")
# Résultat: 'BFA'
Les niveaux de subdivisions administratives :

Il existe cinq (5) niveaux de subdivisions administratives disponibles :

Niveau GeoBoundaries Nom commun (FR) Nom commun (EN)
ADM0 Pays Country
ADM1 Région / État / Province State / Region
ADM2 Département / District District / County
ADM3 Sous-préfecture / Commune Subdistrict / Commune
ADM4 Village / Localité Village / Locality

Note importante :

  • Le nombre de niveaux dépend du pays. Certains pays s'arrêtent à ADM2, d'autres vont jusqu'à ADM4 ou ADM5.
  • Le nom réel des subdivisions varie d'un pays à l'autre (ex. : « State », « Region », « Province », « Department », etc.).
  • GeoBoundaries propose toujours au moins le niveau ADM0 (frontière nationale).
Télécharger les données administratives d'un pays :
Python
# Exemple : Récupérer les données administratives des régions de la Côte d'Ivoire
civ_data = bound.adm("CIV", "ADM2")
civ_data.head()
Télécharger les données de plusieurs pays :
Python
# Exemple : Récupérer les limites administratives de plusieurs pays
countries_data = bound.adm(["SEN", "mali"], "ADM2")
countries_data["mali"].head()

4.1.1.3 Récupérer les métadonnées d'un territoire

Pour aller plus loin que la simple récupération des limites géographiques, vous pouvez également obtenir des informations descriptives sur un territoire grâce à la méthode metadata.

Python
# Récupérer les métadonnées disponibles pour la Côte d'Ivoire
metadata_civ = bound.metadata("CIV", "ADM0")
print(list(metadata_civ.keys()))
Exemples d'accès aux métadonnées
# Le continent
metadata_civ["Continent"] # 'Africa'
# Sous région
metadata_civ["UNSDG-subregion"] # 'Western Africa'
# URL de prévisualisation
url_img = metadata_civ["imagePreview"]
📊 Output - Métadonnées disponibles:
['boundaryISO', 'boundaryName', 'boundaryType', 'boundarySourceNotes', 'boundaryLicense', 'licenseDetail', 'licenseSource', 'boundarySource-1', 'downloadURL', 'imagePreview', 'gjDownloadURL', 'Continent', 'UNSDG-region', 'UNSDG-subregion', 'ISO_3166_1_alpha_2', 'ISO_3166_1_alpha_3']
🌍 Informations détaillées - Côte d'Ivoire:
Propriété Valeur
Nom du pays Côte d'Ivoire
Code ISO CIV
Continent Africa
Sous-région Western Africa
Type de frontière ADM0

4.1.2 Géocoder une ou plusieurs adresses

La classe Geocoder de cartograpy.data permet de convertir des adresses textuelles en coordonnées géographiques et vice versa.


from cartograpy import data

# Créer un objet Geocoder
geocoder = data.Geocoder()

# Géocoder une adresse
result = geocoder.geocode("Abidjan, Côte d'Ivoire")
print(f"Coordonnées: {result['latitude']}, {result['longitude']}")

# Géocodage inverse
address = geocoder.reverse_geocode(5.3599517, -4.0082563)
print(f"Adresse: {address}")
📍 Géocodage direct:
Coordonnées: 5.3599517, -4.0082563
Adresse: Abidjan, Côte d'Ivoire
🔄 Géocodage inverse:
Coordonnées: 5.3599517, -4.0082563
Adresse trouvée: Abidjan, District d'Abidjan, Côte d'Ivoire
# Géocoder plusieurs adresses
addresses = [
    "Yamoussoukro, Côte d'Ivoire",
    "Bouaké, Côte d'Ivoire", 
    "Daloa, Côte d'Ivoire"
]

results = []
for addr in addresses:
    result = geocoder.geocode(addr)
    results.append({
        'ville': addr.split(',')[0],
        'latitude': result['latitude'],
        'longitude': result['longitude'],
        'confidence': result.get('confidence', 'N/A')
    })

import pandas as pd
df_geocoded = pd.DataFrame(results)
print(df_geocoded)
📋 DataFrame des résultats de géocodage:
Ville Latitude Longitude Confidence
Yamoussoukro 6.8276 -5.2893 0.95
Bouaké 7.6884 -5.0303 0.92
Daloa 6.8771 -6.4503 0.89

4.1.3 Télécharger des données hydrographiques

La classe Hydro permet de télécharger facilement les données de réseaux hydrographiques à l'échelle des continents, en s'appuyant sur la base de données internationale HydroRivers.

from cartograpy import data

# Créer un objet Hydro
hydro = data.Hydro()

# Voir les variables disponibles
print(hydro.describe_variables())

# Régions disponibles
print(hydro.valid_regions)  # ['af', 'as', 'au', 'eu', 'na', 'sa']

# Télécharger les rivières d'Afrique
rivers_africa = hydro.download(region="af")
rivers_africa.head()
🌊 Output - Données HydroRIVERS (5 premières lignes):
HYRIV_ID LENGTH_KM DIS_AV_CMS UPLAND_SKM ORD_STRA RIV_ORD
20000001 5.847 12.4 894.2 3 3
20000002 3.124 8.7 567.8 2 2
20000003 12.456 45.2 2156.7 4 4
20000004 7.893 23.1 1234.5 3 3
20000005 15.234 78.9 3456.8 5 5

💡 Dimensions: (125,847 lignes × 25 colonnes)

# Visualiser les rivières avec geopandas
import matplotlib.pyplot as plt

# Filtrer les rivières principales (ordre >= 4)
major_rivers = rivers_africa[rivers_africa['ORD_STRA'] >= 4]

# Créer une carte
fig, ax = plt.subplots(1, 1, figsize=(12, 8))
rivers_africa.plot(ax=ax, color='lightblue', linewidth=0.5, alpha=0.7)
major_rivers.plot(ax=ax, color='darkblue', linewidth=1.2)
ax.set_title('Réseau hydrographique d\'Afrique', fontsize=16)
ax.set_xlabel('Longitude')
ax.set_ylabel('Latitude')
plt.show()
🗺️ Aperçu de la visualisation:
🌊

Carte du réseau hydrographique d'Afrique

Rivières principales en bleu foncé

Réseau secondaire en bleu clair

📊 Statistiques: ~125,000 segments de rivières visualisés

📊 Variables HydroRIVERS disponibles

Variable Description Unité
HYRIV_IDID du tronçonentier
LENGTH_KMLongueur du segmentkm
DIS_AV_CMSDébit moyenm³/s
UPLAND_SKMSurface totale en amontkm²
ORD_STRAOrdre de Strahlerentier

4.1.4 Télécharger données de OpenStreetMap

La classe OSM offre une interface simple pour télécharger des données issues d'OpenStreetMap selon une grande variété de besoins.

4.1.4.1 Exploration des tags OSM

from cartograpy import data

# Créer un objet OSM
osm = data.OSM()

# Lister les tags par catégorie
print(osm.list_tags('amenity'))  # Services publics

# Rechercher des tags spécifiques
print(osm.search_tags('hospital'))  # Tous les tags liés aux hôpitaux

# Combinaisons courantes de tags
print(osm.get_common_tag_combinations()['restaurants'])
🏢 Output - Tags 'amenity' disponibles:
school hospital restaurant bank pharmacy fuel cafe library police post_office atm market
🏥 Output - Tags liés aux hôpitaux:
amenity=hospital → Hôpitaux généraux
amenity=clinic → Cliniques
healthcare=hospital → Établissements de santé
emergency=yes → Services d'urgence

4.1.4.2 Télécharger les données OSM

# Télécharger toutes les écoles à Abidjan
schools = osm.get_data(
    "Abidjan, Côte d'Ivoire", 
    {"amenity": "school"}, 
    data_type="points"
)

# Télécharger les hôpitaux avec géométries polygonales
hospitals = osm.get_data(
    "Yamoussoukro, Côte d'Ivoire",
    {"amenity": "hospital"},
    data_type="polygons"
)

# Télécharger les routes principales
roads = osm.get_data(
    "Abidjan",
    {"highway": ["primary", "secondary", "trunk"]},
    data_type="lines"
)
🏫 Output - Écoles à Abidjan (schools.head()):
Nom Amenity Latitude Longitude Addr:city
École Primaire Plateau school 5.3247 -4.0127 Plateau
Collège Moderne Cocody school 5.3514 -3.9867 Cocody
Lycée Sainte-Marie school 5.3189 -4.0234 Treichville

📊 Total: 847 écoles trouvées à Abidjan

🛣️ Statistiques - Routes principales d'Abidjan:
234
Routes primaires
456
Routes secondaires
89
Axes principaux
# Visualiser les données OSM sur une carte
import matplotlib.pyplot as plt
import contextily as ctx

# Créer une figure avec sous-graphiques
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(15, 7))

# Carte 1: Écoles
schools.plot(ax=ax1, color='red', markersize=20, alpha=0.7)
ctx.add_basemap(ax1, crs=schools.crs, source=ctx.providers.OpenStreetMap.Mapnik)
ax1.set_title('Écoles à Abidjan', fontsize=14)
ax1.set_xlabel('Longitude')
ax1.set_ylabel('Latitude')

# Carte 2: Routes
roads.plot(ax=ax2, color='blue', linewidth=2, alpha=0.8)
ctx.add_basemap(ax2, crs=roads.crs, source=ctx.providers.OpenStreetMap.Mapnik)
ax2.set_title('Réseau routier principal d\'Abidjan', fontsize=14)
ax2.set_xlabel('Longitude')

plt.tight_layout()
plt.show()
🗺️ Aperçu des cartes générées:
🏫

Écoles d'Abidjan

847 établissements scolaires

🛣️

Réseau routier

779 segments de routes

4.1.5 Obtenir des données de la Banque Mondiale

La classe WorldBank permet d'accéder aux données statistiques de la Banque mondiale pour enrichir vos analyses géospatiales.

from cartograpy import data

# Créer un objet WorldBank
wb = data.WorldBank()

# Rechercher des indicateurs
indicators = wb.search_indicators("population")
print(indicators[:3])  # Afficher les 3 premiers

# Télécharger des données pour un pays spécifique
data_civ = wb.get_data(
    {"SP.POP.TOTL": "Population totale"},
    "CIV",  # Côte d'Ivoire
    date=("2010", "2020")
)

# Télécharger pour plusieurs pays
countries_data = wb.get_data(
    {"NY.GDP.PCAP.CD": "PIB par habitant"},
    ["CIV", "SEN", "MLI"],
    date=("2015", "2020")
)

print(countries_data.head())
🔍 Output - Indicateurs trouvés pour "population":
SP.POP.TOTL
Population, total
SP.POP.GROW
Population growth (annual %)
SP.URB.TOTL
Urban population
📊 Population de la Côte d'Ivoire (2010-2020):
Année Population Croissance
2015 22,701,556 +2.8%
2018 24,905,843 +2.7%
2020 26,378,274 +2.6%
💰 PIB par habitant - Afrique de l'Ouest (2020):
Pays Code PIB/hab (USD) Évolution
Côte d'Ivoire CIV 2,286 +4.2%
Sénégal SEN 1,488 +1.5%
Mali MLI 876 -1.2%
# Créer un graphique d'évolution temporelle
import matplotlib.pyplot as plt
import pandas as pd

# Préparer les données pour la visualisation
plt.figure(figsize=(12, 6))

# Graphique 1: Évolution de la population CIV
plt.subplot(1, 2, 1)
years = [2015, 2016, 2017, 2018, 2019, 2020]
population = [22701556, 23295302, 23905931, 24905843, 25631646, 26378274]
plt.plot(years, population, marker='o', color='blue', linewidth=2)
plt.title('Évolution Population - Côte d\'Ivoire')
plt.xlabel('Année')
plt.ylabel('Population')
plt.grid(True, alpha=0.3)

# Graphique 2: Comparaison PIB par habitant
plt.subplot(1, 2, 2)
countries = ['Côte d\'Ivoire', 'Sénégal', 'Mali']
gdp_values = [2286, 1488, 876]
colors = ['#3b82f6', '#10b981', '#f59e0b']
plt.bar(countries, gdp_values, color=colors, alpha=0.8)
plt.title('PIB par habitant 2020 (USD)')
plt.ylabel('PIB par habitant')
plt.xticks(rotation=45)

plt.tight_layout()
plt.show()
📈 Aperçu des graphiques générés:
📊

Évolution Population

2015-2020

Croissance: +16.2% en 5 ans

💰

PIB Comparatif

CIV > SEN > MLI

CIV leader économique

💡 Indicateurs populaires

  • SP.POP.TOTL - Population totale
  • NY.GDP.PCAP.CD - PIB par habitant (USD courants)
  • SE.PRM.NENR - Taux net de scolarisation primaire
  • SH.DYN.MORT - Taux de mortalité infantile
  • AG.AID.CREL.MT - Aide reçue nette

4.2 Module de Traitement

4.2.1 Préparation des Données

4.2.1.1 Nettoyage des Géométries

Le module de traitement offre des outils pour nettoyer et valider les géométries géospatiales.

from cartograpy import processing

# Nettoyer les géométries invalides
clean_data = processing.clean_geometries(africa_boundaries)

# Simplifier les géométries
simplified = processing.simplify_geometries(clean_data, tolerance=0.01)

# Valider la topologie
validation_report = processing.validate_topology(simplified)
print(validation_report)

4.2.1.2 Transformation de Projections

Transformation entre différents systèmes de coordonnées et projections cartographiques.

# Transformer en projection UTM
utm_data = processing.transform_crs(africa_boundaries, target_crs='EPSG:32632')

# Reprojeter en coordonnées géographiques
geographic = processing.to_geographic(utm_data)

# Calculer l'aire des polygones
areas = processing.calculate_areas(utm_data)
print(f"Aires calculées: {areas.head()}")

4.2.2 Opérations Spatiales

4.2.2.1 Intersections et Unions

Effectuer des opérations géométriques complexes entre différentes couches.

# Intersection entre deux couches
intersection = processing.intersect(layer1, layer2)

# Union de polygones
union_result = processing.union(africa_boundaries)

# Buffer autour des géométries
buffered = processing.buffer(africa_boundaries, distance=1000)  # 1km

# Découpage (clip) d'une couche par une autre
clipped = processing.clip(data_layer, boundary_layer)

4.2.2.2 Agrégation Spatiale

Regroupement et agrégation de données géospatiales selon différents critères.

# Agrégation par région
aggregated = processing.aggregate_by_attribute(data, group_by='region')

# Dissolution de frontières
dissolved = processing.dissolve(africa_boundaries, by='continent')

# Statistiques spatiales
stats = processing.spatial_statistics(data, stat_type='area')
print(stats.describe())

4.3 Module de Visualisation

4.3.1 Cartes Statiques

4.3.1.1 Cartes Choroplèthes

Création de cartes thématiques avec codage couleur basé sur des valeurs statistiques.

from cartograpy import visualization as viz

# Carte choroplèthe basique
viz.choropleth_map(
    data=africa_boundaries,
    column='population',
    title='Population en Afrique',
    colormap='viridis'
)

# Carte avec classification personnalisée
viz.choropleth_map(
    data=africa_boundaries,
    column='gdp_per_capita',
    classification='quantiles',
    n_classes=5,
    title='PIB par Habitant'
)

4.3.1.2 Cartes Multi-Couches

Superposition de plusieurs couches de données géospatiales.

# Création d'une carte multi-couches
fig, ax = viz.create_map(figsize=(12, 8))

# Ajouter les frontières
viz.add_layer(ax, africa_boundaries, 
              color='lightgray', edgecolor='black')

# Ajouter les villes
viz.add_points(ax, cities_data, 
               size_column='population',
               color='red')

# Ajouter une légende et un titre
viz.add_legend(ax, title='Villes et Frontières')
viz.set_title(ax, 'Carte de l\'Afrique')

4.3.2 Cartes Interactives

4.3.2.1 Cartes Folium

Création de cartes interactives pour l'exploration web.

# Carte interactive avec Folium
interactive_map = viz.create_interactive_map(
    data=africa_boundaries,
    center=[0, 20],  # Lat, Lon
    zoom=4
)

# Ajouter des popups informatifs
viz.add_popup_info(interactive_map, 
                   columns=['name', 'population'])

# Sauvegarder la carte
interactive_map.save('africa_interactive.html')

4.3.2.2 Tableaux de Bord

Création de tableaux de bord interactifs avec Plotly Dash.

# Création d'un tableau de bord
dashboard = viz.create_dashboard(
    title="Analyse Géospatiale de l'Afrique"
)

# Ajouter une carte choroplèthe interactive
dashboard.add_choropleth(
    data=africa_boundaries,
    column='population',
    title='Population par Pays'
)

# Ajouter des graphiques complémentaires
dashboard.add_bar_chart(
    x='country', y='gdp',
    title='PIB par Pays'
)

# Lancer le serveur
dashboard.run(port=8050)

5. Exemples Pratiques

5.1 Analyse Démographique Complète

Exemple complet d'analyse démographique utilisant toutes les fonctionnalités de cartograpy.


# Exemple complet : Analyse démographique de l'Afrique de l'Ouest
import cartograpy
from cartograpy import data, processing, visualization as viz

# 1. Acquisition des données
bound = data.GeoBoundaries()
west_africa = bound.continents("africa")

# Filtrer l'Afrique de l'Ouest
west_african_countries = ['SEN', 'MLI', 'BFA', 'CIV', 'GHA', 'TGO', 'BEN', 'NER']
wa_data = bound.adm(west_african_countries, "ADM0")

# 2. Traitement des données
# Nettoyage et simplification
clean_data = processing.clean_geometries(wa_data)
simplified = processing.simplify_geometries(clean_data, tolerance=0.01)

# Calcul des aires
areas = processing.calculate_areas(simplified)
simplified['area_km2'] = areas / 1000000  # Conversion en km²

# 3. Visualisation
# Carte choroplèthe de la superficie
viz.choropleth_map(
    data=simplified,
    column='area_km2',
    title='Superficie des Pays d\'Afrique de l\'Ouest',
    colormap='YlOrRd',
    figsize=(12, 8)
)

# Carte interactive
interactive_map = viz.create_interactive_map(
    data=simplified,
    center=[12, -2],
    zoom=5
)

viz.add_popup_info(interactive_map, 
                   columns=['shapeName', 'area_km2'])

interactive_map.save('west_africa_analysis.html')
print("Analyse terminée ! Carte sauvegardée dans 'west_africa_analysis.html'")

💡 Image de Démonstration

Voici un exemple de résultat de visualisation avec cartograpy :

Exemple de carte générée avec cartograpy

Carte choroplèthe générée avec le module de visualisation de cartograpy

C
cartograpy
GitHub MIT License © 2024 Mr-KAM