Changeset 6f951ca in flex_extract.git for source/python/classes

Timestamp:

Jan 15, 2019, 1:05:10 AM (5 years ago)

Author:

Anne Philipp <anne.philipp@…>

Branches:

master, ctbto, dev

Children:

d4696e0

Parents:

2625ca8

Message:

new style of docstring params and updates in docstrings

Location:

source/python/classes

Files:

• ControlFile.py (modified) (8 diffs)
• EcFlexpart.py (modified) (20 diffs)
• MarsRetrieval.py (modified) (22 diffs)
• UioFiles.py (modified) (10 diffs)

source/python/classes/ControlFile.py

@@ -21 +21 @@
 #
 # @License:
-#    (C) Copyright 2015-2018.
+#    (C) Copyright 2014-2019.
+#    Anne Philipp, Leopold Haimberger
 #
-#    This software is licensed under the terms of the Apache Licence Version 2.0
-#    which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
+#    This work is licensed under the Creative Commons Attribution 4.0
+#    International License. To view a copy of this license, visit
+#    http://creativecommons.org/licenses/by/4.0/ or send a letter to
+#    Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
 #
-# @Class Description:
-#    The CONTROL file is the steering part of the FLEXPART extraction
-#    software. All necessary parameters needed to retrieve the data fields
-#    from the MARS archive for driving FLEXPART are set in a CONTROL file.
-#    Some specific parameters like the start and end dates can be overwritten
-#    by the command line parameters, but in generel all parameters needed
-#    for a complete set of fields for FLEXPART can be set in the CONTROL file.
-#
-# @Class Content:
-#    - __init__
-#    - __read_controlfile__
-#    - __str__
-#    - assign_args_to_control
-#    - assign_envs_to_control
-#    - check_conditions
-#    - check_install_conditions
-#    - to_list
-#
-# @Class Attributes:
-#
-#
+# @Class Methods:
+#    __init__
+#    _read_controlfile
+#    __str__
+#    assign_args_to_control
+#    assign_envs_to_control
+#    check_conditions
+#    check_install_conditions
+#    to_list
 #*******************************************************************************
 
