DOC: additional linking from whatsnew and added examples for various features

Author: Chang She

doc/source/io.rst

@@ -296,6 +296,28 @@ a single date rather than the entire array.
 
    os.remove('tmp.csv')
 
+.. _io.dayfirst:
+
+International Date Formats
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+While US date formats tend to be MM/DD/YYYY, many international formats use
+DD/MM/YYYY instead. For convenience, a ``dayfirst`` keyword is provided:
+
+.. ipython:: python
+   :suppress:
+
+   data = "date,value,cat\n1/6/2000,5,a\n2/6/2000,10,b\n3/6/2000,15,c"
+   with open('tmp.csv', 'w') as fh:
+        fh.write(data)
+
+.. ipython:: python
+
+   print open('tmp.csv').read()
+
+   read_csv('tmp.csv', parse_dates=[0])
+
+   read_csv('tmp.csv', dayfirst=True, parse_dates=[0])
+
 .. _io.thousands:
 
 Thousand Separators

doc/source/merging.rst

@@ -537,6 +537,32 @@ columns:
 ``DataFrame.join`` has ``lsuffix`` and ``rsuffix`` arguments which behave
 similarly.
 
+.. _merging.ordered_merge:
+
+Merging Ordered Data
+~~~~~~~~~~~~~~~~~~~~
+
+New in v0.8.0 is the ordered_merge function for combining time series and other
+ordered data. In particular it has an optional ``fill_method`` keyword to
+fill/interpolate missing data:
+
+.. ipython:: python
+   :suppress:
+
+   A = DataFrame({'key' : ['a', 'c', 'e'] * 2,
+                  'lvalue' : [1, 2, 3] * 2,
+                  'group' : ['a', 'a', 'a', 'b', 'b', 'b']})
+   B = DataFrame({'key' : ['b', 'c', 'd'],
+                  'rvalue' : [1, 2, 3]})
+
+.. ipython:: python
+
+   A
+
+   B
+
+   ordered_merge(A, B, fill_method='ffill', left_by='group')
+
 .. _merging.multiple_join:
 
 Joining multiple DataFrame or Panel objects
@@ -575,6 +601,7 @@ For this, use the ``combine_first`` method:
 
    df1.combine_first(df2)
 
+.. _merging.combine_first.update:
 Note that this method only takes values from the right DataFrame if they are
 missing in the left DataFrame. A related method, ``update``, alters non-NA
 values inplace:

doc/source/missing_data.rst

@@ -237,6 +237,51 @@ for interpolation methods outside of the filling methods described above.
 
    plt.close('all')
 
+.. _missing_data.replace:
+
+Replacing Generic Values
+~~~~~~~~~~~~~~~~~~~~~~~~
+Often times we want to replace arbitrary values with other values. New in v0.8
+is the ``replace`` method in Series/DataFrame that provides an efficient yet
+flexible way to perform such replacements.
+
+For a Series, you can replace a single value or a list of values by another
+value:
+
+.. ipython:: python
+
+   ser = Series([0., 1., 2., 3., 4.])
+
+   ser.replace(0, 5)
+
+You can replace a list of values by a list of other values:
+
+.. ipython:: python
+
+   ser.replace([0, 1, 2, 3, 4], [4, 3, 2, 1, 0])
+
+You can also specify a mapping dict:
+
+.. ipython:: python
+
+   ser.replace({0: 10, 1: 100})
+
+For a DataFrame, you can specify individual values by column:
+
+.. ipython:: python
+
+   df = DataFrame({'a': [0, 1, 2, 3, 4], 'b': [5, 6, 7, 8, 9]})
+
+   df.replace({'a': 0, 'b': 5}, 100)
+
+Instead of replacing with specified values, you can treat all given values as
+missing and interpolate over them:
+
+.. ipython:: python
+
+   ser.replace([1, 2, 3], method='pad')
+
+
 Missing data casting rules and indexing
 ---------------------------------------
 

doc/source/visualization.rst

@@ -249,6 +249,11 @@ Scatter plot matrix
 *New in 0.8.0* You can create density plots using the Series/DataFrame.plot and
 setting `kind='kde'`:
 
+.. ipython:: python
+   :suppress:
+
+   plt.figure();
+
 .. ipython:: python
 
    ser = Series(np.random.randn(1000))

doc/source/whatsnew/v0.8.0.txt

@@ -110,12 +110,13 @@ Other new features
 - Add :ref:`limit <missing_data.fillna.limit>` argument to fillna/reindex
 - More flexible multiple function application in GroupBy, and can pass list
   (name, function) tuples to get result in particular order with given names
-- Add flexible ``replace`` method for efficiently substituting values
+- Add flexible :ref:`replace <missing_data.replace>` method for efficiently
+  substituting values
 - Enhanced :ref:`read_csv/read_table <io.parse_dates>` for reading time series
   data and converting multiple columns to dates
 - Add :ref:`comments <io.comments>` option to parser functions: read_csv, etc.
-- Add ``dayfirst`` option to parser functions for parsing international
-  DD/MM/YYYY dates
+- Add :ref`dayfirst <io.dayfirst>` option to parser functions for parsing
+  international DD/MM/YYYY dates
 - Allow the user to specify the CSV reader :ref:`dialect <io.dialect>` to
   control quoting etc.
 - Handling :ref:`thousands <io.thousands>` separators in read_csv to improve
@@ -125,7 +126,7 @@ Other new features
 - Move to klib-based hash tables for indexing; better performance and less
   memory usage than Python's dict
 - Add first, last, min, max, and prod optimized GroupBy functions
-- New ordered_merge function
+- New :ref:`ordered_merge <merging.ordered_merge>` function
 - Add flexible comparison instance methods eq, ne, lt, gt, etc. to DataFrame,
   Series
 - Improve :ref:`scatter_matrix <visualization.scatter_matrix>` plotting
@@ -137,7 +138,8 @@ Other new features
 - Add max_colwidth configuration option for DataFrame console output
 - Interpolate Series values using index values
 - Can select multiple columns from GroupBy
-- Add Series/DataFrame.:ref:`update <merging.combine_first.update>` methods for updating values in place
+- Add :ref:`update <merging.combine_first.update>` methods to Series/DataFrame
+  for updating values in place
 
 Other API changes
 ~~~~~~~~~~~~~~~~~