Merge pull request #8 from acep-uaf/update/expand-readme

update readme

README.md

@@ -1,4 +1,6 @@
-### Welcome
+# Stoatworks Anchorage Solar Locations
+
+## Welcome
 This repository contains code and data regarding locations of solar installations in the Anchorage Alaska area between 2017 and 2023. The maps and visuals generated by this repo are intended for public display, either in publications or presentations, and represent a general portrait of the residential solar sector in Anchorage. 
 
 To go straight to the animated heat map, [click here](https://acep-uaf.github.io/sw_anchorage_solar_locations/)
@@ -13,27 +15,48 @@ You are welcome to interact with this repo on several levels:
 Questions and comments? If you have a GitHub account, please open a new issue in this repo. Otherwise, contact [email protected]
 <br>
 
+## Embed or Link to the Map
+To embed the map in your website, use the following HTML code:
+
+```
+<iframe 
+    width="600" 
+    height="450" 
+    frameborder="0" 
+    style="border:0" 
+    src="https://acep-uaf.github.io/sw_anchorage_solar_locations/" 
+    allowfullscreen>
+</iframe>
+```
 
-#### Address Cleaning Loop
-The source data comes from the City of Anchorage Building Permits. The address strings in this source data did not include common nouns (ex: "Street", "Road", "Circle"), which caused errors during the geocode conversion to coordinates. Approximately 160 addresses failed to parse, returning only "Anchorage, AK". These problem addresses were fed into maps.google.com, and the results were written into `address_changes.csv` as `clean_address`. Pre-cleaned addresses were written as `raw_address`. These addresses changes were iterated through in the script `address_extraction_cleaning.R` and the cleaned permit data was written to `clean_2017_2023_SolarPermits.csv`. Addresses only were written to `input_addresses.csv`.
 
-#### API Call
-Clean addresses from `input_addresses.csv` were read by the script `api_call.js`, which iterated through each address, pinged Google's Geocode API, caught the response, and wrote the collected responses to a JSON file `api_output.json`. 
+## Update, Debug, or Develop
+If you would like to update ARCTIC locations, debug problems with the map, or develop new features, start by cloning the repository to your local machine.
 
-#### Output Trimming and CSV Conversion
-In order to get the JSON results pared down and converted to CSV, the script `output_to_csv.js` imported `api_output.json`, selected the fields `formatted_address, lat, lng`, then wrote to file `output.csv`. 
+The following steps assume you have `R`, `renv` (for managing R dependencies), `node.js`, and `npm` installed:
 
-#### Joining API output and Permit Data
-The flow came full circle via the script `join_output_source.R`, where the output data was loaded from `output.csv` and combined with `clean_2017_2023_SolarPermits.csv`. The combined dataset was written to file as `permits_lat_long.csv`.
+## Install R Dependencies
+Once the repository has been cloned to your computer, install the necessary R dependencies
+1. In a terminal window, navigate to the root directory of the repo
+2. Start R by typing `R` and pressing Enter
+3. In the R console, run the following command to install `renv` (`renv` is a package manager similar to `npm`):
+```
+install.packages("renv")
+```
 
-#### Conversion Back to GeoJSON
-It was useful to have the outputted data in CSV format in order to join back to the source data, but our end product is a web map and it was best to have the data in GeoJSON format. So, a quick script was written, `csv_to_geojson.js` in order to do so. The data was saved as `permits_lat_long.geojson`. Perhaps in the future, this JSON -> CSV -> GeoJSON dance could be eliminated.
+or if you already have `renv` on your global system, skip and run:
+```
+renv::restore()
+```
+This will install the R packages specified in the `renv.lock` file. 
 
+4. Quit R by typing `q()` and pressing Enter
 
-#### Heat Map
-With the source data combined with location coordinates and saved as a GeoJSON file, we were able to place points on a map and build a heat map of solar installations from 2017 to 2023. An animation of the heat map was added, which loops through the years 2017-2023, advancing 1 year every second. Densities are shown as cumulative installations.  
+## Install Javascript Dependencies
+To install Javascript dependencies, navigate to the repo and run `npm install`. 
 
-[Click here](https://github.com/acep-uaf/sw-ARCTIC-locations/issues) to view the heat map on GitHub Pages
+## Adding Changes
+Changes made to update, debug, or develop are best done in a new branch such as `feature/your_cool_widget` or `bugfix/your_solution`. This new local branch can be pushed to a new branch on the remote, then a pull request made to merge the changes into `main`. Please note that direct commits to main are blocked so as not to break the public map. Pull requests will need approval before merging. All merges to `main` will rebuild the map. 
 
 <br>
 <br>