@@ -76 +67 @@
     '''
     Contains the information which are stored in the CONTROL files.
+
+    The CONTROL file is the steering part of the FLEXPART extraction
+    software. All necessary parameters needed to retrieve the data fields
+    from the MARS archive for driving FLEXPART are set in a CONTROL file.
+    Some specific parameters like the start and end dates can be overwritten
+    by the command line parameters, but in generel all parameters needed
+    for a complete set of fields for FLEXPART can be set in the CONTROL file.
+
+    Attributes
+    ----------
+    controlfile : str
+        The name of the control file to be processed. Default value is the
+        filename passed to the init function when initialised.
+
+    start_date : str
+        The first day of the retrieval period. Default value is None.
+
+    end_date :str
+        The last day of the retrieval period. Default value is None.
+
+    date_chunk : int
+        Length of period for a single mars retrieval. Default value is 3.
+
+    dtime :str
+        The time step in hours. Default value is None.
+
+    basetime : str
+        The time for a half day retrieval. The 12 hours upfront are to be
+        retrieved. Default value is None.
+
+    maxstep : int
+        The maximum forecast step for non flux data. Default value is None.
+
+    type : list of str
+        List of field type per retrieving hour. Default value is None.
+
+    time : list of str
+        List of retrieving times in hours. Default valuer is None.
+
+    step : list of str or str
+        List of forecast time steps in hours for non flux data.
+        Default value is None.
+
+    acctype : str
+        The field type for the accumulated forecast fields.
+        Default value is None.
+
+    acctime : str
+        The starting time of the accumulated forecasts. Default value is None.
+
+    accmaxstep : int
+        The maximum forecast step for the accumulated forecast fields
+        (flux data). Default value is None.
+
+    marsclass : str
+        Characterisation of dataset. Default value is None.
+
+    dataset : str
+        For public datasets there is the specific naming and parameter
+        dataset which has to be used to characterize the type of
+        data. Default value is None.
+
+    stream : str
+        Identifies the forecasting system used to generate the data.
+        Default value is None.
+
+    number : str
+        Selects the member in ensemble forecast run. Default value is 'OFF'.
+
+    expver : str
+        The version number of the dataset. Default value is '1'.
+
+    gaussian : str
+        This parameter is deprecated and should no longer be used.
+        Specifies the desired type of Gaussian grid for the output.
+        Default value is an empty string ''.
+
+    grid : str
+        Specifies the output grid which can be either a Gaussian grid
+        or a Latitude/Longitude grid. Default value is None.
+
+    area : str
+        Specifies the desired sub-area of data to be extracted.
+        Default value is None.
+
+    left : str
+        The western most longitude of the area to be extracted.
+        Default value is None.
+
+    lower : str
+        The southern most latitude of the area to be extracted.
+        Default value is None.
+
+    upper : str
+        The northern most latitued of the area to be extracted.
+        Default value is None.
+
+    right : str
+        The eastern most longitude of the area to be extracted.
+        Default value is None.
+
+    level : str
+        Specifies the maximum level. Default value is None.
+
+    levelist : str
+        Specifies the required level list. Default value is None.
+
+    resol : str
+        Specifies the desired triangular truncation of retrieved data,
+        before carrying out any other selected post-processing.
+        Default value is None.
+
+    gauss : int
+        Switch to select gaussian fields (1) or regular lat/lon (0).
+        Default value is 0.
+
+    accuracy : int
+        Specifies the number of bits per value to be used in the
+        generated GRIB coded fields. Default value is 24.
+
+    omega : int
+       Switch to select omega retrieval (1) or not (0). Default value is 0.
+
+    omegadiff : int
+        Switch to decide to calculate Omega and Dps/Dt from continuity
+        equation for diagnostic purposes (1) or not (0). Default value is 0.
+
+    eta : int
+        Switch to select direct retrieval of etadot from MARS (1) or
+        wether it has to be calculated (0). Then Default value is 0.
+
+    etadiff : int
+        Switch to select calculation of etadot and Dps/Dt from continuity
+        equation for diagnostic purposes (1) or not (0). Default value is 0.
+
+    etapar : int
+        GRIB parameter Id for etadot fields. Default value is 77.
+
+    dpdeta : int
+        Switch to select multiplication of etadot with dpdeta.
+        Default value is 1.
+
+    smooth : int
+        Spectral truncation of ETADOT after calculation on Gaussian grid.
+        Default value is 0.
+
+    format : str
+        The format of the GRIB data. Default value is 'GRIB1'.
+
+    addpar : str
+        List of additional surface level ECMWF parameter to be retrieved.
+        Default value is None.
+
+    prefix : str
+        Prefix string for the final FLEXPART/FLEXTRA ready input files.
+        Default value is 'EN'.
+
+    cwc : int
+        Switch to select wether the sum of cloud liquid water content and
+        cloud ice water content should be retrieved. Default value is 0.
+
+    wrf : int
+        Switch to select further parameters for retrievment to support
+        WRF simulations. Default value is 0.
+
+    ecfsdir : str
+        Path to the ECMWF storage  'ectmp:/${USER}/econdemand/'
+
+    mailfail : list of str
+        Email list for sending error log files from ECMWF servers.
+        The email addresses should be seperated by a comma.
+        Default value is ['${USER}'].
+
+    mailops : list of str
+        Email list for sending operational log files from ECMWF servers.
+        The email addresses should be seperated by a comma.
+        Default value is ['${USER}'].
+
+    grib2flexpart : int 0
+        Switch to select generation of preprocessed FLEXPART files ".fp".
+        If it is selected, the program grib2flexpart will try
+        to convert the flex_extract output files into ".fp" format.
+
+    ecstorage : int
+        Switch to select storage of FLEXPART ready output files
+        in the ECFS file system. Default value is 0.
+
+    ectrans : int
+        Switch to select the transfer of FLEXPART ready output files
+        to the gateway server. Default value is 0.
+
+    inputdir : str
+        Path to the temporary directory for the retrieval grib files and
+        other processing files. Default value is _config.PATH_INPUT_DIR.
+
+    outputdir : str
+        Path to the final directory where the final FLEXPART ready input
+        files are stored. Default value is None.
+
+    flexextractdir : str
+        Path to the flex_extract root directory. Default value is
+        _config.PATH_FLEXEXTRACT_DIR.
+
+    exedir : str
+        Path to the FORTRAN executable file. Default value is
+        _config.PATH_FORTRAN_SRC.
+
+    flexpartdir : str
+        Path to a FLEXPART root directory. Default value is None.
+
+    makefile : str
+        Name of the makefile to be used for the Fortran program.
+        Default value is 'Makefile.gfortran'.
+
+    destination : str
+        The remote destination which is used to transfer files
+        from ECMWF server to local gateway server. Default value is None.
+
+    gateway : str
+        The gateway server the user is using. Default value is None.
+
+    ecuid : str
+        The user id on ECMWF server. Default value is None.
+
+    ecgid : str
+        The group id on ECMWF server. Default value is None.
+
+    install_target : str
+        Defines the location where the installation is to be done.
+        Default value is None.
+
+    debug : int
+        Switch to keep temporary files at the end of postprocessing (1) or
+        to delete all temporary files except the final output files (0).
+        Default value is 0.
+
+    request : int
+        Switch to select between just retrieving the data (0), writing the mars
+        parameter values to a csv file (1) or doing both (2).
+        Default value is 0.
+
+    public : int
+        Switch to select kind of ECMWF Web Api access and the
+        possible data sets. Public data sets (1) and Memberstate data sets (0).
+        Default value is 0.
+
+    ecapi : boolean
+        Tells wether the ECMWF Web APi was able to load or not.
+        Default value is None.
+
+    purefc : int
+        Switch to decide wether the job is a pure forecast retrieval or
+        coupled with analysis data. Default value is 0.
+
+    rrint: int
+        Switch to select between old precipitation disaggregation method (0)
+        or the new IA3 disaggegration method (1). Default value is 0.
+
+    logicals : list of str
+        List of the names of logical switches which controls the flow
+        of the program. Default list is ['gauss', 'omega', 'omegadiff', 'eta',
+        'etadiff', 'dpdeta', 'cwc', 'wrf', 'grib2flexpart', 'ecstorage',
+        'ectrans', 'debug', 'request', 'public', 'purefc', 'rrint']
     '''
 
