Release 4.1.1

.nf-core.yml

@@ -24,4 +24,4 @@ template:
     - fastqc
     - multiqc
     - igenomes
-  version: 4.1.0
+  version: 4.1.1

CHANGELOG.md

@@ -3,6 +3,19 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [[4.1.1](https://github.com/nf-core/pixelator/releases/tag/4.1.1)] - 2026-05-29
+
+### Enhancements & fixes
+
+- Improve documentation by @Aratz [#216](https://github.com/nf-core/pixelator/pull/216)
+- Update pixelator by @Aratz [#217](https://github.com/nf-core/pixelator/pull/217)
+
+### Software dependencies
+
+| Dependency  | Old version | New version |
+| ----------- | ----------- | ----------- |
+| `pixelator` | 0.27.1      | 0.27.2      |
+
 ## [[4.1.0](https://github.com/nf-core/pixelator/releases/tag/4.1.0)] - 2026-05-28
 
 ### Enhancements & fixes

README.md

@@ -62,13 +62,13 @@ For hashed PNA data (Proxiome kit v2), the samplesheet will look as follows:
 
 ```csv
 pool,hash_index,sample,sample_alias,condition,design,panel,fastq_1,fastq_2
-pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
-pool1,2,sample2,s2,case,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
-pool2,1,sample3,s3,control,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool2_R1_001.fastq.gz,pool2_R2_001.fastq.gz
+pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
+pool1,2,sample2,s2,case,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
+pool2,1,sample3,s3,control,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool2_R1_001.fastq.gz,pool2_R2_001.fastq.gz
 ```
 
 > [!NOTE]
-> For an example with non-hashed PNA data (Proxiome kit v1), see [Proxiome v1 samplesheet](../assets/samplesheet_proxiome_v1.csv)
+> For an example with non-hashed PNA data (Proxiome kit v1), see [Proxiome v1 samplesheet](../assets/example_samplesheet_proxiome_v1.csv)
 
 > [!WARNING]
 > Panel and design names have been completely renamed in pixelator 0.26

assets/example_samplesheet_proxiome_v2.csv

@@ -1,3 +1,3 @@
 pool,hash_index,sample,sample_alias,condition,design,panel,fastq_1,fastq_2
-pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
-pool1,2,sample2,s2,treatment,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
+pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
+pool1,2,sample2,s2,treatment,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz

assets/schema_input.json

@@ -6,7 +6,7 @@
     "type": "array",
     "items": {
         "type": "object",
-        "required": ["sample", "design", "fastq_1"],
+        "required": ["sample", "sample_alias", "condition", "design", "fastq_1"],
         "additionalProperties": false,
         "allOf": [
             {
@@ -31,25 +31,18 @@
                             "const": "proxiome-v2"
                         },
                         "panel": {
-                            "const": "proxiome-v2-immuno-155-v1.0"
+                            "pattern": "^proxiome-v2-"
                         }
                     },
                     "required": ["design", "panel"]
                 },
                 "then": {
                     "required": ["pool", "hash_index"],
-                    "errorMessage": "The `pool` and `hash_index` columns are required for `proxiome-v2` design with panel `proxiome-v2-immuno-155-v1.0`."
+                    "errorMessage": "The `pool` and `hash_index` columns are required for `proxiome-v2` design with a `proxiome-v2` panel."
                 }
             }
         ],
         "properties": {
-            "sample": {
-                "type": "string",
-                "pattern": "^\\S+$",
-                "errorMessage": "Sample name must be provided and cannot contain spaces",
-                "description": "Sample name (no spaces).",
-                "meta": ["id"]
-            },
             "pool": {
                 "type": "string",
                 "pattern": "^\\S+$",
@@ -60,6 +53,23 @@
                 "type": "integer",
                 "meta": ["hash_index"]
             },
+            "sample": {
+                "type": "string",
+                "pattern": "^\\S+$",
+                "errorMessage": "Sample name must be provided and cannot contain spaces",
+                "description": "Sample name (no spaces).",
+                "meta": ["id"]
+            },
+            "sample_alias": {
+                "type": "string",
+                "description": "Alternative sample name.",
+                "meta": ["sample_alias"]
+            },
+            "condition": {
+                "type": "string",
+                "description": "Experimental condition for the sample.",
+                "meta": ["condition"]
+            },
             "design": {
                 "type": "string",
                 "pattern": "^\\S+$",
@@ -91,26 +101,6 @@
                 "pattern": "^\\S+\\.f(ast)?q\\.gz$",
                 "errorMessage": "FastQ file for reads 2 cannot contain spaces and must have extension '.fq.gz' or '.fastq.gz'",
                 "description": "Optional FASTQ(.gz) path for read 2 (no spaces)."
-            },
-            "condition": {
-                "type": "string",
-                "description": "Optional experimental condition for the sample.",
-                "meta": ["condition"]
-            },
-            "reference_condition": {
-                "type": "string",
-                "description": "Optional reference condition for differential analysis.",
-                "meta": ["reference_condition"]
-            },
-            "sample_alias": {
-                "type": "string",
-                "description": "Optional alternative sample name.",
-                "meta": ["sample_alias"]
-            },
-            "alternative_condition": {
-                "type": "string",
-                "description": "Optional alternative condition for the sample.",
-                "meta": ["alternative_condition"]
             }
         }
     }

docs/output.md

@@ -105,7 +105,7 @@ of the graph (i.e. the putative cells) and assign a unique ID to each component.
 
 From this step and onwards, the output file are in PXL format. This is a custom format used by pixelator to make PNA data easier
 to work with. Internally it used duckdb to store the data. For more information on the PXL format, please refer to
-the [pixelator documentation](https://software.pixelgen.com/pixelator/outputs/pxl-format/).
+the [pixelator documentation](https://software.pixelgen.com/pixelator/outputs/pxl-file/).
 
 <details markdown="1">
 <summary>Output files</summary>
@@ -248,7 +248,7 @@ The output from this step will be placed in the output folder root.
 
 </details>
 
-[Nextflow](https://www.nextflow.io/docs/latest/tracing.html) provides excellent functionality for generating various reports relevant to the running and execution of the pipeline. This will allow you to troubleshoot errors with the running of the pipeline, and also provide you with other information such as launch commands, run times and resource usage.
+[Nextflow](https://docs.seqera.io/platform-cloud/reports/overview) provides excellent functionality for generating various reports relevant to the running and execution of the pipeline. This will allow you to troubleshoot errors with the running of the pipeline, and also provide you with other information such as launch commands, run times and resource usage.
 
 ### Output directory structure
 

docs/usage.md

@@ -4,7 +4,66 @@
 
 > _Documentation of pipeline parameters is generated automatically from the pipeline schema and can no longer be found in markdown files._
 
-## Introduction
+## Quick start
+
+The typical command for running the pipeline is as follows:
+
+```bash
+nextflow run nf-core/pixelator \
+    -profile docker,cells_8k \
+    --input ./samplesheet.csv \
+    --outdir ./results \
+    --technology proxiome-v2
+```
+
+This will launch the pipeline with the `docker` configuration profile, and resource configurations
+for 8000 cells. If you have samples with 1000 cells as input, pick the `cells_1k` profile instead.
+See below for more information about profiles.
+
+Note that the pipeline will create the following files in your working directory:
+
+```bash
+work                # Directory containing the nextflow working files
+<OUTDIR>            # Finished results in specified location (defined with --outdir)
+.nextflow_log       # Log file from Nextflow
+# Other nextflow hidden files, eg. history of pipeline runs and old logs.
+```
+
+## Parameters
+
+nf-core/pixelator can take a wide range of parameters, three of which are mandatory:
+
+- `--input`: the path to your samplesheet
+- `--outdir`: the directory where the `.pxl` files and the experiment summary will be saved.
+- `--technology`: the workflow to use to process your data (`proxiome_v1` or `proxiome_v2`), depending on the kit that was used to process the samples.
+
+Detailed documentation about each parameter can be found at [https://nf-co.re/pixelator/parameters/](https://nf-co.re/pixelator/parameters/).
+
+If you wish to repeatedly use the same parameters for multiple runs, rather than specifying each flag in the command, you can specify these in a params file.
+
+Pipeline settings can be provided in a `yaml` or `json` file via `-params-file <file>`.
+
+> [!WARNING]
+> Do not use `-c <file>` to specify parameters as this will result in errors. Custom config files specified with `-c` must only be used for [tuning process resource specifications](https://nf-co.re/docs/running/run-pipelines#configuring-pipelines), other infrastructural tweaks (such as output directories), or module arguments (args).
+
+The above pipeline run specified with a params file in yaml format:
+
+```bash
+nextflow run nf-core/pixelator -profile docker,cells_8k -params-file params.yaml
+```
+
+with:
+
+```yaml title="params.yaml"
+input: './samplesheet.csv'
+outdir: './results/'
+<...>
+```
+
+You can also generate such `YAML`/`JSON` files via [nf-core/launch](https://nf-co.re/launch).
+
+> [!NOTE]
+> By default, processes from nf-core/pixelator will use the path defined in `TMPDIR` to store temporary file. If this variable is not defined, they will fallback to `/tmp`.
 
 ## Samplesheet input
 
@@ -15,37 +74,16 @@ Use this parameter to specify its location.
 --input '[path to samplesheet file]'
 ```
 
-We provide example samplesheets for [Proxiome v1 data](../assets/samplesheet_proxiome_v1.csv)
-and [Proxiome v2 data](../assets/samplesheet_proxiome_v2.csv), that can be used as a template to
+We provide example samplesheets for [Proxiome v1 data](../assets/example_samplesheet_proxiome_v1.csv)
+and [Proxiome v2 data](../assets/example_samplesheet_proxiome_v2.csv), that can be used as a template to
 create your own samplesheet.
 
 ### Format
 
 The samplesheet is a CSV or TSV formatted file with a few required and some optional columns.
 You can export to CSV from spreadsheet programs such as Microsoft Excel, Google Sheets and LibreOffice Calc.
 
-Following table provides an overview of all possible columns in the samplesheet.
-The samplesheet can have as many columns as you desire, however, there is a strict requirement for the first 5 columns
-to match those defined in the table below.
-
-> [!WARNING]
-> It is important that you select a panel file that matches the kit lot version you are
-> using for your experiment. Using a mismatched panel file will lead to incorrect antibody
-> assignments and erroneous results.
->
-> An updated list of which panel files correspond to which kit lot versions can be found
-> on the [Pixelgen Technologies website](https://www.pixelgen.com/panel-file-for-data-processing/)
-
-Below is an example of a simple samplesheet with two samples.
-
-```csv
-sample,sample_alias,condition,design,panel,fastq_1,fastq_2
-sample1,s1,control,pna-2,proxiome-immuno-155-v2,sample1_R1_001.fastq.gz,sample1_R2_001.fastq.gz
-sample2,s2,treatment,pna-2,proxiome-immuno-155-v2,sample2_R1_001.fastq.gz,sample2_R2_001.fastq.gz
-```
-
-Columns not defined in the table below are ignored by the pipeline but can be useful
-to add extra information for downstream processing.
+The following table provides an overview of all possible columns in the samplesheet.
 
 | Column                              | Required                  | Description                                                                                                                                                              |
 | ----------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -64,6 +102,22 @@ One of them has to be specified.
 
 The pipeline will auto-detect whether a sample is single- or paired-end based on if both `fastq_1` and `fastq_2` or only `fastq_1` is present in the samplesheet.
 
+> [!WARNING]
+> It is important that you select a panel file that matches the kit lot version you are
+> using for your experiment. Using a mismatched panel file will lead to incorrect antibody
+> assignments and erroneous results.
+>
+> An updated list of which panel files correspond to which kit lot versions can be found
+> on the [Pixelgen Technologies website](https://www.pixelgen.com/panel-file-for-data-processing/)
+
+Below is an example of a simple samplesheet with two samples.
+
+```csv
+sample,sample_alias,condition,design,panel,fastq_1,fastq_2
+sample1,s1,control,proxiome-v1,proxiome-v1-immuno-155-v1.1,sample1_R1_001.fastq.gz,sample1_R2_001.fastq.gz
+sample2,s2,treatment,proxiome-v1,proxiome-v1-immuno-155-v1.1,sample2_R1_001.fastq.gz,sample2_R2_001.fastq.gz
+```
+
 ### Pooling samples
 
 Pooled samples are supported with the Proxiome v2 kit. To process them, include
@@ -73,8 +127,8 @@ Typically there are 8 hashed samples per pool (numbering 1 to 8).
 
 ```csv
 pool,hash_index,sample,sample_alias,condition,design,panel,fastq_1,fastq_2
-pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
-pool2,2,sample2,s2,treatment,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
+pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
+pool2,2,sample2,s2,treatment,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_R1_001.fastq.gz,pool1_R2_001.fastq.gz
 ```
 
 ### Multiple runs of the same sample
@@ -91,19 +145,19 @@ Below is an example for the same sample sequenced across 3 lanes:
 
 ```csv title="samplesheet.csv"
 sample,sample_alias,condition,design,panel,fastq_1,fastq_2
-uropod_control_1,s1,control,pna-2,proxiome-immuno-155-v2,uropod_control_S1_L001_R1_001.fastq.gz,uropod_control_S1_L001_R2_001.fastq.gz
-uropod_control_1,s1,control,pna-2,proxiome-immuno-155-v2,uropod_control_S1_L002_R1_001.fastq.gz,uropod_control_S1_L002_R2_001.fastq.gz
-uropod_control_1,s1,control,pna-2,proxiome-immuno-155-v2,uropod_control_S1_L003_R1_001.fastq.gz,uropod_control_S1_L003_R2_001.fastq.gz
+uropod_control_1,s1,control,proxiome-v1,proxiome-v1-immuno-155-v1.1,uropod_control_S1_L001_R1_001.fastq.gz,uropod_control_S1_L001_R2_001.fastq.gz
+uropod_control_1,s1,control,proxiome-v1,proxiome-v1-immuno-155-v1.1,uropod_control_S1_L002_R1_001.fastq.gz,uropod_control_S1_L002_R2_001.fastq.gz
+uropod_control_1,s1,control,proxiome-v1,proxiome-v1-immuno-155-v1.1,uropod_control_S1_L003_R1_001.fastq.gz,uropod_control_S1_L003_R2_001.fastq.gz
 ```
 
 The same approach applies when pooled hashed samples are sequenced again:
 
 ```csv title="samplesheet.csv"
 pool,hash_index,sample,sample_alias,condition,design,panel,fastq_1,fastq_2
-pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_run1_R1_001.fastq.gz,pool1_run1_R2_001.fastq.gz
-pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_run2_R1_001.fastq.gz,pool1_run2_R2_001.fastq.gz
-pool1,2,sample2,s2,treatment,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_run1_R1_001.fastq.gz,pool1_run1_R2_001.fastq.gz
-pool1,2,sample2,s2,treatment,proxiome-v2,proxiome-v2-immuno-155-v1.0,pool1_run2_R1_001.fastq.gz,pool1_run2_R2_001.fastq.gz
+pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_run1_R1_001.fastq.gz,pool1_run1_R2_001.fastq.gz
+pool1,1,sample1,s1,control,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_run2_R1_001.fastq.gz,pool1_run2_R2_001.fastq.gz
+pool1,2,sample2,s2,treatment,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_run1_R1_001.fastq.gz,pool1_run1_R2_001.fastq.gz
+pool1,2,sample2,s2,treatment,proxiome-v2,proxiome-v2-immuno-155-v2.0,pool1_run2_R1_001.fastq.gz,pool1_run2_R2_001.fastq.gz
 ```
 
 ### Relative paths
@@ -168,54 +222,9 @@ A list of available panels can be listed by running following command:
 pixelator single-cell-pna --list-panels
 ```
 
-## Running the pipeline
-
-The typical command for running the pipeline is as follows:
-
-```bash
-nextflow run nf-core/pixelator --input ./samplesheet.csv --outdir ./results  -profile docker,cells_8k --technology proxiome-v2
-```
-
-This will launch the pipeline with the `docker` configuration profile, and resource configurations
-for 8000 cells. If you have samples with 1000 cells as input, pick the `cells_1k` profile instead.
-See below for more information about profiles.
-
-Note that the pipeline will create the following files in your working directory:
-
-```bash
-work                # Directory containing the nextflow working files
-<OUTDIR>            # Finished results in specified location (defined with --outdir)
-.nextflow_log       # Log file from Nextflow
-# Other nextflow hidden files, eg. history of pipeline runs and old logs.
-```
-
-If you wish to repeatedly use the same parameters for multiple runs, rather than specifying each flag in the command, you can specify these in a params file.
-
-Pipeline settings can be provided in a `yaml` or `json` file via `-params-file <file>`.
-
-> [!WARNING]
-> Do not use `-c <file>` to specify parameters as this will result in errors. Custom config files specified with `-c` must only be used for [tuning process resource specifications](https://nf-co.re/docs/running/run-pipelines#configuring-pipelines), other infrastructural tweaks (such as output directories), or module arguments (args).
-
-The above pipeline run specified with a params file in yaml format:
-
-```bash
-nextflow run nf-core/pixelator -profile docker,cells_8k -params-file params.yaml
-```
-
-with:
-
-```yaml title="params.yaml"
-input: './samplesheet.csv'
-outdir: './results/'
-<...>
-```
-
-You can find an extensive example of a `params.yaml` file with all options and
-documentation in comments [here](../assets/params-file.yml).
-You can also generate such `YAML`/`JSON` files via [nf-core/launch](https://nf-co.re/launch).
-
-> [!NOTE]
-> By default, processes from nf-core/pixelator will use the path defined in `TMPDIR` to store temporary file. If this variable is not defined, they will fallback to `/tmp`.
+Alternatively, these panel files can be downloaded from the [`pixelator`
+repository](https://github.com/PixelgenTechnologies/pixelator/tree/main/src/pixelator/pna/resources/panels).
+These files can then serve as a base for further customizations.
 
 ### Updating the pipeline