This plugin converts gridded monthly climate CSV files into district-wise monthly mean tables. It uses only native PyQGIS and the Python standard library.
No external Python installation: GeoPandas, Pandas, SciPy, Rtree, Pyogrio, Google Colab and Google Drive are not required.
1. Introduction and Purpose
The plugin reads one or many CSV files containing longitude, latitude and twelve monthly values. It assigns each valid grid point to district polygons, calculates a monthly arithmetic mean for every district and fills uncovered districts using the nearest N grid points.
Typical applications
- District aggregation of minimum temperature, maximum temperature, rainfall, evapotranspiration and other monthly variables.
- Batch processing of historical and future climate-model scenarios.
- Preparation of district-level datasets for water management, agriculture and climate-impact assessment.
2. Plugin Functions and Processing Logic
| Stage | Operation |
|---|---|
| Input detection | Finds CSV files in the selected folder and optionally its subfolders. |
| Column detection | Recognizes accepted coordinate fields and full or abbreviated month headers. |
| CRS handling | Transforms the selected polygon layer internally to WGS 84 (EPSG:4326). |
| Internal aggregation | Averages valid monthly values from grid points intersecting each district. |
| Fallback | Uses the nearest N grid points when a district contains no valid point. |
| Export | Creates one result CSV per input and a processing report. |
Boundary points: A point exactly on a shared boundary may intersect more than one adjacent district and may contribute to both.
3. System Requirements
| Requirement | Supported setting |
|---|---|
| QGIS | QGIS 3.22+ and QGIS 4.x |
| Operating system | Windows, Linux or macOS |
| Polygon layer | Any QGIS-readable polygon source, including Shapefile and GeoPackage |
| CSV coordinates | WGS 84 longitude and latitude in decimal degrees |
| Permissions | Read access to inputs and write access to output folder |
4. Installing the Plugin from ZIP
- Save
spatial_aggregation_mean_with_manual.zip. Do not extract it. - Open QGIS.
- Choose Plugins → Manage and Install Plugins.
- Open Install from ZIP.
- Browse to the plugin ZIP and select it.
- Click Install Plugin.
- Open the Installed tab and confirm that Spatial Aggregation Mean is enabled.
Confirm successful installation
- A plugin icon appears on the toolbar.
- The Vector menu contains a Spatial Aggregation Mean submenu.
- The Processing Toolbox contains the aggregation algorithm.
- Vector → Spatial Aggregation Mean → User Manual opens this page.
Not visible? Enable the plugin in the Installed tab and restart QGIS.
5. Preparing the District Polygon Layer
- Use polygon or multipolygon geometry.
- Select a populated district-name or unique-ID field.
- Prefer a unique code when the same district name may occur in different states.
- Ensure the layer has a correctly defined CRS.
- Repair invalid geometries where necessary.
Duplicate selected values: Polygon parts with the same selected value are combined logically and produce one output row.
Recommended checks
- Load the boundary layer and open its Attribute Table.
- Check names/codes for blanks, spelling differences and duplicates.
- Use Vector → Geometry Tools → Check Validity when needed.
- Confirm the CRS under Layer Properties → Source.
6. Preparing Monthly Climate CSV Files
Accepted headers
| Data | Accepted field names |
|---|---|
| Longitude | long, longitude, lon, lng, x |
| Latitude | lat, latitude, y |
| Months | January-December, or common abbreviations such as jan, feb, mar, sep/sept |
Correct example
longitude,latitude,january,february,march,april,may,june,july,august,september,october,november,december 91.75,25.60,8.2,9.5,12.4,16.1,18.0,19.2,19.8,19.6,18.7,15.9,12.4,9.1 91.85,25.60,8.1,9.4,12.3,16.0,17.9,19.1,19.7,19.5,18.6,15.8,12.3,9.0
Rules
- Coordinates must be decimal degrees, not metres.
- Longitude must be -180 to 180; latitude must be -90 to 90.
- Every CSV must contain all twelve months.
- Climate values must be numeric.
- Blank, NA, NaN, null, none, -999 and -9999 values are ignored.
- Comma, semicolon, tab and vertical-bar delimiters can be detected.
Avoid recursive reprocessing: Keep the output folder outside the input folder when subfolder search is enabled.
7. Running the Plugin Step by Step
- Add the district polygon layer to QGIS.
- Click the toolbar icon, or choose Vector → Spatial Aggregation Mean → Spatial Aggregation Mean.
- Select the District polygon layer.
- Select the District name or unique ID field.
- Browse to the folder containing input CSV files.
- Select a separate output folder.
- Keep nearest grid points at 8, unless another documented value is required.
- Enable subfolder search only when necessary.
- Keep
_DistrictMeanor enter a suitable output suffix. - Click Run.
- Review the Log for files processed, invalid rows, fallback districts and saved paths.
- Open the output folder and inspect the report and result CSVs.
Processing Toolbox route: Processing Toolbox → Spatial Aggregation Mean → Climate aggregation → Spatial Aggregation Mean.
8. Understanding Plugin Parameters
| Parameter | Purpose | Recommended |
|---|---|---|
| District polygon layer | Defines reporting units. | Clean boundary layer. |
| District field | Creates output rows and groups repeated polygon parts. | Unique code or standardized name. |
| Input folder | Contains monthly gridded CSV files. | One variable/scenario per run. |
| Output folder | Stores result CSVs and report. | Separate writable folder. |
| Nearest grid points | Controls fallback average. | 8. |
| Recursive search | Includes CSV files in subfolders. | Off unless needed. |
| Output suffix | Text added before .csv. | _DistrictMean |
A smaller nearest count preserves more local variation; a larger count creates a smoother estimate. Use the same setting across comparable datasets.
9. Understanding Outputs and Reports
Input model_01.csv produces model_01_DistrictMean.csv by default.
DISTRICT,january,february,march,april,may,june,july,august,september,october,november,december East Khasi Hills,7.93,9.18,12.21,15.87,17.71,18.93,19.54,19.31,18.42,15.61,12.10,8.87 Ri Bhoi,8.41,9.72,12.88,16.52,18.35,19.64,20.13,19.92,18.98,16.17,12.69,9.36
Processing report
| Column | Meaning |
|---|---|
| input_csv | Source path. |
| status | success or failed. |
| output_csv | Created output path. |
| grid_points | Valid coordinate rows used. |
| districts_with_points | Districts containing grid points. |
| districts_nearest_fallback | Districts using nearest-point values. |
| message | Error reason for failed inputs. |
No overwriting: If an output already exists, the plugin creates
_2, _3 and so on.10. Quality-Control Checks
Before running
- Add one sample CSV as a delimited-text point layer and verify its position.
- Ensure X is longitude and Y is latitude.
- Confirm all twelve month headers and units.
- Review district identifiers.
After running
- Confirm every intended file has status success.
- Compare input and output file counts.
- Investigate an unexpectedly high fallback count.
- Check that every district and month is present.
- Manually verify one or two means.
January mean = (8.0 + 8.5 + 9.0) / 3 = 8.5
11. Common Errors and Troubleshooting
| Message/symptom | Cause | Action |
|---|---|---|
| No CSV files found | Wrong folder or files only in subfolders. | Select correct folder or enable recursive search. |
| Longitude/latitude not found | Unsupported field names. | Rename to longitude/latitude or lon/lat. |
| Missing month columns | Month absent or misspelled. | Add all 12 accepted month fields. |
| No valid grid rows | Coordinates blank, swapped, projected or out of range. | Correct coordinates to WGS 84 decimal degrees. |
| Many fallback districts | Grid/boundary mismatch or coarse coverage. | Display a sample point layer and inspect overlap. |
| Permission denied | File open or folder read-only. | Close files and use a writable local folder. |
| Plugin shown as incompatible/deprecated in QGIS 4 | An older plugin ZIP with qgisMaximumVersion=3.99 is installed. | Uninstall the older version, restart QGIS, and install version 1.3.2 or later. |
| Manual does not open | Incomplete installation or missing browser association. | Reinstall complete ZIP or open docs/user_manual.html. |
Diagnose coordinate problems
- Use Layer → Add Layer → Add Delimited Text Layer.
- Set X to longitude and Y to latitude.
- Set CRS to EPSG:4326.
- Compare points with the district boundary.
- If points appear in another country or the ocean, check swapped fields and decimal formatting.
12. Updating, Disabling and Uninstalling
- Finish or cancel active processing.
- Open Installed plugins.
- Disable or uninstall the previous version.
- Restart QGIS if Windows keeps files locked.
- Install the new ZIP and test one sample file.
Uninstalling the plugin does not remove previously generated outputs.
13. Processing Toolbox and Model Designer Use
The plugin is a QGIS Processing provider and can be added to a graphical model. Create model inputs for the polygon layer, district field, input folder and output folder, then add Spatial Aggregation Mean.
Model limitation: Multiple CSV files are written to a folder; the graphical model does not automatically load all of them as map layers.
14. Technical Notes and Limitations
- The original polygon layer is not modified.
- Nearest-neighbour search is performed in longitude/latitude coordinate space, consistent with the original cKDTree workflow.
- The plugin calculates arithmetic means, not area-weighted means.
- It does not apply elevation correction, lapse-rate adjustment or bias correction.
- Districts containing internal points use only those internal points.
- If every selected point is missing for one month, that output cell is blank.
- Large CSV files are processed one at a time and current point values are stored in memory.
Recommended citation
Chakraborty, D., Hoque, A., Naskar, M. K., & Bag, K. (2026). Spatial Aggregation Mean: QGIS plugin for district-wise aggregation of gridded monthly climate data (Version 1.3.2). Water Management Section, DSRE, ICAR Research Complex for NEH Region, Umiam, Meghalaya, India.
15. Quick-Reference Checklist
- ☐ Valid district polygon layer and CRS
- ☐ Populated unique district field
- ☐ Longitude, latitude and twelve months in each CSV
- ☐ Coordinates in WGS 84 decimal degrees
- ☐ Separate writable output folder
- ☐ Nearest-grid count documented (default 8)
- ☐ Recursive search used only deliberately
- ☐ Processing report reviewed
- ☐ At least one result independently checked
Appendix: Glossary
| Term | Meaning in this plugin |
|---|---|
| CSV | A delimited text table saved with the .csv extension. |
| CRS | Coordinate reference system used to locate spatial data correctly. |
| WGS 84 / EPSG:4326 | Longitude-latitude coordinate system expected for CSV points. |
| Point-in-polygon | Test used to determine which district contains or intersects a grid point. |
| Nearest neighbour | Closest point or set of points to a district reference point. |
| Fallback district | A district without an internal grid point, filled from the nearest N points. |
| Processing report | CSV summary of input paths, outputs, status and error messages. |
Support and Institutional Contact
Water Management Section, DSRE
ICAR Research Complex for NEH Region
Umroi Road, Umiam, Ri-Bhoi, Meghalaya - 793103, India
Email: akmaulhoque41@gmail.com
For support: Provide the QGIS version, operating system, one sample CSV header, selected polygon field, exact error message and processing report.