@@ -85 +339 @@
         Parameters
         ----------
-        filename : :obj:`string`
+        filename : str
             Name of CONTROL file.
 
@@ -98 +352 @@
         self.end_date = None
         self.date_chunk = 3
+        self.job_chunk = None
         self.dtime = None
         self.basetime = None
@@ -273 +528 @@
         Parameters
         ----------
-        args : :obj:`Namespace`
+        args : Namespace
             Contains the commandline arguments from script/program call.
 
@@ -298 +553 @@
         Parameters
         ----------
-        envs : :obj:`dictionary` of :obj:`strings`
+        envs : dict of str
             Contains the ECMWF environment parameternames "ECUID", "ECGID",
             "DESTINATION" and "GATEWAY" with its corresponding values.
@@ -320 +575 @@
         Parameters
         ----------
-        queue : :obj:`string`
+        queue : str
             Name of the queue if submitted to the ECMWF servers.
             Used to check if ecuid, ecgid, gateway and destination
@@ -397 +652 @@
         Return
         ------
-        l : :obj:`list`
+        l : list of *
             A sorted list of the all ControlFile class attributes with
             their values except the attributes "_expanded", "exedir",

source/python/classes/EcFlexpart.py

@@ -41 +41 @@
 #
 # @License:
-#    (C) Copyright 2014-2018.
+#    (C) Copyright 2014-2019.
+#    Anne Philipp, Leopold Haimberger
 #
-#    This software is licensed under the terms of the Apache Licence Version 2.0
-#    which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
-#
-# @Class Description:
-#    FLEXPART needs grib files in a specifc format. All necessary data fields
-#    for one time step are stored in a single file. The class represents an
-#    instance with all the parameter and settings necessary for retrieving
-#    MARS data and modifing them so they are fitting FLEXPART need. The class
-#    is able to disaggregate the fluxes and convert grid types to the one needed
-#    by FLEXPART, therefore using the FORTRAN program.
-#
-# @Class Content:
-#    - __init__
-#    - write_namelist
-#    - retrieve
-#    - process_output
-#    - create
-#    - deacc_fluxes
-#
-# @Class Attributes:
-#
-#  TODO
-#
+#    This work is licensed under the Creative Commons Attribution 4.0
+#    International License. To view a copy of this license, visit
+#    http://creativecommons.org/licenses/by/4.0/ or send a letter to
+#    Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
 #*******************************************************************************
 #pylint: disable=unsupported-assignment-operation
