Package: htimeseries
htimeseries - Hydrological and meteorological time seriesThis module provides the HTimeseries class, which is a layer on top of
pandas, offering a little more functionality.Introductionfrom htimeseries import HTimeseries

ts = HTimeseries()This creates aHTimeseriesobject, whosedataattribute is a
pandas time series or dataframe with a datetime index. Besidesdata,
it can have other attributes which serve as the time series’ metadata.
There are also several utility methods described below.HTimeseries objectsHTimeseries(data=None, format=None, start_date=None, end_date=None, default_tzinfo=None)Creates aHTimeseriesobject.datacan be a pandas time series
or dataframe indexed by datetime or a file-like object. If it is a
pandas object, it becomes the value of thedataattribute and the
rest of the keyword arguments are ignored.Thedataattribute should be a dataframe with two columns (besides
date): value and flags. However, in this version,HTimeseriesdoes
not enforce that. A good idea is to create an emptyHTimeseriesobject withHTimeseries(), and then proceed to fill in itsdataattribute. This ensures that the dataframe will have the right columns
and dtypes.If thedataargument is a filelike object, the time series is read
from it.  There must be no newline translation indata(open it withopen(...,newline='\n'). Ifstart_dateandend_dateare
specified, it skips rows outside the range.The contents of the filelike object can be in text format or file format (see
“formats” below). This is usually auto-detected, but a specific format can
be specified with theformatparameter.  If reading in text format,
the returned object just has thedataattribute set. If reading in
file format , the returned object also has attributesunit,title,comment,timezone,time_step,interval_type,variable,precisionandlocation. For the meaning of these
attributes, see section “File format” below.These attributes are purely informational. In particular,time_stepand the other time-step-related attributes don’t necessarily mean that
the pandas object will have a related time step (also called
“frequency”). In fact, raw time series may be irregular but actually
have a time step. For example, a ten-minute time series might end in
:10, :20, etc., but at some point there might be an irregularity and it
could continue with :31, :41, etc.  Strictly speaking, such a time
series has an irregular step. However, when stored in a database,
specifying that its time step is ten minutes (because that’s what it is,
ten minutes with irregularities) can help people who browse or search
the database contents.Thelocationattribute is a dictionary that has itemsabscissa,ordinate,srid,altitude, andasrid.The timestamps of thedataattribute are aware. IfHTimeseries()is called with a dataframe, it should have an aware datetime index. If
it is called with a filelike object whose contents are in file format
and contain thetimezoneheader, that time zone is used to interpret
the file’s timestamps. If it is called with a filelike object that does
not contain atimezoneheader,default_tzinfois used. In the
latter case, ifdefault_tzinfoisNoneor unspecified, an
exception is raised..write(f, format=HTimeseries.TEXT, version=None)Writes the time series to filelike objectf. In accordance with the
formats described below, time series are written
using the CR-LF sequence to terminate lines.  Care should be taken thatf, or any subsequent operations onf, do not perform text
translation; otherwise it may result in lines being terminated with
CR-CR-LF. Iffis a file, it should have been opened withnewline=”n”.versionis ignored unlessformat=HTimeseries.FILE. The defaultversionis latest.While writing, the value of theprecisionattribute is taken into
account.TzinfoFromString objectsfrom htimeseries imort TzinfoFromString

atzinfo = TzinfoFromString("EET (UTC+0200)")TzinfoFromStringis a utility that creates and returns atzinfoobject from a string formatted as “+0000” or as “XXX (+0000)” or as “XXX
(UTC+0000)” (TzinfoFromStringis actually atzinfosubclass). Its
purpose is to read the contents of thetimezoneparameter of the
file format (described below).FormatsThere are two formats: thetext formatis generic text format, without
metadata; thefile formatis like the text format, but additionally
contains headers with metadata.Text formatThe text format for a time series is us-ascii, one line per record,
like this:2006-12-23 18:34,18.2,RANGEThe three fields are comma-separated and must always exist.  In the date
field, the time may be missing. The character that separates the date
from the time may be either a space or a lower caset, or a capitalT(this module produces text format using a space as date separator,
but can read text format that usestorT). The second field
always uses a dot as the decimal separator and may be empty.  The third
field is usually empty but may contain a list of space-separated flags.
The line separator should be the CR-LF sequence used in MS-DOS and
Windows systems. Code that produces text format should always use CR-LF
to end lines, but code that reads text format should be able to also
read lines that end in LF only, as well as CR-CR-LF (for reasons
explained in thewrite()function above).In order to improve performance in file writes, the maximum length of
each time series record line is limited to 255 characters.Flags should be encoded in ASCII; there must be no characters with
code greater than 127.File formatThe file format is like this:Version=2
Title=My timeseries
Unit=°C

2006-12-23 18:34,18.2,RANGE
2006-12-23 18:44,18.3,In other words, the file format consists of a header that specifies
parameters in the formParameter=Value, followed by a blank line,
followed by the timeseries in text format. The same conventions for line
terminators apply here as for the text format. The encoding of the
header section is UTF-8.Client and server software should recognize UTF-8 files with or without
UTF-8 BOM (Byte Order Mark) in the begining of file.  Writes may or may
not include the BOM, according OS. (Usually Windows software attaches
the BOM at the beginning of the file).Parameter names are case insensitive.  There may be white space on
either side of the equal sign, which is ignored. Trailing white space on
the line is also ignored. A second equal sign is considered to be part
of the value. The value cannot contain a newline, but there is a way to
have multi-lined parameters explained in the Comment parameter below.
All parameters except Version are optional: either the value can be
blank or the entireParameter=Valuecan be missing; the only
exception is the Comment parameter.The parameters available are:VersionThere are four versions:Version 1 files are long obsolete. They did not have a header
section.Version 2 files must haveVersion=2as the first line of the
file. All other parameters are optional. The file may not contain
unrecognized parameters; software reading files with unrecognized
parameters may raise an error.Version 3 files do not have theVersionparameter. At least one of
the other parameters must be present. Unrecognized parameters are
ignored when reading. The old deprecated parameter namesNominal_offsetandActual_offsetare used instead of the newer
(but also deprecated) onesTimestamp_roundingandTimestamp_offset.Version 4 files are the same as Version 3, except for the names of
the parametersTimestamp_roundingandTimestamp_offset.Version 5 files are the same as Version 4, except thatTimestamp_roundingandTimestamp_offsetdo not exist, andTime_stepis in a different format (see below).UnitA symbol for the measurement unit, like°Cormm.CountThe number of records in the time series. If present, it need not be
exact; it can be an estimate. Its primary purpose is to enable
progress indicators in software that takes time to read large time
series files. In order to determine the actual number of records,
the records need to be counted.TitleA title for the time series.CommentA multiline comment for the time series. Multiline comments are
stored by specifying multiple adjacent Comment parameters, like
this:Comment=This timeseries is extremely important
Comment=because the comment that describes it
Comment=spans five lines.
Comment=
Comment=These five lines form two paragraphs.The Comment parameter is the only parameter where a blank value is
significant and indicates an empty line, as can be seen in the
example above.TimezoneThe time zone of the timestamps, in the format{XXX}(UTC{+HHmm}), whereXXXis a time zone name and+HHmmis the
offset from UTC. Examples areEET (UTC+0200)andVST(UTC-0430).TheTzinfoFromStringutility (described above) can be used to
convert this string to atzinfoobject.Time_stepIn version 5, a pandas “frequency” string such as10min(10
minutes),H(hour), or2M(two months). If missing or empty,
the time series is without time step.Up to version 4, a comma-separated pair of integers; the number of
minutes and months in the time step (one of the two must be zero).When reading from version 4 or earlier, the pair of integers is
automatically converted to a pandas “frequency” string, so thetime_stepattribute of anHTimeseriesobject is always a
pandas “frequency” string. Likewise, when writing to a version 4
or earlier file, the pandas “frequency” string is automatically
converted to the pair of integers.Timestamp_roundingDeprecated. It might be found in old files, Version 4 or earlier,
buthtimeserieswill ignore it when reading and will never write
it.A comma-separated pair of integers indicating the number of minutes
and months that must be added to a round timestamp to get to the
nominal timestamp.  For example, if an hourly time series has
timestamps that end in :13, such as 01:13, 02:13, etc., then its
rounding is 13 minutes, 0 months, i.e.,(13, 0). Monthly time
series normally have a nominal timestamp of(0, 0), the
timestamps usually being of the form 2008-02-01 00:00, meaning
“February 2008” and usually rendered by application software as “Feb
2008” or “2008-02”. Annual timestamps have a nominal timestamp which
normally has 0 minutes, but may have nonzero months; for example, a
common rounding in Greece is 9 months (0=January), which means that
an annual timestamp is of the form 2008-10-01 00:00, normally
rendered by application software as 2008-2009, and denoting the
hydrological year 2008-2009.timestamp_roundingmay be None, meaning that the timestamps can
be irregular.Timestamp_roundingis named differently in older versions. See theVersionparameter above for more information.Timestamp_offsetDeprecated. It might be found in old files, Version 4 or earlier,
buthtimeserieswill ignore it when reading and will never write
it.A comma-separated pair of integers indicating the number of minutes
and months that must be added to the nominal timestamp to get to the
actual timestamp. The timestamp offset for small time steps, such as
up to daily, is usually zero, except if the nominal timestamp is the
beginning of an interval, in which case the timestamp offset is
equal to the length of the time step, so that the actual timestamp
is the end of the interval. For monthly and annual time steps, the
timestamp offset is usually 1 and 12 months respectively.  For a
monthly time series, a timestamp offset of (-475, 1) means that
2003-11-01 00:00 (often rendered as 2003-11) denotes the interval
2003-10-31 18:05 to 2003-11-30 18:05.Timestamp_offsetis named differently in older versions. See theVersionparameter above for more information.Interval_typeDeprecated. Has one of the valuessum,average,maximum,minimum, andvector_average. If absent it means that the
time series values are instantaneous, they do not refer to
intervals.VariableA textual description of the variable, such asTemperatureorPrecipitation.PrecisionThe precision of the time series values, in number of decimal digits
after the decimal separator. It can be negative; for example, a
precision of -2 indicates values accurate to the hundred, such as
100, 200, 300 etc.Location,Altitude(Versions 3 and later.)Locationis three numbers,
space-separated: abscissa, ordinate, and EPSG SRID.Altitudeis
one or two space-separated numbers: the altitude and the EPSG SRID
for altitude. The altitude SRID may be omitted.MetaHtimeseries isCopyright (C) 2013-2014 TEI of EpirusCopyright (C) 2018-2021 National Technical University of AthensCopyright (C) 2018-2021 Institute of Communications and Computer SystemsCopyright (C) 2022 IRMASYS P.C.Htimeseries is free software: you can redistribute it and/or modify it
under the terms of the GNU Affero General Public License, as published
by the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.The software is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
licenses for more details.You should have received a copy of the license along with this
program.  If not, seehttp://www.gnu.org/licenses/.Htimeseries was funded by several organizations:In 2013-2014 by theTEI of Epirusas part of theIRMAproject.In 2018-2021 byNTUAandICCSas part of theOpenHiproject.History6.0.2 (2023-12-22)Fixed crash when reading csv with aware timestamps.6.0.1 (2023-12-19)Fixed crash when reading csv with only a date column.6.0.0 (2023-12-14)Python 3.9 is now required (the reason for this is that backports.zoneinfo is
behaving differently from zoneinfo).Only pandas>=1.5,<2  is now supported. Pandas<1.5 probably did not work in
5.0.0 either, but it had not been discovered. Pandas>=2 handles ambiguous
times differently and is therefore still unsupported.Increased CSV reading speed by two orders of magnitude.5.0.0 (2023-11-21)Removed compatibility with pandas<1. pandas 1 and 2 are now supported.
This helps avoid an error when reading a data file spanning a time
interval that contains a change to or from DST.4.0.2 (2022-11-27)Worked around an old Pandas bug related to time zones
(https://github.com/pandas-dev/pandas/issues/11736) in order to
maintain compatibility with Pandas 0.23 (the bug was fixed in Pandas
0.24).4.0.1 (2022-11-27)Fixed packaging error where it didn’t install dependency
backports.zoneinfo on Python<3.9.4.0.0 (2022-11-22)The timestamps of the dataframe index are now aware. When initializing
aHTimeseriesobject with a dataframe, the dataframe index
timestamps must be aware. When initializing with a filelike object,
either the filelike object must contain atimezoneheader or the
newdefault_tzinfoparameter must be specified.3.1.1 (2020-12-29)Fixed incompatibility with pandas 1.2.3.1.0 (2020-12-17)When reading a time series from a file-like object, it is now
permitted for it to not have a flags column. In this case, an empty
flags column is automatically added to the HTimeseries object.3.0.0 (2020-02-23)Only Python>=3.7 is now supported.When reading or writing a time series, it now checks that there are no
duplicate timestamps and raises an exception if there are.2.0.5 (2020-01-15)Fix pandas dependency to use pandas<1, so that Python 3.5
compatibility is kept.2.0.4 (2020-01-08)Fixed crash when saving in version 2 and the time step was a mere “M”
or “Y” without multiplier.2.0.3 (2020-01-05)Default version when writing file is now latest.2.0.1 (2020-01-04)Fixed error when the time step was empty.2.0.0 (2020-01-04)Changed the way the time step is specified. Instead of
“minutes,months”, it is now a pandas “frequency” offset specification
such as “5min” or “3M”.The timestamp_offset and timestamp_rounding parameters have been
abolished.1.1.2 (2019-07-18)Fixed some altitude-related bugs: 1) It would crash when trying to
read a file that specified altitude but not location; 2) it wouldn’t
write altitude to the file it the altitude was zero.1.1.1 (2019-06-12)Fixed crash when Timestamp_rounding=None or Timestamp_offset=None.1.1.0 (2019-06-08)Added TzinfoFromString utility (moved in here from pthelma).1.0.1 (2019-06-06)Fixed error in the README (which prevented 1.0.0 from being uploaded
to PyPi).1.0.0 (2019-06-06)API change: .read() is gone, now we use a single overloaded
constructor; either HTimeseries() or HTimeseries(dataframe) or
HTimeseries(filelike).The columns and dtypes of .data are now standardized and properly
created even for empty objects (created with HTimeseries()).0.2.0 (2019-04-09)Auto detect format when reading a file0.1.0 (2019-01-14)Initial release