Skip to content

Commit

Permalink
Improve readme
Browse files Browse the repository at this point in the history
  • Loading branch information
Damonamajor committed Jan 7, 2025
1 parent e7f9d06 commit 4169716
Showing 1 changed file with 3 additions and 3 deletions.
6 changes: 3 additions & 3 deletions analyses/new_feature/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,21 @@

## Overview

This directory contains Quarto analysis documents for the residential model. These documents need to be manually triggered following a model run. At present, they are designed to test the implementation of new features. These `qmd` files are located in the `new_feature` folder. In that folder, there are three sub-folders, `categorical`, `continuous`, and `shared`. `Shared` contains relevant information for both categorical and continuous variables, most notably the ingest script.
This directory contains Quarto analysis documents for the residential model. These documents need to be manually triggered following a model run. At present, the only directory is to test new features. These `qmd` files are located in the `new_feature` folder. In that folder, there are three sub-folders, `categorical`, `continuous`, and `shared`. `Shared` contains relevant information for both categorical and continuous variables, most notably the ingest script.

## Structure

The documents in this directory are **modularized** and separated by topic area. Documents prefixed with an underscore are considered **modules** and can be interpolated into other documents using the Quarto [include shortcode](https://quarto.org/docs/authoring/includes.html).

For example, `categorical/categorial_shaps.qmd` produces charts and tables relating to the SHAP values of the newly added features. It uses the shortcode `{{< include ../_setup.qmd >}}` on the first line to run `_setup.qmd`, which loads all necessary libraries and data dependencies.
For example, `categorical/categorial_shaps.qmd` produces charts and tables relating to the SHAP values of the newly added features. It uses the shortcode `{``{{< include ../shared/setup_shared.qmd >}}` on the first line to run `setup_shared.qmd`, which loads all necessary libraries and data dependencies.

Main documents do not have an underscore prefix. They combine metadata with multiple modules to generate a single, large report. For example, `categorical/categorical_new_feature.qmd` combines modules and renders to a single HTML document with a table of contents.

> \[!NOTE\] Each `.qmd` file (even a module) can be rendered independently. Simply click the **Render** button in RStudio to knit only that document. Note however, that the HTML styling/metadata from `categorical/categorical_new_feature.qmd` will *not* apply to the rendered output (no table of contents, hidden code, etc.).
### Adding New Content

To add new content to a module of a main document, simply edit the relevant module. Your changes will be interpolated directly into the main document when it renders.
To add new content to a module of a document, simply edit the relevant module. Your changes will be interpolated directly into the main document when it renders. Make sure that changes are tracked in both `categorial` and `continuous` (if necessary).

Be sure to load any new data you used in the module in `_shared_setup.qmd`, and add any new libraries you used to the main `DESCRIPTION` file (see [Managing R Dependencies](https://github.com/ccao-data/model-res-avm?tab=readme-ov-file#managing-r-dependencies) in the main README).

Expand Down

0 comments on commit 4169716

Please sign in to comment.