@@ -102 +84 @@
 class EcFlexpart(object):
     '''
-    Class to retrieve FLEXPART specific ECMWF data.
+    Class to represent FLEXPART specific ECMWF data.
+
+    FLEXPART needs grib files in a specifc format. All necessary data fields
+    for one time step are stored in a single file. The class represents an
+    instance with all the parameter and settings necessary for retrieving
+    MARS data and modifing them so they are fitting FLEXPART needs. The class
+    is able to disaggregate the fluxes and convert grid types to the one needed
+    by FLEXPART, therefore using the FORTRAN program.
+
+    Attributes
+    ----------
+    mreq_count : int
+        Counter for the number of generated mars requests.
+
+    inputdir : str
+        Path to the directory where the retrieved data is stored.
+
+    dataset : str
+        For public datasets there is the specific naming and parameter
+        dataset which has to be used to characterize the type of
+        data.
+
+    basetime : str
+        The time for a half day retrieval. The 12 hours upfront are to be
+        retrieved.
+
+    dtime : str
+        Time step in hours.
+
+    acctype : str
+        The field type for the accumulated forecast fields.
+
+    acctime : str
+        The starting time from the accumulated forecasts.
+
+    accmaxstep : str
+        The maximum forecast step for the accumulated forecast fields.
+
+    marsclass : str
+        Characterisation of dataset.
+
+    stream : str
+        Identifies the forecasting system used to generate the data.
+
+    number : str
+        Selects the member in ensemble forecast run.
+
+    resol : str
+        Specifies the desired triangular truncation of retrieved data,
+        before carrying out any other selected post-processing.
+
+    accuracy : str
+        Specifies the number of bits per value to be used in the
+        generated GRIB coded fields.
+
+    addpar : str
+        List of additional parameters to be retrieved.
+
+    level : str
+        Specifies the maximum level.
+
+    expver : str
+        The version of the dataset.
+
+    levelist : str
+        Specifies the required levels.
+
+    glevelist : str
+        Specifies the required levels for gaussian grids.
+
+    gaussian : str
+        This parameter is deprecated and should no longer be used.
+        Specifies the desired type of Gaussian grid for the output.
+
+    grid : str
+        Specifies the output grid which can be either a Gaussian grid
+        or a Latitude/Longitude grid.
+
+    area : str
+        Specifies the desired sub-area of data to be extracted.
+
+    purefc : int
+        Switch for definition of pure forecast mode or not.
+
+    outputfilelist : list of str
+        The final list of FLEXPART ready input files.
+
+    types : dictionary
+        Determines the combination of type of fields, time and forecast step
+        to be retrieved.
+
+    params : dictionary
+        Collection of grid types and their corresponding parameters,
+        levels, level types and the grid definition.
+
+    server : ECMWFService or ECMWFDataServer
+        This is the connection to the ECMWF data servers.
+
+    public : int
+        Decides which Web API Server version is used.
+
+    dates : str
+        Contains start and end date of the retrieval in the format
+        "YYYYMMDD/to/YYYYMMDD"
     '''
+
     # --------------------------------------------------------------------------
     # CLASS FUNCTIONS
@@ -113 +199 @@
         Parameters:
         -----------
-        c : :obj:`ControlFile`
+        c : ControlFile
             Contains all the parameters of CONTROL file and
             command line.
 
-        fluxes : :obj:`boolean`, optional
+        fluxes : boolean, optional
             Decides if the flux parameter settings are stored or
             the rest of the parameter list.
@@ -174 +260 @@
         Parameters:
         -----------
-        ftype : :obj:`list` of :obj:`string`
+        ftype : list of str
             List of field types.
 
-        ftime : :obj:`list` of :obj:`string`
+        ftime : list of str
             The time in hours of the field.
 
-        fstep : :obj:`string`
+        fstep : str
             Specifies the forecast time step from forecast base time.
             Valid values are hours (HH) from forecast base time.
@@ -267 +353 @@
         Parameters:
         -----------
-        gauss : :obj:`integer`
+        gauss : int
             Gaussian grid is retrieved.
 
-        eta : :obj:`integer`
+        eta : int
             Etadot parameter will be directly retrieved.
 
-        omega : :obj:`integer`
+        omega : int
             The omega paramterwill be retrieved.
 
-        cwc : :obj:`integer`
+        cwc : int
             The cloud liquid and ice water content will be retrieved.
 
-        wrf : :obj:`integer`
+        wrf : int
             Additional model level and surface level data will be retrieved for
             WRF/FLEXPART-WRF simulations.
@@ -374 +460 @@
         Parameters
         ----------
-        ftype : :obj:`string`
+        ftype : str
             Shortcut name of the type of the field. E.g. AN, FC, PF, ...
 
