Xlsxreport

Released: 2024-09-21

Internal
- Added GitHub Actions for automatic testing of the package.

Documentation
- Updated the README.md file to provide more useful information about what XlsxReport is and the status of the project.
- Updated the DOCUMENTATION.md file with detailed information on how the table template works and which formatting options are available.
- Added an example output file from MaxQuant that can be used together with the "maxquant.yaml" template to create a formatted Excel report.

----------------------------------------------------------------------------------------

Released: 2024-04-23

This release introduces a new public interface for reading YAML template files, applying the template to a table (which now creates compiled table sections), and for writing compiled table sections to an Excel worksheet. In addition, with the `ReportBuilder` class a convenient high-level interface is introduced for creating (multi-tab) Excel reports from tables and table templates. Moreover, the YAML table templates have been partially redesigned, breaking backward compatibility.

Added
- The `TableTemplate` class serves as the representation of a YAML template file in Python. It provides methods for both loading a YAML template file and saving to a YAML template file.
- When creating a `TableTemplate` instance, the template is checked for type errors. If type errors are detected, a `ValueError` is raised.
- Similarly, when loading a template from a YAML file, a non-parseable YAML file or the presence of type errors will raise a `ValueError`.
- The `TableTemplateSections` class provides methods for adding, removing, and changing the order of sections from a template.
- The `TableTemplate` class, and the classes for the four table template sections, provide a `__str__` method for viewing the content of the template.
- Added the `validate` module, which offers functions for validating YAML template file integrity, checking if data types in a template are correct, and confirming that the sections and parameters of a template are in accordance with the template specifications (which is refered to as the template schema).
- Add a new template section type called "**label tag section**". This section resembles the "tag section" but offers the ability to specify a list of additional labels for further column filtering after tag matching. It's primarily designed for in-code template creation or updating of existing sections, where the labels are known or extracted from the data.
- The column order of the "label tag section" is determined by the order of the labels in the template.
- Introduced new functionality to the `xlsxreport` console script.
- The command for generating a formatted Excel file is now `xlsxreport compile`.
- Added an option to open the compiled Excel file using the `--reveal` flag.
- The `xlsxreport appdir` command now reveals the location of the app directory.
- Added an option to open the appdata directory in the file explorer using the `--reveal` flag.
- Setting up the app directory can be accomplished with `xlsxreport appdir --setup` which creates the app directory and copies default report template files.
- The `xlsxreport validate` command allows validating a YAML template file, with detected issues being printed to the console.
- Added color highlighting to printed messages from command line scripts and improved printed message texts.

Changed
- (!) Changed how the `xlsxreport` console scripts works. Now all scripts are called with `xlsxreport` plus a specific command.
- Renamed the Excel worksheet generated by the `xlsxreport compile` script from "Proteins" to "Report".
- (!) Replaced the term "config" with "template" throughout the codebase.
- (!) Replaced the template keyword "groups" with "sections" in YAML template files.
- (!) Replaced the template keyword "args" with "settings" in YAML template files.
- (!) Replaced the term "report template" with "table template", which refers to the YAML template file as well as its Python representation the `TableTemplate` class.
- (!) Replaced the internally used term "TableSection" with "CompiledTableSection", to clearly distinguish between template and compiled table sections.
- Renamed `writer.TableSectionWriter` to `writer.SectionWriter`.
- Renamed `compiler.prepare_table_sections` to `compiler.prepare_compiled_sections`.
- (!) Replaced the "tag sample section" category with a simpler "tag section".
- The "tag" parameter of the "tag section" is used as a regular expression pattern instead of simply looking for an exact match. This change allows for more flexible matching of columns and makes the additional selection of samples via a "sample_extraction_tag" obsolete.
- (!) Removed the `comparison_group` parameter from the **comparison section**, which is now identified by the simultaneous presence of the parameters "tag" and "columns".
- (!) Renamed the template section parameter "conditional" to "conditional_format".
- (!) Renamed the template section parameter "column_conditional" to "column_conditional_format".
- Changed the default value of the "evaluate_log2_transformation" setting to False.
- Changed the default value of the "write_supheader" setting to False.
- When no supheader name is specified the supheader cells are not merged and no format is applied .
- Changed the default format from `0` to the standard Excel format `General`.
- When attempting to use an invalid format for compiling an Excel report, the compiler will now apply no format and issue a warning instead of raising an exception. This change ensures consistent behavior for both conditional and standard cell formats. This change is also reflected in the validation module. When an invalid format description is identified, it now creates an error with an error level ERROR instead of CRITICAL, indicating that the template could still be utilized to create an Excel format despite the encountered issue.
- Updated the default templates "maxquant.yaml" and "fragpipe.yaml" to reflect the changes in the template schema and to improve the clarity of the generated Excel report.
- `appdir.get_template_path` raises `FileNotFoundError` instead of returning `None` when the specified template does not exist.

