# Object parameters

When instantiating objects, you can define various parameters that influence the appearance of the final product.

## Required parameters

Required parameters are mandatory and you always have to assign them, otherwise the code will fail.

**The required parameters are:**

* **data:** necessary for both ChartSeries and TableSeries objects. 
* **span:** required for Table object to define the scope.

## Optional parameters
Optional parameters allow for customization. They have default settings, which are used if no user-defined values are provided. While omitting these will not break the code, it may result in outputs that are irrelevant. After parameter name, in parenthesis, it shows what data type it expects.

All the parameters below are optional, except for the data and span:

### Report
* `title (str):` Title of the report. Placed in the front page.
* `subtitle (str):` Subtitle of the report. Placed in the front page after the title.
* `load_fonts (list[Dict[str, str]]):` fonts to be loaded for the report. Each dictionary in the list must include the following attributes:
    *  `font_family:` The family name of the font.
    *   `font_style:` The style of the font (e.g., normal, italic).
    * 	 `font_path:` Path to the font file.
* `orientation (str):` Orientation of the report, e.g., 'P' for Portrait or 'L' for Landscape.
* `unit (str):` Measurement unit used in the report, e.g., 'pt' (points), 'mm' (millimeters), 'cm' (centimeters).
* `format (str):` Paper format of the report, e.g., 'A4', 'Letter'.
* `logo (str):` Path to the logo file used in the report.
* `styles (Dict):` A dictionary defining the styling for the report and its child objects.

**Note** :Load_fonts - If Load fonts is specified, every font family needs to contain fonts for three styles: bold, italic and regular. “B”, “I”, “” (regular as empty string)

### Chart
* `title (str):` title of the chart
* `figure (plotly.graph_objs.Figure):` Plotly figure object. If provided, it will plot the given figure object.
* `apply_report_layout (bool):` If set to true, it applies the standard report layout to the provided figure (can only be used for a custom Plotly figure).
* `span (ir.Span):` Specifies the span of the chart.
* `highlight (ir.Span):` Indicates the span of the highlight.
* `show_legend (bool):` Determines whether to show or hide the legend.
* `show_grid (bool):` Controls the visibility of the grid.
* `axis_border (bool):` Allows enabling or disabling axis borders. (chart border)
* `xaxis_title (str):` Specifies the title for the X-axis.
* `yaxis_title (str):` Specifies the title for the Y-axis.
* `yaxis2_title (str):` The title for the secondary Y-axis.
* `legend_orientation (str):` Specifies the orientation of the legend, with options "v" for vertical or "h" for horizontal.
* `legend_position (str):` Indicates the position of the legend, e.g., "SO" for South Outside, "S" for South Inside.
* `series_type (str):` Type of series to display - "line" for line charts, "bar" for bar charts, "bar_contribution" for contribution bar charts; use "line" with markers_mode="markers" for marker-based charts.
* `markers_mode (str):` Display style for data points - "lines+markers" (lines with symbols/dots), "lines" (lines only), or "markers" (symbols/dots only).
* `legend (tuple):` Specifies legend labels for the series. At the chart level, this is primarily useful for multivariate series. Provide multiple labels like ("Label 1", "Label 2", ...).
* `marker_symbol (str):` Specifies the symbol name for markers, default is "asterisk".
* `zeroline (bool):` If true, it displays a horizontal line at Y=0 to help indicate the zero baseline.
* `styles (Dict):` Styles dictionary for additional customization.

### Chart series
* **data (DataPieSeries):** Data for the chart series. (required parameter)
* `span (ir.Span):` Span of the chart series.
* `yaxis (str):` Y-axis position for the chart series. Defaults to "left". Possible values: “left” or “right”.
* `legend (tuple):` Specifies the legend labels for the series. For a single series, use ("Label",). For multivariate series, provide multiple labels like ("Label 1", "Label 2", ...).
* `highlight (ir.Span):` Span of the highlight.
* `series_type (str):` Type of series to display - "line" for line charts, "bar" for bar charts, "bar_contribution" for contribution bar charts; use "line" with markers_mode="markers" for marker-based charts.
* `markers_mode (str):` Display style for data points - "lines+markers" (lines with symbols/dots), "lines" (lines only), or "markers" (symbols/dots only).
* `marker_symbol (str):` Symbol used for markers in the series, e.g., "asterisk".
* `styles (Dict):` Styles dictionary for additional customization.

