Change surface_azimuth convention in get_pvgis_hourly

[AdamRJensen]

• Closes pvlib.iotools.get_pvgis_hourly's surface_azimuth parameter doesn't use pvlib's azimuth convention #1724
• 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.

Nearly everything in pvlib represents azimuth angles as values in [0, 360) clockwise from north, except pvlib.iotools.get_pvgis_hourly. This PR modifies the get_pvgis_hourly function such that it follows the pvlib convention.

[kandersolar]

The supplied azimuth is echoed in the inputs return value... I guess we should translate that one as well? Or maybe just get rid of that return value altogether so that the function can have the same data, metadata return structure as the rest of iotools?

[AdamRJensen]

The supplied azimuth is echoed in the inputs return value... I guess we should translate that one as well? Or maybe just get rid of that return value altogether so that the function can have the same data, metadata return structure as the rest of iotools?

So the second returned element "inputs" actually also contains metadata describing the outputs, so it is useful. I am a strong believer in sticking with the (data, meta) output format and think that the output related content in "inputs" should simply be included in the meta dictionary and the input related content in "inputs" should be discarded. Consistency is key, and I always forget how many items the PVGIS functions return. But changing this would be a breaking change...?

[kandersolar]

Regarding inputs: how about we translate azimuth in this PR and open a new issue for changing the number of return values? Might want to get that into 0.10.0 too.

[AdamRJensen]

Regarding inputs: how about we translate azimuth in this PR and open a new issue for changing the number of return values? Might want to get that into 0.10.0 too.

Translating the azimuth is surprisingly convoluted. First off, it is necessary to update both the description:

metadata['inputs']['mounting_system']['fields']['azimuth']['description'] = \
    'Orientation (azimuth) angle of the (fixed) PV system (0 = N, 90 = E, 180 = S)'

and the value (changing the value requires some wrangling due to the field name changing depending on the type of mounting system):

inputs['mounting_system'][list(inputs['mounting_system'].keys())[0]]['azimuth']['value'] = \
    inputs['mounting_system'][list(inputs['mounting_system'].keys())[0]]['azimuth']['value'] + 180

However, the above line is not sufficient, given that for certain tracking mounting systems the azimuth value is specified as '-'.

Also, the metadata structure is completely different for the json and the csv output formats. In short, translating the azimuth will add significant lines of code to the function, which I don't think is worth it. I'm more inclined to add a warning message stating that the metadata concerning the azimuth is not corrected. @kandersolar what do you think of this?

[kandersolar]

I'm more inclined to add a warning message stating that the metadata concerning the azimuth is not corrected. @kandersolar what do you think of this?

I guess a "warning" does not refer to warnings.warn() but rather text in the docstring? If so, ok with me!

[kandersolar]

LGTM!