<?xml version="1.0" encoding="UTF-8"?>
<chapter id="details.reports">
<chapterinfo>
  <authorgroup>
    <author> &Ace.Jones; &Ace.Jones.mail; </author>
    <author> &Jack.H.Ostroff; &Jack.H.Ostroff.mail; </author>
  </authorgroup>
  <date>2024-12-01</date>
  <releaseinfo>5.2.0</releaseinfo>
</chapterinfo>
<title>Reports</title>

<para>
  The Reports View is a tabbed display.  The <guilabel>Reports</guilabel> tab is
  always displayed, and lists all available reports, grouped under the headings
  listed and described below.  You can click <quote>></quote> to expand or
  collapse the specific reports under each heading.  When you open any report, it is
  displayed in an additional tab, labelled with the name of that report.
</para>

<para>
  The list of reports is always sorted first by the group name (by number) and then
  by report name.  Clicking the <quote>Reports</quote> heading will reverse the
  sort order.  You can also click the <quote>Comment</quote> header to sort by the
  report comment instead of name.  The report's name and comment can be set or edited
  on the <guilabel>General</guilabel> tab of the <link
  linkend="details.reports.config">Report Configuration</link> dialog.
</para>

<sect1 id="details.reports.avail"><title>Available Reports</title>
<screenshot>
  <screeninfo>reports view</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="reports_view_list.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>reports view</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
</para>

<sect2><title>Income and Expenses</title>
<para>
  The reports in this section show your income and expenses either for the current
  month, for each month in the current year, or for each year.  Of course, the
  duration of the overall report and the duration captured by each column can be
  configured to your liking.  Various Graphs and Pie Charts also may be produced.
</para>
</sect2>

<sect2><title>Net Worth</title>
<para>
  Here there are reports that describe your net worth, either at the current moment,
  every month for the current year, or every year of your history.  In addition,
  there is a 7-day Cash Flow Forecast and a Net Worth Graph.  There are also reports
  to get the balances for all of your accounts at any given point in time.
</para>
</sect2>

<sect2 id="details.reports.transaction"><title>Transactions</title>
<para>
  This section includes reports that list individual transactions.  This is the
  best way to print your account register for a specific period of time.  The
  transactions printed can be grouped together according to your liking by
  choosing the appropriate report, such as:
  <itemizedlist>
    <listitem><para>By Account</para></listitem>
    <listitem><para>By Category</para></listitem>
    <listitem><para>By Month or Week</para></listitem>
    <listitem><para>By Payee</para></listitem>
    <listitem><para>By Reconciliation Status</para></listitem>
    <listitem><para>By Tag</para></listitem>
  </itemizedlist>
</para>
</sect2>

<sect2><title>Cash Flow</title>
<para>
  The Cash Flow report is similar to a Transaction report, but it displays all
  cash-flow related transactions for the specified period, which defaults to the
  current month.
</para>
</sect2>

<sect2><title>Investments</title>
<para>
  These reports help you keep track of your investments.  They only include
  investment accounts.  There are a variety of presentation filters and styles,
  as shown in this partial list.
</para>

<itemizedlist>
  <listitem>
    <para> Investment Transactions: Similar to a Transactions report, but it includes
    share prices and quantities.  </para>
  </listitem>
  <listitem>
    <para>Investment Holdings by Account: Shows the current shares, prices, and
    values for each account.</para>
  </listitem>
  <listitem>
    <para>Investment Holdings by Type: Same as the previous report, but organizes the
    accounts by type (Stock, Mutual Fund, &etc;)</para>
  </listitem>
  <listitem>
    <para>Investment Performance by Account: Shows the annualized performance over
    any period of time.  This performs a cash flow analysis of all money coming into
    and going out of the account.  As a result, this is a very accurate picture of
    how well your investments are doing.</para>
  </listitem>
  <listitem>
    <para>Investment Performance by Type: Same as the previous report, but organizes
    the accounts by type (Stock, Mutual Fund, &etc;)</para>
  </listitem>
