@@ -1836,65 +1836,98 @@ def _repr_latex_(self):
1836
1836
# I/O Methods
1837
1837
1838
1838
_shared_docs ['to_excel' ] = """
1839
- Write %(klass)s to an excel sheet
1840
- %(versionadded_to_excel)s
1839
+ Write %(klass)s to an excel sheet.
1840
+
1841
+ To write a single %(klass)s to an excel .xlsx file it is only necessary to
1842
+ specify a target file name. To write to multiple sheets it is necessary to
1843
+ create an `ExcelWriter` object with a target file name, and specify a sheet
1844
+ in the file to write to. Multiple sheets may be written to by
1845
+ specifying unique `sheet_name`. With all data written to the file it is
1846
+ necessary to save the changes. Note that creating an ExcelWriter object
1847
+ with a file name that already exists will result in the contents of the
1848
+ existing file being erased.
1841
1849
1842
1850
Parameters
1843
1851
----------
1844
1852
excel_writer : string or ExcelWriter object
1845
- File path or existing ExcelWriter
1853
+ File path or existing ExcelWriter.
1846
1854
sheet_name : string, default 'Sheet1'
1847
- Name of sheet which will contain DataFrame
1855
+ Name of sheet which will contain DataFrame.
1848
1856
na_rep : string, default ''
1849
- Missing data representation
1850
- float_format : string, default None
1851
- Format string for floating point numbers
1852
- columns : sequence, optional
1853
- Columns to write
1857
+ Missing data representation.
1858
+ float_format : string, optional
1859
+ Format string for floating point numbers. For example
1860
+ ``float_format="%%.2f"`` will format 0.1234 to 0.12.
1861
+ columns : sequence or list of string, optional
1862
+ Columns to write.
1854
1863
header : boolean or list of string, default True
1855
1864
Write out the column names. If a list of strings is given it is
1856
- assumed to be aliases for the column names
1865
+ assumed to be aliases for the column names.
1857
1866
index : boolean, default True
1858
- Write row names (index)
1859
- index_label : string or sequence, default None
1860
- Column label for index column(s) if desired. If None is given , and
1867
+ Write row names (index).
1868
+ index_label : string or sequence, optional
1869
+ Column label for index column(s) if desired. If not specified , and
1861
1870
`header` and `index` are True, then the index names are used. A
1862
1871
sequence should be given if the DataFrame uses MultiIndex.
1863
- startrow :
1864
- upper left cell row to dump data frame
1865
- startcol :
1866
- upper left cell column to dump data frame
1867
- engine : string, default None
1868
- write engine to use - you can also set this via the options
1869
- ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and
1872
+ startrow : integer, default 0
1873
+ Upper left cell row to dump data frame.
1874
+ startcol : integer, default 0
1875
+ Upper left cell column to dump data frame.
1876
+ engine : string, optional
1877
+ Write engine to use, 'openpyxl' or 'xlsxwriter'. You can also set this
1878
+ via the options ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and
1870
1879
``io.excel.xlsm.writer``.
1871
1880
merge_cells : boolean, default True
1872
1881
Write MultiIndex and Hierarchical Rows as merged cells.
1873
- encoding: string, default None
1874
- encoding of the resulting excel file. Only necessary for xlwt,
1882
+ encoding : string, optional
1883
+ Encoding of the resulting excel file. Only necessary for xlwt,
1875
1884
other writers support unicode natively.
1876
1885
inf_rep : string, default 'inf'
1877
1886
Representation for infinity (there is no native representation for
1878
- infinity in Excel)
1879
- freeze_panes : tuple of integer (length 2), default None
1887
+ infinity in Excel).
1888
+ verbose : boolean, default True
1889
+ Display more information in the error logs.
1890
+ freeze_panes : tuple of integer (length 2), optional
1880
1891
Specifies the one-based bottommost row and rightmost column that
1881
- is to be frozen
1892
+ is to be frozen.
1882
1893
1883
- .. versionadded:: 0.20.0
1894
+ .. versionadded:: 0.20.0.
1884
1895
1885
1896
Notes
1886
1897
-----
1887
- If passing an existing ExcelWriter object, then the sheet will be added
1888
- to the existing workbook. This can be used to save different
1889
- DataFrames to one workbook:
1898
+ For compatibility with :meth:`~DataFrame.to_csv`,
1899
+ to_excel serializes lists and dicts to strings before writing.
1890
1900
1891
- >>> writer = pd.ExcelWriter('output.xlsx')
1892
- >>> df1.to_excel(writer,'Sheet1')
1893
- >>> df2.to_excel(writer,'Sheet2')
1894
- >>> writer.save()
1901
+ Once a workbook has been saved it is not possible write further data
1902
+ without rewriting the whole workbook.
1903
+
1904
+ See Also
1905
+ --------
1906
+ pandas.read_excel
1907
+ pandas.ExcelWriter
1908
+
1909
+ Examples
1910
+ --------
1895
1911
1896
- For compatibility with to_csv, to_excel serializes lists and dicts to
1897
- strings before writing.
1912
+ Create, write to and save a workbook:
1913
+
1914
+ >>> df1 = pd.DataFrame([['a', 'b'], ['c', 'd']],
1915
+ ... index=['row 1', 'row 2'],
1916
+ ... columns=['col 1', 'col 2'])
1917
+ >>> df1.to_excel("output.xlsx")
1918
+
1919
+ To specify the sheet name:
1920
+
1921
+ >>> df1.to_excel("output.xlsx", sheet_name='Sheet_name_1')
1922
+
1923
+ If you wish to write to more than one sheet in the workbook, it is
1924
+ necessary to specify an ExcelWriter object:
1925
+
1926
+ >>> writer = pd.ExcelWriter('output2.xlsx', engine='xlsxwriter')
1927
+ >>> df1.to_excel(writer, sheet_name='Sheet1')
1928
+ >>> df2 = df1.copy()
1929
+ >>> df2.to_excel(writer, sheet_name='Sheet2')
1930
+ >>> writer.save()
1898
1931
"""
1899
1932
1900
1933
def to_json (self , path_or_buf = None , orient = None , date_format = None ,
0 commit comments