Documentation: Lens

Lens User Guide & Data Reference

Interactive choropleth mapping, demographic analytics, and GeoJSON boundary export for Philippine administrative divisions.

Launch Lens App →View Source Code on GitHub

Spatial Data Friction in Philippine Administrative Research

Analyzing municipal demographics, local government revenues, and public health indicators in the Philippines traditionally required heavy desktop GIS software like QGIS or ArcGIS. Researchers had to hunt down fragmented shapefiles across separate agency websites, convert legacy Luzon 1911 / PRS92 coordinate systems to standard WGS 84, and manually join Excel tables with inconsistent LGU name spellings (such as "Poblacion" variations or shifting municipality naming conventions).

Lens resolves this friction by serving pre-processed, PSGC-indexed vector boundaries directly in modern browsers. Analysts, journalists, civil society watchdogs, and urban planners can visualize municipal metrics, compare local government units side by side, and export clean GeoJSON files without running desktop GIS software.

Vector Pipeline: TopoJSON Shared Arcs vs Raw GeoJSON

Delivering 82 provinces and over 1,600 municipal boundaries over standard mobile internet connections requires aggressive payload reduction. A raw GeoJSON file containing all Philippine municipalities exceeds 45 megabytes because every shared provincial and municipal boundary is defined twice: once for each adjoining polygon.

1. Shared Arc TopoJSON

Lens compresses spatial geometries into TopoJSON format. Adjoining municipalities share identical coordinate arcs, eliminating boundary duplication, preventing visual sliver gaps, and reducing file size by 78 percent over wire transfer.

2. PSGC Hash Joins

Tabular data is joined in memory using 9-digit PSGC numeric keys. String matching on LGU names is discarded in favor of exact PSA identifier hashes, guaranteeing 100 percent join reliability.

3. RFC 7946 Client Export

When an analyst selects a boundary and clicks Export, the browser unpacks the internal TopoJSON arcs into a standalone RFC 7946 GeoJSON FeatureCollection in WGS 84 (EPSG:4326), ready for Deck.gl, Turf.js, or PostGIS.

Choropleth Classification: Handling Skewed Philippine Distributions

Geographic indicators across the Philippines exhibit extreme variance. In the 2020 Census of Population and Housing, the City of Manila recorded a population density exceeding 73,000 residents per square kilometer, whereas upland municipalities in Apayao or Abra recorded fewer than 40 residents per square kilometer. Applying equal interval binning to such data turns 98 percent of the national map into a single faint shade, obscuring regional nuance.

Lens supports multiple statistical binning algorithms to display variations accurately:

Jenks Natural Breaks Optimization

Minimizes variance within each color tier while maximizing variance between tiers. Jenks calculates natural cluster points in the dataset, making it ideal for displaying municipal internal revenue allocations, poverty incidence rates, and hospital bed counts.

Quantiles (Equal Count Slices)

Divides the 1,634 cities and municipalities into 5 equal groups (quintiles, with approximately 326 LGUs per color bin). Quantiles are effective for comparative rankings, ensuring every color band is populated regardless of extreme outliers.

Logarithmic Scale

Transforms values using base-10 logarithms before applying color ramps. This is the recommended view for population density and gross local business tax collection, where metropolitan centers outstrip rural LGUs by three orders of magnitude.

Pre-Loaded Civic Datasets & Mandanas-Garcia Revenue Tracking

Lens includes curated public datasets compiled from primary statutory filings:

Demographics (PSA 2020 CPH): Total headcounts, sex ratio, dependency ratio, and land area figures from official Philippine Statistics Authority census volumes.

National Tax Allotment (NTA / Mandanas-Garcia Ruling): Under the landmark Supreme Court ruling in Mandanas v. Ochoa (G.R. Nos. 199802 and 208488), the just share of local government units was expanded from internal revenue taxes (BIR) to all national tax collections, including Bureau of Customs duties. Lens tracks the resulting NTA distribution across provinces (23%), cities (23%), municipalities (34%), and barangays (20%).

LGU Financial Audits (COA Annual Reports): Locally Sourced Revenue (LSR) ratios, municipal assets, outstanding liabilities, and debt-to-equity metrics extracted from Commission on Audit annual financial reports.

Electoral Results (COMELEC Transparency Server): Municipal turnout percentages and candidate voting margins from national elections.

Custom CSV Upload Specification

You can map your own survey data, clinical trial sites, or field operations onto Lens by uploading a standard comma-separated text file. The file must satisfy the following schema rules:

The CSV must contain a header row with at least two columns: psgc and value.
The psgc column must hold the 9-digit or 10-digit PSGC numeric code (e.g., 037114000). Quotes around codes are encouraged to prevent spreadsheet software from stripping leading zeros.
The value column must contain numeric integer or floating-point values without currency symbols (e.g. use 14250.75, not PHP 14,250.75).
An optional label column may be supplied to customize the tooltip heading on hover.

psgc,name,value
"037114000",Subic,84.2
"037107000",Castillejos,62.1
"037113000",San Marcelino,49.8
"037108000",Iba,78.5
"037106000",Candelaria,55.0

Data Integrity & Survey Precision Disclaimers

Lens is an open-source civic analytics utility designed for visualization, research, and application development. Users must keep the following technical considerations in mind:

• Cartographic Simplification: Polygons are simplified using Douglas-Peucker algorithms with an epsilon tolerance of 0.001 degrees to ensure real-time client-side rendering. Lens boundaries should not be used as legal cadastral evidence in property disputes or municipal boundary arbitration.

• Cadastral Verification: For formal land registry surveys, developers and engineers must acquire certified cadastral survey sheets and PRS92 control monuments directly from the National Mapping and Resource Information Authority (NAMRIA) or the Land Management Bureau (LMB).

• Institutional Disclaimer: Lens is an independent community project and is not affiliated with, funded by, or officially endorsed by the Philippine Statistics Authority (PSA), the Commission on Elections (COMELEC), or the Commission on Audit (COA).

← PreviousOverview Next →PSGC Reference