-        param : :obj:`string`
+        param : str
             Shortcut of the grid type. E.g. SH__ML, SH__SL, GG__ML,
             GG__SL, OG__ML, OG__SL, OG_OROLSM_SL, OG_acc_SL
 
-        date : :obj:`string`
+        date : str
             The date period of the grib data to be stored in this file.
 
         Return
         ------
-        targetname : :obj:`string`
+        targetname : str
             The target filename for the grib data.
         '''
@@ -401 +487 @@
         Parameters
         ----------
-        request : :obj:`integer`
+        request : int
             Selects the mode of retrieval.
             0: Retrieves the data from ECMWF.
@@ -407 +493 @@
             2: Retrieves the data and prints the mars request.
 
-        par_dict : :obj:`dictionary`
+        par_dict : dictionary
             Contains all parameter which have to be set for creating the
             Mars Retrievals. The parameter are:
@@ -463 +549 @@
         Parameters
         ----------
-        keys : :obj:`dictionary`
+        keys : dictionary
             List of parameter names which serves as index.
 
-        inputfiles : :obj:`UioFiles`
+        inputfiles : UioFiles
             Contains a list of files.
 
         Return
         ------
-        iid : :obj:`codes_index`
+        iid : codes_index
             This is a grib specific index structure to access
             messages in a file.
 
-        index_vals : :obj:`list`
+        index_vals : list of list  of str
             Contains the values from the keys used for a distinct selection
             of grib messages in processing  the grib files.
@@ -517 +603 @@
         Parameters
         ----------
-        server : :obj:`ECMWFService` or :obj:`ECMWFDataServer`
+        server : ECMWFService or ECMWFDataServer
             The connection to the ECMWF server. This is different
             for member state users which have full access and non
@@ -525 +611 @@
             for member state users its False (ECMWFService)
 
-        dates : :obj:`string`
+        dates : str
             Contains start and end date of the retrieval in the format
             "YYYYMMDD/to/YYYYMMDD"
 
-        request : :obj:`integer`
+        request : int
             Selects the mode of retrieval.
             0: Retrieves the data from ECMWF.
@@ -535 +621 @@
             2: Retrieves the data and prints the mars request.
 
-        inputdir : :obj:`string`, optional
+        inputdir : str, optional
             Path to the directory where the retrieved data is about
             to be stored. The default is the current directory ('.').
@@ -723 +809 @@
         Parameters
         ----------
-        c : :obj:`ControlFile`
+        c : ControlFile
             Contains all the parameters of CONTROL file and
             command line.
 
-        filename : :obj:`string`
+        filename : str
                 Name of the namelist file.
 
@@ -810 +896 @@
         Parameters
         ----------
-        inputfiles : :obj:`UioFiles`
+        inputfiles : UioFiles
             Contains the list of files that contain flux data.
 
-        c : :obj:`ControlFile`
+        c : ControlFile
             Contains all the parameters of CONTROL file and
             command line.
@@ -837 +923 @@
         # index_vals[0]: ('20171106', '20171107', '20171108') ; date
         # index_vals[1]: ('0', '600', '1200', '1800') ; time
-        # index_vals[2]: ('0', '12', '3', '6', '9') ; stepRange
+        # index_vals[2]: ('0', '3', '6', '9', '12') ; stepRange
 
         if c.rrint:
@@ -1096 +1182 @@
         Parameters
         ----------
-        ni : :obj:`integer`
+        ni : int
             Amount of zonal grid points.
 
-        nj : :obj:`integer`
+        nj : int
             Amount of meridional grid points.
 
-        nt : :obj:`integer`
+        nt : int
             Number of time steps.
 
-        lsp_np : :obj:`numpy array` of :obj:`float`
+        lsp_np : numpy array of float
             The large scale precipitation fields for each time step.
             Shape (ni * nj, nt).
 
-        cp_np : :obj:`numpy array` of :obj:`float`
+        cp_np : numpy array of float
             The convective precipitation fields for each time step.
             Shape (ni * nj, nt).
 
-        date_list : :obj:`list` of :obj:`datetime`
+        date_list : list of datetime
             The list of dates for which the disaggregation is to be done.
 
-        step_list : :obj:`list` of :obj:`integer`
+        step_list : list of int
             The list of steps for a single forecast time.
             Only necessary for pure forecasts.
 
-        c : :obj:`ControlFile`
+        c : ControlFile
             Contains all the parameters of CONTROL file and
             command line.
@@ -1217 +1303 @@
         Parameters
         ----------
-        ifile : :obj:`string`
+        ifile : str
             Filename of the input file to read the grib messages from.
 
-        inputdir : :obj:`string`, optional
+        inputdir : str, optional
             Path to the directory where the retrieved data is stored.
 
@@ -1255 +1341 @@
         Parameters
         ----------
-        inputfiles : :obj:`UioFiles`
+        inputfiles : UioFiles
             Contains a list of files.
 
-        c : :obj:`ControlFile`
+        c : ControlFile
             Contains all the parameters of CONTROL file and
             command line.
@@ -1486 +1572 @@
         Parameters
         ----------
-        c : :obj:`ControlFile`
+        c : ControlFile
             Contains all the parameters of CONTROL file and
             command line.
@@ -1545 +1631 @@
         Parameters
         ----------
-        c : :obj:`ControlFile`
+        c : ControlFile
             Contains all the parameters of CONTROL file and
             command line.

source/python/classes/MarsRetrieval.py

@@ -17 +17 @@
 #        - added documentation
 #        - applied some minor modifications in programming style/structure
+#        - added writing of mars request attributes to a csv file
 #
 # @License:
-#    (C) Copyright 2015-2018.
+#    (C) Copyright 2014-2019.
+#    Anne Philipp, Leopold Haimberger
 #
-#    This software is licensed under the terms of the Apache Licence Version 2.0
-#    which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
-#
-# @Class Description:
-#    A MARS revtrieval has a specific syntax with a selection of keywords and
-#    their corresponding values. This class provides the necessary functions
-#    by displaying the selected parameters and their values and the actual
-#    retrievement of the data through a mars request or a Python web api
-#    interface. The initialization already expects all the keyword values.
-#
-# @Class Content:
-#    - __init__
-#    - display_info
-#    - data_retrieve
-#
-# @Class Attributes:
-#    - server
-#    - marsclass
-#    - dtype
-#    - levtype
-#    - levelist
-#    - repres
-#    - date
-#    - resol
-#    - stream
-#    - area
-#    - time
-#    - step
-#    - expver
-#    - number
-#    - accuracy
-#    - grid
-#    - gaussian
-#    - target
-#    - param
-#
+#    This work is licensed under the Creative Commons Attribution 4.0
+#    International License. To view a copy of this license, visit
+#    http://creativecommons.org/licenses/by/4.0/ or send a letter to
+#    Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
 #*******************************************************************************
 
@@ -73 +43 @@
 # ------------------------------------------------------------------------------
 class MarsRetrieval(object):
-    '''Class for submitting MARS retrievals.
+    '''Specific syntax and content for submission of MARS retrievals.
+
+    A MARS revtrieval has a specific syntax with a selection of keywords and
+    their corresponding values. This class provides the necessary functions
+    by displaying the selected parameters and their values and the actual
+    retrievement of the data through a mars request or a Python web api
+    interface. The initialization already expects all the keyword values.
 
     A description of MARS keywords/arguments and examples of their
@@ -79 +55 @@
     https://software.ecmwf.int/wiki/display/UDOC/\
                    Identification+keywords#Identificationkeywords-class
+
+    Attributes
+    ----------
+    server : ECMWFService or ECMWFDataServer
+        This is the connection to the ECMWF data servers.
+
+    public : int
+        Decides which Web API Server version is used.
+
+    marsclass : str, optional
+        Characterisation of dataset.
+
+    dataset : str, optional
+        For public datasets there is the specific naming and parameter
+        dataset which has to be used to characterize the type of
+        data.
+
+    type : str, optional
+        Determines the type of fields to be retrieved.
+
+    levtype : str, optional
+        Denotes type of level.
+
+    levelist : str, optional
+        Specifies the required levels.
+
+    repres : str, optional
+        Selects the representation of the archived data.
+
+    date : str, optional
+        Specifies the Analysis date, the Forecast base date or
+        Observations date.
+
+    resol : str, optional
+        Specifies the desired triangular truncation of retrieved data,
+        before carrying out any other selected post-processing.
+
+    stream : str, optional
+        Identifies the forecasting system used to generate the data.
+
+    area : str, optional
+        Specifies the desired sub-area of data to be extracted.
+
+    time : str, optional
+        Specifies the time of the data in hours and minutes.
+
+    step : str, optional
+        Specifies the forecast time step from forecast base time.
+
+    expver : str, optional
+        The version of the dataset.
+
+    number : str, optional
+        Selects the member in ensemble forecast run.
+
+    accuracy : str, optional
+        Specifies the number of bits per value to be used in the
+        generated GRIB coded fields.
+
+    grid : str, optional
+        Specifies the output grid which can be either a Gaussian grid
+        or a Latitude/Longitude grid.
+
+    gaussian : str, optional
+        This parameter is deprecated and should no longer be used.
+        Specifies the desired type of Gaussian grid for the output.
+
+    target : str, optional
+        Specifies a file into which data is to be written after
+        retrieval or manipulation.
+
+    param : str, optional
+        Specifies the meteorological parameter.
     '''
 