</itemizedlist>

<para>
  There are also graphs for Investment Prices and Investment Worth.
</para>
</sect2>

<sect2><title>Taxes</title>
<para>
  The tax reports are just like the transactions reports, with the addition that only
  Tax related categories are included.  This allows you to flag certain categories as
  being tax-related, and then get one big report at the end of the year to see the
  transactions for those categories all in one place.  They may be listed either by
  Category or by Payee, and for the last fiscal year.
</para>
</sect2>

<sect2><title>Budgeting</title>
<para>
  The budgeting reports are similar to net worth reports, but the reports can display
  the budget for a given year, or even compare it to the actual income and expenses
  for the same period.
</para>
</sect2>

<sect2><title>Forecast</title>
<para>
  The forecast reports are just like the net worth reports, but they use the
  information to display forecast information.  You can display the information at
  various levels and for the time frame of your choosing.
</para>
</sect2>

<sect2><title>Information</title>
<para>
  These reports display non-transaction information about accounts, loans, and
  schedules.
</para>
</sect2>

<sect2><title>Charts</title>
<para>
  If <link linkend="details.reports.charts">Charts</link> are enabled, this section
  lists all the reports which are marked to display a graphical chart as the default.
  They are also listed in one of the other sections, but they are aggregated here for
  your easy reference.
</para>
</sect2>

<sect2><title>Favorite Reports</title>
<para>
  This section lists all the reports you have marked as a favorite in the report
  configuration dialog.  They are still listed in one of the other sections, but they
  are aggregated here for your easy reference.  Favorite reports can also be included
  on the Home View for even easier reference.
</para>
</sect2>
</sect1>

<sect1 id="details.reports.working"><title>Working With Reports</title>
<para>
  There are a number of actions you can take on each report.  You can access some
  these by right-clicking the report name in the list of reports, which brings up the
  <guilabel>Report options</guilabel> context menu.  Alternately, once you have run a
  report, there are buttons across the top of the view to invoke each of these:
</para>

<itemizedlist>
  <listitem>
    <para> Chart: Only present if the report is capable of displaying a chart.
    Clicking this option toggles between the report and the chart.
    </para>
  </listitem>
  <listitem>
    <para>Configure report: Change the properties of this report.  You can customize
    the report to your liking and save it for future use.  See the next section for
    more details</para>
  </listitem>
  <listitem>
    <para>New report: Create a new, customized report based on the selected
    report.</para>
  </listitem>
  <listitem>
    <para>Export report: Reports can be exported, or saved, in &HTML; or CSV format.
    &HTML; is intended to preserve the displayed formatting of the report.  CSV
    exports the data underlying the report.</para>
  </listitem>
  <listitem>
    <para>Delete report: Customized reports can be deleted.  The default reports that
    ship with &kmymoney; cannot be deleted.</para>
  </listitem>
  <listitem>
    <para>
      The <guilabel>Close report</guilabel> button was removed in 5.2.  To close the
      current report tab, click the small <guilabel>x</guilabel> to the right of the
      report name on the tab.
    </para>
  </listitem>
</itemizedlist>
</sect1>

<sect1 id="details.reports.config"><title>Configuring Reports</title>

<sect2><title>Working with custom reports</title>
<para>
  You can configure the default reports or create your own from them by selecting
  <guilabel>New report</guilabel>, and then configuring the new report.  When you
  click <guilabel>Configure report</guilabel> you will be presented with the Report
  Tab of the <guilabel>Report Configuration</guilabel> dialog.  Initially, the new
  report it is named the same as the old report with <quote>(Customized)</quote>
  added to the end.  You can change the name to whatever you want.  You can even name
  your custom reports the same as a default report, or the same as another custom
  report.  You can use the Comment field to further distinguish reports.
</para>

