Changeset 274f9ef in flex_extract.git for source/python/mods


Ignore:
Timestamp:
Oct 22, 2018, 11:44:47 AM (6 years ago)
Author:
Anne Philipp <anne.philipp@…>
Branches:
master, ctbto, dev
Children:
db27c09
Parents:
708c667
Message:

Converted docstrings to numpy style and build first structure for sphinxdocumentation (incl API)

Location:
source/python/mods
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • source/python/mods/get_mars_data.py

    r70fee58 r274f9ef  
    6969# ------------------------------------------------------------------------------
    7070def main():
    71     '''
    72     @Description:
    73         If get_mars_data is called directly from command line,
    74 
    75         the program flow and calls the argumentparser function and
    76         the get_mars_data function for retrieving EC data.
    77 
    78     @Input:
    79         <nothing>
    80 
    81     @Return:
    82         <nothing>
     71    '''Controls the program to get data out of mars.
     72
     73    This is done if it is called directly from command line.
     74    Then it also takes program call arguments and control file input.
     75
     76    Parameters
     77    ----------
     78
     79    Return
     80    ------
     81
    8382    '''
    8483
    … …  
    9796
    9897def get_mars_data(c):
    99     '''
    100     @Description:
    101         Retrieves the EC data needed for a FLEXPART simulation.
    102         Start and end dates for retrieval period is set. Retrievals
    103         are divided into smaller periods if necessary and datechunk parameter
    104         is set.
    105 
    106     @Input:
    107         c: instance of class ControlFile
    108             Contains all the parameters of CONTROL file and
    109             command line.
    110             For more information about format and content of the parameter
    111             see documentation.
    112 
    113     @Return:
    114         <nothing>
     98    '''Retrieves the EC data needed for a FLEXPART simulation.
     99
     100    Start and end dates for retrieval period is set. Retrievals
     101    are divided into smaller periods if necessary and datechunk parameter
     102    is set.
     103
     104    Parameters
     105    ----------
     106    c : :obj:`ControlFile`
     107        Contains all the parameters of CONTROL file and
     108        command line.
     109
     110    Return
     111    ------
     112
    115113    '''
    116114
    … …  
    206204
    207205def do_retrievement(c, server, start, end, delta_t, fluxes=False):
    208     '''
    209     @Description:
    210         Divides the complete retrieval period in smaller chunks and
    211         retrieves the data from MARS.
    212 
    213     @Input:
    214         c: instance of class ControlFile
    215             Contains all the parameters of CONTROL file and
    216             command line.
    217             For more information about format and content of the parameter
    218             see documentation.
    219 
    220         server: instance of ECMWFService
    221             The server connection to ECMWF
    222 
    223         start: instance of datetime
    224             The start date of the retrieval.
    225 
    226         end: instance of datetime
    227             The end date of the retrieval.
    228 
    229         delta_t: instance of datetime
    230             Delta_t +1 is the maximal time period of a single
    231             retrieval.
    232 
    233         fluxes: boolean, optional
    234             Decides if the flux parameters are to be retrieved or
    235             the rest of the parameter list.
    236             Default value is False.
    237 
    238     @Return:
    239         <nothing>
     206    '''Divides the complete retrieval period in smaller chunks and
     207    retrieves the data from MARS.
     208
     209    Parameters
     210    ----------
     211    c : :obj:`ControlFile`
     212        Contains all the parameters of CONTROL file and
     213        command line.
     214
     215    server : :obj:`ECMWFService`
     216            The server connection to ECMWF.
     217
     218    start : :obj:`datetime`
     219        The start date of the retrieval.
     220
     221    end : :obj:`datetime`
     222        The end date of the retrieval.
     223
     224    delta_t : :obj:`datetime`
     225        Delta_t + 1 is the maximal time period of a single
     226        retrieval.
     227
     228    fluxes : :obj:`boolean`, optional
     229        Decides if the flux parameters are to be retrieved or
     230        the rest of the parameter list.
     231        Default value is False.
     232
     233    Return
     234    ------
     235
    240236    '''
    241237

  • source/python/mods/prepare_flexpart.py

    r70fee58 r274f9ef  
    7979# ------------------------------------------------------------------------------
    8080def main():
    81     '''
    82     @Description:
    83         If prepare_flexpart is called from command line, this function controls
    84         the program flow and calls the argumentparser function and
    85         the prepare_flexpart function for preparation of GRIB data for FLEXPART.
     81    '''Controls the program to prepare flexpart input files from mars data.
    8682
    87     @Input:
    88         <nothing>
     83    This is done if it is called directly from command line.
     84    Then it also takes program call arguments and control file input.
    8985
    90     @Return:
    91         <nothing>
     86    Parameters
     87    ----------
     88
     89    Return
     90    ------
     91
    9292    '''
    9393
    … …  
    105105
    106106def prepare_flexpart(ppid, c):
    107     '''
    108     @Description:
    109         Lists all grib files retrieved from MARS with get_mars_data and
    110         uses prepares data for the use in FLEXPART. Specific data fields
    111         are converted to a different grid and the flux data are going to be
    112         disaggregated. The data fields are collected by hour and stored in
    113         a file with a specific FLEXPART relevant naming convention.
     107    '''Converts the mars data into flexpart ready input files.
    114108
    115     @Input:
    116         ppid: int
    117             Contains the ppid number of the current ECMWF job. If it is called
    118             from this script, it is "None".
     109    Specific data fields are converted to a different grid and the flux
     110    data are going to be disaggregated. The data fields are collected by
     111    hour and stored in a file with a specific FLEXPART relevant naming
     112    convention.
    119113
    120         c: instance of class ControlFile
    121             Contains all the parameters of CONTROL file and
    122             command line.
    123             For more information about format and content of the parameter
    124             see documentation.
     114    Parameters
     115    ----------
     116    ppid : :obj:`int`
     117        Contains the ppid number of the current ECMWF job. It will be None if
     118        the method was called within this module.
    125119
    126     @Return:
    127         <nothing>
     120    c : :obj:`ControlFile`
     121        Contains all the parameters of CONTROL file and
     122        command line.
     123
     124    Return
     125    ------
     126
    128127    '''
    129128

  • source/python/mods/tools.py

    r5bad6ec r274f9ef  
    6161
    6262def none_or_str(value):
    63     '''
    64     @Description:
    65         Converts the input string into pythons None-type if the string
    66         contains "None".
    67 
    68     @Input:
    69         value: string
    70             String to be checked for the "None" word.
    71 
    72     @Return:
    73         None or value:
    74             Return depends on the content of the input value. If it was "None",
    75             then the python type None is returned. Otherwise the string itself.
     63    '''Converts the input string into pythons None-type if the string
     64    contains string "None".
     65
     66    Parameters
     67    ----------
     68    value : :obj:`string`
     69        String to be checked for the "None" word.
     70
     71    Return
     72    ------
     73    None or value:
     74        Return depends on the content of the input value. If it was "None",
     75        then the python type None is returned. Otherwise the string itself.
    7676    '''
    7777    if value == 'None':
    … …  
    8080
    8181def none_or_int(value):
    82     '''
    83     @Description:
    84         Converts the input string into pythons None-type if the string
    85         contains "None". Otherwise it is converted to an integer value.
    86 
    87     @Input:
    88         value: string
    89             String to be checked for the "None" word.
    90 
    91     @Return:
    92         None or int(value):
    93             Return depends on the content of the input value. If it was "None",
    94             then the python type None is returned. Otherwise the string is
    95             converted into an integer value.
     82    '''Converts the input string into pythons None-type if the string
     83    contains string "None". Otherwise it is converted to an integer value.
     84
     85    Parameters
     86    ----------
     87    value : :obj:`string`
     88        String to be checked for the "None" word.
     89
     90    Return
     91    ------
     92    None or int(value):
     93        Return depends on the content of the input value. If it was "None",
     94        then the python type None is returned. Otherwise the string is
     95        converted into an integer value.
    9696    '''
    9797    if value == 'None':
    … …  
    100100
    101101def get_cmdline_arguments():
    102     '''
    103     @Description:
    104         Decomposes the command line arguments and assigns them to variables.
    105         Apply default values for non mentioned arguments.
    106 
    107     @Input:
    108         <nothing>
    109 
    110     @Return:
    111         args: instance of ArgumentParser
    112             Contains the commandline arguments from script/program call.
     102    '''Decomposes the command line arguments and assigns them to variables.
     103    Apply default values for non mentioned arguments.
     104
     105    Parameters
     106    ----------
     107
     108    Return
     109    ------
     110    args : :obj:`Namespace`
     111        Contains the commandline arguments from script/program call.
    113112    '''
    114113
    … …  
    190189
    191190def read_ecenv(filename):
    192     '''
    193     @Description:
    194         Reads the file into a dictionary where the key values are the parameter
    195         names.
    196 
    197     @Input:
    198         filename: string
    199             Path to file where the ECMWV environment parameters are stored.
    200 
    201     @Return:
    202         envs: dict
    203             Contains the environment parameter ecuid, ecgid, gateway
    204             and destination for ECMWF server environments.
     191    '''Reads the file into a dictionary where the key values are the parameter
     192    names.
     193
     194    Parameters
     195    ----------
     196    filename : :obj:`string`
     197        Path to file where the ECMWF environment parameters are stored.
     198
     199    Return
     200    ------
     201    envs : :obj:`dictionary`
     202        Contains the environment parameter ecuid, ecgid, gateway
     203        and destination for ECMWF server environments.
    205204    '''
    206205    envs= {}
    … …  
    214213
    215214def clean_up(c):
    216     '''
    217     @Description:
    218         Remove all files from intermediate directory
    219         (inputdir from CONTROL file).
    220 
    221     @Input:
    222         c: instance of class ControlFile
    223             Contains all the parameters of CONTROL file and
    224             command line.
    225             For more information about format and content of the parameter
    226             see documentation.
    227 
    228     @Return:
    229         <nothing>
     215    '''Remove all files from intermediate directory (inputdir).
     216
     217    Parameters
     218    ----------
     219    c : :obj:`ControlFile`
     220        Contains all the parameters of CONTROL file and
     221        command line.
     222
     223    Return
     224    ------
     225
    230226    '''
    231227
    … …  
    245241
    246242def my_error(users, message='ERROR'):
    247     '''
    248     @Description:
    249         Prints a specified error message which can be passed to the function
    250         before exiting the program.
    251 
    252     @Input:
    253         user: list of strings
    254             Contains all email addresses which should be notified.
    255             It might also contain just the ecmwf user name which wil trigger
    256             mailing to the associated email address for this user.
    257 
    258         message: string, optional
    259             Error message. Default value is "ERROR".
    260 
    261     @Return:
    262         <nothing>
     243    '''Prints a specified error message which can be passed to the function
     244    before exiting the program.
     245
     246    Parameters
     247    ----------
     248    user : :obj:`list` of :obj:`string`
     249        Contains all email addresses which should be notified.
     250        It might also contain just the ecmwf user name which wil trigger
     251        mailing to the associated email address for this user.
     252
     253    message : :obj:`string`, optional
     254        Error message. Default value is "ERROR".
     255
     256    Return
     257    ------
     258
    263259    '''
    264260
    … …  
    291287
    292288def normal_exit(users, message='Done!'):
    293     '''
    294     @Description:
    295         Prints a specific exit message which can be passed to the function.
    296 
    297     @Input:
    298         user: list of strings
    299             Contains all email addresses which should be notified.
    300             It might also contain just the ecmwf user name which wil trigger
    301             mailing to the associated email address for this user.
    302 
    303         message: string, optional
    304             Message for exiting program. Default value is "Done!".
    305 
    306     @Return:
    307         <nothing>
     289    '''Prints a specific exit message which can be passed to the function.
     290
     291    Parameters
     292    ----------
     293    user : :obj:`list` of :obj:`string`
     294        Contains all email addresses which should be notified.
     295        It might also contain just the ecmwf user name which wil trigger
     296        mailing to the associated email address for this user.
     297
     298    message : :obj:`string`, optional
     299        Message for exiting program. Default value is "Done!".
     300
     301    Return
     302    ------
    308303
    309304    '''
    … …  
    333328
    334329def product(*args, **kwds):
    335     '''
    336     @Description:
    337         This method is taken from an example at the ECMWF wiki website.
    338         https://software.ecmwf.int/wiki/display/GRIB/index.py; 2018-03-16
    339 
    340         This method combines the single characters of the passed arguments
    341         with each other. So that each character of each argument value
    342         will be combined with each character of the other arguments as a tuple.
    343 
    344         Example:
    345         product('ABCD', 'xy') --> Ax Ay Bx By Cx Cy Dx Dy
    346         product(range(2), repeat = 3) --> 000 001 010 011 100 101 110 111
    347 
    348     @Input:
    349         *args: tuple
    350             Positional arguments (arbitrary number).
    351 
    352         **kwds: dictionary
    353             Contains all the keyword arguments from *args.
    354 
    355     @Return:
    356         prod: tuple
    357             Return will be done with "yield". A tuple of combined arguments.
    358             See example in description above.
     330    '''This method combines the single characters of the passed arguments
     331    with each other. So that each character of each argument value
     332    will be combined with each character of the other arguments as a tuple.
     333
     334    Note
     335    ----
     336    This method is taken from an example at the ECMWF wiki website.
     337    https://software.ecmwf.int/wiki/display/GRIB/index.py; 2018-03-16
     338
     339    Example
     340    -------
     341    product('ABCD', 'xy') --> Ax Ay Bx By Cx Cy Dx Dy
     342
     343    product(range(2), repeat = 3) --> 000 001 010 011 100 101 110 111
     344
     345    Parameters
     346    ----------
     347    \*args : :obj:`tuple`
     348        Positional arguments (arbitrary number).
     349
     350    \*\*kwds : :obj:`dictionary`
     351        Contains all the keyword arguments from \*args.
     352
     353    Return
     354    ------
     355    prod : :obj:`tuple`
     356        Return will be done with "yield". A tuple of combined arguments.
     357        See example in description above.
    359358    '''
    360359    pools = map(tuple, args) * kwds.get('repeat', 1)
    … …  
    369368
    370369def silent_remove(filename):
    371     '''
    372     @Description:
    373         Remove file if it exists.
    374         The function does not fail if the file does not exist.
    375 
    376     @Input:
    377         filename: string
    378             The name of the file to be removed without notification.
    379 
    380     @Return:
    381         <nothing>
     370    '''Remove file if it exists.
     371    The function does not fail if the file does not exist.
     372
     373    Parameters
     374    ----------
     375    filename : :obj:`string`
     376        The name of the file to be removed without notification.
     377
     378    Return
     379    ------
     380
    382381    '''
    383382    try:
    … …  
    392391
    393392def init128(filepath):
    394     '''
    395     @Description:
    396         Opens and reads the grib file with table 128 information.
    397 
    398     @Input:
    399         filepath: string
    400             Path to file of ECMWF grib table number 128.
    401 
    402     @Return:
    403         table128: dictionary
    404             Contains the ECMWF grib table 128 information.
    405             The key is the parameter number and the value is the
    406             short name of the parameter.
     393    '''Opens and reads the grib file with table 128 information.
     394
     395    Parameters
     396    ----------
     397    filepath : :obj:`string`
     398        Path to file of ECMWF grib table number 128.
     399
     400    Return
     401    ------
     402    table128 : :obj:`dictionary`
     403        Contains the ECMWF grib table 128 information.
     404        The key is the parameter number and the value is the
     405        short name of the parameter.
    407406    '''
    408407    table128 = dict()
    … …  
    417416
    418417def to_param_id(pars, table):
    419     '''
    420     @Description:
    421         Transform parameter names to parameter ids
    422         with ECMWF grib table 128.
    423 
    424     @Input:
    425         pars: string
    426             Addpar argument from CONTROL file in the format of
    427             parameter names instead of ids. The parameter short
    428             names are sepearted with "/" and they are passed as
    429             one single string.
    430 
    431         table: dictionary
    432             Contains the ECMWF grib table 128 information.
    433             The key is the parameter number and the value is the
    434             short name of the parameter.
    435 
    436     @Return:
    437         ipar: list of integer
    438             List of addpar parameters from CONTROL file transformed to
    439             parameter ids in the format of integer.
     418    '''Transform parameter names to parameter ids with ECMWF grib table 128.
     419
     420    Parameters
     421    ----------
     422    pars : :obj:`string`
     423        Addpar argument from CONTROL file in the format of
     424        parameter names instead of ids. The parameter short
     425        names are sepearted with "/" and they are passed as
     426        one single string.
     427
     428    table : :obj:`dictionary`
     429        Contains the ECMWF grib table 128 information.
     430        The key is the parameter number and the value is the
     431        short name of the parameter.
     432
     433    Return
     434    ------
     435    ipar : :obj:`list` of :obj:`integer`
     436        List of addpar parameters from CONTROL file transformed to
     437        parameter ids in the format of integer.
    440438    '''
    441439    cpar = pars.upper().split('/')
    … …  
    452450
    453451def get_list_as_string(list_obj, concatenate_sign=', '):
    454     '''
    455     @Description:
    456         Converts a list of arbitrary content into a single string.
    457 
    458     @Input:
    459         list_obj: list
    460             A list with arbitrary content.
    461 
    462         concatenate_sign: string, optional
    463             A string which is used to concatenate the single
    464             list elements. Default value is ", ".
    465 
    466     @Return:
    467         str_of_list: string
    468             The content of the list as a single string.
     452    '''Converts a list of arbitrary content into a single string.
     453
     454    Parameters
     455    ----------
     456    list_obj : :obj:`list`
     457        A list with arbitrary content.
     458
     459    concatenate_sign : :obj:`string`, optional
     460        A string which is used to concatenate the single
     461        list elements. Default value is ", ".
     462
     463    Return
     464    ------
     465    str_of_list : :obj:`string`
     466        The content of the list as a single string.
    469467    '''
    470468
    … …  
    474472
    475473def make_dir(directory):
    476     '''
    477     @Description:
    478         Creates a directory and gives a warning if the directory
    479         already exists. The program stops only if there is another problem.
    480 
    481     @Input:
    482         directory: string
    483             The directory name including the path which should be created.
    484 
    485     @Return:
    486         <nothing>
     474    '''Creates a directory and gives a warning if the directory
     475    already exists. The program stops only if there is another problem.
     476
     477    Parameters
     478    ----------
     479    directory : :obj:`string`
     480        The directory name including the path which should be created.
     481
     482    Return
     483    ------
     484
    487485    '''
    488486    try:
    … …  
    498496
    499497def put_file_to_ecserver(ecd, filename, target, ecuid, ecgid):
    500     '''
    501     @Description:
    502         Uses the ecaccess-file-put command to send a file to the ECMWF servers.
    503 
    504         NOTE:
    505         The return value is just for testing reasons. It does not have
    506         to be used from the calling function since the whole error handling
    507         is done in here.
    508 
    509     @Input:
    510         ecd: string
    511             The path were the file is stored.
    512 
    513         filename: string
    514             The name of the file to send to the ECMWF server.
    515 
    516         target: string
    517             The target queue where the file should be sent to.
    518 
    519         ecuid: string
    520             The user id on ECMWF server.
    521 
    522         ecgid: string
    523             The group id on ECMWF server.
    524 
    525     @Return:
    526         rcode: string
    527             Resulting code of command execution. If successful the string
    528             will be empty.
     498    '''Uses the ecaccess-file-put command to send a file to the ECMWF servers.
     499
     500    Note
     501    ----
     502    The return value is just for testing reasons. It does not have
     503    to be used from the calling function since the whole error handling
     504    is done in here.
     505
     506    Parameters
     507    ----------
     508    ecd : :obj:`string`
     509        The path were the file is stored.
     510
     511    filename : :obj:`string`
     512        The name of the file to send to the ECMWF server.
     513
     514    target : :obj:`string`
     515        The target queue where the file should be sent to.
     516
     517    ecuid : :obj:`string`
     518        The user id on ECMWF server.
     519
     520    ecgid : :obj:`string`
     521        The group id on ECMWF server.
     522
     523    Return
     524    ------
     525    rcode : :obj:`string`
     526        Resulting code of command execution. If successful the string
     527        will be empty.
    529528    '''
    530529
    … …  
    546545
    547546def submit_job_to_ecserver(target, jobname):
    548     '''
    549     @Description:
    550         Uses ecaccess-job-submit command to submit a job to the ECMWF server.
    551 
    552         NOTE:
    553         The return value is just for testing reasons. It does not have
    554         to be used from the calling function since the whole error handling
    555         is done in here.
    556 
    557     @Input:
    558         target: string
    559             The target where the file should be sent to, e.g. the queue.
    560 
    561         jobname: string
    562             The name of the jobfile to be submitted to the ECMWF server.
    563 
    564     @Return:
    565         rcode: string
    566             Resulting code of command execution. If successful the string
    567             will contain an integer number, representing the id of the job
    568             at the ecmwf server.
     547    '''Uses ecaccess-job-submit command to submit a job to the ECMWF server.
     548
     549    Note
     550    ----
     551    The return value is just for testing reasons. It does not have
     552    to be used from the calling function since the whole error handling
     553    is done in here.
     554
     555    Parameters
     556    ----------
     557    target : :obj:`string`
     558        The target where the file should be sent to, e.g. the queue.
     559
     560    jobname : :obj:`string`
     561        The name of the jobfile to be submitted to the ECMWF server.
     562
     563    Return
     564    ------
     565    rcode : :obj:`string`
     566        Resulting code of command execution. If successful the string
     567        will contain an integer number, representing the id of the job
     568        at the ecmwf server.
    569569    '''
    570570
Note: See TracChangeset for help on using the changeset viewer.
hosted by ZAMG