deploy: cd5b713

_sources/quickstarter.rst.txt

@@ -3,24 +3,24 @@ Quickstarter
 ============
 
 
-Data input
+Input data
 ----------
 
 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`
------------------
+1. 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 variables and create run script
--------------------------------------------
+2. Edit config variables and create run script
+----------------------------------------------
 
 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.
 
@@ -62,10 +62,49 @@ To run data other than the example data, create the `run.py` below.
     df = model.execute()
     model.graph()
 
-Run `naturf`
-------------
+3. Run `naturf`
+---------------
 This will run all functions required to create the output specified in the `run.py` `output_columns` variable. Currently `write_binary` and `write_index`. The `path` variable should point towards the input shapefile.
 
 .. code:: bash
 
     python run.py
+
+
+Run using the `DAGWorks Platform <app.dagworks.io>`_
+----------------------------------------------------
+
+Import os and the DAGWorks Tracker:
+
+.. code:: python3
+
+    import os
+    from dagworks import adapters
+
+Add this to `run.py` at the top of main:
+
+.. code:: python3
+
+    tracker = adapters.DAGWorksTracker(
+            project_id=<your project ID>,
+            api_key=os.environ["DAGWORKS_API_KEY"],
+            username="<your username>",
+            dag_name="<name of the DAG>",
+            tags={"environment": "DEV", "team": "MY_TEAM", "version": "X"}
+        )
+
+Set the API Key as an environment variable:
+
+.. code:: bash
+
+    $ export DAGWORKS_API_KEY="<your API Key>"
+
+Add `tracker` in the `hamilton_adaptors` list:
+
+.. code:: python3
+
+    hamilton_adapters = [
+                base.SimplePythonDataFrameGraphAdapter(),
+                h_tqdm.ProgressBar("Naturf DAG"),
+                tracker,
+            ]

_sources/release_notes.rst.txt

@@ -4,6 +4,12 @@ Release notes
 This is the list of changes to **naturf** between each release. For full details,
 see the `commit logs <https://github.com/IMMM-SFA/naturf/commits>`_.
 
+Version 1.0.2
+_____________
+
+- See the `v1.0.2 release notes <https://github.com/IMMM-SFA/naturf/releases/tag/v1.0.2>`_.
+
+
 Version 1.0.1
 _____________
 

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>: Apr 02, 2024 <strong>Version</strong>: 1.0.1</p>
+<p><strong>Date</strong>: Apr 09, 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

@@ -59,10 +59,11 @@
         </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
               <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 <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>
+<li class="toctree-l2"><a class="reference internal" href="#input-data">Input data</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#install-naturf">1. Install <cite>naturf</cite></a></li>
+<li class="toctree-l2"><a class="reference internal" href="#edit-config-variables-and-create-run-script">2. Edit config variables and create run script</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#run-naturf">3. Run <cite>naturf</cite></a></li>
+<li class="toctree-l2"><a class="reference internal" href="#run-using-the-dagworks-platform">Run using the DAGWorks Platform</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide.html">User guide</a></li>
@@ -102,20 +103,20 @@
 
   <section id="quickstarter">
 <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>
+<section id="input-data">
+<h2>Input data<a class="headerlink" href="#input-data" title="Link to this heading"></a></h2>
 <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 <cite>naturf</cite><a class="headerlink" href="#install-naturf" title="Link to this heading"></a></h2>
+<h2>1. 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-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>
+<h2>2. 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>
@@ -152,12 +153,42 @@ <h2>Edit config variables and create run script<a class="headerlink" href="#edit
 </div>
 </section>
 <section id="run-naturf">
-<h2>Run <cite>naturf</cite><a class="headerlink" href="#run-naturf" title="Link to this heading"></a></h2>
+<h2>3. Run <cite>naturf</cite><a class="headerlink" href="#run-naturf" title="Link to this heading"></a></h2>
 <p>This will run all functions required to create the output specified in the <cite>run.py</cite> <cite>output_columns</cite> variable. Currently <cite>write_binary</cite> and <cite>write_index</cite>. The <cite>path</cite> variable should point towards the input shapefile.</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>run.py
 </pre></div>
 </div>
 </section>