<para>
  The Report Configuration dialog has a <guilabel>Report</guilabel> tab and a
  <guilabel>Filters</guilabel> tab, which each have a number of subtabs.  Each subtab
  displays options for configuring different aspects of the report.  Note that
  specific subtabs and options within them may not appear if they are not relevant to
  the report being configured.
</para>
</sect2>

<sect2 id="details.reports.config.report"><title>Report Tab</title>
<para>
  This is where you configure general information about the report as well as controlling
  details about what data is presented and how it is presented.
</para>

<sect3 id="details.reports.config.general"><title>General subtab</title>
<screenshot>
  <screeninfo>report configuration report tab general subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="reports_configuration_general.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>report configuration report tab general subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  Here you set the basic properties of the report.
  <itemizedlist>
    <listitem>
      <para>Report Name: Choose or edit the name for this report.</para>
    </listitem>
    <listitem>
      <para>Comment: Enter a comment to help you remember the details of this report
      and identify it if the name is the same as any other report.</para>
    </listitem>
    <listitem>
      <para>Convert values to base currency: Select this option to convert all values
      in the report to your base currency.  Leave it unchecked if you'd like to see
      values in their original currency.  If currencies are not converted, then
      subtotals will not be shown.</para>
    </listitem>
    <listitem>
      <para>Mark as favorite report: Check this to cause this report to show up on
      the Home View and in the group of <guilabel>Favorite Reports</guilabel>.</para>
    </listitem>
    <listitem>
      <para>
        Skip value if price is zero: This option is only used for investments reports
        which show prices instead of balances as all other reports do.  Selecting
        this option includes prices only if there is an actual price for the date;
        otherwise 0 will be shown.  In a graph, the value will be skipped.  If this
        option is off, the last existing price is shown for a period.  If it is on,
        in a table <quote>0</quote> is shown, and in a chart a linear interpolation
        for the missing values will be performed.
      </para>
    </listitem>
  </itemizedlist>
</para>
</sect3>

<sect3 id="details.reports.config.rowscolumns"><title>Rows/Columns subtab</title>
<para>
  This is where you configure how you would like the rows and columns of the report
  to be selected and organized.  This tab presents different configuration options
  depending on the style of report you are configuring.
</para>

<screenshot>
  <screeninfo>report configuration report tab rows/columns subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="reports_configuration_rowscolumns.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>report configuration report tab rows/columns subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  For income/expense and net worth reports:
  <itemizedlist>
    <listitem>
      <para>Budgets: If you have any <link
      linkend="details.budgets">budgets</link> defined, you can select one as well as
      whether differences between budget and actual amounts should be propagated from
      one time period to the next</para>
    </listitem>
    <listitem>
      <para>Totals: Choose whether to display a row and/or column for total
      amounts.</para>
    </listitem>
    <listitem>
      <para>Rows: Choose whether to base the report on Income and Expense
      (Categories) or on Asset and Liability accounts.</para>
    </listitem>
    <listitem>
      <para>Detail: Choose the level of detail required for this report.</para>
      
      <para>The following levels of detail are available:
      <itemizedlist>
        <listitem><para>All: Show every category or account.</para></listitem>
        <listitem><para>Top-Level: Show only the highest-level categories or
        accounts, and roll up the sums of the subordinate categories or accounts into
        those values.</para></listitem>
        <listitem><para>Groups: Show only the totals of the income and expense or
        asset and liabilities.</para></listitem>
        <listitem><para>Totals: Show only the grand totals.</para></listitem>
      </itemizedlist>
      </para>
    </listitem>

    <listitem>
      <para>In addition you can specify whether or not to include scheduled and/or
      transfer transactions and unused accounts or categories.</para>
    </listitem>
  </itemizedlist>
</para>

