Add spectral mismatch model comparison table

[RDaxini]

• Partially addresses Model comparison tables #2329
• I am familiar with the contributing guidelines
• Tests added
• Updates entries in docs/sphinx/source/reference for API changes.
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

Build: https://pvlib-python--2353.org.readthedocs.build/en/2353/user_guide/spectrum.html

[RDaxini]

Questions:
Should the inputs be linked to the pvlib functions that can calculate these inputs? I think it would be convenient for readers, but I also think it would a) clutter the table with long links, and b) in the case of multiple options, introduce bias if we were to select one. Overall, I lean away from linking inside the table. Thoughts? Alternatives? Maybe a list of links at the bottom, or at least a sentence or two informing users of pvlib's general capability to calculate inputs

How many cell technologies is too many to list? I think after 2 or 3, it might be best just to write "multiple"?

[cwhanse]

I don't think links to the input definitions add much value. It would be easier to read the list of inputs if the list had one input on each line, rather than a comma-separate text paragraph.

It doesn't seem very helpful when most "Cell technology" fields have a value of "Multiple". I'd use the vertical real estate to list all the cell technologies, except for 'sapm' and 'mismatch_field' which aren't specific to a cell type. The SAPM model is specific to a module product, not to a cell type.

I think "Data source" doesn't add much here. The primary use is for a modeler looking to select a model. Data used for development and validation can be relegated to the references.

[kandersolar]

@RDaxini it looks like you're thinking to create a single page to house all comparison tables, is that right?

In #2329 I was imagining these tables would live in pages dedicated to the relevant modeling topic. For example, the table in this PR would be one component of a broader page explaining pvlib's functionality related to spectrum and spectral mismatch. Similarly, the transposition model table would be in a page talking about the irradiance models. I still think that's a good approach, although of course I am interested in hearing opposing viewpoints.

[RDaxini]

@kandersolar you're too fast again, haha. I went for single page originally because we did not have subsections at that time, but I think 0be2e46 just before your comment should have fixed this in line with your suggestion. We now have one main subsection called model comparisons, and then there will be individual subsubsections explaining the functionality and comparing models. Have a look, let me know if that's what you had in mind. Or did you mean a whole subsection for "spectrum", another for "irradiance", rather than a subsection called "model comparison" (can be renamed) with subsections for those topics (spectrum, irradiance, etc.)?

[kandersolar]

Ok I see, nice. I suggest merging the Model comparisons section with the existing Modeling topics section. Also this new page's filename should be renamed to something involving "spectrum".

[RDaxini]

@kandersolar, how about 7e79344?
I left it as just "spectrum" to keep it general for now as we could potentially add more content to that page. Spectral corrections could be a single subsection on the "spectrum" page. I can fix up these details later too, I don't have any strong preference currently.

Aside, related: the user guide folder could benefit with some organization of the files, what do you think? I was considering opening a separate issue to seek opinions on categorizing those files into folders, perhaps folders aligned with the subsections perhaps... not urgent/major but the thought came to mind while working on this

[kandersolar]

I am +1 to where it's going now.

opening a separate issue to seek opinions on categorizing those files into folders, perhaps folders aligned with the subsections

+1 to this as well

[RDaxini]

Converted from draft. I think we're ready for a full review now.

[kandersolar]

I like it. What do you think about reworking the structure to look like this?

Source code:

.. currentmodule:: pvlib.spectrum

+-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
| Model                                               | Inputs                      | Generic coefficient values available?               | Reference |
+                                                     +                             +---------+---------+------+------+------+------------+           +
|                                                     |                             | mono-Si | poly-Si | CdTe | CIGS | a-Si | perovskite |           |
+=====================================================+=============================+=========+=========+======+======+======+============+===========+
| :py:func:`Caballero <spectral_factor_caballero>`    | :term:`airmass_absolute`,   | yes     | yes     | yes  | yes  | yes  | yes        | [2]_      |
|                                                     | :term:`precipitable_water`, |         |         |      |      |      |            |           |
|                                                     | :term:`aod`                 |         |         |      |      |      |            |           |
+-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
| :py:func:`First Solar <spectral_factor_firstsolar>` | :term:`airmass_absolute`,   |         | yes     | yes  |      |      |            | [3]_      |
|                                                     | :term:`precipitable_water`  |         |         |      |      |      |            |           |
+-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
| :py:func:`JRC <spectral_factor_jrc>`                | :term:`airmass_relative`,   |         | yes     | yes  |      |      |            | [6]_      |
|                                                     | :term:`clearsky_index`      |         |         |      |      |      |            |           |
+-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
| :py:func:`PVSPEC <spectral_factor_pvspec>`          | :term:`airmass_absolute`,   | yes     | yes     | yes  | yes  | yes  |            | [5]_      |
|                                                     | :term:`clearsky_index`      |         |         |      |      |      |            |           |
+-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+
| :py:func:`SAPM <spectral_factor_sapm>`              | :term:`airmass_absolute`    |         |         |      |      |      |            | [4]_      |
+-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+