@@ -96 +145 @@
         Parameters
         ----------
-        server : :obj:`ECMWFService`
+        server : ECMWFService or ECMWFDataServer
             This is the connection to the ECMWF data servers.
             It is needed for the pythonic access of ECMWF data.
 
-        public : :obj:`integer`
+        public : int
             Decides which Web API version is used:
             0: member-state users and full archive access
@@ -107 +156 @@
             Default is "0" and for member-state users.
 
-        marsclass : :obj:`string`, optional
+        marsclass : str, optional
             Characterisation of dataset. E.g. EI (ERA-Interim),
             E4 (ERA40), OD (Operational archive), ea (ERA5).
             Default is the ERA-Interim dataset "ei".
 
-        dataset : :obj:`string`, optional
+        dataset : str, optional
             For public datasets there is the specific naming and parameter
             dataset which has to be used to characterize the type of
@@ -119 +168 @@
             Default is an empty string.
 
-        type : :obj:`string`, optional
+        type : str, optional
             Determines the type of fields to be retrieved.
             Selects between observations, images or fields.
@@ -126 +175 @@
             Default is an empty string.
 
-        levtype : :obj:`string`, optional
+        levtype : str, optional
             Denotes type of level. Has a direct implication on valid
             levelist values!
@@ -134 +183 @@
             Default is an empty string.
 
