Create README.md

README.md

@@ -0,0 +1,184 @@
+---
+license: apache-2.0
+---
+
+# Model Card for Model ID
+
+<!-- Provide a quick summary of what the model is/does. -->
+
+This causal model takes environmental inputs for an area of a city, and returns an estimated effect of tree coverage change on the surface temperature, for that area.
+The model expects the following information as inputs, for a 100x100 meter area: 
+-Confounding variables (X): Elevation, Proximity to water, Average percentage of tree coverage of neighboring areas, Average NDBI of neighboring areas
+-Treatment variable (T) - optional: Percentage of tree canopy coverage
+
+The model can be used in two ways:
+**Method 1**: A simulation of tree coverage (in % - T1) is fed into the model, alongside the original tree coverage (in % - T0) and the rest of the confounding variables (X). The model then provides an output for each area that corresponds to the estimation of the effect on temperature for that tree coverage change.
+**Method 2**: The confounding variables (X) are fed into the model. The model then provides an output for each area that corresponds to expected temperature change per unit change (in %pt) in tree cover.
+The model was trained on raster data (satellite and orthophoto) of the city of Guatemala.
+The goal is to understand how increasing tree coverage could help reduce the temperature in the city.
+
+
+
+## Model Details
+
+### Model Description
+
+<!-- Provide a longer summary of what this model is. -->
+
+- **Developed by:** Projects by IF for the Municipality of Guatemala, within the Artificial Intelligence Specialization of the Bloomberg Philanthropies City Data Alliance program 
+- **Funded by:** Bloomberg Philanthropies
+- **Model type:** Causal inference model (CausalForestDML)
+- **Task:** Estimating the causal effect of tree coverage on local temperature
+- **Resolution:** 100 x 100 m grid cells
+- **License:** Apache licence 2.0
+
+
+### Model Sources
+
+<!-- Provide the basic links for the model. -->
+
+- **Demo:** https://huggingface.co/spaces/Projects-by-IF/dashboard-temp-final
+
+## Uses
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+### Direct Use
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+- Estimating the effect of tree coverage on local surface temperature
+
+
+### Downstream Use
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+
+- Urban heat island mitigation studies
+- Environmental planning and policy design
+- Scenario analysis of reforestation interventions
+ 
+
+### Out-of-Scope Use
+
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+
+- Do not use outputs for regulatory or economic decisions without expert validation.
+
+## Bias, Risks, and Limitations
+
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+
+- The model is trained only on satellite data from Guatemala City and may not generalize well to other regions or climates.
+- The model uses satellite-derived Land Surface Temperature (LST) instead of air temperature. Results should be seen as surface cooling potential, not human thermal comfort.
+- The 100 x 100 m resolution limits detail. Tree cover is represented as percentage canopy cover, not individual trees.
+- The model doesn’t consider tree species, spacing, canopy structure, or feasibility of planting in densely built areas, all of which affect real cooling outcomes.
+- It captures localized, near-term effects, not long-term dynamics such as tree growth, survival, or maintenance. Cooling benefits may be nonlinear or delayed in reality.
+- Results are estimates under causal assumptions; external validation is recommended before policy use.
+- Local microclimate, building geometry, and temporal variation are not directly modeled.
+- Only tree planting is modeled; other cooling measures (e.g., reflective roofs, water features, ventilation corridors) are excluded.
+- Some edge cases produce unrealistic outputs (positive impact of trees on temperature) so the model isn’t applicable in those cases.
+
+### Recommendations
+
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+
+- Interpret outputs as relative indicators of potential cooling, not precise temperature predictions.
+- Combine results with local expert knowledge and on-site assessments before designing interventions.
+- Use in conjunction with other urban heat mitigation strategies for comprehensive planning.
+
+## How to Get Started with the Model
+You can call the model through the API interface found here: https://huggingface.co/spaces/Projects-by-IF/model-temp-api, using the code below (as an example)
+
+```python
+import requests
+
+url = "https://Projects-by-IF-model-temp-api.hf.space/model-effect"
+
+headers = {"Content-Type": "application/json"}
+data = {"X": X.tolist(), "T0":T.tolist(), "T1":(T_sim).tolist()}
+ response = requests.post(url, headers=headers, json=data)
+ if response.ok:
+     result = response.json()
+     print("Model response:", result["effect"])
+
+```
+
+## Training Details
+
+### Training Data
+
+<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+
+The model was trained on satellite and orthophoto-derived raster data for Guatemala City, combining environmental, land cover, and built-environment layers.
+Key raster datasets included: LST (Land Surface Temperature), NDBI, Elevation, Proximity to water and Percentage tree canopy coverage.
+All datasets were cropped to the Guatemala City boundary and resampled to a 100×100 m grid, producing one record per cell with accompanying neighborhood statistics.
+
+
+### Training Procedure
+
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+
+#### Preprocessing 
+
+**Resampling:** mean aggregation using rasterio
+**Neighbor features:** for each variable, the average of the 8 surrounding cells was computed to capture local spatial context.
+**Data cleaning:** removed null entries and standardized column names.
+**Rounding:** All numeric values rounded to 2 decimals; no normalization or scaling applied.
+
+#### Training parameters 
+
+**Training regime:**
+Model trained on 100x100 m resolution grid cells across Guatemala City.
+Inputs included confounding variables (X): Elevation, Proximity to water, Average percentage of tree coverage of neighboring areas, Average NDBI of neighboring areas; and the treatment variable (T): Percentage of tree canopy coverage
+The target variable (Y) was LST (Land Surface Temperature).
+Training was optimized to estimate the causal effect of tree coverage on LST, accounting for spatial confounders.
+
+**Model type:** Causal inference framework (Causal Forest DML; econml). 
+The treatment model (T given X) is a Linear Regression model (sklearn), while the outcome model (Y given X) is a Random Forest model (sklearn)
+
+**Objective:** Estimation of treatment effect rather than direct temperature prediction.
+
+
+## Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+<!-- This should link to a Dataset Card if possible. -->
+
+Model evaluation was conducted using historical data from Guatemala City.
+For each 100×100 m grid cell, the dataset included:
+- Historical tree coverage (%) for two time periods
+- Corresponding Land Surface Temperature (LST) observations for the same periods
+These data allowed comparison between observed temperature changes and model-predicted temperature effects based on changes in tree cover
+
+#### Factors
+Evaluation considered how well the model could reproduce observed temperature differences across space and time.
+
+#### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+The model’s predicted temperature change was computed by multiplying each area’s estimated Individual Treatment Effect (ITE) by the observed change in tree coverage across that period of time.
+This predicted change was then added to the historical baseline temperature and compared against the actual observed LST for the later period.
+Performance was assessed using standard error-based metrics, including:
+- Mean Squared Error (MSE)
+- Correlation (R²) between predicted and observed temperature changes
+
+
+### Results
+
+- MSE: 0.2318
+- R²: 0.9767
+
+
+## Model Card Authors
+
+Projects by IF https://www.projectsbyif.com/ for the Municipality of Guatemala, within the framework of the Artificial Intelligence Specialization of the Bloomberg Philanthropies City Data Alliance program. 
+
+## Model Card Contact
+
+weare@projectsbyif.com - Projects by IF