Input parameter naming convention - time vs times

[AdamRJensen]

Several pvlib functions take an index as one of the input parameters, however, it is inconsistent whether this parameter is called times or time.

I think we should document the preferred naming, add it to the symbols and variables list, and make an effort to standardize.

See a few examples below of TIME:

pvlib-python/pvlib/solarposition.py

Line 30 in 4cfda4a

def get_solarposition(time, latitude, longitude,

pvlib-python/pvlib/solarposition.py

Line 128 in 4cfda4a

def spa_c(time, latitude, longitude, pressure=101325, altitude=0,

pvlib-python/pvlib/tools.py

Line 120 in 4cfda4a

def localize_to_utc(time, location):

Here's a few examples of TIMES:

pvlib-python/pvlib/tools.py

Line 424 in 4cfda4a

def _get_sample_intervals(times, win_length):

pvlib-python/pvlib/solarposition.py

Line 392 in 4cfda4a

def sun_rise_set_transit_spa(times, latitude, longitude, how='numpy',

pvlib-python/pvlib/solarposition.py

Line 1343 in 4cfda4a

def hour_angle(times, longitude, equation_of_time):

[RDaxini]

Related: #1253
In particular this comment (btw I have updated the table with time/times now thanks to this issue)

[adriesse]

I vote for time.

[AdamRJensen]

I personally prefer times 😋

[kandersolar]

A good guiding principle may be to use plural words only when multiple values are necessary. For example, I think times is an appropriate name for the _get_sample_intervals(times, win_length) function, since it actually requires multiple timestamps. For other functions (e.g. hour_angle) that work fine with single timestamps, would we say that the function returns hour_angles, and do the rise/set functions return sunrises and sunsets? Here I think singular makes sense.

An argument against time in general is that it has the same name as a python standard library.

[cwhanse]

An argument against time in general is that it has the same name as a python standard library.

Good point. I overlooked this when agreeing with "time" with the singular/plural grammar in mind. I retract my vote; pvlib should not shadow any standard python names.

[adriesse]

An argument against time in general is that it has the same name as a python standard library.

Good point. I overlooked this when agreeing with "time" with the singular/plural grammar in mind. I retract my vote; pvlib should not shadow any standard python names.

As the shadowing only occurs within the function, this doesn't seem so serious. It will not cause any problems for the user of the function.

[cwhanse]

As the shadowing only occurs within the function, this doesn't seem so serious. It will not cause any problems for the user of the function.

Yes, but we can't anticipate how a user structures their code.

[echedey-ls]

As the shadowing only occurs within the function, this doesn't seem so serious. It will not cause any problems for the user of the function.

Yes, but we can't anticipate how a user structures their code.

I don't see an issue and fully agree with @adriesse on that it is not a problem. Can you provide an example of what you have in mind? AFAIK, this parameter will only override time identifier inside its namespace, the pvlib func.

[cwhanse]

I can't provide an example where code fails to run. And we've had time as a function parameter for years, so I yield my objection.

[echedey-ls]

No problem.

[echedey-ls]

I was about to edit this function:

pvlib-python/pvlib/solarposition.py

Line 392 in 4cfda4a

def sun_rise_set_transit_spa(times, latitude, longitude, how='numpy',

in #2237 to add another example and test that all works flawlessly, but reading through its documentation I think the appropriate rename is date instead of times. From the docs (and code) of the internal function it uses:

pvlib-python/pvlib/spa.py

Line 1106 in 29b1f86

def transit_sunrise_sunset(dates, lat, lon, delta_t, numthreads):

These "times" must be at 00:00. Funny, isn't it?

Feel free to weight in if there are other words to be considered that I've missed.

[adriesse]

No opinion here for pvlib, but in my own work I standardized on time for many dates ago. I see date simply as low-resolution time, with the time-of-day unspecified.

[echedey-ls]

I see date simply as low-resolution time, with the time-of-day unspecified.

That did convince me.

[echedey-ls]

Shall transit_sunrise_sunset:

pvlib-python/pvlib/spa.py

Line 1106 in cbe4cc5

def transit_sunrise_sunset(dates, lat, lon, delta_t, numthreads):

be changed to time too? It requires the time part to be exactly at 00:00.