Update IPR docs

mathieulemieux · mathieulemieux · commit 59d1ca3ff630 · 2025-12-10T11:46:07.000-08:00
diff --git a/docs/ipr/core_variants/copy.md b/docs/ipr/core_variants/copy.md
@@ -1,6 +1,6 @@
 # Copy Variants
 
-Copy variants should be passed to the IPR python adapter in the main report content JSON.
+Copy variants should be passed to the python adapter in the main report content JSON.
 
 ```json
 {
diff --git a/docs/ipr/core_variants/expression.md b/docs/ipr/core_variants/expression.md
@@ -11,7 +11,7 @@ The kbCategory field is how IPR knows this row/entry should be treated as a vari
 
 Computing the various expression metrics is largely optional and done prior by the user prior to upload/report-creation. These metrics are displayed to the analyst reviewing the case along with the variant status. The standard fields we provide input for are listed below.
 
-As with the other variants, these should be passed to the IPR python adapter in the main report content JSON.
+As with the other variants, these should be passed to the python adapter in the main report content JSON.
 
 ```json
 {
@@ -22,7 +22,7 @@ As with the other variants, these should be passed to the IPR python adapter in
 }
 ```
 
-Each variant is an object which may contain any of the following fields (in addition to the required fields). Examples of how these fields are calculated can be found in the [scripting examples section](../../scripting/RNA_Expression_Metrics).
+Each variant is an object which may contain any of the following fields (in addition to the required fields). Examples of how these fields are calculated can be found in the [scripting examples section](../scripting/RNA_Expression_Metrics.ipynb).
 
 {%
    include-markdown "../includes/expressionVariants.md"
@@ -80,7 +80,7 @@ The use can optionally include expression density plots to allow the user to vie
 
 !!! Info
 
-    These will be passed to the report upload function via the [images section](../../optional_analyses/images) of the JSON input
+    These will be passed to the report upload function via the [images section](../optional_analyses/images.md) of the JSON input
 
 key: `expDensity\.(\S+)`
 
diff --git a/docs/ipr/core_variants/index.md b/docs/ipr/core_variants/index.md
@@ -1,3 +1,3 @@
 # About
 
-The core variant types are: expression variants, copy number variants, structural variants, and small mutations. All of these variants are matched against GraphKB and annotated by the python IPR adapter during upload to IPR.
+The core variant types are: expression variants, copy number variants, structural variants, signature variants and small mutations. All of these variants are matched against GraphKB and annotated by the python adapter during upload to IPR.
diff --git a/docs/ipr/core_variants/mutations.md b/docs/ipr/core_variants/mutations.md
@@ -1,6 +1,6 @@
 # Small Mutations
 
-Small mutations are composed of indels and single nucleotide variants. These should be passed to the IPR python adapter in the main report content JSON.
+Small mutations are composed of indels and single nucleotide variants. These should be passed to the python adapter in the main report content JSON.
 
 ```json
 {
diff --git a/docs/ipr/core_variants/structural.md b/docs/ipr/core_variants/structural.md
@@ -1,6 +1,6 @@
 # Structural Variants
 
-Structural variants should be passed to the IPR python adapter in the main report content JSON.
+Structural variants should be passed to the python adapter in the main report content JSON.
 
 ```json
 {
diff --git a/docs/ipr/index.md b/docs/ipr/index.md
@@ -1,12 +1,7 @@
 # About IPR
 
-Integrated Pipeline Reports (IPR) is the main reporting application of IPR. It is a web application
-that is used to review and curate reports which summarize the interpretation of molecular data from
-precision oncology patients.
+Integrated Pipeline Reports (IPR) is the main reporting application of PORI. It is a web application that is used to review and curate reports which summarize the interpretation of molecular data from precision oncology patients.
 
-This project is modularized across three repositories: [web client](https://github.com/bcgsc/pori_ipr_client),
-[REST API](https://github.com/bcgsc/pori_ipr_api), and a [python adapter](https://github.com/bcgsc/pori_ipr_python).
-The API and web client are servers and are provided as docker containers. The python adapter is
-used to build reports and upload them into IPR.
+This project is modularized across two repositories: a [web client](https://github.com/bcgsc/pori_ipr_client) and a [REST API](https://github.com/bcgsc/pori_ipr_api); both are servers and are provided as docker containers. It is also relying on the IPR utilities found in the [PORI Python Adapter](https://github.com/bcgsc/pori_python), used to build reports and upload them into IPR.
 
-Reports in IPR are divided into a series of sections. These are either: created by the IPR python adaptor (ex. knowledge base matches section); manually curated post-report creation (ex. analyst comments); or generated beforehand and included in the content passed to IPR via the python adaptor (ex. optional analyses).
+Reports in IPR are divided into a series of sections. These are either: created by the PORI python adaptor (ex. knowledge base matches section); manually curated post-report creation (ex. analyst comments); or generated beforehand and included in the content passed to IPR via the python adaptor (ex. optional analyses).
diff --git a/docs/ipr/optional_analyses/burden.md b/docs/ipr/optional_analyses/burden.md
@@ -32,7 +32,7 @@ of samples. The "role" determines with comparator these values are calculated in
 ## Comparators and Roles
 
 The role used by the mutation burden data is linked to the mutation burden images in the report
-that is created by the [comparators input](../comparators).
+that is created by the [comparators input](comparators.md).
 
 The images use the following key: `mutationBurden\.(barplot|density|legend)_(sv|snv|indel)\.(primary|secondary|tertiary|quaternary)`
 
diff --git a/docs/ipr/optional_analyses/circos_plots.md b/docs/ipr/optional_analyses/circos_plots.md
@@ -4,7 +4,7 @@ There are a number of fields for including circos plots in the report. Circos pl
 
 !!! Info
 
-    These will be passed to the report upload function via the [images section](../images) of the JSON input
+    These will be passed to the report upload function via the [images section](images.md) of the JSON input
 
 ## Copy Number Circos Plot
 
diff --git a/docs/ipr/optional_analyses/expression_correlation.md b/docs/ipr/optional_analyses/expression_correlation.md
@@ -6,13 +6,13 @@ keys: `expression.chart`, `expression.legend`
 
 !!! Info
 
-    These will be passed to the report upload function via the [images section](../images) of the JSON input
+    These will be passed to the report upload function via the [images section](images.md) of the JSON input
 
 This plot represents the pairwise correlation of the RNA expression of the current sample against samples from a variety of reference distributions. Often this is used as a *sanity check* of the diagnosis. It is expected that the sample should correlate most highly with other samples within the disease distribution that is most closely related to the diagnosis. It is also expected that samples with a lower tumour content/purity may show correlation with their biopsy site.
 
 ![expression correlation plot](../images/expression_correlation.png)
 
-An example of how this type of plot is created can be found in the scripting examples [here](../../scripting/RNA_Expression_Similarity).
+An example of how this type of plot is created can be found in the scripting examples [here](../scripting/RNA_Expression_Similarity.ipynb).
 
 ## Subtyping Plots
 
diff --git a/docs/ipr/optional_analyses/immune.md b/docs/ipr/optional_analyses/immune.md
@@ -74,7 +74,7 @@ Example cell type values are
 
 !!! Info
 
-    These will be passed to the report upload function via the [images section](../images) of the JSON input
+    These will be passed to the report upload function via the [images section](images.md) of the JSON input
 
 key: `cibersort.cd8_positive_t-cell_scatter`
 
@@ -88,7 +88,7 @@ key: `cibersort.combined_t-cell_scatter`
 
 !!! Info
 
-    These will be passed to the report upload function via the [images section](../images) of the JSON input
+    These will be passed to the report upload function via the [images section](images.md) of the JSON input
 
 [MiXCR Publication](https://pubmed.ncbi.nlm.nih.gov/25924071/)
 
diff --git a/docs/ipr/upload.md b/docs/ipr/upload.md
@@ -2,37 +2,36 @@
 
 ## Install
 
-Before you can generate and upload reports you will first need to install the package with pip
+Before you can generate and upload reports you will first need to install the [PORI Python Adapter library](https://pypi.org/project/pori-python/). The package has been tested for python versions from 3.9 to 3.12.
 
 ```bash
-pip install ipr
+pip install pori-python
 ```
 
-This will require python 3.6 or greater.
+The `ipr` command is available as an endpoint to the [command_interface()](../../developer_reference/pori_python/ipr/main/#command_interface) function, which call the [ipr_report()](../../developer_reference/pori_python/ipr/main/#ipr_report) function based on parsed user input. This can be used to upload a report from the command line. Use the `--help`/`-h` option to see a help menu with full options.
 
-Use the `--help`/`-h` option to see a help menu with full options.
 
 ```bash
 ipr -h
 ```
 
-Then this can be used to upload a report from the command line. Users should use the `--ipr_url` argument to point the loader to their particular instance of IPR. A similar option exists for GraphKB.
+Users should use the `--ipr_url` argument to point the loader to their particular instance of IPR. A similar option exists for GraphKB.
 
 ```bash
 ipr -c /path/to/your/json/input/file.json --ipr_url https://youriprinstance-api.com/api
 ```
 
-or as part of a script (see the [developer reference](../../developer_reference/ipr/main/#create_report))
+Report creation and upload can also be done as part of a script (see the [developer reference](../developer_reference/pori_python/ipr/main.md#ipr_report))
 
 ```python
-from ipr.main import create_report
+from ipr.main import ipr_report
 
-create_report(...)
+ipr_report(...)
 ```
 
 The pre-generated content (ex. variant calls) of the report is passed to this function via a JSON object. The various sections of this object are desribed in the core variants and optional analyses sections.
 
-The [full specification](https://raw.githubusercontent.com/bcgsc/pori_ipr_python/master/ipr/content.spec.json) for the upload can be viewed/explored via the JSON schema explorer [here](https://json-schema.app/view?url=https://raw.githubusercontent.com/bcgsc/pori_ipr_python/master/ipr/content.spec.json)
+The [full specification](https://raw.githubusercontent.com/bcgsc/pori_python/main/pori_python/ipr/content.spec.json) for the upload can be viewed/explored via the JSON schema explorer [here](https://json-schema.app/view?url=https://raw.githubusercontent.com/bcgsc/pori_python/main/pori_python/ipr/content.spec.json)
 
 Most content is optional with a few top-level elements required.
 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`# Copy Variants`
`2`	`2`
`3`		`-Copy variants should be passed to the IPR python adapter in the main report content JSON.`
	`3`	`+Copy variants should be passed to the python adapter in the main report content JSON.`
`4`	`4`
`5`	`5`	```json
`6`	`6`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`# About`
`2`	`2`
`3`		`-The core variant types are: expression variants, copy number variants, structural variants, and small mutations. All of these variants are matched against GraphKB and annotated by the python IPR adapter during upload to IPR.`
	`3`	`+The core variant types are: expression variants, copy number variants, structural variants, signature variants and small mutations. All of these variants are matched against GraphKB and annotated by the python adapter during upload to IPR.`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`# Small Mutations`
`2`	`2`
`3`		`-Small mutations are composed of indels and single nucleotide variants. These should be passed to the IPR python adapter in the main report content JSON.`
	`3`	`+Small mutations are composed of indels and single nucleotide variants. These should be passed to the python adapter in the main report content JSON.`
`4`	`4`
`5`	`5`	```json
`6`	`6`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`# Structural Variants`
`2`	`2`
`3`		`-Structural variants should be passed to the IPR python adapter in the main report content JSON.`
	`3`	`+Structural variants should be passed to the python adapter in the main report content JSON.`
`4`	`4`
`5`	`5`	```json
`6`	`6`	`{`