|
|
--- |
|
|
title: Remote audit |
|
|
emoji: 📚 |
|
|
colorFrom: blue |
|
|
colorTo: yellow |
|
|
sdk: docker |
|
|
pinned: false |
|
|
license: openrail |
|
|
short_description: Remote auditor |
|
|
--- |
|
|
|
|
|
|
|
|
# Remote Audit App - Setup Instructions |
|
|
|
|
|
This Hugging Face Space performs design-based tests of randomization integrity using pre-treatment satellite imagery, implementing the conditional randomization test from your paper. |
|
|
|
|
|
## Quick Start |
|
|
|
|
|
### Option 1: Use Pre-computed Satellite Data (Recommended for HF) |
|
|
|
|
|
The app expects satellite features (NDVI, EVI, VIIRS) to be pre-computed. To replicate the Begum et al. 2022 audit: |
|
|
|
|
|
1. Download the pre-processed dataset with satellite features |
|
|
2. Place `Islam2019_WithGeocodesAndSatData.Rdata` in the app directory |
|
|
3. Select "Use Example (Islam 2019)" in the app |
|
|
|
|
|
### Option 2: Upload Your Own CSV |
|
|
|
|
|
Your CSV should include: |
|
|
- Treatment assignment column (e.g., `begum_treat` with values 1=control, 2=treatment) |
|
|
- Satellite features: `ndvi_median`, `viirs_median` (or similar) |
|
|
- Any other columns for reference |
|
|
|
|
|
Example CSV structure: |
|
|
``` |
|
|
id,begum_treat,ndvi_median,viirs_median |
|
|
1,1,0.45,2.3 |
|
|
2,2,0.52,3.1 |
|
|
... |
|
|
``` |
|
|
|
|
|
## Setting Up GEE for New Data |
|
|
|
|
|
The app uses **pre-computed** satellite features. To add GEE capabilities for computing features on-the-fly: |
|
|
|
|
|
### Prerequisites |
|
|
1. Google Earth Engine account (free): https://earthengine.google.com/signup/ |
|
|
2. Python environment with `earthengine-api` |
|
|
|
|
|
### Installation Steps |
|
|
|
|
|
```bash |
|
|
# Install Earth Engine Python API |
|
|
pip install earthengine-api |
|
|
|
|
|
# Authenticate (first time only) |
|
|
earthengine authenticate |
|
|
|
|
|
# Initialize in your script |
|
|
import ee |
|
|
ee.Initialize() |
|
|
``` |
|
|
|
|
|
### Computing Satellite Features |
|
|
|
|
|
Use the GEE code from `RemoteAuditOfBrokenRCT.R` to compute features: |
|
|
|
|
|
```python |
|
|
import ee |
|
|
import pandas as pd |
|
|
|
|
|
def compute_satellite_features(lat, lon, start_date, end_date): |
|
|
""" |
|
|
Compute NDVI, EVI, and VIIRS features for a location |
|
|
|
|
|
Args: |
|
|
lat, lon: Coordinates |
|
|
start_date, end_date: Date range (YYYY-MM-DD) |
|
|
|
|
|
Returns: |
|
|
dict with ndvi_median, viirs_median, etc. |
|
|
""" |
|
|
point = ee.Geometry.Point([lon, lat]) |
|
|
|
|
|
# MODIS vegetation indices |
|
|
modis = (ee.ImageCollection('MODIS/061/MOD13Q1') |
|
|
.filterDate(start_date, end_date) |
|
|
.select(['NDVI', 'EVI']) |
|
|
.map(lambda img: img.multiply(0.0001))) |
|
|
|
|
|
ndvi_median = modis.select('NDVI').median() |
|
|
evi_median = modis.select('EVI').median() |
|
|
|
|
|
# VIIRS nighttime lights |
|
|
viirs = (ee.ImageCollection('NOAA/VIIRS/DNB/MONTHLY_V1/VCMSLCFG') |
|
|
.filterDate(start_date, end_date) |
|
|
.select(['avg_rad'])) |
|
|
|
|
|
viirs_median = viirs.median() |
|
|
|
|
|
# Sample at location |
|
|
sample = (ndvi_median.addBands([evi_median, viirs_median]) |
|
|
.sample(point, 250) |
|
|
.first() |
|
|
.getInfo()) |
|
|
|
|
|
return { |
|
|
'ndvi_median': sample['properties'].get('NDVI'), |
|
|
'evi_median': sample['properties'].get('EVI'), |
|
|
'viirs_median': sample['properties'].get('avg_rad') |
|
|
} |
|
|
``` |
|
|
|
|
|
### Integration with R (via reticulate) |
|
|
|
|
|
To integrate GEE in your R workflow: |
|
|
|
|
|
```r |
|
|
library(reticulate) |
|
|
|
|
|
# Set Python environment |
|
|
Sys.setenv(RETICULATE_PYTHON = "/path/to/python") |
|
|
|
|
|
# Import Earth Engine |
|
|
ee <- import("ee") |
|
|
ee$Initialize() |
|
|
|
|
|
# Call Python function from R |
|
|
compute_features <- py_run_string(" |
|
|
def get_features(lat, lon): |
|
|
# Your GEE code here |
|
|
return {'ndvi_median': ..., 'viirs_median': ...} |
|
|
") |
|
|
|
|
|
features <- compute_features$get_features(lat, lon) |
|
|
``` |
|
|
|
|
|
## App Configuration on Hugging Face |
|
|
|
|
|
### Required Files |
|
|
- `app.R` - Main Shiny application |
|
|
- `Dockerfile` - Container configuration |
|
|
- `Islam2019_WithGeocodesAndSatData.Rdata` - Example dataset (optional) |
|
|
|
|
|
### Environment Variables |
|
|
None required for basic functionality. |
|
|
|
|
|
### Secrets (if adding GEE) |
|
|
If you want to enable on-the-fly GEE queries: |
|
|
1. Add `GOOGLE_APPLICATION_CREDENTIALS` secret in HF Space settings |
|
|
2. Upload service account JSON |
|
|
3. Modify app to call GEE API |
|
|
|
|
|
## Usage Guide |
|
|
|
|
|
### Running a Randomization Audit |
|
|
|
|
|
1. **Load Data**: Upload CSV or use example |
|
|
2. **Configure Audit**: |
|
|
- Audit Type: "Randomization" |
|
|
- Treatment Column: Select column (e.g., `begum_treat`) |
|
|
- Control Value: 1 |
|
|
- Treatment Value: 2 |
|
|
3. **Select Features**: Check `ndvi_median` and `viirs_median` |
|
|
4. **Choose Learner**: Logistic (fast) or XGBoost (more flexible) |
|
|
5. **Set Parameters**: |
|
|
- K-Folds: 5-10 (higher = more robust) |
|
|
- Resamples: 1000-2000 (higher = more precise p-value) |
|
|
6. **Run Audit**: Click "Run Audit" button |
|
|
|
|
|
### Running a Missingness Audit |
|
|
|
|
|
Same steps but: |
|
|
- Audit Type: "Missingness" |
|
|
- Select variable to check for missing data patterns |
|
|
|
|
|
### Interpreting Results |
|
|
|
|
|
- **p < 0.05**: Assignment is MORE predictable from satellite features than expected → potential deviation from stated randomization |
|
|
- **p ≥ 0.05**: No evidence of deviation detected (but doesn't prove perfect randomization) |
|
|
|
|
|
## Technical Notes |
|
|
|
|
|
### Computation Time |
|
|
- Logistic: ~1-3 minutes for 500 units, 1000 resamples |
|
|
- XGBoost: ~3-10 minutes (depends on tree settings) |
|
|
|
|
|
### Memory Requirements |
|
|
- Small datasets (<1000 units): 2GB RAM sufficient |
|
|
- Large datasets (>5000 units): Consider 4GB+ RAM |
|
|
|
|
|
### Handling Missing Satellite Data |
|
|
|
|
|
If your CSV has missing satellite features: |
|
|
- App will drop rows with missing values |
|
|
- Consider imputation before upload, or |
|
|
- Use GEE to compute features for missing locations |
|
|
|
|
|
## Troubleshooting |
|
|
|
|
|
### "Feature not found" error |
|
|
- Check that your CSV has columns named exactly: `ndvi_median`, `viirs_median` |
|
|
- Column names are case-sensitive |
|
|
|
|
|
### "Too few complete cases" error |
|
|
- Ensure at least 10 units have both valid treatment assignment and satellite features |
|
|
- Check for NA values in your data |
|
|
|
|
|
### GEE authentication issues |
|
|
```bash |
|
|
# Re-authenticate |
|
|
earthengine authenticate |
|
|
|
|
|
# Check credentials |
|
|
python -c "import ee; ee.Initialize(); print('Success!')" |
|
|
``` |
|
|
|
|
|
### Dockerfile build fails |
|
|
```bash |
|
|
# Test locally |
|
|
docker build -t remote-audit . |
|
|
docker run -p 7860:7860 remote-audit |
|
|
``` |
|
|
|
|
|
## Citation |
|
|
|
|
|
If you use this app, please cite: |
|
|
|
|
|
``` |
|
|
Jerzak, C. T., & Daoud, A. (2025). Remote Auditing: Design-Based Tests |
|
|
of Randomization, Selection, and Missingness with Broadly Accessible |
|
|
Satellite Imagery. |
|
|
``` |
|
|
|
|
|
## Support |
|
|
|
|
|
For issues or questions: |
|
|
- Check the paper's technical appendix |
|
|
- Review example code in `RemoteAuditOfBrokenRCT.R` |
|
|
- Contact: [your contact info] |
|
|
|
