diff --git a/README.md b/README.md index 9ba1c55..ec8348b 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ pip install NREL-landbosse At its most basic, the following setup is required, though the provided input data in `project_inpute_template` can be used to test out the model and view results before diving into configuring custom scenarios. -1. Create an "input" and "output" folder for LandBOSSE to access. If you are using a source +1. Create an input and output folder for LandBOSSE to access. If you are using a source installation, then ensure the folders are not located inside the local copy of the repository. 2. Create a `project_list.xlsx` like `LandBOSSE/project_list.xlsx` and a subfolder called `project_data` inside of `inputs`. diff --git a/docs/example.md b/docs/example.md index e6c525a..4bb9e38 100644 --- a/docs/example.md +++ b/docs/example.md @@ -558,17 +558,20 @@ running LandBOSSE through each of these methods. Per the installation instructions, this example assumes your conda (or other) Python environment has been created and LandBOSSE has been installed. -1. Determine the desired input and output folder locations for your data. +1. Determine the desired input and output folder locations for your data, ensuring the input folder + contains project listing Excel sheets in the top-level of this folder, and all project-specific + Excel data in the `project_data` subfolder. This should mirror the + [repository's `project_input_template`](https://github.com/NLRWindSystems/LandBOSSE/tree/main/project_input_template). 2. Configure your project listing Excel file and the project data Excel file for each listed project described in [Project Input Data](#project-input-data). - + :::{important} The name of the project listing must be called `project_list.xlsx` as it will be the only file that is used for running projects. ::: 3. Open a terminal (or Anaconda Prompt or other) session. 4. Navigate to where LandBOSSE has been downloaded. In the terminal: - + ```bash cd /path/to/LandBOSSE ``` @@ -597,7 +600,7 @@ has been created and LandBOSSE has been installed. ### `LandBOSSERunner` -#### Converting the Excel project list to a dictionary +#### Converting The Excel Project List To A Dictionary The below code snippet demonstrates how to convert the project list file for a given project, such as the "foundation_validation_ge15" project found in `project_list_simplified.xlsx` that is @@ -627,14 +630,59 @@ inputs["data_tables"] = pd.read_excel( ) ``` -#### Running the model +#### Running In A Python Script -1. Determine the desired input and output folder locations for your data. +1. Determine the desired input and output folder locations for your data, ensuring the input folder + contains project listing Excel sheets in the top-level of this folder, and all project-specific + Excel data in the `project_data` subfolder. This should mirror the + [repository's `project_input_template`](https://github.com/NLRWindSystems/LandBOSSE/tree/main/project_input_template). 2. Configure your project listing Excel file and the project data Excel file for each listed project described in [Project Input Data](#project-input-data). -3. In a Python script, Jupyter Notebook, etc., some form of the following code can be used to run - a single project listing. Please read the inline comments for further context about what steps - are beging taken and why. +3. Manually load the project data and run the project (single workflow example after step-by-step + instructions). + + 1. Import the required dependencies. + + ```python + from pathlib import Path + + import yaml + import pandas as pd + + from landbosse.landbosse_runner import LandBOSSERunner + ``` + + 2. Optional: Load the hourly weather profile. + + ```python + weather = pd.read_csv("/my/weather/data.csv") + weather = LandBOSSERunner.add_header_to_weather_dataframe(weather) + ``` + + 3. Load the project listing Excel data. + + ```python + with Path("/path/to/my_project_data.yaml").open() as f: + inputs = yaml.safe_load(f) + ``` + + 4. Load the single project's Excel data and connect it to the project listing dictionary above. + + ```python + data_path = Path("/path/to/data_tables/").resolve() + inputs["data_tables"] = pd.read_excel( + data_path /inputs["data_tables"], sheet_name=None + ) + ``` + + 5. Create the LandBOSSE object and run + + ```python + lb = LandBOSSERunner(input_config=inputs, weather=weather) + lb.run() + ``` + + As a single, combined workflow, the below can serve as a base workflow for most projects. ```python from pathlib import Path diff --git a/docs/intro.md b/docs/intro.md index 2b26499..e8aa3d2 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,2 +1,2 @@ :::{include} ../README.md -::: \ No newline at end of file +:::