<para>
  For transaction reports:
  <itemizedlist>
    <listitem>
      <para>Organize by: Choose how to group the transactions in this report.</para>
    </listitem>
    <listitem>
      <para>Show Columns: Choose which columns should be shown in the report. The
      date and transaction amount are always shown.</para>
    </listitem>
    <listitem>
      <para>Include only Tax Categories: Only show categories which have been marked
      as tax-related.</para>
    </listitem>
    <listitem>
      <para>Include only Investment Accounts: Only show transactions from investment
      accounts.</para>
    </listitem>
    <listitem>
      <para>Include only Loan Accounts: Only show transactions from loan
      accounts.</para>
    </listitem>
    <listitem>
      <para>Include transfers: Unless this is checked, transfer transactions are not
      included in transaction reports</para>
    </listitem>
    <listitem>
      <para>Hide Split Transaction Details: When this option is available, it lets
      you specify that only the total amount of a split transaction is to be
      displayed.</para>
    </listitem>
    <listitem>
      <para>Hide totals: Selecting this prevents Total lines from being calculated
      and displayed</para>
    </listitem>
  </itemizedlist>
</para>
</sect3>
</sect2>

<sect2 id="details.reports.config.chart"><title>Chart Subtab</title><para>
  This subtab allows you to configure what the report should look like when it is
  displayed as a chart.  See the <link linkend="details.reports.charts">Graphs &amp;
  Charts</link> section for more explanation of the charting functions.
</para>

<screenshot>
  <screeninfo>report configuration report tab chart subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="reports_configuration_chart.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>report configuration report tab chart subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<itemizedlist>
  <listitem>
    <para>Chart Type: The visual format of chart desired.</para>
  </listitem>
  <listitem>
    <para>Show grid lines: Whether to print horizontal and vertical grid lines on the
    chart.</para>
  </listitem>
  <listitem>
    <para>Draw values on chart: Whether to print the data values on the chart itself
    for chosen data points.</para>
  </listitem>
  <listitem>
    <para>Show chart by default: Whether this report should first be displayed as a
    chart when it's opened.</para>
  </listitem>
  <listitem>
    <para>Logarithmic vertical axis: normally the vertical axis is linear.</para>
  </listitem>
  <listitem>
    <para>Plot expenses downwards: normally both income and expenses are plotted
    upwards.</para>
  </listitem>
  <listitem>
    <para>Line width: The width of data lines on the chart, specified in
    pixels.</para>
  </listitem>
</itemizedlist>
</sect2>

<sect2 id="details.reports.config.range"><title>Range Subtab</title>
<para>
  The Range subtab has two sections, <guilabel>Date range</guilabel> and
  <guilabel>Data range</guilabel> for controlling the limits and subdivisions of the
  displayed data.  Note that this only controls the display, to control the data used
  by &kmymoney; to create the report, see the section on the <link
  linkend="details.reports.config.report">Filters tab</link>.
</para>

<screenshot>
  <screeninfo>report configuration report tab range subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="reports_configuration_range.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>report configuration report tab range subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<sect3><title>Date range</title>
<para>
  Selecting one of the descriptive values from the <guilabel>Range</guilabel>
  dropdown automatically sets the values of the <guilabel>From</guilabel> and
  <guilabel>To</guilabel> date fields.  You can override either or both of those
  dates, in which case the first dropdown will show <quote>User defined</quote>.
</para>

<para>
  The <guilabel>Ticks</guilabel> dropdown controls the placement of ticks on the date
  axis of the chart.
</para>
</sect3>

<sect3><title>Data range</title>
<para>
  This lets you control the limits, ticks, and labels on the vertical data axis.  The
  default value for the <guilabel>Range</guilabel> dropdown is
  <quote>Automatic</quote>, lets &kmymoney; choose reasonable values for the other
  fields.  If you select <quote>User defined</quote> you need to specify all the
  other fields.  <guilabel>From</guilabel> and <guilabel>To</guilabel> set the lower
  and upper limits of the axis.  <guilabel>Major tick length</guilabel> and
  <guilabel>Minor tick length</guilabel> control the positioning of larger and
  smaller tick marks along the axis.  <guilabel>Labels Precision</guilabel> controls
  the number of decimal places used in the numbers displayed along the axis.