-        levelist : :obj:`string`, optional
+        levelist : str, optional
             Specifies the required levels. It has to have a valid
             correspondence to the selected levtype.
@@ -140 +189 @@
             Default is an empty string.
 
-        repres : :obj:`string`, optional
+        repres : str, optional
             Selects the representation of the archived data.
             E.g. sh - spherical harmonics, gg - Gaussian grid,
@@ -146 +195 @@
             Default is an empty string.
 
-        date : :obj:`string`, optional
+        date : str, optional
             Specifies the Analysis date, the Forecast base date or
             Observations date. Valid formats are:
@@ -152 +201 @@
             Default is an empty string.
 
-        resol : :obj:`string`, optional
+        resol : str, optional
             Specifies the desired triangular truncation of retrieved data,
             before carrying out any other selected post-processing.
@@ -169 +218 @@
             Default is an empty string.
 
-        stream : :obj:`string`, optional
+        stream : str, optional
             Identifies the forecasting system used to generate the data.
             E.g. oper (Atmospheric model), enfo (Ensemble forecats), ...
             Default is an empty string.
 
-        area : :obj:`string`, optional
+        area : str, optional
             Specifies the desired sub-area of data to be extracted.
             Areas can be defined to wrap around the globe.
@@ -192 +241 @@
             Default is an empty string.
 
-        time : :obj:`string`, optional
+        time : str, optional
             Specifies the time of the data in hours and minutes.
             Valid values depend on the type of data: Analysis time,
@@ -202 +251 @@
             Default is an empty string.
 
-        step : :obj:`string`, optional
+        step : str, optional
             Specifies the forecast time step from forecast base time.
             Valid values are hours (HH) from forecast base time. It also
@@ -210 +259 @@
             Default is an empty string.
 
-        expver : :obj:`string`, optional
+        expver : str, optional
             The version of the dataset. Each experiment is assigned a
             unique code (version). Production data is assigned 1 or 2,
@@ -218 +267 @@
             Default is "1".
 
-        number : :obj:`string`, optional
+        number : str, optional
             Selects the member in ensemble forecast run. (Only then it
             is necessary.) It has a different meaning depending on
@@ -225 +274 @@
             Default is an empty string.
 
-        accuracy : :obj:`string`, optional
+        accuracy : str, optional
             Specifies the number of bits per value to be used in the
             generated GRIB coded fields.
