Model time conversion

The SCHISM *.th file has two flavors, binary and text. Both are multicolumn formats, with elapsed time in seconds in the left column since the start of the simulation and the other columns representing values. There is no datum within the file to link elapsed time to calendar or geophysical time, and it is hard to search for events, re-use the *.th file with a different start date or make sense of orphaned files.

The model_time script utility performs conversions between geophysical and elapsed times on flat files. This is a pretty easy task on simple files using just pandas, but this utility preserves formatting and floating precision of the source, copies over comments and can clip the file to a new start date.

model_time.py

Interpret model times in elapsed seconds and translate between calendar time and elapsed. The script requires a subcommand like: $ model_time.py to_elapsed. You can also get subject-specific help on a subcommand by typing $ model_time.py subcommand –help

usage: model_time [-h] {to_elapsed,to_date,clip} ...

subcommands

subcommand

Possible choices: to_elapsed, to_date, clip

sub-commands indicating the particular action required.

Sub-commands

to_elapsed

Convert input datetime string or *.th file with datetime column to equivalent output in elapsed seconds.

model_time to_elapsed [-h] [--start START] [--annotate] [--step [STEP]]
                      [--out OUT] [--skip_nan SKIP_NAN]
                      dated_input [dated_input ...]

Positional Arguments

dated_input: One or more dates to be converted in ISO-like format 2009-03-12T00:00:00 (time can be ommitted) or the name of a *.th file with the time column in this format.

Named Arguments

--start

Starting date and time basis for output if the input is a file. Allows a larger database with readable times to be clipped

--annotate

Default: False

--step

Model time step. If given, answer will be the integer time step.

--out

Name of output file. If input is a *.th file the file will be converted and output to this file, otherwise printed to screen

--skip_nan

Skip a record with nan if True

Default: False

to_date

Convert input elapsed seconds or *.th file with elapsed seconds as the time column to equivalent output with a datetime or annotated with datetimes.

model_time to_date [-h] --start START [--step [STEP]]
                   [--elapsed_unit ELAPSED_UNIT] [--time_format TIME_FORMAT]
                   [--annotate] [--out OUT]
                   elapsed_input [elapsed_input ...]

Positional Arguments

elapsed_input: One or more numbers representing elapsed seconds since the start argument or the name of a *.th file with the time column in elapsed seconds.

Named Arguments

--start

Start time in ISO-like format 2009-03-12T00:00:00. Time part is optional.

--step

Model time step in seconds. If given, answer will be the integer time step.

--elapsed_unit

Time unit of input file. Must be either ‘s’ for seconds or ‘d’ for days. Only used for files

Default: “s”

--time_format

Time format for output, e.g. the default is %Y-%m-%dT%H:%M:%S for 2009-03-14T22:40:00. Only used when converting fields.

Default: “%Y-%m-%dT%H:%M”

--annotate

Default: False

--out

Name of output file. If input is a *.th file the file will be converted and output to this file, otherwise printed to screen

clip

Clip (subset) an input file in elapsed time to a new, later, start date

model_time clip [-h] --start START --clip_start CLIP_START [--out OUT]
                elapsed_input [elapsed_input ...]

Positional Arguments

elapsed_input: One or more numbers representing elapsed seconds since the start argument or the name of a *.th file with the time column in elapsed seconds.

Named Arguments

--start: Start time in ISO-like format 2009-03-12T00:00:00. Time part is optional.
--clip_start: Starting date for output.
--out: Name of output file. If input is a *.th file the file will be converted and output to this file, otherwise printed to screen