"""
solar - Plot day-night terminators and twilight.
"""
import pandas as pd
from pygmt.clib import Session
from pygmt.exceptions import GMTInvalidInput
from pygmt.helpers import build_arg_string, fmt_docstring, kwargs_to_strings, use_alias
__doctest_skip__ = ["solar"]
@fmt_docstring
@use_alias(
B="frame",
G="fill",
J="projection",
R="region",
V="verbose",
W="pen",
c="panel",
p="perspective",
t="transparency",
)
@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
def solar(self, terminator="d", terminator_datetime=None, **kwargs):
r"""
Plot day-light terminators or twilights.
This function plots the day-night terminator. Alternatively, it can plot
the terminators for civil twilight, nautical twilight, or astronomical
twilight.
Full option list at :gmt-docs:`solar.html`
{aliases}
Parameters
----------
terminator : str
Set the type of terminator displayed. Valid arguments are
``"day_night"``, ``"civil"``, ``"nautical"``, and ``"astronomical"``,
which can be set with either the full name or the first letter of the
name [Default is ``"day_night"``].
Refer to https://en.wikipedia.org/wiki/Twilight for the definitions of
different types of twilight.
terminator_datetime : str or datetime object
Set the UTC date and time of the displayed terminator
[Default is the current UTC date and time]. It can be
passed as a string or Python datetime object.
{region}
{projection}
{frame}
fill : str
Set color or pattern for filling terminators [Default is no fill].
pen : str
Set pen attributes for lines [Default is ``"0.25p,black,solid"``].
{verbose}
{panel}
{perspective}
{transparency}
Example
-------
>>> # import the Python module "datetime"
>>> import datetime
>>> import pygmt
>>> # create a datetime object at 8:52:18 on June 24, 1997 (time in UTC)
>>> date = datetime.datetime(
... year=1997, month=6, day=24, hour=8, minute=52, second=18
... )
>>> # create a new plot with pygmt.Figure()
>>> fig = pygmt.Figure()
>>> # create a map of the Earth with the coast method
>>> fig.coast(
... land="darkgreen", water="lightblue", projection="W10c", region="d"
... )
>>> fig.solar(
... # set the terminator to "day_night"
... terminator="day_night",
... # pass the datetime object
... terminator_datetime=date,
... # fill the night-section with navyblue at 75% transparency
... fill="navyblue@75",
... # draw the terminator with a 1-point black line
... pen="1p,black",
... )
>>> # show the plot
>>> fig.show()
"""
kwargs = self._preprocess(**kwargs) # pylint: disable=protected-access
if kwargs.get("T") is not None:
raise GMTInvalidInput(
"Use 'terminator' and 'terminator_datetime' instead of 'T'."
)
if terminator not in [
"day_night",
"civil",
"nautical",
"astronomical",
"d",
"c",
"n",
"a",
]:
raise GMTInvalidInput(
f"Unrecognized solar terminator type '{terminator}'. Valid values "
"are 'day_night', 'civil', 'nautical', and 'astronomical'."
)
kwargs["T"] = terminator[0]
if terminator_datetime:
try:
datetime_string = pd.to_datetime(terminator_datetime).strftime(
"%Y-%m-%dT%H:%M:%S.%f"
)
except ValueError as verr:
raise GMTInvalidInput("Unrecognized datetime format.") from verr
kwargs["T"] += f"+d{datetime_string}"
with Session() as lib:
lib.call_module(module="solar", args=build_arg_string(kwargs))