[adriesse]

Can we work in a shout-out to: https://datahub.duramat.org/dataset/module-sr-library?

Also wondering about chronological ordering of the models so new ones will get added at the end.

[echedey-ls]

In addition to @kandersolar suggestion I want to suggest:

1. Instead of yes, use "x", unicode ticks ✓ or emojis (I prefer unicode ticks for this)
2. Reorder the types columns, so we have all Si types near the same place (start as it is the most common?)
3. Add a nested column index the same way Generic coefficient values available? has the types, but for the inputs. It would be easier to find a model for a given set of inputs.
4. Can we shorten Generic coefficient values available? / Generic parameters available? to something along Default parameters for tech / Default tech parameters / Default values for? Just thinking out loud, I'm okay as it currently is.

Also wondering about chronological ordering of the models so new ones will get added at the end.

5. Instead of chrono order, I prefer to group them by the common inputs/default tech params. Kind of this recommendatio for statistics, but for the table. Make it easy to read.

If you want to change the widths of each column, you may need to use the .. table directive:

• pvlib-python/docs/examples/floating-pv/plot_floating_pv_cell_temperature.py

  Line 56 in 2ca40aa

  .. table:: Heat transfer coefficients for different PV systems

• https://docutils.sourceforge.io/docs/ref/rst/directives.html#table (for other rST attributes)

Point 4. makes this table too wide:

Details

+-----------------------------------------------------+---------------------------------------------------------------------------------+-----------------------------------------------------+------------------+
|                                                     |                                      Inputs                                     |             Default parameters for tech             |                  |
|                        Model                        +------------------+------------------+--------------------+----------------+-----+------+---------+---------+------+------+------------+ Reference & year |
|                                                     | airmass_relative | airmass_absolute | precipitable_water | clearsky_index | aod | a-Si | mono-Si | poly-Si | CdTe | CIGS | perovskite |                  |
+=====================================================+==================+==================+====================+================+=====+======+=========+=========+======+======+============+==================+
| :py:func:`Caballero <spectral_factor_caballero>`    |                  |         ✓        |          ✓         |                |  ✓  |   ✓  |    ✓    |    ✓    |   ✓  |   ✓  |      ✓     | [2]_, 2018       |
+-----------------------------------------------------+------------------+------------------+--------------------+----------------+-----+------+---------+---------+------+------+------------+------------------+
| :py:func:`First Solar <spectral_factor_firstsolar>` |                  |         ✓        |          ✓         |                |     |      |         |    ✓    |   ✓  |      |            | [3]_, 2016       |
+-----------------------------------------------------+------------------+------------------+--------------------+----------------+-----+------+---------+---------+------+------+------------+------------------+
| :py:func:`JRC <spectral_factor_jrc>`                |         ✓        |                  |                    |        ✓       |     |      |         |    ✓    |   ✓  |      |            | [6]_, 2008       |
+-----------------------------------------------------+------------------+------------------+--------------------+----------------+-----+------+---------+---------+------+------+------------+------------------+
| :py:func:`PVSPEC <spectral_factor_pvspec>`          |                  |         ✓        |                    |        ✓       |     |   ✓  |    ✓    |    ✓    |   ✓  |      |            | [5]_, 2020       |
+-----------------------------------------------------+------------------+------------------+--------------------+----------------+-----+------+---------+---------+------+------+------------+------------------+
| :py:func:`SAPM <spectral_factor_sapm>`              |                  |         ✓        |                    |                |     |      |         |    ✓    |   ✓  |      |            | [4]_, 2004       |
+-----------------------------------------------------+------------------+------------------+--------------------+----------------+-----+------+---------+---------+------+------+------------+------------------+