+<section id="run-using-the-dagworks-platform">
+<h2>Run using the <a class="reference external" href="app.dagworks.io">DAGWorks Platform</a><a class="headerlink" href="#run-using-the-dagworks-platform" title="Link to this heading"></a></h2>
+<p>Import os and the DAGWorks Tracker:</p>
+<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
+<span class="kn">from</span> <span class="nn">dagworks</span> <span class="kn">import</span> <span class="n">adapters</span>
+</pre></div>
+</div>
+<p>Add this to <cite>run.py</cite> at the top of main:</p>
+<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">tracker</span> <span class="o">=</span> <span class="n">adapters</span><span class="o">.</span><span class="n">DAGWorksTracker</span><span class="p">(</span>
+        <span class="n">project_id</span><span class="o">=&lt;</span><span class="n">your</span> <span class="n">project</span> <span class="n">ID</span><span class="o">&gt;</span><span class="p">,</span>
+        <span class="n">api_key</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&quot;DAGWORKS_API_KEY&quot;</span><span class="p">],</span>
+        <span class="n">username</span><span class="o">=</span><span class="s2">&quot;&lt;your username&gt;&quot;</span><span class="p">,</span>
+        <span class="n">dag_name</span><span class="o">=</span><span class="s2">&quot;&lt;name of the DAG&gt;&quot;</span><span class="p">,</span>
+        <span class="n">tags</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;environment&quot;</span><span class="p">:</span> <span class="s2">&quot;DEV&quot;</span><span class="p">,</span> <span class="s2">&quot;team&quot;</span><span class="p">:</span> <span class="s2">&quot;MY_TEAM&quot;</span><span class="p">,</span> <span class="s2">&quot;version&quot;</span><span class="p">:</span> <span class="s2">&quot;X&quot;</span><span class="p">}</span>
+    <span class="p">)</span>
+</pre></div>
+</div>
+<p>Set the API Key as an environment variable:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span><span class="nb">export</span><span class="w"> </span><span class="nv">DAGWORKS_API_KEY</span><span class="o">=</span><span class="s2">&quot;&lt;your API Key&gt;&quot;</span>
+</pre></div>
+</div>
+<p>Add <cite>tracker</cite> in the <cite>hamilton_adaptors</cite> list:</p>
+<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">hamilton_adapters</span> <span class="o">=</span> <span class="p">[</span>
+            <span class="n">base</span><span class="o">.</span><span class="n">SimplePythonDataFrameGraphAdapter</span><span class="p">(),</span>
+            <span class="n">h_tqdm</span><span class="o">.</span><span class="n">ProgressBar</span><span class="p">(</span><span class="s2">&quot;Naturf DAG&quot;</span><span class="p">),</span>
+            <span class="n">tracker</span><span class="p">,</span>
+        <span class="p">]</span>
+</pre></div>
+</div>
+</section>
 </section>
 
 

release_notes.html

@@ -63,6 +63,7 @@
 <li class="toctree-l1"><a class="reference internal" href="modules.html">naturf</a></li>
 <li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing to <strong>naturf</strong></a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Release notes</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#version-1-0-2">Version 1.0.2</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#version-1-0-1">Version 1.0.1</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#version-1-0-0">Version 1.0.0</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#version-0-0-0">Version 0.0.0</a></li>
@@ -103,6 +104,12 @@
 <h1>Release notes<a class="headerlink" href="#release-notes" title="Link to this heading"></a></h1>
 <p>This is the list of changes to <strong>naturf</strong> between each release. For full details,
 see the <a class="reference external" href="https://github.com/IMMM-SFA/naturf/commits">commit logs</a>.</p>
+<section id="version-1-0-2">
+<h2>Version 1.0.2<a class="headerlink" href="#version-1-0-2" title="Link to this heading"></a></h2>
+<ul class="simple">
+<li><p>See the <a class="reference external" href="https://github.com/IMMM-SFA/naturf/releases/tag/v1.0.2">v1.0.2 release notes</a>.</p></li>
+</ul>
+</section>
 <section id="version-1-0-1">
 <h2>Version 1.0.1<a class="headerlink" href="#version-1-0-1" title="Link to this heading"></a></h2>
 <ul class="simple">