<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Extract time series from sen2r archives — extract_s2ts • sen2rts</title><!-- jquery --><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script><!-- Bootstrap --><link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.4.0/yeti/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous"><script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script><!-- bootstrap-toc --><link rel="stylesheet" href="../bootstrap-toc.css"><script src="../bootstrap-toc.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet"><script src="../pkgdown.js"></script><meta property="og:title" content="Extract time series from sen2r archives — extract_s2ts"><meta property="og:description" content="Extract time series from a Sentinel-2 data archive
(created with the package sen2r) over spatial features (points or
polygons). Quality flags can be added exploiting an additional
extracted archive (see arguments scl_paths and cld_paths)."><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]--></head><body data-spy="scroll" data-target="#toc">
    

    <div class="container template-reference-topic">
      <header><div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <span class="navbar-brand">
        <a class="navbar-link" href="../index.html">sen2rts</a>
        <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="">0.4.1</span>
      </span>
    </div>

    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav"></ul><ul class="nav navbar-nav navbar-right"><li>
  <a href="../index.html">
    <span class="fa fa-home fa-lg"></span>
     
  </a>
</li>
<li>
  <a href="../reference/index.html">
    <span class="fa fa-file-code"></span>
     
     Reference
  </a>
</li>
<li>
  <a href="../articles/workflow.html">
    <span class="fa fa-book"></span>
     
     The sen2rts workflow
  </a>
</li>
<li>
  <a href="../news/index.html">
    <span class="fa fa-newspaper"></span>
     
     Changelog
  </a>
</li>
<li>
  <a href="http://luigi.ranghetti.info" class="external-link">
    <span class="fa fa-user"></span>
     
  </a>
</li>
<li>
  <a href="https://github.com/ranghetti/sen2rts/" class="external-link">
    <span class="fa fa-github fa-lg"></span>
     
  </a>
</li>
      </ul></div><!--/.nav-collapse -->
  </div><!--/.container -->
</div><!--/.navbar -->

      

      </header><div class="row">
  <div class="col-md-9 contents">
    <div class="page-header">
    <h1>Extract time series from sen2r archives</h1>
    <small class="dont-index">Source: <a href="https://github.com/ranghetti/sen2rts/blob/HEAD/R/extract_s2ts.R" class="external-link"><code>R/extract_s2ts.R</code></a></small>
    <div class="hidden name"><code>extract_s2ts.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>Extract time series from a Sentinel-2 data archive
(created with the package <code>sen2r</code>) over spatial features (points or
polygons). Quality flags can be added exploiting an additional
extracted archive (see arguments <code>scl_paths</code> and <code>cld_paths</code>).</p>
    </div>

    <div id="ref-usage">
    <div class="sourceCode"><pre class="sourceCode r"><code><span class="fu">extract_s2ts</span><span class="op">(</span>
  <span class="va">in_paths</span>,
  <span class="va">in_sf</span>,
  fun <span class="op">=</span> <span class="st">"mean"</span>,
  <span class="va">in_sf_id</span>,
  <span class="va">scl_paths</span>,
  <span class="va">cld_paths</span>,
  <span class="va">scl_w</span>,
  fun_w <span class="op">=</span> <span class="st">"mean"</span>
<span class="op">)</span></code></pre></div>
    </div>

    <div id="arguments">
    <h2>Arguments</h2>
    <dl><dt>in_paths</dt>