### Grid
* `title (str):` Title of the grid.
* `footnotes (tuple[str, ...]):` Table footnotes referencing the table title. The value for this parameter should be provided as strings enclosed in parentheses and separated by commas, e.g., ("footnote 1", "footnote 2",).
* `ncol (int):` Number of columns in the grid.
* `nrow (int):` Number of rows in the grid.
* `layout (Dict):` layout configuration for the chart (see section “Grid layout”).
* `styles (Dict):` Styles dictionary for additional customization.

### Chapter
* `title (str):` Title of the section.
* `styles (Dict):` Styles dictionary for additional customization.

### Table
* `title (str):` Title of the table.
* **span (ir.Span):** Span of the table. **(required parameter)**
* `footnotes (tuple[str, ...]):` Table footnotes referencing the table title. The value for this parameter should be provided as strings enclosed in parentheses and separated by commas, e.g., ("footnote 1", "footnote 2",).
* `Width (int):` The maximum width allowed for rendering the table. By default, the table will use the available page width.
* `highlight (ir.Span):` Span of the highlight.
* `show_units (bool):` Option to display or hide units in the table.
* `frequency (str):` Frequency of the data in the table.
* `decimal_precision (int):` Sets number of decimal places after the decimal point.
* `compare_style (str):` Comparison style for the table series, options include "diff", "pct".
* `layout (Dict):` Layout configuration for the table (Plotly specific).
* `styles (Dict):` Styles dictionary for additional customization.

### Table Section

* `title (str):` Title of the table section.  
* `highlight (ir.Span):` Span of the highlight in the table section.  
* `show_units (bool):` To show/hide units for the table section.  
* `styles (Dict):` Styles dictionary for the table section.  

### Table series
* **data (DataPieSeries):** Data for the table series. **(required parameter)**
* `title (str):` Name of the table series / row.
* `unit (str):` The text value for the "units" column in this specific row of the table series. This defines what will be displayed as the unit for the corresponding row.
* `span (ir.Span):` Span of the table series.
* `highlight (ir.Span):` Span of the highlight in the table series.
* `compare_style (str):` Comparison style for the table series, options include "diff", "pct".
* `decimal_precision (int):` Sets number of decimal places after the decimal point.
* `comparison_series (bool):` Indicates whether the series should be displayed as a comparison series.
* `styles (Dict):` Styles dictionary for additional customization.

### Text
* `title (str):` The title of the text object.
* `text (str):` The body of the text object.
* `align (Literal["x", "c", "l", "j", "r"]):` Alignment of the text body. Default “j” - justify.
* `Markdown (bool):` Enables Markdown syntax within the text body. Default is False.
* `styles (Dict):` Styles dictionary for additional customization.

### Page Break
The PageBreak class does not take any parameters. It is used to insert a page break in the report.

### Footnote
* `text (str):` The textual data you want to hold in the Footnote object.

## Special parameters

### load_fonts
Parameters that accept a specific data structure as their value.
Rephorm requires to define and load fonts manually. Currently it has a pre-installed “OpenSans” with styles: “Regular”, “Italic” and “Bold”. If you want to use some other font, you would need to load it manually, via this parameter.

load_fonts is an optional parameter for the Report object. It expects a list of dictionaries, each specifying the details of a font you want to load.
When loading a specific font into the Rephorm package, make sure that the same font is also installed on your **local machine** — that is, the computer where your code is running.

Below is an example of the fonts data structure, where the "YujiMai" font family is defined and loaded into the report instance. 
```python
  1. fonts = [
 2.     {
 3.         "font_family": "YujiMai",
 4.         "font_style": "",
 5.         "font_path": "./testing/fonts/YujiMai.ttf",
 6.     },
 7.     {
 8.         "font_family": "YujiMai",
 9.         "font_style": "B",
10.         "font_path": "./testing/fonts/YujiMai - Copy.ttf",
11.     },
12.     {
13.         "font_family": "YujiMai",
14.         "font_style": "I",
15.         "font_path": "./testing/fonts/YujiMai - Copy (2).ttf",
16.     },
17. ]
```

