Source code for pycif.plugins.datastreams.fields.bc_plugin_template.fetch

import os

import numpy as np
import pandas as pd
import datetime
from .....utils import path




def fetch(
    ref_dir, ref_file, input_interval, target_dir, tracer=None, component=None
):
    """Template showing how to retrieve BC files and build the date/file maps.

    Illustrates how a real ``fetch`` implementation should locate the
    original data files matching ``input_interval``, link them into
    ``target_dir``, and build the ``list_dates``/``list_files`` dictionaries
    consumed by ``read``. The body below is placeholder ``print(...)``
    statements only; it returns empty structures and must be replaced with
    real logic in any plugin derived from this template.

    Choosing the keys for both dictionaries: the most efficient options are
    either (i) the dates at which the data files begin, or (ii) dates
    matching the typical use of this data. Example: if the data is
    typically used for generating BCs per day, use the dates of the days to
    simulate as keys. The idea is to avoid listing the same file under
    several keys, since ``read`` is called once per key.

    Examples for a simulation from 01-01-2001 00H00 to 01-02-2001 00H00 for
    which input BC files cover 24 hours at an hourly resolution:

    - data = annual data for 2001::

          list_dates = { '01-01-2001': [[01-01-2001 00H00, 31-12-2001 23H59]] }
          list_files = { '01-01-2001': [[yearly_data_file]] }

    - data = hourly data in daily files::

          list_dates = { '01-01-2001 00H00': [[01-01-2001 00H00, 01-01-2001 01H00],
                                                [01-01-2001 01H00, 01-01-2001 02H00],
                                                ...
                                                [01-01-2001 23H00, 01-02-2001 00H00]] }
          list_files = { '01-01-2001 00H00': [daily_data_file_for_01/01/2001, ...] }

    Args:
        ref_dir: Directory where the original files are found.
        ref_file: (template) Name of the original files.
        input_interval: List of two dates, the beginning and end of the
            simulation.
        target_dir: Directory where the links to the original files are
            created.
        tracer: Tracer/component configuration; ``tracer.file_freq`` is used
            here (and only here) to list the dates matching file
            availability.
        component: Unused in this template.

    Returns:
        A tuple ``(list_files, list_dates)`` of dictionaries. ``list_dates``
        maps each key to a list of ``[date_beginning, date_end]`` intervals,
        each covered by one value taken from the matching file stored in
        ``list_files``; ``list_files`` maps each key to the list of files
        covering those intervals. The intervals listed in ``list_dates``
        must be the smallest intervals during which the values are
        constant (e.g. if time profiles are applied to yearly data, the
        intervals must be those obtained after applying the profiles, not
        the whole year). Decumulation of fields, if needed, is handled in
        ``read``, not here.
    """

    print('Initialize dictionaries')
    list_files = {}
    list_dates = {}
    print('List dates in the simulation with a frequency matching the files\' availability')
    print('i.e. case i) for generating keys')
    list_period_dates = \
        pd.date_range(input_interval[0], input_interval[1], freq=tracer.file_freq)
    # XXX donner adaptation si file_freq plus grande que  l'ecart entre les deux input_intervalXX
    print('Fill in dictionary for each key')
    for dd in list_period_dates:
        print('Put here the building of the list of intervals for this key')
        # Example: to get an hourly resolution (assuming file_freq >= 1H)
        # list_hours = pd.date_range(
        #            dd, dd + pd.to_timedelta(tracer.file_freq), freq="1H")
        # WARNING: to_timedelta does not work with all frequencies!
        # list_dates[dd] = [[hh, hh + datetime.timedelta(hours=1)]
        #                           for hh in list_hours]

        print('Put here the retrieving of the file names for the intervals')
        # Example: file_freq >= 1H
        # a) retrieve file name for the key:
        # file = dd.strftime("{}/{}".format(ref_dir, ref_file))
        # b) repeat it for the one-hour intervals
        # list_files[dd] = (len(list_hours) * [file])

        print('Fetching as such = link the actual files in target_dir')
        # Example: if one file per key
        # target_file = "{}/{}".format(target_dir, os.path.basename(file))
        # path.link(file, target_file)

    return list_files, list_dates