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.

[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]

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.

[RDaxini]

Lots of good suggestions here.

I could be convinced otherwise, but atm I'm not 100% on board with ticking off variables. Is there a chance we imply more ticks => better, ie more variables => better? We know that is not necessarily the case since there is variation in importance among individual variables for different PV types, climates, etc., and mixed value in their use in conjunction with one another.
It's similar with ticking off modules since some modules may be more/less important based on age/technology/etc but... I don't think that is as big of an issue though.

So maybe we go with Kevin's formatting suggestion, but with ticks rather than "yes" as suggested by Echedey?

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

+1, adding rows will fit better on the page, so one model per row sounds good.

each term has its own row so I'm not reading a paragraph of variable names.

You mean a new line within each table cell, or a full distinct table row for each variable?

[echedey-ls]

@RDaxini regarding

I could be convinced otherwise, but atm I'm not 100% on board with ticking off variables. Is there a chance we imply more ticks => better, ie more variables => better? We know that is not necessarily the case since there is variation in importance among individual variables for different PV types, climates, etc., and mixed value in their use in conjunction with one another.
It's similar with ticking off modules since some modules may be more/less important based on age/technology/etc but... I don't think that is as big of an issue though.

I now regret small recommendations I wrote in past PRs. I don't think pvlib is the place to put not entirely factual information, cause it can get misunderstood and sometimes misses a bigger picture of the modelling. But feel free to study and publish that in a paper, it may make for a relevant piece of knowledge. Great observation.

On the other hand, if you think how to format is holding back this PR for too long, it may be time to:

• add them all so we can all see each one (and vote)
• go ahead with the one you like the most and let's see if there's something to be improved

Just an opinion update: I strongly believe putting each model input in a column is beneficial, so that libraries like DataTables (also this repo) can let users sort by inputs. My opinion was not so strong in the past.

[RDaxini]

New build: https://pvlib-python--2353.org.readthedocs.build/en/2353/user_guide/modeling_topics/spectrum.html
(note: no idea why but when I open this link, after it has opened, I have to hit refresh for the rendered page to update to the latest version...)

Included three examples based on suggestions from @kandersolar and @echedey-ls (thanks)

[cwhanse]

Mild preferences for the third table version over the first. Either are better than the 2nd. The one disadvantage of the third table is that if pvlib adds a few more spectral models, the table has to expand horizontally.

[RDaxini]

The one disadvantage of the third table is that if pvlib adds a few more spectral models, the table has to expand horizontally.

I lean towards the first table and this is one of main the reasons why. I also think the readability logic makes more sense going from left to right, starting with the model (left) and then introducing info about the model (right), rather than top to bottom.

Re new models, we can expect at least one new model from First Solar soon. Not sure what the current status is but we have been hearing about it for at least a year now. I think it is reasonable to expect new models for bifacial and/or tandems to be published in the future too.

[adriesse]

I prefer the first table and would suggest putting the year and reference in the first column and then sorting by date. Maybe suppress the shading of alternate rows.

The text is not always clear, for example the last sentence. I would suggest a structure like:

1. spectra and spectral responses: functions and data
2. spectral mismatch meaning and calculation
3. spectral factor models (= spectra mismatch estimators?)