It accepts `.ttf` or `.otf` font file format.

When adding a font family, you need to provide the file paths for three styles within that family:

* Regular – “font_style” as “” (empty) string
* Bold – “font_style” as “B” string
* Bold Italic – “font_style” as “I” string

After, you can pass this “fonts” list in the report as: 

```python
1. report = Rephorm.Report(load_fonts = fonts)
```
This will load custom fonts, enabling you to use them in the report through the styles dictionary.

### styles

The styles parameter works like a design setting that controls how your report looks. It passes design instructions to the related objects in your report.

The styles parameter is inheritable within objects, which means styling properties flow downward from parent objects to their children. Therefore, if we want to set a consistent highlight color for all charts throughout a report, we can specify this at the report level using the following code:

```bash
1. report = Rephorm.Report(
2.     styles={
3.         "chart": {
4.             "highlight_color": "green"
5.         }
6.     }
7. )
```

In this example, we define the styles parameter and provide a structured, nested dictionary containing the key "chart". This configuration means that any styling properties we specify for charts will automatically be applied to all chart objects subsequently added to this report instance. Specifically, we set the highlight_color property to "green", ensuring all charts in the report will utilize this consistent highlight color without requiring individual styling for each chart.

The styles parameter can be expressed using either nested dictionaries or a flattened structure with dot notation. The first example demonstrates how styling can be applied using a nested dictionary structure. However, the same configuration can also be achieved using a simplified, flat dictionary format as shown below:

```bash
1. report = Rephorm.Report(
2.     styles={
3.         "chart.highlight_color": "green"
4.     }
5. )

```
For individual chart styling, you can apply specific design parameters directly to a particular chart object instance. This approach allows you to customize styling on a specific object basis, overriding any previously established styles. For instance:

```bash
 1. chart = Rephorm.Chart(
 2.    span=chart_span,
 3.    highlight=dp.qq(2026, 1) >> dp.qq(2028, 1),
 4.    styles={
 5.        "highlight_color": "blue"
 6.    }
 7. )
```
**dp - stands for DataPie** (imported as `from rephorm import DataPie as dp`)


In this case, the specific chart will use a highlight_color of blue, even if the highlight color for charts at the report or grid level was set to yellow.

## Simplification of styles dictionary keys

When defining styles directly within an object, to simplify style definitions, you can omit the object name.

For example:

```bash
1. chart = Rephorm.Chart(
2.     span=chart_span,
3.     highlight=dp.qq(2026, 1) >> dp.qq(2028, 1),
4.     styles={
5.         "highlight_color": "blue",
6.     },
7. )
```
**dp - stands for DataPie** (imported as `from rephorm import DataPie as dp`)


## Adding styles to Report object.

As you are aware, the report object serves as the parent for all other objects. Therefore, to modify the default styles of the report, it is recommended to include a specific style dictionary when creating the report object.

## Styles dictionary keys:

Here is the full definition of the styles dictionary that details the various style options available for customization.

Information about the styles dictionary structure below:

* **First Level**: Represents parent objects (like "Table").
* **Second Level**: Represents top-level style properties for each parent.
    * If a second-level property has no further numbering: It is a direct attribute of the parent that accepts a value.
    * If a second-level property has third-level: It represents a child element with its own set of styling properties.

Style key-value pairs below come in such definition:

When applied at the Table level, it affects all rows; when applied to a specific TableSeries, it affects only that row.

To view the default values for each key, refer to **Appendix A – Styles Dictionary.**

**1. Table**

* **highlight_color (str):** Highlight color for the entire table, including all child objects (sections and series). Accepted values: Hex (`#000000`), RGB (`rgb(255, 255, 255)`), or color names (`green`).

* **title**
    - **font_style (str):** Font style for the table title. Accepted values: `"B"` (Bold), `"I"` (Italic), `""` (Regular).  
    - **font_family (str):** Font family for the table title.  
    - **font_color (str):** Font color for the table title. Accepted values: Hex (`#000000`), RGB (`rgb(255, 255, 255)`), or color names (`green`).  
    - **font_size (int):** Font size for the table title.  