@@ -236 +285 @@
             Default is an empty string.
 
-        grid : :obj:`string`, optional
+        grid : str, optional
             Specifies the output grid which can be either a Gaussian grid
             or a Latitude/Longitude grid. MARS requests specifying
@@ -257 +306 @@
             Default is an empty string.
 
-        gaussian : :obj:`string`, optional
+        gaussian : str, optional
             This parameter is deprecated and should no longer be used.
             Specifies the desired type of Gaussian grid for the output.
@@ -265 +314 @@
             Default is an empty string.
 
-        target : :obj:`string`, optional
+        target : str, optional
             Specifies a file into which data is to be written after
             retrieval or manipulation. Path names should always be
@@ -279 +328 @@
             Default is an empty string.
 
-        param : :obj:`string`, optional
+        param : str, optional
             Specifies the meteorological parameter.
             The list of meteorological parameters in MARS is extensive.
@@ -352 +401 @@
         Parameters
         ----------
-        inputdir : :obj:`string`
+        inputdir : str
             The path where all data from the retrievals are stored.
 
-        request_number : :obj:`integer`
+        request_number : int
             Number of mars requests for flux and non-flux data.
 

source/python/classes/UioFiles.py

@@ -12 +12 @@
 #        - added pattern search in method list_files
 #
-#    February 2018 - Anne Philipp (University of Vienna):
+#    February - December 2018 - Anne Philipp (University of Vienna):
 #        - applied PEP8 style guide
 #        - added documentation
@@ -20 +20 @@
 #        - modified the class so that it is initiated with a pattern instead
 #          of suffixes. Gives more precision in selection of files.
+#        - added delete method
 #
 # @License:
-#    (C) Copyright 2014-2018.
+#    (C) Copyright 2014-2019.
+#    Anne Philipp, Leopold Haimberger
 #
-#    This software is licensed under the terms of the Apache Licence Version 2.0
-#    which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
-#
-# @Class Decription:
-#    The class is for file manipulation. It is initiated with a regular
-#    expression pattern for this instance and can produce a list of Files
-#    from the given file pattern. These files can be deleted.
-#
-# @Class Content:
-#    - __init__
-#    - __str__
-#    - __list_files__
-#    - delete_files
-#
-# @Class Attributes:
-#    - pattern
-#    - files
-#
+#    This work is licensed under the Creative Commons Attribution 4.0
+#    International License. To view a copy of this license, visit
+#    http://creativecommons.org/licenses/by/4.0/ or send a letter to
+#    Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
 #*******************************************************************************
 
@@ -51 +39 @@
 import fnmatch
 
-# software specific module from flex_extract
+# software specific modules from flex_extract
 sys.path.append('../')
-#import profiling
 from mods.tools import silent_remove, get_list_as_string
 
@@ -61 +48 @@
 
 class UioFiles(object):
-    '''Class to manipulate files. At initialisation it has the pattern
-    which stores a regular expression pattern for the files, the path
-    to the files and the files already.
+    '''Collection of files matching a specific pattern.
+
+    The pattern can contain regular expressions for the files.
+    The files are listed and can be transformed to a single string or
+    they can be deleted.
+
+    Attributes
+    ----------
+    path : str
+        Directory where to list the files.
+
+    pattern : str
+        Regular expression pattern. For example: '\*.grb'
+
+    files : list of str
+        List of files matching the pattern in the path.
     '''
     # --------------------------------------------------------------------------
-    # CLASS FUNCTIONS
+    # CLASS METHODS
     # --------------------------------------------------------------------------
     def __init__(self, path, pattern):
@@ -73 +73 @@
         Parameters
         ----------
-        path : :obj:`string`
+        path : str
             Directory where to list the files.
 
-        pattern : :obj:`string`
+        pattern : str
             Regular expression pattern. For example: '\*.grb'
 
@@ -92 +92 @@
         return
 
-    #@profiling.timefn
+
     def _list_files(self, path):
         '''Lists all files in the directory with the matching
@@ -99 +99 @@
         Parameters
         ----------
-        path : :obj:`string`
+        path : str
             Path to the files.
 
@@ -116 +116 @@
         return
 
+
     def __str__(self):
         '''Converts the list of files into a single string.
@@ -125 +126 @@
         Return
         ------
-        files_string : :obj:`string`
+        files_string : str
             The content of the list as a single string.
         '''
@@ -133 +134 @@
 
         return files_string
+
 
     def delete_files(self):