def list_templates():
'''List the model templates in the Apollo database.
Untrained models can be constructed from these template names using
:func:`apollo.models.make_model`.
Returns:
list of str:
The named templates.
'''
base = apollo.path('templates')
base.mkdir(parents=True, exist_ok=True)
template_paths = base.glob('*.json')
template_stems = [p.stem for p in template_paths]
return template_stems
def list_models():
'''List trained models in the Apollo database.
Trained models can be constructed from these names using
:func:`apollo.models.load_named_model`.
Returns:
list of str:
The trained models.
'''
base = apollo.path('models')
base.mkdir(parents=True, exist_ok=True)
model_paths = base.glob('*.model')
model_stems = [p.stem for p in model_paths]
return model_stems
def load_named_model(name):
'''Load a model from the Apollo database.
Models in the Apollo database can be listed with :func:`list_models`
or from the command line with ``apollo ls models``.
Arguments:
name (str):
The name of the model.
Returns:
apollo.models.Model:
The model.
'''
path = apollo.path(f'models/{name}.model')
return load(path)
def nc_path(reftime):
'''The path to a netCDF for the given reference time.
NetCDF files are generated after forecasts are processed from the raw
GRIB data. This file does not necessarily exist.
Arguments:
reftime (timestamp):
The reference time.
Returns:
pathlib.Path:
The local path to a netCDF file, which may not exist.
'''
reftime = reftime = apollo.Timestamp(reftime).floor('6h')
prefix = f'nam.{reftime.year:04d}{reftime.month:02d}{reftime.day:02d}'
filename = f'nam.t{reftime.hour:02d}z.awphys.tm00.nc'
return apollo.path(f'NAM-NMM/{prefix}/{filename}')
def from_named_template(template_name, **kwargs):
'''Load a model from named template in the Apollo database.
Templates in the Apollo database can be listed with :func:`list_templates`
or from the command line with ``apollo ls templates``.
Arguments:
template_name (str):
The name of a template in the Apollo database.
**kwargs:
Additional keyword arguments to pass to the model constructor.
Returns:
apollo.models.Model:
An untrained model.
'''
template = apollo.path(f'templates/{template_name}.json')
return from_template(template)
def raw_connect():
'''Get a connection to the SQLite database.
This is a lower-level function to create a SQLite connection object. It is
your responsibility to commit or roll back your transactions and to close
the connection when you are done.
To accomplish these tasks automatically with a context manager, use the
higher-level :func:`connect` function.
The database is located at ``$APOLLO_DATA/GA-POWER/solar_farm.sqlite``.
Returns:
sqlite3.Connection:
The database connection.
'''
path = apollo.path('GA-POWER/solar_farm.sqlite')
return sqlite3.connect(str(path))
def iter_available_forecasts():
'''Iterate over the reftimes of available forecasts.
Yields:
pandas.Timestamp:
The forecast's reference time, with UTC timezone.
'''
for day_dir in sorted(apollo.path('NAM-NMM').glob('nam.*')):
name = day_dir.name # Formatted like "nam.20180528".
year = int(name[4:8])
month = int(name[8:10])
day = int(name[10:12])
for path in sorted(day_dir.glob('nam.*')):
name = path.name # Formatted like "nam.t18z.awphys.tm00.nc".
if not name.endswith('.nc'): continue
hour = int(name[5:7])
yield apollo.Timestamp(f'{year:04}-{month:02}-{day:02}T{hour:02}Z')
def grib_path(reftime, forecast):
'''The path to a GRIB for the given reference and forecast times.
GRIB forecasts are downloaded to this path and may be deleted once the
forecast is processed into netCDF. This file does not necessarily exist.
Arguments:
reftime (timestamp):
The reference time.
forecast (int):
The forecast hour.
Returns:
pathlib.Path:
The local path for a GRIB file, which may not exist.
'''
reftime = apollo.Timestamp(reftime).floor('6h')
prefix_fmt = 'nam.{ref.year:04d}{ref.month:02d}{ref.day:02d}'
filename_fmt = 'nam.t{ref.hour:02d}z.awphys{forecast:02d}.tm00.grib'
prefix = prefix_fmt.format(forecast=forecast, ref=reftime)
filename = filename_fmt.format(forecast=forecast, ref=reftime)
return apollo.path(f'NAM-NMM/{prefix}/{filename}')
def save(self, path=None):
'''Persist a model to disk.
Arguments:
path (str or pathlib.Path or None):
The path at which to save the model. The default is a path
within the Apollo database derived from the model's name.
Returns:
pathlib.Path:
The path at which the model was saved.
'''
if path is None:
path = apollo.path(f'models/{self.name}.model')
path.parent.mkdir(parents=True, exist_ok=True)
else:
path = Path(path)
logger.debug(f'save: writing model to {path}')
fd = path.open('wb')
pickle.dump(self, fd, protocol=5)
return path
def load_model(name):
'''Load a model from the Apollo database.
Models in the Apollo database can be listed with :func:`list_models`
or from the command line with ``apollo ls models``.
Arguments:
name (str):
The name of the model.
Returns:
apollo.models.Model:
The model.
Raises:
FileNotFoundError:
No model exists in the database with the given name.
'''
path = apollo.path(f'models/{name}.model')
if not path.exists():
raise FileNotFoundError(f'No such model: {name}')
return load_model_at(path)
def make_model(template_name, **kwargs):
'''Construct a model from named template in the Apollo database.
Templates in the Apollo database can be listed with :func:`list_templates`
or from the command line with ``apollo ls templates``.
Arguments:
template_name (str):
The name of a template in the Apollo database.
**kwargs:
Additional keyword arguments to pass to the model constructor.
Returns:
apollo.models.Model:
An untrained model.
Raises:
FileNotFoundError:
No template exists in the database with the given name.
'''
path = apollo.path(f'templates/{template_name}.json')
if not path.exists():
raise FileNotFoundError(f'No such template: {template_name}')
return make_model_from(path)