* **Heading**
    - **highlight_color (str):** Highlight color for the table header. Accepted values: Hex (`#000000`), RGB (`rgb(255, 255, 255)`), or color names (`green`).  
    - **font_style (str):** Font style for the table header. Accepted values: `"B"` (Bold), `"I"` (Italic), `""` (Regular).  
    - **font_family (str):** Font family for the table header.  
    - **font_color (str):** Font color for the table header. Accepted values: Hex (`#000000`), RGB (`rgb(255, 255, 255)`), or color names (`green`).  
    - **font_size (int):** Font size for the table header.  

* **series**
    - **font_style (str):** Font style for table rows (TableSeries object). Accepted values: "B" (Bold), "I" (Italic), "" (Regular).  
    - **font_family (str):** Font family for table rows.  
    - **font_color (str):** Font color for table rows (TableSeries object). Accepted values: Hex (#000000), RGB (rgb(255, 255, 255)), or color names (green).  
    - **font_size (int):** Font size for table rows (TableSeries object).  
    - **highlight_color (str):** Highlight color for table rows (TableSeries object). Accepted values: Hex (#000000), RGB (rgb(255, 255, 255)), or color names (green).  

* **section**
    - **font_style (str):** Font style of the table section. Accepted values: "B" (Bold), "I" (Italic), "" (Regular).  
    - **font_family (str):** Font family of the table section. Table section child objects will inherit this style.  
    - **font_color (str):** Font color of the table section. Table section child objects will inherit this style. Accepted values: Hex (#000000), RGB (rgb(255, 255, 255)), or color names (green).  
    - **font_size (int):** Font size of the table section.  
    - **highlight_color (str):** Highlight color for the table section. Accepted values: Hex (#000000), RGB (rgb(255, 255, 255)), or color names (green).  

---

**2. Chart**

* **highlight_color (str):** Highlight color for the chart elements.  
* **grid_color (str):** Color for the grid lines of the chart.  
* **bg_color (str):** Background color of the chart.  
* **chart_border_color (str):** Border color of the chart.  
* **line_styles_order (str[]):** Array that defines the default sequence of line styles.  
* **line_color_order (str[]):** Array that defines the default sequence of colors for ChartSeries. Accepted value is list of (rgb) strings.  
* **bar_color_order (str[]):** Array that defines the default sequence of colors for bars in a bar chart.  
* **line_width_order (list[float | int]):** Array that defines the default sequence of line widths.  

* **legend**
    - **border_width (int):** Border width for the legend box.  
    - **bg_color (str):** Background color for the legend.  
    - **font_style (str):** Font style for the chart legend text.  
    - **font_family (str):** Font family for the chart legend text.  
    - **font_color (str):** Font color for the chart legend text.  
    - **font_size (int):** Font size for the chart legend text.  

* **title**
    - **font_style (str):** Font style for the chart title.  
    - **font_family (str):** Font family for the chart title.  
    - **font_color (str):** Font color for the chart title.  
    - **font_size (int):** Font size for the chart title.  

* **x_axis**
    - **ticks**
        - **font_size (int):** Font size for the x-axis tick marks.  
        - **font_color (str):** Font color for the x-axis tick marks.  
        - **font_family (str):** Font family for the x-axis tick marks.  
    - **label**
        - **font_size (int):** Font size for the x-axis label.  
        - **font_color (str):** Font color for the x-axis label.  
        - **font_family (str):** Font family for the x-axis label.  

* **y_axis**
    - **ticks**
        - **font_size (int):** Font size for the y-axis tick marks.  
        - **font_color (str):** Font color for the y-axis tick marks.  
        - **font_family (str):** Font family for the y-axis tick marks.  
    - **label**
        - **font_size (int):** Font size for the y-axis label.  
        - **font_color (str):** Font color for the y-axis label.  
        - **font_family (str):** Font family for the y-axis label.  

* **y_axis2**
    - **ticks**
        - **font_size (int):** Font size for the y-axis tick marks.  
        - **font_color (str):** Font color for the y-axis tick marks.  
        - **font_family (str):** Font family for the y-axis tick marks.  
    - **label**
        - **font_size (int):** Font size for the y-axis label.  
        - **font_color (str):** Font color for the y-axis label.  
        - **font_family (str):** Font family for the y-axis label.  

* **series**
    - **bar_edge_color (str):** Border color for bars in bar charts.  
    - **bar_edge_width (int):** Border width for bars in bar charts.  
    - **bar_face_color (str):** Fill color for bars in bar charts.  
    - **line_width (int):** Line width for line series.  
    - **line_style (str):** Line style for line series.  
    - **line_color (str):** Line color for line series.  
    - **marker_color (str):** Color of the marker symbol.  
    - **marker_size (int):** Size of the marker symbol.  
    - **marker_width (int):** Width of the marker symbol.  

---

**3. Report**

* **title**
    - **font_style (str):** Font style for the report title.  
    - **font_size (int):** Font size for the report title.  
    - **font_color (str):** Font color for the report title.  
    - **font_family (str):** Font family for the report title.  

* **subtitle**
    - **font_style (str):** Font style for the report subtitle.  
    - **font_size (int):** Font size for the report subtitle.  
    - **font_color (str):** Font color for the report subtitle.  
    - **font_family (str):** Font family for the report subtitle.  

* **abstract**
    - **height (int):** Height of the abstract block.  
    - **font_size (int):** Font size for the abstract text.  
    - **font_color (str):** Font color for the abstract text.  

* **footer**
    - **height (int):** Height of the footer block.  
    - **top_margin (int):** Space above the footer.  
    - **top_padding (int):** Space inside the footer.  

* **header**
    - **height (int):** Height of the header block.  
    - **bottom_margin (int):** Space below the header.  

* **font_style (str):** Font style for the report (inherited by child objects).  
* **font_family (str):** Font family for the report text.  
* **font_color (str):** Font color for the report text.  
* **page_margin_top (int):** Top page margin.  
* **page_margin_right (int):** Right page margin.  
* **page_margin_bottom (int):** Bottom page margin.  
* **page_margin_left (int):** Left page margin.  
* **title_bottom_padding (int):** Space between the title and its object.  
* **logo_height (int):** Height of the logo.  

---

**4. Text**

* **font_style (str):** Font style for the main body of the Text object.  
* **font_family (str):** Font family for the main body of the Text object.  
* **font_size (int):** Font size for the main body of the Text object.  

* **title**
    - **font_style (str):** Font style of the Text object title.  
    - **font_family (str):** Font family of the Text object title.  
    - **font_size (int):** Font size of the Text object title.  

---

**5. Footnotes**

* **font_style (str):** Font style for footnotes.  
* **font_family (str):** Font family for footnotes.  
* **font_color (str):** Font color for footnotes.  
* **font_size (int):** Font size for footnotes.  

---

**6. Grid**

* **title**
    - **font_style (str):** Font style for Grid title.  
    - **font_family (str):** Font family for Grid title.  
    - **font_color (str):** Font color for Grid title.  
    - **font_size (int):** Font size for Grid title.  

---

**7. Chapter**

* **Title**
    - **font_style (str):** Font style for Chapter title.  
    - **font_family (str):** Font family for Chapter title.  
    - **font_color (str):** Font color for Chapter title.  
    - **font_size (int):** Font size for Chapter title.  

* **font_style (str):** Font style for Chapter (inherited by child objects).  
* **font_family (str):** Font family for Chapter.  
* **font_size (int):** Font size for Chapter.  

## Customizing Chart Highlight Colors

You can customize the chart highlight color using various formats, including hex, RGB, or natural language (e.g., “g” or “green”). However, using RGB will create a solid color fill for the highlighted range. For custom colors, use RGBA (e.g., “rgba(0, 128, 0, 0.25)”) or HSLA (e.g., “hsla(120, 100%, 25%, 0.25)”).

For simple highlights, you can use natural language such as “green.” When you specify “green,” the highlight will use MATLAB’s default green color with added transparency of 25%, that is applied in the backend. 