<dd><p>Paths of the <code>sen2r</code> files (eventually obtained using
<code>read_in_cube(..., out_format = "path")</code>).</p></dd>
<dt>in_sf</dt>
<dd><p>Object with polygonal or point geometries</p></dd>
<dt>fun</dt>
<dd><p>(optional) aggregation function (or function name)
to be used in case of polygonal <code>in_sf</code> features. Default is <code>mean</code>.
If <code>scl_paths</code> and/or <code>cld_paths</code> are defined:</p><ul><li><p>the default <code>mean</code> is intended as <code><a href="https://rdrr.io/r/stats/weighted.mean.html" class="external-link">weighted.mean()</a></code> (where the computed
quality flags are used as weights);</p></li>
<li><p>only the alternative value <code>"best"</code> is accepted (in this case, the pixel
with the higher quality flag - or the average of pixels with the same
higher quality flags - is considered).</p></li>
</ul></dd>
<dt>in_sf_id</dt>
<dd><p>(optional) character vector corresponding to the name/names
of the <code>in_sf</code> column with the features IDs.
If missing, the row number is used.</p></dd>
<dt>scl_paths</dt>
<dd><p>(optional) Paths of the SCL files (they must correspond
to <code>in_paths</code>); if provided, it is used to weight pixels
during the aggregation and to provide an output quality flag.
See details for the conversion between SCL and weights.</p></dd>
<dt>cld_paths</dt>
<dd><p>(optional) Paths of the CLD files (they must correspond
to <code>in_paths</code>); see <code>scl_paths</code>.
See details for the conversion between SCL and weights.</p></dd>
<dt>scl_w</dt>
<dd><p>(optional) weights to be used for each SCL class,
which can be created using function <code><a href="scl_weights.html">scl_weights()</a></code>.
If missing, the default outputs of <code><a href="scl_weights.html">scl_weights()</a></code> are used.
See details for the conversion between SCL and weights.</p></dd>
<dt>fun_w</dt>
<dd><p>(optional) function to be used to aggregate quality flags
in case of polygonal <code>in_sf</code> features. Default is <code>mean</code>.</p></dd>
</dl></div>
    <div id="value">
    <h2>Value</h2>
    <p>The output time series in <code>s2ts</code> format.</p>
    </div>
    <div id="details">
    <h2>Details</h2>
    <p>To generate pixel weights, SCL and/or CLD layers can be used.</p>
<p>SCL are categorical layers (12 levels), so each level must be converted
in a 0-1 numeric value. This is done by function <code><a href="scl_weights.html">scl_weights()</a></code>.
If the user provides only <code>scl_paths</code>, the layer of weights will be a
0-1 numeric layer in which each pixel value corresponds to the 0-1 value
associated with the corresponding SCL class.</p>
<p>CLD are integer layers with the percentage (0-100) of cloud probability.
Assumed that a CLD of 0% is associated to a weight of 1 and a CLD of 100%
to a weight of 0, intermediate values are computed taking into account
the output of <code><a href="scl_weights.html">scl_weights()</a></code> for classes <code>"cloud_high_probability"</code>,
<code>"cloud_medium_probability"</code> and <code>"unclassified"</code>
(this because CLD values are in the range 80-100 when associated to the SCL
class <code>"cloud_high_probability"</code>, in the range 20-80 when associated to
<code>"cloud_medium_probability"</code> and in the range 20-80 when associated to
<code>"unclassified"</code> or <code>"thin_cirrus"</code>).
The two values <code>"cloud_medium_probability" - "cloud_high_probability"</code>
and <code>"unclassified" - "cloud_medium_probability"</code> are taken as breaks
to reclassify CLD.
I.e., consider the default case:
<code>scl_weights()[c("cloud_high_probability", "cloud_medium_probability", "unclassified")]</code>
returns <code>0.0 0.1 0.5</code>; so, breaks <code>0.05</code> and <code>0.35</code> are used, meaning that
CLD values in the range 80-100% are rescaled to 0-0.05,
CLD values in the range 20-80% are rescaled to 0.05-0.35 and
CLD values in the range 80-100% are rescaled to 0.35-1.
If the user provides only <code>cld_paths</code>, the layer of weights will be a
0-1 numeric layer with the above described values.</p>
<p>Finally, if the user provides both <code>scl_paths</code> and <code>cld_paths</code>, the two
layers of weights are combined and the lowest quality flag is considered.</p>
    </div>
    <div id="author">
    <h2>Author</h2>
    <p>Luigi Ranghetti, PhD (2020) <a href="mailto:luigi@ranghetti.info">luigi@ranghetti.info</a></p>
    </div>

    <div id="ref-examples">
    <h2>Examples</h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span class="co"># Load input data</span></span>
