deploy: 3aefd2e

_sources/quickstarter.rst.txt

@@ -6,28 +6,30 @@ Quickstarter
 Data input
 ----------
 
-The only input data required for *naturf* is a shapefile with building footprints and height data. There should be a field with a unique ID for each building the shapefile, and it should be in a projected coordinate system such as Alber Equal Area Conic. For input to the Weather Research and Forecasting model (WRF), the computed parameters for each building will be projected into WGS 84.
+The only input data required for `naturf` is a shapefile with building footprints and height data. There should be a field with a unique ID for each building the shapefile, and it should be in a projected coordinate system such as Alber Equal Area Conic. For input to the Weather Research and Forecasting model (WRF), the computed parameters for each building will be projected into WGS 84.
 
 Either check out our interactive `quickstarter <quickstarter.rst>`_, or continue below to run `naturf` using a python file.
 
-Install ``naturf`
+Install `naturf`
 -----------------
 
+In a clean virtual or Conda environment, install `naturf`. NOTE: For Conda environments using Python 3.12, the `setuptools` package does not work as intended. One workaround is to create a Conda environment in Python 3.11.
+
 .. code:: bash
 
     pip install naturf
 
-Edit config file
-----------------
+Edit config variables and create run script
+-------------------------------------------
 
-The *config.py* file in the naturf/ directory sets the default names for variables used in the *naturf* workflow. The two variables below need to be modified to reflect the ID field and the building height field of the input shapefile.
+The `config` module in `naturf` sets the default names for variables used in the `naturf` workflow. The two variables below need to be modified to reflect the ID field and the building height field of the input shapefile. Instructions on changing field names will be given further below.
 
 .. code:: python
 
-    data_id_field_name
-    data_height_field_name
+    DATA_ID_FIELD_NAME
+    DATA_HEIGHT_FIELD_NAME
 
-Create a python script called `run.py` to run `naturf`
+Create a python script called `run.py` to run `naturf`. The code below runs the example data.
 
 .. code:: python3
 
@@ -42,6 +44,23 @@ Create a python script called `run.py` to run `naturf`
     df = model.execute()
     model.graph()
 
+To run data other than the example data, create the `run.py` below.
+
+.. code:: python3
+
+    from naturf import driver
+    from naturf.config import Settings
+
+    Settings.DATA_ID_FIELD_NAME = "YOUR_ID_FIELD_NAME_HERE"
+    Settings.DATA_HEIGHT_FIELD_NAME = "YOUR_HEIGHT_FIELD_NAME_HERE"
+
+    input_shapefile_path = "PATH_TO_YOUR_DATA"
+    inputs = {"input_shapefile": input_shapefile_path}
+    outputs = ["write_binary", "write_index"]
+    model = driver.Model(inputs, outputs)
+
+    df = model.execute()
+    model.graph()
 
 Run `naturf`
 ------------

index.html

@@ -95,7 +95,7 @@
 
   <section id="naturf-documentation">
 <h1>naturf documentation<a class="headerlink" href="#naturf-documentation" title="Link to this heading"></a></h1>
-<p><strong>Date</strong>: Feb 21, 2024 <strong>Version</strong>: 1.0.1</p>
+<p><strong>Date</strong>: Feb 22, 2024 <strong>Version</strong>: 1.0.1</p>
 <p><strong>Useful links</strong>:
 <a class="reference external" href="https://github.com/immm-sfa/naturf">Source Repository</a> |
 <a class="reference external" href="https://github.com/immm-sfa/naturf/issues">Issues &amp; Ideas</a> |

quickstarter.html

@@ -60,8 +60,8 @@
               <ul class="current">
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Quickstarter</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#data-input">Data input</a></li>
-<li class="toctree-l2"><a class="reference internal" href="#install-naturf">Install ``naturf`</a></li>
-<li class="toctree-l2"><a class="reference internal" href="#edit-config-file">Edit config file</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#install-naturf">Install <cite>naturf</cite></a></li>
+<li class="toctree-l2"><a class="reference internal" href="#edit-config-variables-and-create-run-script">Edit config variables and create run script</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#run-naturf">Run <cite>naturf</cite></a></li>
 </ul>
 </li>
@@ -104,23 +104,24 @@
 <h1>Quickstarter<a class="headerlink" href="#quickstarter" title="Link to this heading"></a></h1>
 <section id="data-input">
 <h2>Data input<a class="headerlink" href="#data-input" title="Link to this heading"></a></h2>
-<p>The only input data required for <em>naturf</em> is a shapefile with building footprints and height data. There should be a field with a unique ID for each building the shapefile, and it should be in a projected coordinate system such as Alber Equal Area Conic. For input to the Weather Research and Forecasting model (WRF), the computed parameters for each building will be projected into WGS 84.</p>
+<p>The only input data required for <cite>naturf</cite> is a shapefile with building footprints and height data. There should be a field with a unique ID for each building the shapefile, and it should be in a projected coordinate system such as Alber Equal Area Conic. For input to the Weather Research and Forecasting model (WRF), the computed parameters for each building will be projected into WGS 84.</p>
 <p>Either check out our interactive <a class="reference internal" href="#"><span class="doc">quickstarter</span></a>, or continue below to run <cite>naturf</cite> using a python file.</p>
 </section>
 <section id="install-naturf">
