Specification: GxP Analytics Tool (Script, Notebook, Dashboard, or Query)

This is a ready-to-use specification for one analytics tool. It exists so that testing has a pass criterion: without a written statement of what the tool must do, “we tested it” means “we ran it and the output looked reasonable”. Replace every <<FILL: ...>> placeholder with your own specifics, set your document numbers and dates, and route it through your normal document control, review, and approval before testing begins. A worked filled specimen follows. This content is educational reference, not legal or regulatory advice; verify each cited regulation against the current source before you rely on it.

Document control header

How to write requirements in this document

Every requirement carries a unique ID, is written so that a tester can observe pass or fail without interpretation, and states one thing. Use the prefixes below so that a traceability table sorts sensibly and a reader can see at a glance what a failing test threatens.

Wording that is not testable: “the tool shall handle errors appropriately”, “performance shall be acceptable”, “results shall be accurate”. Wording that is testable: “on encountering a non-numeric value in the timepoint column, the tool shall write no output file and shall exit with a non-zero status and a message naming the offending row”.

1. Purpose and intended use

2. Inputs

2.1 Input sources

2.2 Input contract

State the expected schema exactly. A tool that accepts whatever it is given cannot be tested.

2.3 Input requirements

3. Processing logic and calculation

3.1 Narrative description

<<FILL: describe the processing in ordered steps, in plain language, so a reviewer who does not read code can follow what happens to the data from input to output>>

3.2 The calculation

State the equation where a calculation is performed. Where the method comes from a compendial procedure, a pharmacopoeial chapter, an SOP, or a statistical reference, name it and describe the method in your own words rather than reproducing the source text.

<<FILL: the equation, with every term defined and its units stated>>

Terms:

Source method implemented: <<FILL: name, version, and clause>>

3.3 Exclusion, filtering, and grouping rules

Any rule that removes or partitions data is a calculation and must be specified, because it is where results most often silently diverge from expectation.

3.4 Calculation requirements

4. Rounding and significant figures

Rounding is stated explicitly because it is a common source of silent disagreement between a homegrown tool and a validated source system, and because “the two systems round differently” is a finding that is trivially avoidable and frequently found.

5. Outputs

5.1 Output definition

5.2 Output schema

5.3 Provenance block

Every GxP output carries a provenance block so that the result can be traced back to the exact logic and data that produced it.

5.4 Output requirements

6. Error handling

The governing rule is fail loudly. A GxP tool that cannot compute a correct answer must produce no answer, visibly, rather than a plausible wrong one.

7. Environment and dependencies

Pinned manifest:

<<FILL: exact runtime and library versions, one per line>>

8. Access and source protection

9. For low-code dashboards: per-measure specification

Complete this section instead of, or in addition to, sections 3 to 5 where the tool is a dashboard or a visual data-preparation flow. Each calculated measure, each transformation step, each calculated column, and each relationship gets its own row and its own requirement ID, because each one is independently capable of producing a wrong number.

9.1 Data model

9.2 Calculated measures

9.3 Query and transformation steps

9.4 Calculated columns

9.5 Refresh and stale data

9.6 Row-level security and filters

10. Limits of validity

State what the tool is not valid for. This is the section that stops a tool being reused in a context nobody assessed.

11. Requirement-to-test traceability

Every requirement traces to at least one test case, and every test case traces back to at least one requirement. A requirement with no test is unverified. A test with no requirement is testing something nobody specified.

Coverage statement: <<FILL: number>> requirements, <<FILL: number>> test cases, <<FILL: number>> requirements with no test case (must be zero, or each justified below).

Justified exceptions: <<FILL: none, or requirement ID and reason>>

12. Approvals

Filled specimen

Specification extract for tool ANL-0007, a class A Python script that fits a stability regression for drug product potency and produces the values reported in the annual product review. Identifiers, products, and dates are illustrative.

Purpose and intended use

Produces, for one lot, the ordinary least squares slope of potency against time, the predicted potency at the proposed shelf life, and the one-sided lower 95% confidence bound on that prediction. The output populates the stability trend table in the annual product review and supports the conclusion that the lot remains within the potency specification through the proposed shelf life. Used by the stability lead, once per lot per annual review cycle. Output is the record of origin: no other system computes these values. Implements the linear regression approach described in the stability data evaluation section of <<FILL: internal SOP-ID>>, which is written against the ICH stability guidance series. This tool does not perform poolability testing across lots and does not set the shelf life; it produces the per-lot inputs to that assessment.

