# geo4bolivia > Spatial data science for Bolivia's subnational development data: find, load, map and analyse it across spatial scales. geo4bolivia is the Python package of the GeoDevelopment Observatory of Bolivia. It reads the observatory's published data (https://github.com/quarcs-lab/gdo4bolivia) and runs the fundamental analyses of spatial data science on them. Install with `pip install geo4bolivia` and `import geo4bolivia as geo`. Every analysis function takes a dataset id or a panel with `geo_id` and `year`, finds boundaries, weights and labels itself, and returns a result object with `.df`, `.fig` (Plotly), `.gt` (table) and `.interpret()`. ## Pages - [Analyze](https://quarcs-lab.github.io/geo4bolivia/analyze.html): A tour of the analysis functions on one question: did sustainable development become more equal across Bolivia's municipalities, and what role does space play? - [Changelog](https://quarcs-lab.github.io/geo4bolivia/changelog.html): What changed in each release of geo4bolivia. - [Explore](https://quarcs-lab.github.io/geo4bolivia/explore.html): A first pass over one indicator, the Sustainable Development Index: summaries, distributions, extremes, correlations, trends and maps, before any model. - [Get started](https://quarcs-lab.github.io/geo4bolivia/get-started.html): Install geo4bolivia, find a variable, load it, map it and run a first spatial analysis, in ten minutes. - [For AI assistants and LLMs](https://quarcs-lab.github.io/geo4bolivia/use-with-llms.html): How an AI assistant should install and call geo4bolivia, and the files that describe the package to it. - [Case study: the Sustainable Development Index, ~2012 to ~2024](https://quarcs-lab.github.io/geo4bolivia/articles/case-study-sdg.html): One complete analysis with geo4bolivia: how the Sustainable Development Index of Bolivia's 343 municipalities changed between two periods, which goals moved, whether municipalities converged, and where. - [Convergence: β, σ and clubs](https://quarcs-lab.github.io/geo4bolivia/articles/convergence.html): Three questions about catching up, and the method for each: do units that start lower grow faster, is dispersion falling, and do units head for one path or for several? - [The data model: scales, geo IDs, datasets and metadata](https://quarcs-lab.github.io/geo4bolivia/articles/data-model.html): How the observatory's data are organised (spatial scales, geo IDs, panels and metadata) and how the package reads them. - [Exploring the data](https://quarcs-lab.github.io/geo4bolivia/articles/exploring.html): A question-driven exploration of multidimensional poverty in Bolivia's municipalities, and the pitfalls of these data that a newcomer should know. - [Spatial heterogeneity: MGWR](https://quarcs-lab.github.io/geo4bolivia/articles/heterogeneity.html): Multiscale geographically weighted regression asks whether an association differs from place to place and at what spatial scale it operates: how to run it with geo.mgwr and how to read its bandwidths, coefficient maps and diagnostics. - [Articles](https://quarcs-lab.github.io/geo4bolivia/articles/index.html): One article per method, written around Bolivia's data, and a complete case study. - [Regional inequality](https://quarcs-lab.github.io/geo4bolivia/articles/inequality.html): How unequal Bolivia's municipalities are, whether that is changing, and whether the inequality lies between departments or inside them: Gini, Theil, the Lorenz curve and Theil's decomposition. - [Regression, panel and spatial models](https://quarcs-lab.github.io/geo4bolivia/articles/models.html): Three kinds of regression model for subnational data, what each one compares and when it is the right tool: least squares with fixed effects and clustered errors, panel estimators with the Hausman test, and spatial models with their diagnostics and impacts. - [Building your own indicators](https://quarcs-lab.github.io/geo4bolivia/articles/own-indicators.html): From a table or a raster of your own to an analysis: link it to the geo IDs, compute zonal statistics, move it across scales, save it and analyse it. - [Maps and spatial dependence](https://quarcs-lab.github.io/geo4bolivia/articles/spatial-dependence.html): From a map to a test: classed maps, spatial weights, global Moran's I and LISA clusters of multidimensional poverty in Bolivia's municipalities, and how far the conclusions depend on the choices made. - [Transitions and mobility](https://quarcs-lab.github.io/geo4bolivia/articles/transitions.html): How units move inside a distribution: changes of rank between two years, moves between spatial cluster types, and Markov transition matrices with and without the neighbours. - [Function reference](https://quarcs-lab.github.io/geo4bolivia/reference/index.html): every public function, with an example - [llms-full.txt](https://quarcs-lab.github.io/geo4bolivia/llms-full.txt): all of the above in one file ## Find and understand the data - [`geo.datasets(ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/datasets.html): The catalog: one row per dataset and scale. - [`geo.search(text: 'str', dataset: 'str | None' = None, ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/search.html): Find variables whose name, label or description contain every word of ``text``. - [`geo.info(dataset: 'str', ref: 'str | None' = None) -> 'DatasetInfo'`](https://quarcs-lab.github.io/geo4bolivia/reference/info.html): What a dataset is: description, coverage (scales, units, years), actual reference - [`geo.dictionary(dataset: 'str', scale: 'str | None' = None, ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/dictionary.html): The variable dictionary of a dataset, one row per column. - [`geo.reference_years(dataset: 'str', variable: 'str | None' = None, scale: 'str | None' = None, ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/reference_years.html): The actual years behind each stored year, one row per variable and stored year. - [`geo.cite(dataset: 'str', style: 'str' = 'apa', ref: 'str | None' = None) -> 'str'`](https://quarcs-lab.github.io/geo4bolivia/reference/cite.html): How to cite a dataset: its recommended citation, then the credits its sources require. - [`geo.labels(data, own: 'dict[str, str] | None' = None, ref: 'str | None' = None) -> 'dict[str, str]'`](https://quarcs-lab.github.io/geo4bolivia/reference/labels.html): Readable labels for the columns of a panel (or every field of a dataset id). - [`geo.describe(df: 'pd.DataFrame', variables=None, by: 'str | None' = 'year', ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/describe.html): Summary statistics of a panel's variables, per ``by`` group (default: per year). ## Load data, units and boundaries - [`geo.load(dataset: 'str', scale: 'str | None' = None, years=None, variables=None, wide: 'str | None' = None, geometry: 'bool' = False, names: 'bool' = False, groups=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/load.html): Load a dataset as a panel: one row per unit (``geo_id``) and year. - [`geo.add_names(df: 'pd.DataFrame', groups=None, scale: 'str | None' = None, ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/add_names.html): Add the unit ``name`` and, for each scale in ``groups``, the name of the unit it lies in. - [`geo.units(scale: 'str | None' = None, ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/units.html): All units (or the units of one scale) with names, parents and source keys. - [`geo.boundaries(scale: 'str', ref: 'str | None' = None) -> 'gpd.GeoDataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/boundaries.html): Unit polygons for a scale (CRS84), with ``geo_id`` and ``name``. - [`geo.crosswalk(source: 'str', target: 'str', ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/crosswalk.html): Links between two scales: ``geo_id_from``, ``geo_id_to``, ``weight_area``. - [`geo.scales(active_only: 'bool' = False, ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/scales.html): The registry of spatial scales as a table, one row per scale (``geo.scales()``). - [`geo.ancestors(scale: 'str', ref: 'str | None' = None) -> 'list[str]'`](https://quarcs-lab.github.io/geo4bolivia/reference/ancestors.html): Coarser scales a unit of ``scale`` nests in, in breadth-first order. - [`geo.scale_of(geo_id: 'str', ref: 'str | None' = None) -> 'str'`](https://quarcs-lab.github.io/geo4bolivia/reference/scale_of.html): The scale a geo ID belongs to, from the ID patterns (e.g. a municipality ID -> ``"municipality"``). - [`geo.config() -> 'dict'`](https://quarcs-lab.github.io/geo4bolivia/reference/config.html): The project settings: the package's project.yaml, with the data repository's on top inside a checkout. ## Work with panels and scales - [`geo.change(df: 'pd.DataFrame', variables=None, first: 'int | None' = None, last: 'int | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/change.html): The change of each unit between two years of a panel, one row per unit. - [`geo.aggregate(df: 'pd.DataFrame', to, dataset: 'str | None' = None, rules: 'dict | None' = None, variables=None, weights: 'pd.DataFrame | None' = None, ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/aggregate.html): Aggregate a panel up to a coarser, nested scale (or to several at once). - [`geo.combine(datasets, scale: 'str', years=None, extra=(), rules: 'dict | None' = None, ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/combine.html): Merge datasets into one panel at ``scale``, aggregating finer ones up. - [`geo.overlay(df: 'pd.DataFrame', target, extensive=(), intensive=(), source=None, id_col: 'str' = 'geo_id') -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/overlay.html): Area-weighted interpolation of a panel onto non-nested units. - [`geo.overlay_weights(source, target, id_col: 'str' = 'geo_id') -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/overlay_weights.html): Area of every source-target intersection, in an equal-area projection. ## Build your own indicators - [`geo.link(df: 'pd.DataFrame', scale: 'str', on: 'str', key: 'str' = 'auto', errors: 'str' = 'raise', ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/link.html): Attach ``geo_id`` to a table that identifies units by name or by a source code. - [`geo.check(df: 'pd.DataFrame', scale: 'str | None' = None, time: 'str | None' = 'year', ref: 'str | None' = None) -> 'list[str]'`](https://quarcs-lab.github.io/geo4bolivia/reference/check.html): Problems that would stop ``df`` from being a valid panel at ``scale`` (empty list = OK). - [`geo.zonal(raster, scale, stats=('sum', 'mean'), name: 'str' = 'value', year: 'int | None' = None, band: 'int' = 1, all_touched: 'bool' = False, ref: 'str | None' = None) -> 'pd.DataFrame'`](https://quarcs-lab.github.io/geo4bolivia/reference/zonal.html): Summarise a raster (GeoTIFF path or URL) over the units of a scale. - [`geo.save(df: 'pd.DataFrame', name: 'str', scale: 'str', directory='.', title: 'str | None' = None, description: 'str' = '', variables: 'dict | None' = None, sources=(), citation: 'str | None' = None, license: 'str' = 'CC-BY-4.0') -> 'dict'`](https://quarcs-lab.github.io/geo4bolivia/reference/save.html): Save a panel exactly like the published datasets, ready to share or contribute. ## Explore - [`geo.correlation(data, variables=None, year=None, *, method: 'str' = 'pearson', digits: 'int' = 2, title: 'str | None' = None, ref: 'str | None' = None) -> 'CorrelationResult'`](https://quarcs-lab.github.io/geo4bolivia/reference/correlation.html): Correlations between the variables of a panel in one year. - [`geo.extremes(data, variable: 'str', year=None, *, n: 'int' = 5, title: 'str | None' = None, ref: 'str | None' = None) -> 'ExtremesResult'`](https://quarcs-lab.github.io/geo4bolivia/reference/extremes.html): The units with the highest and the lowest values of a variable in one year. - [`geo.distribution(data, variable: 'str', year=None, *, by: 'str | None' = None, kind: 'str' = 'histogram', bins: 'int' = 30, title: 'str | None' = None, ref: 'str | None' = None) -> 'DistributionResult'`](https://quarcs-lab.github.io/geo4bolivia/reference/distribution.html): The distribution of a variable across units, per year or per group. - [`geo.scatter(data, x: 'str', y: 'str', year=None, *, color: 'str | None' = None, size: 'str | None' = None, fit: 'str | None' = 'ols', log_x: 'bool' = False, log_y: 'bool' = False, title: 'str | None' = None, ref: 'str | None' = None) -> 'ScatterResult'`](https://quarcs-lab.github.io/geo4bolivia/reference/scatter.html): Two variables against each other in one year, one point per unit. - [`geo.trend(data, variable: 'str', *, by: 'str | None' = None, units: 'bool' = True, stat: 'str' = 'mean', max_units: 'int' = 400, title: 'str | None' = None, ref: 'str | None' = None) -> 'TrendResult'`](https://quarcs-lab.github.io/geo4bolivia/reference/trend.html): A variable over time: its mean (or median) across units, with a band, and each unit's path. ## Maps and spatial dependence - [`geo.map(data, variable: 'str', year=None, scale: 'str | None' = None, title: 'str | None' = None, simplify: 'float | str | None' = 'auto', ref: 'str | None' = None, *, scheme: 'str | None' = None, k: 'int' = 5, bins=None, change: 'bool' = False, **kwargs)`](https://quarcs-lab.github.io/geo4bolivia/reference/map.html): An interactive choropleth map (Plotly) of one variable: in one year, in several years side by - [`geo.weights(data, method: 'str' = 'queen', *, k: 'int' = 6, threshold: 'float | None' = None, power: 'float' = 1.0, row_standardize: 'bool' = True, attach_islands: 'bool' = True, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/weights.html): Spatial weights for the units of a scale, a dataset or a panel. - [`geo.connectivity(data, w=None, *, method: 'str' = 'queen', tiles: 'str | None' = 'carto-positron', title: 'str | None' = None, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/connectivity.html): A map of the neighbour links of a set of weights, with the distribution of neighbours per unit. - [`geo.moran(data, variable: 'str', year=None, *, w=None, permutations: 'int' = 999, seed: 'int | None' = 12345, title: 'str | None' = None, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/moran.html): Global Moran's I of a variable: is it clustered in space? - [`geo.lisa(data, variable: 'str', year=None, *, w=None, permutations: 'int' = 999, seed: 'int | None' = 12345, alpha: 'float' = 0.05, panels: 'str' = 'both', tiles: 'str | None' = 'carto-positron', title: 'str | None' = None, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/lisa.html): Local Moran (LISA) clusters of a variable: where are the hot spots, cold spots and outliers? ## Convergence - [`geo.beta_convergence(data, variable: 'str', controls=None, *, first=None, last=None, model: 'str' = 'ols', w=None, fixed_effects=None, vcov: 'str' = 'hetero', draws: 'int' = 10000, seed: 'int' = 12345, min_obs: 'int' = 10, title: 'str | None' = None, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/beta_convergence.html): Beta-convergence: did the units that started lower grow faster between two years? - [`geo.sigma_convergence(data, variable: 'str', *, first=None, last=None, vcov: 'str' = 'hetero', title: 'str | None' = None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/sigma_convergence.html): Sigma-convergence: does the dispersion of a variable across units fall over time? - [`geo.convergence_clubs(data, variable: 'str', *, first=None, last=None, log: 'bool' = False, hp_filter: 'bool' = True, hp_lambda: 'float' = 400.0, trim: 'float' = 0.3, tcrit: 'float' = -1.65, cr: 'float' = 0.0, increment: 'float' = 0.05, max_cr: 'float' = 3.0, fraction: 'float' = 0.0, adjust: 'bool' = False, merge: 'str' = 'ps', map: 'bool' = True, tiles: 'str | None' = 'carto-positron', title: 'str | None' = None, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/convergence_clubs.html): Convergence clubs (Phillips and Sul): do all units converge, or do groups of them? ## Transitions and mobility - [`geo.transitions(data, variable: 'str', *, k: 'int' = 5, scheme: 'str' = 'quantiles', bins=None, per_year: 'bool' = True, relative: 'bool' = False, title: 'str | None' = None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/transitions.html): Markov transitions between classes of a variable's distribution: how mobile are the units? - [`geo.spatial_transitions(data, variable: 'str', *, w=None, k: 'int' = 5, m: 'int | None' = None, per_year: 'bool' = False, relative: 'bool' = True, title: 'str | None' = None, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/spatial_transitions.html): Spatial Markov transitions: does a unit's mobility depend on where its neighbours stand? - [`geo.lisa_transitions(data, variable: 'str', first=None, last=None, *, w=None, permutations: 'int' = 999, seed: 'int | None' = 12345, alpha: 'float' = 0.05, tiles: 'str | None' = 'carto-positron', title: 'str | None' = None, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/lisa_transitions.html): Transitions between local Moran (LISA) types: did the hot spots and cold spots persist? - [`geo.rank_mobility(data, variable: 'str', first=None, last=None, *, k: 'int' = 5, top: 'int' = 10, ascending: 'bool' = False, title: 'str | None' = None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/rank_mobility.html): Rank mobility between two years: how much did the units change position? ## Inequality - [`geo.inequality(data, variable: 'str', *, measures=('gini', 'theil'), first=None, last=None, spatial: 'bool' = False, w=None, permutations: 'int' = 99, lorenz: 'bool' = True, title: 'str | None' = None, gdf=None, ref: 'str | None' = None) -> 'InequalityResult'`](https://quarcs-lab.github.io/geo4bolivia/reference/inequality.html): Inequality between units in each year: is it narrowing or widening? - [`geo.theil_decomposition(data, variable: 'str', by: 'str | None' = None, *, permutations: 'int' = 0, seed: 'int' = 12345, title: 'str | None' = None, ref: 'str | None' = None) -> 'TheilResult'`](https://quarcs-lab.github.io/geo4bolivia/reference/theil_decomposition.html): Theil's index split in two: inequality between groups of units and inequality within them. ## Models - [`geo.regression(data, y: 'str', x, year=None, *, fixed_effects=None, cluster: 'str | None' = None, robust: 'bool' = True, title: 'str | None' = None, ref: 'str | None' = None) -> 'RegressionResult'`](https://quarcs-lab.github.io/geo4bolivia/reference/regression.html): Ordinary least squares, with several specifications side by side. - [`geo.panel_model(data, y: 'str', x, *, models=('pooled', 'between', 'fe', 're'), time_effects: 'bool' = False, cluster: 'bool' = True, title: 'str | None' = None, ref: 'str | None' = None) -> 'PanelModelResult'`](https://quarcs-lab.github.io/geo4bolivia/reference/panel_model.html): The standard panel estimators side by side, and the Hausman test of fixed against random effects. - [`geo.spatial_model(data, y: 'str', x, year=None, *, model: 'str' = 'durbin', method: 'str' = 'ml', w=None, fixed_effects: 'str | None' = None, impacts: 'bool' = True, n_draws: 'int' = 10000, seed: 'int | None' = 12345, title: 'str | None' = None, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/spatial_model.html): A spatial regression for one year, with direct, indirect (spillover) and total impacts. - [`geo.spatial_diagnostics(data, y: 'str', x, year=None, *, w=None, fixed_effects: 'str | None' = None, alpha: 'float' = 0.05, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/spatial_diagnostics.html): Tests for spatial dependence left in a least-squares regression, and the spatial model they point to. ## Spatial heterogeneity - [`geo.mgwr(data, y: 'str', x, year=None, *, kernel: 'str' = 'bisquare', criterion: 'str' = 'AICc', max_iter: 'int' = 200, tiles: 'str | None' = 'carto-positron', title: 'str | None' = None, gdf=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/mgwr.html): Multiscale geographically weighted regression: where, and at which scale, does ``x`` relate to ``y``? ## Companion packages - [`geo.for_expdpy(data, scale: 'str | None' = None, years=None, variables=None, labels: 'dict | None' = None, groups=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/for_expdpy.html): ``(df, df_def)`` in the format expdpy expects. - [`geo.for_geometrics(data, scale: 'str | None' = None, years=None, variables=None, labels: 'dict | None' = None, groups=None, ref: 'str | None' = None)`](https://quarcs-lab.github.io/geo4bolivia/reference/for_geometrics.html): ``(gdf, df, df_dict)`` in the format geometrics expects.