build based on 12823d7

dev/experimental/index.html

@@ -75,8 +75,8 @@
 ds_subset.dim["lon"]
 
 # output
-2</code></pre><p>Such sliced datasets can for example be saved into a new NetCDF file using <code>write</code>:</p><pre><code class="language-julia hljs">write(&quot;slice.nc&quot;,ds_subset)</code></pre><p>Any dimension not mentioned in the <code>@view</code> call is not sliced. While <code>@view</code> produces a slice based on indices, the <code>NCDatasets.@select</code> macro produces a slice (of an NetCDF variable or dataset) based on the values of other related variables (typically coordinates).</p><h2 id="Data-selection-based-on-values"><a class="docs-heading-anchor" href="#Data-selection-based-on-values">Data selection based on values</a><a id="Data-selection-based-on-values-1"></a><a class="docs-heading-anchor-permalink" href="#Data-selection-based-on-values" title="Permalink"></a></h2><article class="docstring"><header><a class="docstring-binding" id="NCDatasets.@select" href="#NCDatasets.@select"><code>NCDatasets.@select</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">vsubset = NCDatasets.@select(v,expression)
-dssubset = NCDatasets.@select(ds,expression)</code></pre><p>Return a subset of the variable <code>v</code> (or dataset <code>ds</code>) satisfying the condition <code>expression</code> as a view. The condition has the following form:</p><p><code>condition₁ &amp;&amp; condition₂ &amp;&amp; condition₃ ... conditionₙ</code></p><p>Every condition should involve a single 1D NetCDF variable (typically a coordinate variable, referred as <code>coord</code> below). If <code>v</code> is a variable, the related 1D NetCDF variable should have a shared dimension with the variable <code>v</code>. All local variables need to have a <code>$</code> prefix (see examples below). This macro is experimental and subjected to change.</p><p>Every condition can either perform:</p><ul><li><p>a nearest match: <code>coord ≈ target_coord</code> (for <code>≈</code> type <code>\approx</code> followed by the TAB-key). Only the data corresponding to the index closest to <code>target_coord</code> is loaded.</p></li><li><p>a nearest match with tolerance: <code>coord ≈ target_coord ± tolerance</code>. As before, but if the difference between the closest value in <code>coord</code> and <code>target_coord</code> is larger (in absolute value) than <code>tolerance</code>, an empty array is returned.</p></li><li><p>a condition operating on scalar values. For example, a <code>condition</code> equal to <code>10 &lt;= lon &lt;= 20</code> loads all data with the longitude between 10 and 20 or <code>abs(lat) &gt; 60</code> loads all variables with a latitude north of 60° N and south of 60° S (assuming that the NetCDF has the 1D variables <code>lon</code> and <code>lat</code> for longitude and latitude).</p></li></ul><p>Only the data which satisfies all conditions is loaded. All conditions must be chained with an <code>&amp;&amp;</code> (logical and). They should not contain additional parenthesis or other logical operators such as <code>||</code> (logical or).</p><p>To convert the view into a regular array one can use <code>collect</code>, <code>Array</code> or regular indexing. As in julia, views of scalars are wrapped into a zero dimensional arrays which can be dereferenced by using <code>[]</code>. Modifying a view will modify the underlying NetCDF file (if the file is opened as writable, otherwise an error is issued).</p><p>As for any view, one can use <code>parentindices(vsubset)</code> to get the indices matching a select query.</p><p><strong>Examples</strong></p><p>Create a sample file with random data:</p><pre><code class="language-julia hljs">using NCDatasets, Dates
+2</code></pre><p>Such sliced datasets can for example be saved into a new NetCDF file using <code>write</code>:</p><pre><code class="language-julia hljs">write(&quot;slice.nc&quot;,ds_subset)</code></pre><p>Any dimension not mentioned in the <code>@view</code> call is not sliced. While <code>@view</code> produces a slice based on indices, the <code>NCDatasets.@select</code> macro produces a slice (of an NetCDF variable or dataset) based on the values of other related variables (typically coordinates).</p><h2 id="Data-selection-based-on-values"><a class="docs-heading-anchor" href="#Data-selection-based-on-values">Data selection based on values</a><a id="Data-selection-based-on-values-1"></a><a class="docs-heading-anchor-permalink" href="#Data-selection-based-on-values" title="Permalink"></a></h2><article class="docstring"><header><a class="docstring-binding" id="CommonDataModel.@select" href="#CommonDataModel.@select"><code>CommonDataModel.@select</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">vsubset = CommonDataModel.@select(v,expression)
+dssubset = CommonDataModel.@select(ds,expression)</code></pre><p>Return a subset of the variable <code>v</code> (or dataset <code>ds</code>) satisfying the condition <code>expression</code> as a view. The condition has the following form:</p><p><code>condition₁ &amp;&amp; condition₂ &amp;&amp; condition₃ ... conditionₙ</code></p><p>Every condition should involve a single 1D variable (typically a coordinate variable, referred as <code>coord</code> below). If <code>v</code> is a variable, the related 1D variable should have a shared dimension with the variable <code>v</code>. All local variables need to have a <code>$</code> prefix (see examples below). This macro is experimental and subjected to change.</p><p>Every condition can either perform:</p><ul><li><p>a nearest match: <code>coord ≈ target_coord</code> (for <code>≈</code> type <code>\approx</code> followed by the TAB-key). Only the data corresponding to the index closest to <code>target_coord</code> is loaded.</p></li><li><p>a nearest match with tolerance: <code>coord ≈ target_coord ± tolerance</code>. As before, but if the difference between the closest value in <code>coord</code> and <code>target_coord</code> is larger (in absolute value) than <code>tolerance</code>, an empty array is returned.</p></li><li><p>a condition operating on scalar values. For example, a <code>condition</code> equal to <code>10 &lt;= lon &lt;= 20</code> loads all data with the longitude between 10 and 20 or <code>abs(lat) &gt; 60</code> loads all variables with a latitude north of 60° N and south of 60° S (assuming that the has the 1D variables <code>lon</code> and <code>lat</code> for longitude and latitude).</p></li></ul><p>Only the data which satisfies all conditions is loaded. All conditions must be chained with an <code>&amp;&amp;</code> (logical and). They should not contain additional parenthesis or other logical operators such as <code>||</code> (logical or).</p><p>To convert the view into a regular array one can use <code>collect</code>, <code>Array</code> or regular indexing. As in julia, views of scalars are wrapped into a zero dimensional arrays which can be dereferenced by using <code>[]</code>. Modifying a view will modify the underlying file (if the file is opened as writable, otherwise an error is issued).</p><p>As for any view, one can use <code>parentindices(vsubset)</code> to get the indices matching a select query.</p><p><strong>Examples</strong></p><p>Create a sample file with random data:</p><pre><code class="language-julia hljs">using NCDatasets, Dates
 fname = &quot;sample_file.nc&quot;
 lon = -180:180
 lat = -90:90