<span class="r-in"><span class="fu"><a href="https://rdrr.io/r/utils/data.html" class="external-link">data</a></span><span class="op">(</span><span class="st">"sampleroi"</span><span class="op">)</span></span>
<span class="r-in"><span class="va">sen2r_ndvi_paths</span> <span class="op">&lt;-</span> <span class="fu"><a href="sample_paths.html">sample_paths</a></span><span class="op">(</span><span class="st">"NDVI"</span><span class="op">)</span></span>
<span class="r-in"><span class="va">sen2r_scl_paths</span> <span class="op">&lt;-</span> <span class="fu"><a href="sample_paths.html">sample_paths</a></span><span class="op">(</span><span class="st">"SCL"</span><span class="op">)</span></span>
<span class="r-in"></span>
<span class="r-in"><span class="co"># \donttest{</span></span>
<span class="r-in"><span class="co"># Simple TS extraction from polygons (without quality flags)</span></span>
<span class="r-in"><span class="va">ts_raw_0</span> <span class="op">&lt;-</span> <span class="fu">extract_s2ts</span><span class="op">(</span><span class="va">sen2r_ndvi_paths</span>, <span class="va">sampleroi</span><span class="op">)</span></span>
<span class="r-in"><span class="fu"><a href="https://rdrr.io/r/base/print.html" class="external-link">print</a></span><span class="op">(</span><span class="va">ts_raw_0</span>, topn <span class="op">=</span> <span class="fl">5</span><span class="op">)</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> A raw s2ts time series with 60 dates and 2 IDs.</span>
<span class="r-out co"><span class="r-pr">#&gt;</span>           Date Orbit Sensor          1            2  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  1: 2020-01-04   022     2B 1161.33333   1733.06250  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  2: 2020-01-09   022     2A  201.70833    223.52083  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  3: 2020-01-14   022     2B  -43.72917    150.77083  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  4: 2020-01-19   022     2A 1163.68750    967.04167  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  5: 2020-01-24   022     2B 1233.87500   1657.27083  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> ---                                                  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 56: 2020-10-10   022     2B  572.33333   1018.64583  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 57: 2020-10-15   022     2A  -86.37500    -93.22917  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 58: 2020-10-20   022     2B  571.81250    983.20833  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 59: 2020-10-25   022     2A -385.56250   -677.97917  </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 60: 2020-10-30   022     2B  676.35417    783.27083  </span>
<span class="r-in"><span class="co"># }</span></span>
<span class="r-in"></span>
<span class="r-in"><span class="co"># TS extraction from polygons using a SCL archive for quality flags</span></span>
<span class="r-in"><span class="co"># (example used to produce the sample dataset "ts_raw")</span></span>
<span class="r-in"><span class="va">ts_raw</span> <span class="op">&lt;-</span> <span class="fu">extract_s2ts</span><span class="op">(</span></span>
<span class="r-in">  <span class="va">sen2r_ndvi_paths</span>, </span>
<span class="r-in">  <span class="va">sampleroi</span>,</span>
<span class="r-in">  scl_paths <span class="op">=</span> <span class="va">sen2r_scl_paths</span></span>
<span class="r-in"><span class="op">)</span></span>
<span class="r-wrn co"><span class="r-pr">#&gt;</span> <span class="warning">Warning: </span>no_data_value not set: missing values will appear as zero values</span>
<span class="r-in"><span class="va">ts_raw</span><span class="op">$</span><span class="va">value</span> <span class="op">&lt;-</span> <span class="va">ts_raw</span><span class="op">$</span><span class="va">value</span> <span class="op">/</span> <span class="fl">1E4</span> <span class="co"># reshape to standard NDVI range -1 to 1</span></span>
<span class="r-in"><span class="fu"><a href="https://rdrr.io/r/base/print.html" class="external-link">print</a></span><span class="op">(</span><span class="va">ts_raw</span>, topn <span class="op">=</span> <span class="fl">5</span><span class="op">)</span> <span class="co"># standard print</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> A raw s2ts time series with 60 dates and 2 IDs.</span>
<span class="r-out co"><span class="r-pr">#&gt;</span>           Date Orbit Sensor            1               2   </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  1: 2020-01-04   022     2B  0.116133333 ○   0.173306250 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  2: 2020-01-09   022     2A  0.020170833 ○   0.022352083 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  3: 2020-01-14   022     2B -0.004372917 ○   0.015077083 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  4: 2020-01-19   022     2A  0.116368750 ○   0.096704167 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span>  5: 2020-01-24   022     2B  0.123387500 ○   0.165727083 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> ---                                                        </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 56: 2020-10-10   022     2B  0.057233333 ○   0.104959233 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 57: 2020-10-15   022     2A -0.008637500 ○  -0.009322917 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 58: 2020-10-20   022     2B  0.057181250 ○   0.098320833 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 59: 2020-10-25   022     2A -0.038556250 ○  -0.067797917 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 60: 2020-10-30   022     2B  0.067635417 ○   0.078327083 ○ </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> Quality flags:  ● [1]  ◕ [0.9,1)  ◑ [0.75,0.9)  ◔ [0.5,0.75)  ○ [0,0.5)</span>
<span class="r-in"><span class="fu"><a href="https://rdrr.io/r/utils/head.html" class="external-link">head</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/as.data.frame.html" class="external-link">as.data.frame</a></span><span class="op">(</span><span class="va">ts_raw</span><span class="op">)</span><span class="op">)</span> <span class="co"># see content</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span>   id       date orbit sensor        value   qa</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 1  1 2020-01-04   022     2B  0.116133333 0.33</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 2  1 2020-01-09   022     2A  0.020170833 0.00</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 3  1 2020-01-14   022     2B -0.004372917 0.00</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 4  1 2020-01-19   022     2A  0.116368750 0.00</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 5  1 2020-01-24   022     2B  0.123387500 0.33</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 6  1 2020-01-29   022     2A  0.114379167 0.33</span>
<span class="r-in"><span class="fu"><a href="plot.html">plot</a></span><span class="op">(</span><span class="va">ts_raw</span><span class="op">)</span></span>
<span class="r-plt img"><img src="extract_s2ts-1.png" alt="" width="864" height="432"></span>
<span class="r-in"></span>
<span class="r-in"><span class="co"># \donttest{</span></span>
<span class="r-in"><span class="co"># TS extraction from polygons using a different aggregation function</span></span>
<span class="r-in"><span class="va">ts_raw_2</span> <span class="op">&lt;-</span> <span class="fu">extract_s2ts</span><span class="op">(</span><span class="va">sen2r_ndvi_paths</span>, <span class="va">sampleroi</span>, fun <span class="op">=</span> <span class="st">"max"</span><span class="op">)</span></span>
<span class="r-in"></span>
<span class="r-in"><span class="co"># TS extraction from points</span></span>
<span class="r-in"><span class="va">samplepts</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/warning.html" class="external-link">suppressWarnings</a></span><span class="op">(</span><span class="fu">sf</span><span class="fu">::</span><span class="fu"><a href="https://r-spatial.github.io/sf/reference/geos_unary.html" class="external-link">st_centroid</a></span><span class="op">(</span><span class="va">sampleroi</span><span class="op">)</span><span class="op">)</span></span>
<span class="r-in"><span class="va">ts_raw_3</span> <span class="op">&lt;-</span> <span class="fu">extract_s2ts</span><span class="op">(</span><span class="va">sen2r_ndvi_paths</span>, <span class="va">samplepts</span><span class="op">)</span></span>
<span class="r-in"><span class="co"># }</span></span>
</code></pre></div>
    </div>
  </div>
  <div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
    <nav id="toc" data-toggle="toc" class="sticky-top"><h2 data-toc-skip>Contents</h2>
    </nav></div>
</div>


      <footer><div class="copyright">
  <p></p><p>Developed by Luigi Ranghetti.</p>
</div>

<div class="pkgdown">
  <p></p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a>
2.0.2.</p>
</div>

      </footer></div>

  


  

  </body></html>

