You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## change
- functions in individual files
- rewrite functions with snake case
- fix error when computing n_struct with transmittance only
- updated documentation according to v2
Copy file name to clipboardExpand all lines: vignettes/prospect.Rmd
+87-33Lines changed: 87 additions & 33 deletions
Original file line number
Diff line number
Diff line change
@@ -31,19 +31,45 @@ knitr::opts_chunk$set(
31
31
32
32
# Brief introduction & useful links to go further
33
33
34
-
This tutorial summarizes the different functionalities of the R package `prospect` based on the eponym leaf physical model.
34
+
This tutorial summarizes the different functionalities of the R package
35
+
`prospect` based on the eponym leaf physical model.
35
36
36
-
This tutorial does not aim at detailling the principles of PROSPECT or comparing it to other models, as:
37
+
This tutorial does not aim at detailing the principles of PROSPECT or comparing
38
+
it to other models, as:
37
39
38
-
* The comprehensive description of the model and the physical principes it relies on can be found in the original paper from [Jacquemoud & Baret (1990)](https://www.sciencedirect.com/science/article/abs/pii/003442579090100Z"Jacquemoud & Baret, RSE 1990")
39
-
*[this website](http://photobiology.info/Jacq_Ustin.html) and [this one](http://teledetection.ipgp.jussieu.fr/opticleaf/models.htm) provide a lot of information on this topic
40
-
*[this website](http://opticleaf.ipgp.fr/) gathers references and important links for anyone interested in leaf optical properties and physical modeling
40
+
* The comprehensive description of the model and the physical principles it
41
+
relies on can be found in the original paper from [Jacquemoud & Baret (1990)](https://www.sciencedirect.com/science/article/abs/pii/003442579090100Z"Jacquemoud & Baret, RSE 1990")
42
+
*[this website](http://photobiology.info/Jacq_Ustin.html) and
43
+
[this one](http://teledetection.ipgp.jussieu.fr/opticleaf/models.htm) provide a
44
+
lot of information on this topic
45
+
*[this website](http://opticleaf.ipgp.fr/) gathers references and important
46
+
links for anyone interested in leaf optical properties and physical modeling.
41
47
42
-
PROSPECT aims at simulating leaf optical properties in the optical domain from 400 nm to 2500 nm based on their biophysical properties, including a limited number of biochemical constituents and a unique structure parameter, `N`. PROSPECT is based on a simple representation derived from the __extended plate model__ ([Allen et al., 1970](https://www.osapublishing.org/josa/abstract.cfm?uri=josa-60-4-542)).
48
+
PROSPECT aims at simulating leaf optical properties in the optical domain from
49
+
400 nm to 2500 nm based on their biophysical properties, including a limited
50
+
number of biochemical constituents and a unique structure parameter `N`.
43
51
44
-
Leaf optical properties correspond to __conical-hemispherical reflectance and transmittance__, and are typically measured with an integrating sphere. These optical properties are often described as __directional-hemispherical reflectance and transmittance__, although such directional quantities are conceptual quantities (see [Schaepman-Strub et al. (2006)](https://www.sciencedirect.com/science/article/abs/pii/S0034425706001167?via%3Dihub"Schaepman-Strub, RSE 2006") for a comprehensive definition of optical measurements).
45
52
46
-
Leaf reflectance measured with a leaf clip / contact probe (such as the device provided with the ASD FieldSpec spectroradiometer) does not correspond to __conical-hemispherical reflectance__. Therefore comparing such reflectance with PROSPECT simulations (in forward and inverse mode) may lead to biased or uncertain results. See [Li et al. (2018)](https://www.sciencedirect.com/science/article/abs/pii/S0034425717305898?via%3Dihub"Li, RSE 2018") for alternative approaches taking advantage ofphysical modeling for the estimation of leaf chemistry from such reflectance measurements.
53
+
__To avoid confusion between `N`and Nitrogen content (made by multiple users), `N` has been renamed `n_struct` starting from v2.0.__
54
+
55
+
PROSPECT is based on a simple representation derived from the __extended plate model__
56
+
([Allen et al., 1970](https://www.osapublishing.org/josa/abstract.cfm?uri=josa-60-4-542)).
57
+
58
+
Leaf optical properties correspond to __conical-hemispherical reflectance and transmittance__,
59
+
and are typically measured with an integrating sphere.
60
+
These optical properties are often described as __directional-hemispherical reflectance and transmittance__,
61
+
although such directional quantities are conceptual quantities (see
62
+
[Schaepman-Strub et al. (2006)](https://www.sciencedirect.com/science/article/abs/pii/S0034425706001167?via%3Dihub"Schaepman-Strub, RSE 2006")
63
+
for a comprehensive definition of optical measurements).
64
+
65
+
Leaf reflectance measured with a leaf clip / contact probe (such as the device
66
+
provided with the ASD FieldSpec spectroradiometer) does not correspond to
67
+
__conical-hemispherical reflectance__. Therefore comparing such reflectance with
68
+
PROSPECT simulations (in forward and inverse mode) may lead to biased or
69
+
uncertain results.
70
+
See [Li et al. (2018)](https://www.sciencedirect.com/science/article/abs/pii/S0034425717305898?via%3Dihub"Li, RSE 2018")
71
+
for alternative approaches taking advantage of physical modeling for the
72
+
estimation of leaf chemistry from such reflectance measurements.
47
73
48
74
49
75
<p> </p>
@@ -52,47 +78,70 @@ Leaf reflectance measured with a leaf clip / contact probe (such as the device p
52
78
</center>
53
79
<p> </p>
54
80
<center>
55
-
Fig. 1. Representation of a leaf according to PROSPECT and corresponding leaf optical properties obtained as output
81
+
Fig. 1. Representation of a leaf according to PROSPECT and corresponding leaf
82
+
optical properties obtained as output
56
83
</center>
57
84
<p> </p>
58
85
59
-
Note that the `alpha` parameter is also available as input, and corresponds to the maximum incidence angle relative to the normal defining the solid angle of incident light at the surface of leaf (aims at including surface roughness, default value = 40 degrees).
86
+
Note that the `alpha` parameter is also available as input, and corresponds to
87
+
the maximum incidence angle relative to the normal defining the solid angle of
88
+
incident light at the surface of leaf (aims at including surface roughness,
89
+
default value = 40 degrees).
60
90
61
-
Many simplications can be identified, and alternative versions of the model have been developed through the years in order to increase the realism of the model. Among the many simplifications:
91
+
Many simplications can be identified, and alternative versions of the model have
92
+
been developed through the years in order to increase the realism of the model.
93
+
Among the many simplifications:
62
94
63
-
* The refractive index identifcal for all leaves. It should theoretically change with leaf properties
95
+
* The refractive index identical for all leaves.
96
+
It should theoretically change with leaf properties.
64
97
65
-
* The leaf anatomy is not differentiated between an adaxial and an abaxial face
98
+
* The leaf anatomy is not differentiated between an adaxial and an abaxial face.
66
99
67
-
* the leaf surface, which is defined my many properties in real life (presence of waxes, hairs, ...) is identical among leaves in PROSPECT
100
+
* the leaf surface, which is defined my many properties in real life (presence
101
+
of waxes, hairs, ...) is identical among leaves in PROSPECT.
68
102
69
103
* ...
70
104
71
-
The current version of the model implemented in `prospect` is __PROSPECT-PRO__, which includes the following biochemical constituents (defined as _C<sub>i</sub>_ in Fig. 1):
105
+
Two versions of the model are currently implemented in `prospect`:
106
+
__PROSPECT-PRO__ and __PROSPECT-D__.
107
+
108
+
__PROSPECT-D__ accounts for the absorption of the following biochemical
109
+
constituents (defined as _C<sub>i</sub>_ in Fig. 1):
110
+
111
+
* chlorophyll a + b `chl`
112
+
* carotenoids `car`
113
+
* anthocyanins `ant`
114
+
* brown pigments `brown`
115
+
* equivalent water thickness `ewt`
116
+
* leaf mass per area `lma` (also identified as dry matter in the literature)
72
117
73
-
* Chlorophyll a + b `CHL`
74
-
* Carotenoids `CAR`
75
-
* Anthocyanins `ANT`
76
-
* Prown pigments `BROWN`
77
-
* Equivalent water thickness `EWT`
78
-
* proteins `PROT`
79
-
* carbon-based consituents `CBC` (constituents of dry matter other than proteins)
118
+
__PROSPECT-PRO__ includes the same constituents, except for `lma`, which is
119
+
replaced by proteins (`prot`) and carbon-based constituents (`cbc`).
80
120
81
-
If you want to use __PROSPECT-D__ instead of __PROSPECT-PRO__, please define a value for `LMA` (Leaf mass per area) and set `PROT` and `CBC` to 0, or leave no value (default value = 0)
121
+
If you want to use __PROSPECT-D__ instead of __PROSPECT-PRO__, please define a
122
+
value for `lma` (Leaf mass per area) and set `prot` and `cbc` to 0, or leave no
123
+
value (default value = 0)
82
124
83
125
84
126
85
-
The specific absoprtion coefficients corresponding to these constituents are recorded in the variable `SpecPROSPECT` available when loading the package `prospect`.
127
+
The specific absorption coefficients corresponding to these constituents are
128
+
recorded in the variable `spec_prospect` available when loading the package
129
+
`prospect`.
86
130
87
131
# `prospect`: forward and inverse mode
88
132
89
-
In the forward mode, PROSPECT simulates leaf optical propertes based on a set of input parameters corresponding to the biochemical constituents and the N structure parameter.
133
+
In the forward mode, PROSPECT simulates leaf optical properties based on a set
134
+
of input parameters corresponding to the biochemical constituents and `n_struct`.
90
135
91
-
The performances of PROSPECT for the simulation of the leaf optical properties are based on the proper calibration of the optical constants, more particularly the specific absorption coefficients corresponding to each biochemical constituent.
136
+
The performances of PROSPECT for the simulation of the leaf optical properties
137
+
are based on the proper calibration of the optical constants, more particularly
138
+
the specific absorption coefficients corresponding to each biochemical constituent.
92
139
93
-
In the inverse mode, an algorithm is used to derive the input parameters from the leaf optical properties.
140
+
In the inverse mode, an algorithm is used to derive the input parameters from
141
+
the leaf optical properties.
94
142
95
-
See the following pages of the tutorial for an illustration of how to use `prospect` in forward and inverse mode.
143
+
See the following pages of the tutorial for an illustration of how to use
144
+
`prospect` in forward and inverse mode.
96
145
97
146
<p> </p>
98
147
<center>
@@ -109,10 +158,15 @@ See the following pages of the tutorial for an illustration of how to use `prosp
109
158
110
159
## Fluorescence & extended infrared domain
111
160
112
-
The package currently only includes a version of the model covering the domain from 400 nm to 2500 nm. However, several valuable alternative versions exist, but are not available in the current version of the package:
161
+
The package currently only includes a version of the model covering the domain
162
+
from 400 nm to 2500 nm. However, several valuable alternative versions exist,
163
+
but are not available in the current version of the package:
113
164
114
-
-[PROSPECT-VISIR](https://www.sciencedirect.com/science/article/abs/pii/S0034425710002841?via%3Dihub), modeling directional–hemispherical reflectance and transmittance of fresh and dry leaves from 0.4 μm to 5.7 μm.
115
-
-[FLUSPECT](https://www.sciencedirect.com/science/article/abs/pii/S0034425718301573?via%3Dihub), radiative transfer model for leaf chlorophyll fluorescence.
By default, the merit function used for the inversion named [merit_prospect_rmse](https://jbferet.gitlab.io/prospect/reference/merit_prospect_rmse.html)
36
37
minimizes the RMSE between the simulated and the measured leaf optical properties.
@@ -103,6 +104,21 @@ not found in juvenile, mature or early senescent leaves.
103
104
*`estimate_alpha` boolean. Should `alpha` be assessed or not? Keep in mind that most
104
105
published results use `alpha` with its default value.
105
106
107
+
In order to reduce the number of input parameters for `invert_prospect` and
108
+
other functions, an input variable `options` has been implemented.
109
+
`options` is list combining several variables that advanced users may need to
110
+
adjust.
111
+
This variable is created as follows, and elements of the list can then be
112
+
modified.
113
+
Examples will follow, illustrating how to proceed to use it.
# PROSPECT-D inversion: using optimal spectral domains
230
-
The function `invert_prospect_OPT` automatically sets the optimal spectral domains during inversion for all constituents to be assessed.
246
+
The function `invert_prospect_OPT` automatically sets the optimal spectral
247
+
domains during inversion for all constituents to be assessed.
231
248
232
-
Optimal spectral domains and configuration are defined in [Féret et al. (2019)](https://doi.org/10.1016/j.rse.2018.11.002), [Féret et al. (2021)](https://doi.org/10.1016/j.rse.2020.112173), and [Spafford et al. (2021)](https://doi.org/10.1016/j.rse.2020.112176).
249
+
Optimal spectral domains and configuration are defined in
250
+
[Féret et al. (2019)](https://doi.org/10.1016/j.rse.2018.11.002),
251
+
[Féret et al. (2021)](https://doi.org/10.1016/j.rse.2020.112173), and
252
+
[Spafford et al. (2021)](https://doi.org/10.1016/j.rse.2020.112176).
233
253
234
-
`n_struct` does not need to be part of `parms_to_estimate`, as it is automatically assessed when needed.
254
+
`n_struct` does not need to be part of `parms_to_estimate`, as it is
Such definition of optimal spectral domains can also be set manually.
251
-
For example, here is how to estimate protein content from leaf optical properties using the optimal spectral domain defined in [Féret et al. (2021)](https://doi.org/10.1016/j.rse.2020.112173).
272
+
For example, here is how to estimate protein content from leaf optical
273
+
properties using the optimal spectral domain defined in
274
+
[Féret et al. (2021)](https://doi.org/10.1016/j.rse.2020.112173).
252
275
253
-
Please note that `n_struct` needs to be added to `parms_to_estimate`, if user want it to be assessed during the inversion, otherwise it will be set to its default value.
276
+
Please note that `n_struct` needs to be added to `parms_to_estimate`, if user
277
+
want it to be assessed during the inversion, otherwise it will be set to its
0 commit comments