=========================================================
htimeseries - Hydrological and meteorological time series
=========================================================
.. image:: https://img.shields.io/pypi/v/htimeseries.svg
:target: https://pypi.python.org/pypi/htimeseries
.. image:: https://img.shields.io/travis/openmeteo/htimeseries.svg
:target: https://travis-ci.org/openmeteo/htimeseries
.. image:: https://codecov.io/github/openmeteo/htimeseries/coverage.svg
:target: https://codecov.io/gh/openmeteo/htimeseries
:alt: Coverage
.. image:: https://pyup.io/repos/github/openmeteo/htimeseries/shield.svg
:target: https://pyup.io/repos/github/openmeteo/htimeseries/
:alt: Updates
This module provides the HTimeseries class, which is a layer on top of
pandas, offering a little more functionality.
Introduction
============
::
from htimeseries import HTimeseries
ts = HTimeseries()
This creates a ``HTimeseries`` object, whose ``data`` attribute is a
pandas time series or dataframe with a datetime index. Besides ``data``,
it can have other attributes which serve as the time series' metadata.
There are also several utility methods described below.
HTimeseries objects
===================
**HTimeseries(data=None, format=None, start_date=None, end_date=None, default_tzinfo=None)**
Creates a ``HTimeseries`` object. ``data`` can 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 the ``data`` attribute and the
rest of the keyword arguments are ignored.
The ``data`` attribute should be a dataframe with two columns (besides
date): value and flags. However, in this version, ``HTimeseries`` does
not enforce that. A good idea is to create an empty ``HTimeseries``
object with ``HTimeseries()``, and then proceed to fill in its ``data``
attribute. This ensures that the dataframe will have the right columns
and dtypes.
If the ``data`` argument is a filelike object, the time series is read
from it. There must be no newline translation in ``data`` (open it with
``open(..., newline='\n')``. If ``start_date`` and ``end_date`` are
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 the ``format`` parameter. If reading in
text format, the returned object just has the ``data`` attribute set. If
reading in file format , the returned object also has attributes
``unit``, ``title``, ``comment``, ``time_step``, ``interval_type``,
``variable``, ``precision`` and ``location``. For the meaning of these
attributes, see section "File format" below.
These attributes are purely informational. In particular, ``time_step``
and 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.
The ``location`` attribute is a dictionary that has items ``abscissa``,
``ordinate``, ``srid``, ``altitude``, and ``asrid``.
The timestamps of the ``data`` attribute are aware. If ``HTimeseries()``
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 the ``timezone`` header, that time zone is used to interpret
the file's timestamps. If it is called with a filelike object that does
not contain a ``timezone`` header, ``default_tzinfo`` is used. In the
latter case, if ``default_tzinfo`` is ``None`` or unspecified, an
exception is raised. Creating an empty ``HTimeseries`` object without
specifying ``default_tzinfo`` (e.g. with ``HTimeseries()``) assumes
``default_tzinfo=ZoneInfo("UTC")``.
**.write(f, format=HTimeseries.TEXT, version=None)**
Writes the time series to filelike object ``f``. In accordance with the
formats described below, time series are written
using the CR-LF sequence to terminate lines. Care should be taken that
``f``, or any subsequent operations on ``f``, do not perform text
translation; otherwise it may result in lines being terminated with
CR-CR-LF. If ``f`` is a file, it should have been opened with
`newline="\n"`.
``version`` is ignored unless ``format=HTimeseries.FILE``. The default
``version`` is latest.
While writing, the value of the ``precision`` attribute is taken into
account.
TzinfoFromString objects
========================
::
from htimeseries imort TzinfoFromString
atzinfo = TzinfoFromString("EET (UTC+0200)")
``TzinfoFromString`` is a utility that creates and returns a tzinfo_
object from a string formatted as "+0000" or as "XXX (+0000)" or as "XXX
(UTC+0000)" (``TzinfoFromString`` is actually a tzinfo_ subclass). Its
purpose is to read the contents of the ``timezone`` parameter of the
file format (described below).
.. _tzinfo: https://docs.python.org/3/library/datetime.html#tzinfo-objects
Formats
=======
There are two formats: the *text format* is generic text format, without
metadata; the *file format* is like the text format, but additionally
contains headers with metadata.
.. _textformat:
Text format
-----------
The text format for a time series is us-ascii, one line per record,
like this:
2006-12-23 18:34,18.2,RANGE
The 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 case ``t``, or a capital
``T`` (this module produces text format using a space as date separator,
but can read text format that uses ``t`` or ``T``). 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 the ``write()`` 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.
.. _fileformat:
File format
-----------
The 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 form ``Parameter=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 entire ``Parameter=Value`` can be missing; the only
exception is the Comment parameter.
The parameters available are:
**Version**
There are four versions:
* Version 1 files are long obsolete. They did not have a header
section.
* Version 2 files must have ``Version=2`` as 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 the *Version* parameter. At least one of
the other parameters must be present. Unrecognized parameters are
ignored when reading. The old deprecated parameter names
*Nominal_offset* and *Actual_offset* are used instead of the newer
(but also deprecated) ones *Timestamp_rounding* and
*Timestamp_offset*.
* Version 4 files are the same as Version 3, except for the names of
the parameters *Timestamp_rounding* and *Timestamp_offset*.
* Version 5 files are the same as Version 4, except that
*Timestamp_rounding* and *Timestamp_offset* do not exist, and
*Time_step* is in a different format (see below).
**Unit**
A symbol for the measurement unit, like ``°C`` or ``mm``.
**Count**
The 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.
**Title**
A title for the time series.
**Comment**
A 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.
**Timezone**
The time zone of the timestamps, in the format ``{+HHmm}``, where
*+HHmm* is the offset from UTC. Examples are ``+0200`` and
``-0430``.
Format ``{XXX} (UTC{+HHmm})``, where *XXX* is a time zone name, is
also supported but deprecated. It exists only in order to be able to
read old files.
The ``TzinfoFromString`` utility (described above) can be used to
convert this string to a tzinfo_ object.
**Time_step**
In version 5, a pandas "frequency" string such as ``10min`` (10
minutes), ``H`` (hour), or ``2M`` (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 the
``time_step`` attribute of an ``HTimeseries`` object 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_rounding**
Deprecated. It might be found in old files, Version 4 or earlier,
but ``htimeseries`` will 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_rounding`` may be None, meaning that the timestamps can
be irregular.
*Timestamp_rounding* is named differently in older versions. See the
*Version* parameter above for more information.
**Timestamp_offset**
Deprecated. It might be found in old files, Version 4 or earlier,
but ``htimeseries`` will 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_offset* is named differently in older versions. See the
*Version* parameter above for more information.
**Interval_type**
Deprecated. Has one of the values ``sum``, ``average``, ``maximum``,
``minimum``, and ``vector_average``. If absent it means that the
time series values are instantaneous, they do not refer to
intervals.
**Variable**
A textual description of the variable, such as ``Temperature`` or
``Precipitation``.
**Precision**
The 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.) *Location* is three numbers,
space-separated: abscissa, ordinate, and EPSG SRID. *Altitude* is
one or two space-separated numbers: the altitude and the EPSG SRID
for altitude. The altitude SRID may be omitted.
Meta
====
Htimeseries is
| Copyright (C) 2013-2014 TEI of Epirus
| Copyright (C) 2018-2021 National Technical University of Athens
| Copyright (C) 2018-2021 Institute of Communications and Computer Systems
| Copyright (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, see http://www.gnu.org/licenses/.
Htimeseries was funded by several organizations:
* In 2013-2014 by the `TEI of Epirus`_ as part of the IRMA_ project.
* In 2018-2021 by NTUA_ and ICCS_ as part of the OpenHi_ project.
.. _ntua: http://www.ntua.gr/
.. _tei of epirus: http://www.teiep.gr/en/
.. _irma: http://www.irrigation-management.eu/
.. _iccs: https://www.iccs.gr
.. _openhi: https://openhi.net
=======
History
=======
7.0.0 (2024-04-14)
==================
- When saving in file format, the Timezone= parameter now merely
contains +HHmm.
- The HTimeseries.timezone attribute has been abolished; use
HTimeseries.data.index.tz instead.
- When initialized with a dataframe, it checks that the index is aware.
6.0.3 (2024-03-21)
==================
- Fixed error with unspecified time zone in HTimeseries objects created
empty. Now creating an empty object with ``HTimeseries()`` assumes
``default_tzinfo=ZoneInfo("UTC")``.
6.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
a ``HTimeseries`` object with a dataframe, the dataframe index
timestamps must be aware. When initializing with a filelike object,
either the filelike object must contain a ``timezone`` header or the
new ``default_tzinfo`` parameter 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 file
0.1.0 (2019-01-14)
==================
- Initial release
Raw data
{
"_id": null,
"home_page": "https://github.com/openmeteo/htimeseries",
"name": "htimeseries",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Antonis Christofides",
"author_email": "antonis@antonischristofides.com",
"download_url": "https://files.pythonhosted.org/packages/a3/a5/cac847d9a1493e00e25e3317e4e3db0f3e664c2037813fd9b10cc435c867/htimeseries-7.0.0.tar.gz",
"platform": null,
"description": "=========================================================\nhtimeseries - Hydrological and meteorological time series\n=========================================================\n\n\n.. image:: https://img.shields.io/pypi/v/htimeseries.svg\n :target: https://pypi.python.org/pypi/htimeseries\n\n.. image:: https://img.shields.io/travis/openmeteo/htimeseries.svg\n :target: https://travis-ci.org/openmeteo/htimeseries\n\n.. image:: https://codecov.io/github/openmeteo/htimeseries/coverage.svg\n :target: https://codecov.io/gh/openmeteo/htimeseries\n :alt: Coverage\n\n.. image:: https://pyup.io/repos/github/openmeteo/htimeseries/shield.svg\n :target: https://pyup.io/repos/github/openmeteo/htimeseries/\n :alt: Updates\n\nThis module provides the HTimeseries class, which is a layer on top of\npandas, offering a little more functionality.\n\nIntroduction\n============\n\n::\n\n from htimeseries import HTimeseries\n\n ts = HTimeseries()\n\nThis creates a ``HTimeseries`` object, whose ``data`` attribute is a\npandas time series or dataframe with a datetime index. Besides ``data``,\nit can have other attributes which serve as the time series' metadata.\nThere are also several utility methods described below.\n\nHTimeseries objects\n===================\n\n**HTimeseries(data=None, format=None, start_date=None, end_date=None, default_tzinfo=None)**\n\nCreates a ``HTimeseries`` object. ``data`` can be a pandas time series\nor dataframe indexed by datetime or a file-like object. If it is a\npandas object, it becomes the value of the ``data`` attribute and the\nrest of the keyword arguments are ignored.\n\nThe ``data`` attribute should be a dataframe with two columns (besides\ndate): value and flags. However, in this version, ``HTimeseries`` does\nnot enforce that. A good idea is to create an empty ``HTimeseries``\nobject with ``HTimeseries()``, and then proceed to fill in its ``data``\nattribute. This ensures that the dataframe will have the right columns\nand dtypes.\n\nIf the ``data`` argument is a filelike object, the time series is read\nfrom it. There must be no newline translation in ``data`` (open it with\n``open(..., newline='\\n')``. If ``start_date`` and ``end_date`` are\nspecified, it skips rows outside the range.\n\nThe contents of the filelike object can be in text format or file format\n(see \"formats\" below). This is usually auto-detected, but a specific\nformat can be specified with the ``format`` parameter. If reading in\ntext format, the returned object just has the ``data`` attribute set. If\nreading in file format , the returned object also has attributes\n``unit``, ``title``, ``comment``, ``time_step``, ``interval_type``,\n``variable``, ``precision`` and ``location``. For the meaning of these\nattributes, see section \"File format\" below.\n\nThese attributes are purely informational. In particular, ``time_step``\nand the other time-step-related attributes don't necessarily mean that\nthe pandas object will have a related time step (also called\n\"frequency\"). In fact, raw time series may be irregular but actually\nhave a time step. For example, a ten-minute time series might end in\n:10, :20, etc., but at some point there might be an irregularity and it\ncould continue with :31, :41, etc. Strictly speaking, such a time\nseries has an irregular step. However, when stored in a database,\nspecifying that its time step is ten minutes (because that's what it is,\nten minutes with irregularities) can help people who browse or search\nthe database contents.\n\nThe ``location`` attribute is a dictionary that has items ``abscissa``,\n``ordinate``, ``srid``, ``altitude``, and ``asrid``.\n\nThe timestamps of the ``data`` attribute are aware. If ``HTimeseries()``\nis called with a dataframe, it should have an aware datetime index. If\nit is called with a filelike object whose contents are in file format\nand contain the ``timezone`` header, that time zone is used to interpret\nthe file's timestamps. If it is called with a filelike object that does\nnot contain a ``timezone`` header, ``default_tzinfo`` is used. In the\nlatter case, if ``default_tzinfo`` is ``None`` or unspecified, an\nexception is raised. Creating an empty ``HTimeseries`` object without\nspecifying ``default_tzinfo`` (e.g. with ``HTimeseries()``) assumes\n``default_tzinfo=ZoneInfo(\"UTC\")``.\n\n**.write(f, format=HTimeseries.TEXT, version=None)**\n\nWrites the time series to filelike object ``f``. In accordance with the\nformats described below, time series are written\nusing the CR-LF sequence to terminate lines. Care should be taken that\n``f``, or any subsequent operations on ``f``, do not perform text\ntranslation; otherwise it may result in lines being terminated with\nCR-CR-LF. If ``f`` is a file, it should have been opened with\n`newline=\"\\n\"`.\n\n``version`` is ignored unless ``format=HTimeseries.FILE``. The default\n``version`` is latest.\n\nWhile writing, the value of the ``precision`` attribute is taken into\naccount.\n\nTzinfoFromString objects\n========================\n\n::\n\n from htimeseries imort TzinfoFromString\n\n atzinfo = TzinfoFromString(\"EET (UTC+0200)\")\n\n``TzinfoFromString`` is a utility that creates and returns a tzinfo_\nobject from a string formatted as \"+0000\" or as \"XXX (+0000)\" or as \"XXX\n(UTC+0000)\" (``TzinfoFromString`` is actually a tzinfo_ subclass). Its\npurpose is to read the contents of the ``timezone`` parameter of the\nfile format (described below).\n\n.. _tzinfo: https://docs.python.org/3/library/datetime.html#tzinfo-objects\n\nFormats\n=======\n\nThere are two formats: the *text format* is generic text format, without\nmetadata; the *file format* is like the text format, but additionally\ncontains headers with metadata.\n\n.. _textformat:\n\nText format\n-----------\n\nThe text format for a time series is us-ascii, one line per record,\nlike this:\n\n 2006-12-23 18:34,18.2,RANGE\n\nThe three fields are comma-separated and must always exist. In the date\nfield, the time may be missing. The character that separates the date\nfrom the time may be either a space or a lower case ``t``, or a capital\n``T`` (this module produces text format using a space as date separator,\nbut can read text format that uses ``t`` or ``T``). The second field\nalways uses a dot as the decimal separator and may be empty. The third\nfield is usually empty but may contain a list of space-separated flags.\nThe line separator should be the CR-LF sequence used in MS-DOS and\nWindows systems. Code that produces text format should always use CR-LF\nto end lines, but code that reads text format should be able to also\nread lines that end in LF only, as well as CR-CR-LF (for reasons\nexplained in the ``write()`` function above).\n\nIn order to improve performance in file writes, the maximum length of\neach time series record line is limited to 255 characters.\n\nFlags should be encoded in ASCII; there must be no characters with\ncode greater than 127.\n\n.. _fileformat:\n\nFile format\n-----------\n\nThe file format is like this::\n\n Version=2\n Title=My timeseries\n Unit=\u00b0C\n\n 2006-12-23 18:34,18.2,RANGE\n 2006-12-23 18:44,18.3,\n\nIn other words, the file format consists of a header that specifies\nparameters in the form ``Parameter=Value``, followed by a blank line,\nfollowed by the timeseries in text format. The same conventions for line\nterminators apply here as for the text format. The encoding of the\nheader section is UTF-8.\n\nClient and server software should recognize UTF-8 files with or without\nUTF-8 BOM (Byte Order Mark) in the begining of file. Writes may or may\nnot include the BOM, according OS. (Usually Windows software attaches\nthe BOM at the beginning of the file).\n\nParameter names are case insensitive. There may be white space on\neither side of the equal sign, which is ignored. Trailing white space on\nthe line is also ignored. A second equal sign is considered to be part\nof the value. The value cannot contain a newline, but there is a way to\nhave multi-lined parameters explained in the Comment parameter below.\nAll parameters except Version are optional: either the value can be\nblank or the entire ``Parameter=Value`` can be missing; the only\nexception is the Comment parameter.\n\nThe parameters available are:\n\n**Version**\n There are four versions:\n\n * Version 1 files are long obsolete. They did not have a header\n section.\n\n * Version 2 files must have ``Version=2`` as the first line of the\n file. All other parameters are optional. The file may not contain\n unrecognized parameters; software reading files with unrecognized\n parameters may raise an error.\n\n * Version 3 files do not have the *Version* parameter. At least one of\n the other parameters must be present. Unrecognized parameters are\n ignored when reading. The old deprecated parameter names\n *Nominal_offset* and *Actual_offset* are used instead of the newer\n (but also deprecated) ones *Timestamp_rounding* and\n *Timestamp_offset*.\n\n * Version 4 files are the same as Version 3, except for the names of\n the parameters *Timestamp_rounding* and *Timestamp_offset*.\n\n * Version 5 files are the same as Version 4, except that\n *Timestamp_rounding* and *Timestamp_offset* do not exist, and\n *Time_step* is in a different format (see below).\n\n**Unit**\n A symbol for the measurement unit, like ``\u00b0C`` or ``mm``.\n\n**Count**\n The number of records in the time series. If present, it need not be\n exact; it can be an estimate. Its primary purpose is to enable\n progress indicators in software that takes time to read large time\n series files. In order to determine the actual number of records,\n the records need to be counted.\n\n**Title**\n A title for the time series.\n\n**Comment**\n A multiline comment for the time series. Multiline comments are\n stored by specifying multiple adjacent Comment parameters, like\n this::\n\n Comment=This timeseries is extremely important\n Comment=because the comment that describes it\n Comment=spans five lines.\n Comment=\n Comment=These five lines form two paragraphs.\n\n The Comment parameter is the only parameter where a blank value is\n significant and indicates an empty line, as can be seen in the\n example above.\n\n**Timezone**\n The time zone of the timestamps, in the format ``{+HHmm}``, where\n *+HHmm* is the offset from UTC. Examples are ``+0200`` and\n ``-0430``.\n\n Format ``{XXX} (UTC{+HHmm})``, where *XXX* is a time zone name, is\n also supported but deprecated. It exists only in order to be able to\n read old files.\n\n The ``TzinfoFromString`` utility (described above) can be used to\n convert this string to a tzinfo_ object.\n\n**Time_step**\n In version 5, a pandas \"frequency\" string such as ``10min`` (10\n minutes), ``H`` (hour), or ``2M`` (two months). If missing or empty,\n the time series is without time step.\n\n Up to version 4, a comma-separated pair of integers; the number of\n minutes and months in the time step (one of the two must be zero).\n\n When reading from version 4 or earlier, the pair of integers is\n automatically converted to a pandas \"frequency\" string, so the\n ``time_step`` attribute of an ``HTimeseries`` object is always a\n pandas \"frequency\" string. Likewise, when writing to a version 4\n or earlier file, the pandas \"frequency\" string is automatically\n converted to the pair of integers.\n\n**Timestamp_rounding**\n Deprecated. It might be found in old files, Version 4 or earlier,\n but ``htimeseries`` will ignore it when reading and will never write\n it.\n\n A comma-separated pair of integers indicating the number of minutes\n and months that must be added to a round timestamp to get to the\n nominal timestamp. For example, if an hourly time series has\n timestamps that end in :13, such as 01:13, 02:13, etc., then its\n rounding is 13 minutes, 0 months, i.e., ``(13, 0)``. Monthly time\n series normally have a nominal timestamp of ``(0, 0)``, the\n timestamps usually being of the form 2008-02-01 00:00, meaning\n \"February 2008\" and usually rendered by application software as \"Feb\n 2008\" or \"2008-02\". Annual timestamps have a nominal timestamp which\n normally has 0 minutes, but may have nonzero months; for example, a\n common rounding in Greece is 9 months (0=January), which means that\n an annual timestamp is of the form 2008-10-01 00:00, normally\n rendered by application software as 2008-2009, and denoting the\n hydrological year 2008-2009.\n\n ``timestamp_rounding`` may be None, meaning that the timestamps can\n be irregular.\n\n *Timestamp_rounding* is named differently in older versions. See the\n *Version* parameter above for more information.\n\n**Timestamp_offset**\n Deprecated. It might be found in old files, Version 4 or earlier,\n but ``htimeseries`` will ignore it when reading and will never write\n it.\n\n A comma-separated pair of integers indicating the number of minutes\n and months that must be added to the nominal timestamp to get to the\n actual timestamp. The timestamp offset for small time steps, such as\n up to daily, is usually zero, except if the nominal timestamp is the\n beginning of an interval, in which case the timestamp offset is\n equal to the length of the time step, so that the actual timestamp\n is the end of the interval. For monthly and annual time steps, the\n timestamp offset is usually 1 and 12 months respectively. For a\n monthly time series, a timestamp offset of (-475, 1) means that\n 2003-11-01 00:00 (often rendered as 2003-11) denotes the interval\n 2003-10-31 18:05 to 2003-11-30 18:05.\n\n *Timestamp_offset* is named differently in older versions. See the\n *Version* parameter above for more information.\n\n**Interval_type**\n Deprecated. Has one of the values ``sum``, ``average``, ``maximum``,\n ``minimum``, and ``vector_average``. If absent it means that the\n time series values are instantaneous, they do not refer to\n intervals.\n\n**Variable**\n A textual description of the variable, such as ``Temperature`` or\n ``Precipitation``.\n\n**Precision**\n The precision of the time series values, in number of decimal digits\n after the decimal separator. It can be negative; for example, a\n precision of -2 indicates values accurate to the hundred, such as\n 100, 200, 300 etc.\n\n**Location**, **Altitude**\n (Versions 3 and later.) *Location* is three numbers,\n space-separated: abscissa, ordinate, and EPSG SRID. *Altitude* is\n one or two space-separated numbers: the altitude and the EPSG SRID\n for altitude. The altitude SRID may be omitted.\n\nMeta\n====\n\nHtimeseries is\n\n| Copyright (C) 2013-2014 TEI of Epirus\n| Copyright (C) 2018-2021 National Technical University of Athens\n| Copyright (C) 2018-2021 Institute of Communications and Computer Systems\n| Copyright (C) 2022 IRMASYS P.C.\n\nHtimeseries is free software: you can redistribute it and/or modify it\nunder the terms of the GNU Affero General Public License, as published\nby the Free Software Foundation; either version 3 of the License, or\n(at your option) any later version.\n\nThe software is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nlicenses for more details.\n\nYou should have received a copy of the license along with this\nprogram. If not, see http://www.gnu.org/licenses/.\n\nHtimeseries was funded by several organizations:\n\n* In 2013-2014 by the `TEI of Epirus`_ as part of the IRMA_ project.\n* In 2018-2021 by NTUA_ and ICCS_ as part of the OpenHi_ project.\n\n.. _ntua: http://www.ntua.gr/\n.. _tei of epirus: http://www.teiep.gr/en/\n.. _irma: http://www.irrigation-management.eu/\n.. _iccs: https://www.iccs.gr\n.. _openhi: https://openhi.net\n\n\n=======\nHistory\n=======\n\n7.0.0 (2024-04-14)\n==================\n\n- When saving in file format, the Timezone= parameter now merely\n contains +HHmm.\n- The HTimeseries.timezone attribute has been abolished; use\n HTimeseries.data.index.tz instead.\n- When initialized with a dataframe, it checks that the index is aware.\n\n6.0.3 (2024-03-21)\n==================\n\n- Fixed error with unspecified time zone in HTimeseries objects created\n empty. Now creating an empty object with ``HTimeseries()`` assumes\n ``default_tzinfo=ZoneInfo(\"UTC\")``.\n\n6.0.2 (2023-12-22)\n==================\n\n- Fixed crash when reading csv with aware timestamps.\n\n6.0.1 (2023-12-19)\n==================\n\n- Fixed crash when reading csv with only a date column.\n\n6.0.0 (2023-12-14)\n==================\n\n- Python 3.9 is now required (the reason for this is that\n backports.zoneinfo is behaving differently from zoneinfo).\n- Only pandas>=1.5,<2 is now supported. Pandas<1.5 probably did not\n work in 5.0.0 either, but it had not been discovered. Pandas>=2\n handles ambiguous times differently and is therefore still\n unsupported.\n- Increased CSV reading speed by two orders of magnitude.\n\n5.0.0 (2023-11-21)\n==================\n\n- Removed compatibility with pandas<1. pandas 1 and 2 are now supported.\n This helps avoid an error when reading a data file spanning a time\n interval that contains a change to or from DST.\n\n4.0.2 (2022-11-27)\n==================\n\n- Worked around an old Pandas bug related to time zones\n (https://github.com/pandas-dev/pandas/issues/11736) in order to\n maintain compatibility with Pandas 0.23 (the bug was fixed in Pandas\n 0.24). \n\n4.0.1 (2022-11-27)\n==================\n\n- Fixed packaging error where it didn't install dependency\n backports.zoneinfo on Python<3.9.\n\n4.0.0 (2022-11-22)\n==================\n\n- The timestamps of the dataframe index are now aware. When initializing\n a ``HTimeseries`` object with a dataframe, the dataframe index\n timestamps must be aware. When initializing with a filelike object,\n either the filelike object must contain a ``timezone`` header or the\n new ``default_tzinfo`` parameter must be specified.\n\n3.1.1 (2020-12-29)\n==================\n\n- Fixed incompatibility with pandas 1.2.\n\n3.1.0 (2020-12-17)\n==================\n\n- When reading a time series from a file-like object, it is now\n permitted for it to not have a flags column. In this case, an empty\n flags column is automatically added to the HTimeseries object.\n\n3.0.0 (2020-02-23)\n==================\n\n- Only Python>=3.7 is now supported.\n- When reading or writing a time series, it now checks that there are no\n duplicate timestamps and raises an exception if there are.\n\n2.0.5 (2020-01-15)\n==================\n\n- Fix pandas dependency to use pandas<1, so that Python 3.5\n compatibility is kept.\n\n2.0.4 (2020-01-08)\n==================\n\n- Fixed crash when saving in version 2 and the time step was a mere \"M\"\n or \"Y\" without multiplier.\n\n2.0.3 (2020-01-05)\n==================\n\n- Default version when writing file is now latest.\n\n2.0.1 (2020-01-04)\n==================\n\n- Fixed error when the time step was empty.\n\n2.0.0 (2020-01-04)\n==================\n\n- Changed the way the time step is specified. Instead of\n \"minutes,months\", it is now a pandas \"frequency\" offset specification\n such as \"5min\" or \"3M\".\n- The timestamp_offset and timestamp_rounding parameters have been\n abolished.\n\n1.1.2 (2019-07-18)\n==================\n\n- Fixed some altitude-related bugs: 1) It would crash when trying to\n read a file that specified altitude but not location; 2) it wouldn't\n write altitude to the file it the altitude was zero.\n\n1.1.1 (2019-06-12)\n==================\n\n- Fixed crash when Timestamp_rounding=None or Timestamp_offset=None.\n\n1.1.0 (2019-06-08)\n==================\n\n- Added TzinfoFromString utility (moved in here from pthelma).\n\n1.0.1 (2019-06-06)\n==================\n\n- Fixed error in the README (which prevented 1.0.0 from being uploaded\n to PyPi).\n\n1.0.0 (2019-06-06)\n==================\n\n- API change: .read() is gone, now we use a single overloaded\n constructor; either HTimeseries() or HTimeseries(dataframe) or \n HTimeseries(filelike).\n- The columns and dtypes of .data are now standardized and properly\n created even for empty objects (created with HTimeseries()).\n\n0.2.0 (2019-04-09) \n==================\n\n- Auto detect format when reading a file\n\n0.1.0 (2019-01-14)\n==================\n\n- Initial release\n",
"bugtrack_url": null,
"license": "GNU General Public License v3",
"summary": "Hydrological and meteorological timeseries",
"version": "7.0.0",
"project_urls": {
"Homepage": "https://github.com/openmeteo/htimeseries"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3fce3092569fd74f8ba4be2e4d3985de70e19cc30a185ea91952dfe6568d3ff9",
"md5": "fa4ed65391f58690c4a6a1aabe8ddea3",
"sha256": "1eeef6b4a9543c86fe137b834c77e51071d07915105eafc23122ff24846fa6e2"
},
"downloads": -1,
"filename": "htimeseries-7.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa4ed65391f58690c4a6a1aabe8ddea3",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 15106,
"upload_time": "2024-04-14T08:49:20",
"upload_time_iso_8601": "2024-04-14T08:49:20.145728Z",
"url": "https://files.pythonhosted.org/packages/3f/ce/3092569fd74f8ba4be2e4d3985de70e19cc30a185ea91952dfe6568d3ff9/htimeseries-7.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a3a5cac847d9a1493e00e25e3317e4e3db0f3e664c2037813fd9b10cc435c867",
"md5": "d5fb45b20b5827758142dcb05ca4c6e8",
"sha256": "82d4ea6c83c97a7c34217c967796d90fdf228781fcb6ca7818cd2a36e9be883c"
},
"downloads": -1,
"filename": "htimeseries-7.0.0.tar.gz",
"has_sig": false,
"md5_digest": "d5fb45b20b5827758142dcb05ca4c6e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 28401,
"upload_time": "2024-04-14T08:49:23",
"upload_time_iso_8601": "2024-04-14T08:49:23.110130Z",
"url": "https://files.pythonhosted.org/packages/a3/a5/cac847d9a1493e00e25e3317e4e3db0f3e664c2037813fd9b10cc435c867/htimeseries-7.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 08:49:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openmeteo",
"github_project": "htimeseries",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "htimeseries"
}
JSON