Removed
- (!) Removed the `cassiopeia_report` command line script.
- (!) Removed the `xlsxreport_setup` script.
- (!) Removed `xlsxreport.writer.Datasheet` and `xlsxreport.writer.Reportbook`, which previously represented the public interface for creating a formatted Excel report.
- (!) Removed the default templates "msreport_lfq_protein.yaml" and "cassiopeia.yaml".
- (!) Removed the "sample_extraction_tag" parameter from the table template settings.

Internal
- Replaced the `appdirs` library with `platformdirs`, as `appdirs` is officially deprecated.

----------------------------------------------------------------------------------------

Released: 2023-11-22

Changed
- `groups` in the yaml config file with the setting "border: True" will now always have
a thick border line in the written Excel file (which is a border type 2 in Excel).
- NaN entries are now always written as an empty string to the Excel file.

Added
- Added additional parameters to the settings (`args`) section of the yaml config file,
which allow to control behaviors that were previously applied by default.
- `write_supheader` (default: True), determines if a supheader row will be written.
- `evaluate_log2_transformation` (default: True), if True values are evaluated before
applying a log2 transformation to `groups` that have the "log2: True" setting.
- `remove_duplicate_columns` (default: True), if True columns that were already used
in a compiled `group` are removed from subsequent groups.
- `add_autofilter` (default: True), if True adds an Excel auto filter to header row.
- `freeze_cols` (default: 1), if larger than 0 applies freeze pane to the Excel file.
The selected row for freezing will always be the header row, the selected column
corresponds to the specified value.
- Added additional settings to `groups` in the yaml config file.
- "hide_section: True" results in sections being hidden in the Excel file.
- A "conditional" setting can now be added to "feature" groups, which allows applying
a conditional format to all columns of the group.

Removed
- (!) Removed parameters `border_weight` and `nan_symbol` from the settings (`args`)
section of the yaml config file.

Internal
- Changed the build config file to `pyproject.toml`.
- Added extensive unit testing.
- Added an integration test for generating a formatted Excel file.

----------------------------------------------------------------------------------------

Released: 2023-10-11

Fixes
- Fixes a mix up of columns in comparison groups that was caused when an experiment
comparison was the exact substring of another, for example "exp1 vs exp2" and
"exp3exp1 vs exp2".

----------------------------------------------------------------------------------------

Released: 2023-03-14

Fixes
- Supheader not being written when a block contains only one column.

----------------------------------------------------------------------------------------

Released: 2023-01-27

Changed
- (!) Renamed console script "xlsx_report" to "xlsxreport"
- (!) Renamed console script "xlsx_report_setup" to "xlsxreport_setup"
- Columns retrieved for "Sample group" blocks now must contain the group tag and a
sample name. Columns not containing a sample name are ignored. For example, using the
tag "Intensity" will no longer include columns such as "Intensity" or
"Intensity total".
- Renamed the "qtable_proteins.yaml" config file to "msreport_lfq_protein.yaml"
- Updated "msreport_lfq_protein.yaml" config file
- Changed columns in the "protein_features" block
- Changed comparison group tag from "logFC" to "Ratio [log2]"
- Added new format for "Ratio [log2]"
- Changed formatting of the quantified_events block
- Updated console ouput for the "xlsxreport_setup" console script.

----------------------------------------------------------------------------------------