An idea to make it work would be to transpose it:

Details

.. currentmodule:: pvlib.spectrum

+--------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                       Model                      | :py:func:`Caballero <spectral_factor_caballero>` | :py:func:`First Solar <spectral_factor_firstsolar>` | :py:func:`JRC <spectral_factor_jrc>` | :py:func:`PVSPEC <spectral_factor_pvspec>` | :py:func:`SAPM <spectral_factor_sapm>` |
+-----------------------------+--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |  airmass_relative  |                                                  |                                                     |                   ✓                  |                                            |                                        |
|                             +--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |  airmass_absolute  |                         ✓                        |                          ✓                          |                                      |                      ✓                     |                    ✓                   |
|                             +--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|            Inputs           | precipitable_water |                         ✓                        |                          ✓                          |                                      |                                            |                                        |
|                             +--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |   clearsky_index   |                                                  |                                                     |                   ✓                  |                      ✓                     |                                        |
|                             +--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |         aod        |                         ✓                        |                                                     |                                      |                                            |                                        |
+-----------------------------+--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |        a-Si        |                         ✓                        |                                                     |                                      |                      ✓                     |                                        |
|                             +--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |       mono-Si      |                         ✓                        |                                                     |                                      |                      ✓                     |                                        |
|                             +--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |       poly-Si      |                         ✓                        |                          ✓                          |                   ✓                  |                      ✓                     |                                        |
| Default parameters for tech +--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |        CdTe        |                         ✓                        |                          ✓                          |                   ✓                  |                      ✓                     |                                        |
|                             +--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |        CIGS        |                         ✓                        |                                                     |                                      |                                            |                                        |
|                             +--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
|                             |     perovskite     |                         ✓                        |                                                     |                                      |                                            |                                        |
+-----------------------------+--------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+
| Reference & year                                 | [2]_, 2018                                       | [3]_, 2016                                          | [6]_, 2008                           | [5]_, 2020                                 | [4]_, 2004                             |
+--------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+--------------------------------------+--------------------------------------------+----------------------------------------+

This table does not have point 5 applied.

Spreadsheet file: pv-dax-spectrum-comparison.ods

Btw, I'm using this generator here: https://www.tablesgenerator.com/text_tables

[kandersolar]

Instead of yes, use "x", unicode ticks ✓ or emojis (I prefer unicode ticks for this)

I used the ticks at first too, but my editor did not display them in monospace font, so it messed up the table alignment. I switched to "yes" out of irritation. I am +1 to the unicode ticks, as long as someone else makes them work ;)

[echedey-ls]

Instead of yes, use "x", unicode ticks ✓ or emojis (I prefer unicode ticks for this)

I used the ticks at first too, but my editor did not display them in monospace font, so it messed up the table alignment. I switched to "yes" out of irritation. I am +1 to the unicode ticks, as long as someone else makes them work ;)

I did have that mismatch too. DejaVu Sans Mono fixes it and looks great. Uniglyph does too, but it's too pixeled for me. I had DejaVu already installed in Windows, IDK if that was past me, some program I had installed or Microsoft getting something right.

[cwhanse]

I mildly prefer the "models in column" format. I think it is more likely to add new models (rows) than to add columns.

"Default parameters" > "Generic parameters" for me.

I also like the link to pvlib terms, as long as each term has its own row so I'm not reading a paragraph of variable names.

[RDaxini]

Thanks all for the reviews. I will get back onto this PR soon.

[RDaxini]

Can we work in a shout-out to: https://datahub.duramat.org/dataset/module-sr-library?

@adriesse, a suggestion: 298caa8. Your thoughts?

(note Ref. was changed to Reference in the next commit)

[adriesse]

Can we work in a shout-out to: https://datahub.duramat.org/dataset/module-sr-library?

@adriesse, a suggestion: 298caa8. Your thoughts?

Having reread the whole page now, I think it would benefit from an introduction that clearly separates functions/models that actually use spectrally-resolved data vs. those that don't. Then I think the reference will also fall into place more naturally.