Typically the node factor from the middle of the time series is used for tidal analysis. This is fine for relatively short time series. TAPPy actually calculates the node factor for each point in the time series and is therefore suited to long time series. TAPPy will also only report the tidal constituents that can be resolved based on the length of the input time series.
[TOC]
Input Data¶
The input data can be in almost any text form as long as each line has either (‘year’, ‘month’, ‘day’, ‘hour’, optional[‘minute’, ‘second’]) OR a single real or integer number representing time since an origin, and ‘water elevation’. Time can be to any standard, though UTC is preferred. TAPPy will maintain the input time throughout the analysis, but the only way to calculate phases to compare against other tidal constituents is to use UTC. The units for the water elevation can be anything and the output amplitude will be in the input units.
Definition File¶
The glue that binds the input format to TAPPy is a definition file. It is easy to understand and implement. Basically it tells TAPPy how to parse the input data file. Delimiters and white space are ignored, actually anything in the way of TAPPy finding the next value is ignored.
The definition file is a Python file (though with a .def extension) that specifies the order that values can be found on each line. Two variables are set within the definition file, ‘decimal_sep’ and ‘parse’. The ‘decimal_sep’ is set to the separator that marks the decimal part of a real number. In most of Europe this would be a “,” whereas for the United States it is a “.”. The ‘parse’ variable is where the magic happens. It is an ordered list of Python functions that retrieve and name values from each line in the order specified. TAPPy requires the following named values; ‘water_level’, and either ‘datetime’ or the group of (‘year’, ‘month’, ‘day’, ‘hour’, ‘minute’, ‘second’). If the later selection to define the time stamp is used and ‘minute’ and ‘second’ are not specified they are both set to zero. All other names (like ‘state’ and ‘station’ in the example below) are parsed, but ignored by TAPPy.
Example Definition File¶
Definition File | Matching Data File |
|---|---|
You need to specify the separator between¶the integer part and the decimal¶part of real numbers, even if you only¶have integers in your data file.¶decimal_sep = “.” # TAPPy needs the variables ‘year’, ‘month’, # ‘day’, ‘hour’, ‘minute’, ‘water_level’. # Any other variable name can be used as a # placeholder. parse = [ integer(‘state’, exact=3), integer_as_string(‘station’, exact=4), positive_integer(‘year’, exact=4), positive_integer(‘month’, exact=2), positive_integer(‘day’, exact=2), positive_integer(‘hour’), positive_integer(‘minute’), positive_integer(‘toss’), real(‘water_level’), ] | Station Date Time Pred 6 Vrfy 6 DCP#: 1 Units: Feet Feet Data%: MLLW GMT 100.00 100.00 Maximum: 5.00 Minimum: -0.91 ““——- ——– —– ——- ——-”” 8721604 20061109 00:00 2.03 2.23 8721604 20061109 00:06 2.11 2.32 8721604 20061109 00:12 2.19 2.38 8721604 20061109 00:18 2.28 2.41 8721604 20061109 00:24 2.36 2.55 … |
The example definition file above would correctly parse the data format used by COOPS. Example data for Trident Pier, Florida, USA from COOPS.
List of functions that can appear in the definition file.
Function name |
Find the next … |
|---|---|
integer(name, minimum=1, maximum=None, exact=None) |
integer |
positive_integer(name, minimum=1, maximum=None, exact=None) |
positive integer (‘+’ is optional) |
negative_integer(name, minimum=1, maximum=None, exact=None) |
negative integer |
real(name) |
real |
real_as_datetime(‘datetime’, origin=datetime.datetime(1900,1,1), unit=‘days’) |
indexed time, (days since… or hours since…) origin and unit have to be compatible with Python datetime. The name will always be ‘datetime’. |
integer_as_datetime(‘datetime’, minimum=1, maximum=None, exact=None, origin=datetime.datetime(1900,1,1), unit=‘days’) |
indexed time (days since… or hours since…), origin and unit have to be compatible with Python datetime. The name will always be ‘datetime’. |
positive_real(name) |
positive real (‘+’ is optional) |
negative_real(name) |
negative real |
number(name) |
an integer or a real |
number_as_real(name) |
an integer or a real, converted to a real using float() |
number_as_integer(name) |
an integer or a real, converted to an integer using int() |
Additional general purpose parsing functions probably not useful to TAPPy users.
Function name |
Find the next … |
|---|---|
real_as_string(name) |
real, but return as a string |
integer_as_string(name, minimum=1, maximum=None, exact=None) |
integer, but return as string |
qstring(name) |
quoted string (single or double) |
delimited_as_string(name) |
any group of letters and/or numbers |
string(name, exact=None) |
any group of letters, numbers, and/or spaces |
number_as_string(name) |
and number as string |
insert(name, value) |
sets name to value |
Filters¶
[CompareTidalFilters]
Command Line Arguments¶
Subcommands¶
tappy.py
Usage: /usr/bin/tappy.py COMMAND <options>
Available commands:
analysis Traditional analysis with separately calculated nodal factors.
Constituent amplitude units are the same as the input heights.
Constituent phases are based in the same time zone as the
dates.
prediction Prediction based upon earlier constituent analysis saved in
IHOTC XML transfer format.
writeconfig OVERWRITES an ini style config file that holds all of default
the command line options.
Use "/usr/bin/tappy.py <command> --help" for individual command help.
Analysis Arguments¶
tappy.py analysis --help
Usage: /usr/bin/tappy.py analysis <data_filename> [<def_filename>] [<config>] [<quiet>] [<debug>] [<outputts>] [<outputxml>] [<ephemeris>] [<rayleigh>] [<print_vau_table>] [<missing_data>] [<linear_trend>] [<remove_extreme>] [<zero_ts>] [<filter>] [<pad_filters>] [<include_inferred>] [<xmlname>] [<xmlcountry>] [<xmllatitude>] [<xmllongitude>] [<xmltimezone>] [<xmlcomments>] [<xmlunits>] [<xmldecimalplaces>]
Traditional analysis with separately calculated nodal factors. Constituent
amplitude units are the same as the input heights. Constituent phases are
based in the same time zone as the dates.
Required Arguments:
data_filename The time-series of elevations to be analyzed.
Options:
--rayleigh The Rayleigh coefficient is used to compare against
to determine time series length to differentiate
between two frequencies. [default: default]
--xmlunits Not used in analysis. Used ONLY to complete the XML
file. Units of the observed water level. Defaults to
'm'.
--xmllongitude Not used in analysis. Used ONLY to complete the XML
file. Longitude of the station. Defaults to 0.0.
--missing_data What should be done if there is missing data. One of:
fail, ignore, or fill. [default: default]
--ephemeris Print out ephemeris tables.
--zero_ts Zero the input time series before constituent
analysis by subtracting filtered data. One of:
transform,usgs,doodson,boxcar
--pad_filters Pad input data set with values to return same size
after filtering. Realize edge effects are
unavoidable. One of ["tide", "minimum", "maximum",
"mean", "median", "reflect", "wrap"]
--xmldecimalplaces Not used in analysis. Used ONLY to complete the XML
file. Format of the observed amplitude and phase.
Default depends on length of analysis record.
--xmlname Not used in analysis. Used ONLY to complete the XML
file. Name of the station supplying the observations.
Defaults to 'A port in a storm'.
--config Read command line options from config file, override
config file entries on the command line.
--def_filename Containes the definition string to parse the input
data.
--xmlcountry Not used in analysis. Used ONLY to complete the XML
file. Name of the country containing the station.
Defaults to 'A man without a country'.
--xmltimezone Not used in analysis. Used ONLY to complete the XML
file. Time zone of the station. Defaults to '0000'.
--include_inferred Do not incorporate any inferred constituents into the
least squares fit.
--xmllatitude Not used in analysis. Used ONLY to complete the XML
file. Latitude of the station. Defaults to 0.0.
--linear_trend Include a linear trend in the least squares fit.
--outputts Output time series for each constituent.
--xmlcomments Not used in analysis. Used ONLY to complete the XML
file. Station comments. Defaults to 'No comment'.
--quiet Print nothing to the screen.
--print_vau_table For debugging - will print a table of V and u values
to compare against Schureman.
--filter Filter input data set with tide elimination filters.
The -o outputts option is implied. Any mix separated
by commas and no spaces:
transform,usgs,doodson,boxcar
--remove_extreme Remove values outside of 2 standard deviations before
analysis.
--outputxml File name to output constituents as IHOTC XML format.
--debug Print debug messages.
(specifying a single hyphen (-) in the argument list means all
subsequent arguments are treated as bare arguments, not options)
Prediction Arguments¶
tappy.py prediction --help
Usage: /usr/bin/tappy.py prediction <xml_filename> <start_date> <end_date> <interval> [<include_inferred>] [<fname>]
Prediction based upon earlier constituent analysis saved in IHOTC XML
transfer format.
Required Arguments:
xml_filename The tidal constituents in IHOTC XML transfer format.
start_date The start date as a ISO 8601 string. '2010-01-01T00:00:00'
end_date The end date as a ISO 8601 string. '2011-01-01T00:00:00:00'
interval The interval as the number of minutes.
Options:
--fname Output filename, default is '-' to print to screen.
--include_inferred Include the inferred constituents.
(specifying a single hyphen (-) in the argument list means all
subsequent arguments are treated as bare arguments, not options)