Input contract

Calculation

Ordinary least squares regression of potency on time, fitted per lot per storage condition.

Slope:

b = sum_i (t_i - t_bar) * (y_i - y_bar) / sum_i (t_i - t_bar)^2

Intercept:

a = y_bar - b * t_bar

Predicted potency at the proposed shelf life T:

y_hat(T) = a + b * T

One-sided lower 95% confidence bound on the mean response at T:

LCB(T) = y_hat(T) - t_(0.95, n-2) * s * sqrt( 1/n + (T - t_bar)^2 / Sxx )

Rounding

Reference dataset and expected values agreed before testing

Lot <<FILL: lot ID>>, long-term condition, seven timepoints.

Hand-computed intermediate values, verified independently by the statistician before the tool was run:

Error handling extract

Environment

python==3.11.8
numpy==1.26.4
pandas==2.2.1
scipy==1.12.0
statsmodels==0.14.1

Built into container image digest sha256:9c1d4b..., executed on analytics server ANSRV-01.

Traceability extract

Coverage: 14 requirements in this extract, verified by 14 distinct test cases, with 0 requirements left without a test case. The counts match rather than the test cases outnumbering the requirements, because TC-12 verifies two requirements at once, IN-05 and OUT-03, in a single inspection of the output provenance block.

Dashboard specimen extract, for contrast

For tool ANL-0021, the class B release results dashboard, the equivalent section 9 rows read as follows for two of the fourteen measures.

Frozen verification dataset agreed before testing: 52 lots disposed in the period, of which 47 were disposed within 30 days. Expected MEA-03 = 47 / 52 = 90.4%. In the same period, 1,240 reportable results with 18 flagged out of specification. Expected MEA-07 = 18 / 1,240 = 1.45%.

Row-level security requirement for the same dashboard: the site A role sees 31 of the 52 lots and the site B role sees 21, and the two together account for all 52 with no lot visible to both.

Common inspection findings this specification prevents

• Testing was performed but no document states what the tool was supposed to do, so no result could have failed.
• The tool and the validated source system disagree on a value at a rounding boundary, and neither rounding rule was ever specified.
• A filter or date-window rule quietly changes the population the calculation runs on, and nobody can say what the intended population was.
• A specification limit, a shelf-life value, or a conversion constant is hard-coded in the tool, and it silently became wrong when the product changed.
• The tool substitutes a default when a value is missing, and the substitution is invisible in the output.
• A dashboard has fourteen calculated measures and one paragraph of documentation, so only the measures someone happened to think of were tested.
• Nobody can state what the tool is not valid for, so it was reused for a second product with different assumptions.
• Requirements exist but half of them have no corresponding test, and the gap was not visible because no traceability table was maintained.
• A refresh failed and the dashboard kept showing last week’s data with no indication, so a reviewer looked at stale results believing they were current.

How to adapt this specification

1. Scale the depth to the risk class. A class C tool may need only sections 1, 3.2, 4, 6, and 10, and one page is a legitimate specification for it. Class A tools get everything.
2. Delete sections 3 to 5 for a pure dashboard and complete section 9 instead, or complete both where a dashboard sits on top of a script.
3. Write the calculation section before writing any code. Specifications written after the code are descriptions of what the code happens to do, and they never catch the error you were trying to catch.
4. Agree the reference dataset and the hand-computed expected values with the independent reviewer before the tool is run against them. Expected values derived from the tool’s own output are not a test.
5. State the rounding rule of the downstream system you must agree with, by name, in RND-03. This one line prevents a recurring class of discrepancy investigation.
6. Keep the traceability table in this document rather than in a separate matrix for small tools. A separate matrix is worth maintaining only when the requirement count runs to the dozens.
7. Treat section 10 as the most reused part of the document. When someone asks whether the tool can also be used for a different product or a different condition, the answer is either already there or the tool needs reclassification.
8. Confirm the current status of every cited regulation and guidance in the governing SOP before issue.