@@ -142,5 +142,5 @@
 v2 = ds[&quot;temperature&quot;][findall(Dates.month.(time) .== 1 .&amp;&amp; salinity .&gt;= 35)]
 
 @test v == v2
-close(ds)</code></pre><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>For optimal performance, one should try to load contiguous data ranges, in particular when the data is loaded over HTTP/OPeNDAP.</p></div></div></div><a class="docs-sourcelink" target="_blank" href="https://github.com/Alexander-Barth/NCDatasets.jl/blob/330611d3835afa346953b69e2b4caa44fbae8c64/src/select.jl#L94-L209">source</a></section></article><h2 id="Experimental-functions"><a class="docs-heading-anchor" href="#Experimental-functions">Experimental functions</a><a id="Experimental-functions-1"></a><a class="docs-heading-anchor-permalink" href="#Experimental-functions" title="Permalink"></a></h2><article class="docstring"><header><a class="docstring-binding" id="NCDatasets.ancillaryvariables" href="#NCDatasets.ancillaryvariables"><code>NCDatasets.ancillaryvariables</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">ncvar = NCDatasets.ancillaryvariables(ncv::NCDatasets.CFVariable,modifier)</code></pre><p>Return the first ancillary variables from the NetCDF variable <code>ncv</code> with the standard name modifier <code>modifier</code>. It can be used for example to access related variable like status flags.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/Alexander-Barth/NCDatasets.jl/blob/330611d3835afa346953b69e2b4caa44fbae8c64/src/cfconventions.jl#L13-L19">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Base.filter" href="#Base.filter"><code>Base.filter</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">data = NCDatasets.filter(ncv, indices...; accepted_status_flags = nothing)</code></pre><p>Load and filter observations by replacing all variables without an acepted status flag to <code>missing</code>. It is used the attribute <code>ancillary_variables</code> to identify the status flag.</p><pre><code class="nohighlight hljs"># da[&quot;data&quot;] is 2D matrix
-good_data = NCDatasets.filter(ds[&quot;data&quot;],:,:, accepted_status_flags = [&quot;good_data&quot;,&quot;probably_good_data&quot;])</code></pre></div><a class="docs-sourcelink" target="_blank" href="https://github.com/Alexander-Barth/NCDatasets.jl/blob/330611d3835afa346953b69e2b4caa44fbae8c64/src/cfconventions.jl#L45-L57">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../issues/">« Known issues</a><a class="docs-footer-nextpage" href="../tutorials/">Tutorials »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Thursday 2 November 2023 09:57">Thursday 2 November 2023</span>. Using Julia version 1.9.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+close(ds)</code></pre><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>For optimal performance, one should try to load contiguous data ranges, in particular when the data is loaded over HTTP/OPeNDAP.</p></div></div></div></section></article><h2 id="Experimental-functions"><a class="docs-heading-anchor" href="#Experimental-functions">Experimental functions</a><a id="Experimental-functions-1"></a><a class="docs-heading-anchor-permalink" href="#Experimental-functions" title="Permalink"></a></h2><article class="docstring"><header><a class="docstring-binding" id="CommonDataModel.ancillaryvariables" href="#CommonDataModel.ancillaryvariables"><code>CommonDataModel.ancillaryvariables</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">ncvar = CommonDataModel.ancillaryvariables(ncv::CFVariable,modifier)</code></pre><p>Return the first ancillary variables from the NetCDF (or other format) variable <code>ncv</code> with the standard name modifier <code>modifier</code>. It can be used for example to access related variable like status flags.</p></div></section></article><article class="docstring"><header><a class="docstring-binding" id="Base.filter" href="#Base.filter"><code>Base.filter</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">data = CommonDataModel.filter(ncv, indices...; accepted_status_flags = nothing)</code></pre><p>Load and filter observations by replacing all variables without an acepted status flag to <code>missing</code>. It is used the attribute <code>ancillary_variables</code> to identify the status flag.</p><pre><code class="nohighlight hljs"># da[&quot;data&quot;] is 2D matrix
+good_data = NCDatasets.filter(ds[&quot;data&quot;],:,:, accepted_status_flags = [&quot;good_data&quot;,&quot;probably_good_data&quot;])</code></pre></div></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../issues/">« Known issues</a><a class="docs-footer-nextpage" href="../tutorials/">Tutorials »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Thursday 7 December 2023 16:33">Thursday 7 December 2023</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/index.html

@@ -131,4 +131,4 @@
 # if the attribute does not exists
 
 units = get(v,"units","adimensional")
-close(ds)</code></pre></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="dataset/">Datasets »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Thursday 2 November 2023 09:57">Thursday 2 November 2023</span>. Using Julia version 1.9.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+close(ds)</code></pre></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="dataset/">Datasets »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Thursday 7 December 2023 16:33">Thursday 7 December 2023</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>