<commit_before>.. currentmodule:: pandas
.. _timeseries:

.. ipython:: python
   :suppress:

   from datetime import datetime
   import numpy as np
   np.random.seed(123456)
   from pandas import *
   randn = np.random.randn
   randint = np.random.randint
   np.set_printoptions(precision=4, suppress=True)
   from dateutil.relativedelta import relativedelta
   from pandas.tseries.api import *
   from pandas.tseries.offsets import *

********************************
Time Series / Date functionality
********************************

pandas has proven very successful as a tool for working with time series data,
especially in the financial data analysis space. With the 0.8 release, we have
further improved the time series API in pandas by leaps and bounds. Using the
new NumPy ``datetime64`` dtype, we have consolidated a large number of features
from other Python libraries like ``scikits.timeseries`` as well as created
a tremendous amount of new functionality for manipulating time series data.

In working with time series data, we will frequently seek to:

  - generate sequences of fixed-frequency dates and time spans
  - conform or convert time series to a particular frequency
  - compute "relative" dates based on various non-standard time increments
    (e.g. 5 business days before the last business day of the year), or "roll"
    dates forward or backward

pandas provides a relatively compact and self-contained set of tools for
performing the above tasks.

Create a range of dates:

.. ipython:: python

   # 72 hours starting with midnight Jan 1st, 2011
   rng = date_range('1/1/2011', periods=72, freq='H')
   rng[:5]

Index pandas objects with dates:

.. ipython:: python

   ts = Series(randn(len(rng)), index=rng)
   ts.head()

Change frequency and fill gaps:

.. ipython:: python

   # to 45 minute frequency and forward fill
   converted = ts.asfreq('45Min', method='pad')
   converted.head()

Resample:

.. ipython:: python

   # Daily means
   ts.resample('D', how='mean')


.. _timeseries.representation:

Time Stamps vs. Time Spans
--------------------------

Time-stamped data is the most basic type of timeseries data that associates
values with points in time. For pandas objects it means using the points in
time to create the index

.. ipython:: python

   dates = [datetime(2012, 5, 1), datetime(2012, 5, 2), datetime(2012, 5, 3)]
   ts = Series(np.random.randn(3), dates)

   type(ts.index)

   ts

However, in many cases it is more natural to associate things like change
variables with a time span instead.

For example:

.. ipython:: python

   periods = PeriodIndex([Period('2012-01'), Period('2012-02'),
                          Period('2012-03')])

   ts = Series(np.random.randn(3), periods)

   type(ts.index)

   ts

Starting with 0.8, pandas allows you to capture both representations and
convert between them. Under the hood, pandas represents timestamps using
instances of ``Timestamp`` and sequences of timestamps using instances of
``DatetimeIndex``. For regular time spans, pandas uses ``Period`` objects for
scalar values and ``PeriodIndex`` for sequences of spans. Better support for
irregular intervals with arbitrary start and end points are forth-coming in
future releases.

.. _timeseries.daterange:

Generating Ranges of Timestamps
-------------------------------

To generate an index with time stamps, you can use either the DatetimeIndex or
Index constructor and pass in a list of datetime objects:<commit_msg>WIP some to_datetime docs additions<commit_after>.. currentmodule:: pandas
.. _timeseries:

.. ipython:: python
   :suppress:

   from datetime import datetime
   import numpy as np
   np.random.seed(123456)
   from pandas import *
   randn = np.random.randn
   randint = np.random.randint
   np.set_printoptions(precision=4, suppress=True)
   from dateutil.relativedelta import relativedelta
   from pandas.tseries.api import *
   from pandas.tseries.offsets import *

********************************
Time Series / Date functionality
********************************

pandas has proven very successful as a tool for working with time series data,
especially in the financial data analysis space. With the 0.8 release, we have
further improved the time series API in pandas by leaps and bounds. Using the
new NumPy ``datetime64`` dtype, we have consolidated a large number of features
from other Python libraries like ``scikits.timeseries`` as well as created
a tremendous amount of new functionality for manipulating time series data.

In working with time series data, we will frequently seek to:

  - generate sequences of fixed-frequency dates and time spans
  - conform or convert time series to a particular frequency
  - compute "relative" dates based on various non-standard time increments
    (e.g. 5 business days before the last business day of the year), or "roll"
    dates forward or backward

pandas provides a relatively compact and self-contained set of tools for
performing the above tasks.

Create a range of dates:

.. ipython:: python

   # 72 hours starting with midnight Jan 1st, 2011
   rng = date_range('1/1/2011', periods=72, freq='H')
   rng[:5]

Index pandas objects with dates:

.. ipython:: python

   ts = Series(randn(len(rng)), index=rng)
   ts.head()

Change frequency and fill gaps:

.. ipython:: python

   # to 45 minute frequency and forward fill
   converted = ts.asfreq('45Min', method='pad')
   converted.head()

Resample:

.. ipython:: python

   # Daily means
   ts.resample('D', how='mean')


.. _timeseries.representation:

Time Stamps vs. Time Spans
--------------------------

Time-stamped data is the most basic type of timeseries data that associates
values with points in time. For pandas objects it means using the points in
time to create the index

.. ipython:: python

   dates = [datetime(2012, 5, 1), datetime(2012, 5, 2), datetime(2012, 5, 3)]
   ts = Series(np.random.randn(3), dates)

   type(ts.index)

   ts

However, in many cases it is more natural to associate things like change
variables with a time span instead.

For example:

.. ipython:: python

   periods = PeriodIndex([Period('2012-01'), Period('2012-02'),
                          Period('2012-03')])

   ts = Series(np.random.randn(3), periods)

   type(ts.index)

   ts

Starting with 0.8, pandas allows you to capture both representations and
convert between them. Under the hood, pandas represents timestamps using
instances of ``Timestamp`` and sequences of timestamps using instances of
``DatetimeIndex``. For regular time spans, pandas uses ``Period`` objects for
scalar values and ``PeriodIndex`` for sequences of spans. Better support for
irregular intervals with arbitrary start and end points are forth-coming in
future releases.


.. _timeseries.converting:

Converting to Timestamps
------------------------

To convert a list or Series of datetimes or strings (or a mixture, or NAs),
you can use the ``to_datetime`` function:

.. ipython:: python

    pd.to_datetime(['Jul 31, 2009', '2010-01-10'])

    pd.to_datetime(['2005/11/23', '2010.12.31''])

If you use dates start with the dayfirst (European style), you can pass
the dayfirst flag:

.. ipython:: python

    to_datetime(['12-13-2012'], dayfirst=True)

*There is a known bug that this falls back to not dayfirst if there are
inconsistent date formats.*

Pass ``coerce=True`` to convert data to ``NaT`` (not a time):

.. ipython:: python

    pd.to_datetime(['2009-07-31', 'asd'], coerce=True)

.. _timeseries.daterange:

Generating Ranges of Timestamps
-------------------------------

To generate an index with time stamps, you can use either the DatetimeIndex or
Index constructor and pass in a list of datetime objects:
{'fraction_non_alphanumeric': 0.1143302585422892, 'fraction_numerical': 0.024684942185266987, 'mean_word_length': 3.606822262118492, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1042152', 'n_tokens_mistral': 2293, 'n_tokens_neox': 2078, 'n_words': 927}