</para>
</sect3>
</sect2>

<sect2><title>Filters tab</title>
<para>
  The filters tab has several subtabs, which can be used to filter or limit the data
  &kmymoney; uses to prepare the report.  These are the same subtabs used to control
  searching for transactions.  Please refer to the <link
  linkend="details.search">Search Transactions</link> section for details on those
  tabs.</para>
</sect2>

<sect2 id="details.reports.config.plugin"><title>Report Plugin Configuration</title>
<para>
  Behind the scenes, Reports are actually implemented as a plugin in &kmymoney;, and
  there are some items which can be configured through the <link
  linkend="details.settings.plugins.reports">Reports View Plugin Configuration</link>
  dialog.
</para>

<screenshot>
  <screeninfo>report plugin configuration</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="reports_configuration_plugin.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>report plugin configuration</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  <guilabel>Maximum number of legend items to display</guilabel> limits the number of
  items to list in the legend of the graph or chart display of a report.  This can be
  useful if there are enough items that the legend would otherwise overwhelm the main
  display.
</para>

<para>
  <guilabel>Charts line width</guilabel> is the default width in pixels of any lines
  in the chart display of a report.
</para>

<para>
  <guilabel>Charts palette</guilabel> gives some choice in the array of colors used
  in graphs and chart displays of a report.
</para>

<para>
  Since the graph and chart displays of reports are shown using HTML, the
  <guilabel>Default CSS file</guilabel> lets you provide a css file to customize
  these displays.
</para>
</sect2>
</sect1>

<sect1 id="details.reports.charts"><title>Graphs &amp; Charts</title>

<sect2><title>Viewing as a Chart</title>
<para>
  Many reports can be viewed in either textual form or graphical (chart) form.  The
  same report configuration parameters are used in either case.  You can easily jump
  back and forth between the textual and graphical forms by pressing the
  <guibutton>Chart</guibutton> or <guibutton>Report</guibutton> buttons along the top
  of the Report View.
</para>

<para>
  Please pay attention to the amount of data you choose to display on a chart.  If
  you are not careful, using the same configuration for both textual and graphical
  forms means it's possible to configure a chart to be visually cluttered,
  unappealing, and uninformative. &kmymoney; will not force you to keep your charts
  readable and useful!  Also be aware that some reports will take a long time to
  calculate and display if too much is included.
</para>
</sect2>

<sect2><title>Available Chart Types</title>

<sect3><title>Line Graph</title>
<para>
  A line graph is one of the simplest forms of a chart.  There is one line for each
  series.  Usually, a series is data from a single account or category over time; see
  below for more details.  The time periods stretch out along the bottom axis, and
  the currency values are along the left axis.
</para>

<para>
  The detail level for each line is controlled in the <link
  linkend="details.reports.config.rowscolumns">Rows/Columns</link> Subtab of chart
  configuration.  If you choose the <quote>Top-Level</quote> detail level, there will
  be one line for each of the top-most accounts or categories, which shows the sum
  total of all underlying accounts or categories.  If you choose
  <quote>Groups,</quote> it will instead show one line each for Income, Expenses,
  Assets, or Liabilities, depending on the other settings.
</para>
</sect3>

<sect3><title>Bar Graph</title>
<para>
  The bar graph works exactly the same as the line graph, except there is one bar for
  each series in each time slice.
</para>
</sect3>

<sect3><title>Pie Chart</title>
<para>
  The pie chart is the simplest chart type available.  It shows data from only one
  time slice, as opposed to showing the values across time.  This chart shows only
  the data from the totals column of whatever report is selected.  If your report is
  configured to NOT convert values to the base currency, there will be no totals
  column, in which case this report is not useful.
</para>
</sect3>

<sect3><title>Ring Chart</title>
<para>
  The ring chart is very similar to a pie chart, except there is one
  <quote>ring</quote> for each time slice in the report.
</para>
</sect3>
</sect2>
</sect1>
</chapter>