-<h2>Install <a href="#id2"><span class="problematic" id="id3">``</span></a>naturf`<a class="headerlink" href="#install-naturf" title="Link to this heading"></a></h2>
+<h2>Install <cite>naturf</cite><a class="headerlink" href="#install-naturf" title="Link to this heading"></a></h2>
+<p>In a clean virtual or Conda environment, install <cite>naturf</cite>. NOTE: For Conda environments using Python 3.12, the <cite>setuptools</cite> package does not work as intended. One workaround is to create a Conda environment in Python 3.11.</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>naturf
 </pre></div>
 </div>
 </section>
-<section id="edit-config-file">
-<h2>Edit config file<a class="headerlink" href="#edit-config-file" title="Link to this heading"></a></h2>
-<p>The <em>config.py</em> file in the naturf/ directory sets the default names for variables used in the <em>naturf</em> workflow. The two variables below need to be modified to reflect the ID field and the building height field of the input shapefile.</p>
-<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">data_id_field_name</span>
-<span class="n">data_height_field_name</span>
+<section id="edit-config-variables-and-create-run-script">
+<h2>Edit config variables and create run script<a class="headerlink" href="#edit-config-variables-and-create-run-script" title="Link to this heading"></a></h2>
+<p>The <cite>config</cite> module in <cite>naturf</cite> sets the default names for variables used in the <cite>naturf</cite> workflow. The two variables below need to be modified to reflect the ID field and the building height field of the input shapefile. Instructions on changing field names will be given further below.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">DATA_ID_FIELD_NAME</span>
+<span class="n">DATA_HEIGHT_FIELD_NAME</span>
 </pre></div>
 </div>
-<p>Create a python script called <cite>run.py</cite> to run <cite>naturf</cite></p>
+<p>Create a python script called <cite>run.py</cite> to run <cite>naturf</cite>. The code below runs the example data.</p>
 <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">importlib.resources</span> <span class="kn">import</span> <span class="n">files</span>
 <span class="kn">from</span> <span class="nn">naturf</span> <span class="kn">import</span> <span class="n">driver</span>
 
@@ -129,6 +130,22 @@ <h2>Edit config file<a class="headerlink" href="#edit-config-file" title="Link t
 <span class="n">outputs</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;write_binary&quot;</span><span class="p">,</span> <span class="s2">&quot;write_index&quot;</span><span class="p">]</span>
 <span class="n">model</span> <span class="o">=</span> <span class="n">driver</span><span class="o">.</span><span class="n">Model</span><span class="p">(</span><span class="n">inputs</span><span class="p">,</span> <span class="n">outputs</span><span class="p">)</span>
 
+<span class="n">df</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">execute</span><span class="p">()</span>
+<span class="n">model</span><span class="o">.</span><span class="n">graph</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>To run data other than the example data, create the <cite>run.py</cite> below.</p>
+<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">naturf</span> <span class="kn">import</span> <span class="n">driver</span>
+<span class="kn">from</span> <span class="nn">naturf.config</span> <span class="kn">import</span> <span class="n">Settings</span>
+
+<span class="n">Settings</span><span class="o">.</span><span class="n">DATA_ID_FIELD_NAME</span> <span class="o">=</span> <span class="s2">&quot;YOUR_ID_FIELD_NAME_HERE&quot;</span>
+<span class="n">Settings</span><span class="o">.</span><span class="n">DATA_HEIGHT_FIELD_NAME</span> <span class="o">=</span> <span class="s2">&quot;YOUR_HEIGHT_FIELD_NAME_HERE&quot;</span>
+
+<span class="n">input_shapefile_path</span> <span class="o">=</span> <span class="s2">&quot;PATH_TO_YOUR_DATA&quot;</span>
+<span class="n">inputs</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;input_shapefile&quot;</span><span class="p">:</span> <span class="n">input_shapefile_path</span><span class="p">}</span>
+<span class="n">outputs</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;write_binary&quot;</span><span class="p">,</span> <span class="s2">&quot;write_index&quot;</span><span class="p">]</span>
+<span class="n">model</span> <span class="o">=</span> <span class="n">driver</span><span class="o">.</span><span class="n">Model</span><span class="p">(</span><span class="n">inputs</span><span class="p">,</span> <span class="n">outputs</span><span class="p">)</span>
+
 <span class="n">df</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">execute</span><span class="p">()</span>
 <span class="n">model</span><span class="o">.</span><span class="n">graph</span><span class="p">()</span>
 </pre></div>