crosswalk¶

The parameter tables of other NCA tools: Phoenix WinNonlin, PKNCA and NonCompart.

Every tool names the same parameter differently (AUCINF_obs in Phoenix WinNonlin, aucinf.obs in PKNCA, AUCIFO in NonCompart, auc_inf_obs here), reports a fraction as a percentage and lays its results out in its own table. This module holds the crosswalk from the variables of an NCAResult to the names of each tool and writes and reads the result table of each:

Phoenix WinNonlin, the "Final Parameters Pivoted" table: one row per profile, one column per parameter (to_winnonlin, write_winnonlin, read_winnonlin, WINNONLIN_NAMES);
PKNCA, the long table of as.data.frame(pk.nca(...)): one row per profile, interval and parameter with PPTESTCD and PPORRES (to_pknca_results, write_pknca_results, read_pknca_results, PKNCA_NAMES);
NonCompart, the wide table of tblNCA: one row per profile, the CDISC PPTESTCD code of every parameter as its column (to_noncompart, write_noncompart, read_noncompart, NONCOMPART_NAMES).

A writer exports what the result carries: a parameter which the tool reports and the result does not is left out, and so is a variable which the tool has no name for. A reader returns one row per profile with the variables of pkpdutils as columns and the percentages as fractions, so that a published result table of another tool compares against NCAResult.to_dataframe column by column; a column without a pkpdutils name is dropped and logged.

The names are taken from the tools themselves: the WinNonlin columns from the Phoenix output of the NonCompart validation report (Han 2018), the PKNCA parameters from get.interval.cols() of PKNCA 0.12.1 and the NonCompart columns from sNCA of NonCompart 0.8.4. The page "Benchmark datasets" of the documentation compares every name against the output of the three tools.

to_winnonlin ¶

to_winnonlin(result)

Lay a result out as the "Final Parameters Pivoted" table of Phoenix WinNonlin.

One row per sample with the sample dimensions of the result as the sort columns, then every parameter the result carries under its WinNonlin name (WINNONLIN_NAMES) in the order Phoenix writes them. The extrapolated fractions are percentages (AUC_%Extrap_obs), as WinNonlin reports them. The table carries no units: Phoenix writes them into a row of their own, which the export of the pivoted table leaves out.

Parameters:

Name	Type	Description	Default
`result`	`ParameterResult`	the result, e.g. of `pkpdutils.nca.nca`	required

Returns:

Type	Description
`DataFrame`	The table, one row per sample.

write_winnonlin ¶

write_winnonlin(result, path)

Write the "Final Parameters Pivoted" table of a result as a csv file.

Parameters:

Name	Type	Description	Default
`result`	`ParameterResult`	the result	required
`path`	`str \| Path`	the file to write	required

Returns:

Type	Description
`DataFrame`	The table that was written, `to_winnonlin`.

read_winnonlin ¶

read_winnonlin(source)

Read a "Final Parameters Pivoted" table of Phoenix WinNonlin.

The sort columns before the first parameter (Subject) become the index, every parameter column with a pkpdutils name (WINNONLIN_NAMES) becomes that variable and the percentages become fractions. Corr_XY and any column without a name are dropped.

Parameters:

Name	Type	Description	Default
`source`	`str \| Path \| DataFrame`	the table or the path of its csv file	required

Returns:

Type	Description
`DataFrame`	One row per profile, one column per variable of `pkpdutils`.

to_noncompart ¶

to_noncompart(result)

Lay a result out as the table of NonCompart::tblNCA.

One row per sample with the sample dimensions of the result, then every parameter the result carries under its NonCompart column (NONCOMPART_NAMES; the mean residence time after NONCOMPART_NAMES_BY_ROUTE), the extrapolated fractions as percentages.

Parameters:

Name	Type	Description	Default
`result`	`ParameterResult`	the result, e.g. of `pkpdutils.nca.nca`	required

Returns:

Type	Description
`DataFrame`	The table, one row per sample.

Raises:

Type	Description
`ValueError`	if the samples of the result were given different routes, which name the mean residence time differently.

write_noncompart ¶

write_noncompart(result, path)

Write the NonCompart table of a result as a csv file.

Parameters:

Name	Type	Description	Default
`result`	`ParameterResult`	the result	required
`path`	`str \| Path`	the file to write	required

Returns:

Type	Description
`DataFrame`	The table that was written, `to_noncompart`.

read_noncompart ¶

read_noncompart(source)

Read a table of NonCompart::tblNCA.

The grouping columns before the first parameter become the index, every column with a pkpdutils name becomes that variable and the percentages become fractions. b0, CORRXY and any column without a name are dropped.

Parameters:

Name	Type	Description	Default
`source`	`str \| Path \| DataFrame`	the table or the path of its csv file	required

Returns:

Type	Description
`DataFrame`	One row per profile, one column per variable of `pkpdutils`.

to_pknca_results ¶

to_pknca_results(result)

Lay a result out as the long table of PKNCA, as.data.frame(pk.nca(...)).

One row per sample and parameter: the sample dimensions of the result, then start and end of the interval the parameter belongs to, PPTESTCD the name of the parameter in PKNCA (PKNCA_NAMES, PKNCA_NAMES_BY_ROUTE), PPORRES its value and exclude, which is empty as PKNCA leaves it for a parameter it computed. The interval is 0 to inf for a single dose, 0 to tau for a sample analysed over its dosing intervals, in the times of the analysis (relative to the dose). A parameter which is NaN gets no row, and the extrapolated fractions are percentages.

A clearance over the bioavailability is cl.obs like a clearance: PKNCA does not tell them apart.

Parameters:

Name	Type	Description	Default
`result`	`ParameterResult`	the result, e.g. of `pkpdutils.nca.nca`	required

Returns:

Type	Description
`DataFrame`	The long table.

write_pknca_results ¶

write_pknca_results(result, path)

Write the long PKNCA table of a result as a csv file.

Parameters:

Name	Type	Description	Default
`result`	`ParameterResult`	the result	required
`path`	`str \| Path`	the file to write	required

Returns:

Type	Description
`DataFrame`	The table that was written, `to_pknca_results`.

read_pknca_results ¶

read_pknca_results(source, *, route=None)

Read the long table of PKNCA into one row per profile and interval.

The grouping columns before start and end and the two bounds of the interval become the index, every PPTESTCD with a pkpdutils name becomes that variable and the percentages become fractions. A row PKNCA excluded (a non-empty exclude) is dropped, and so is a parameter without a name. The same PKNCA parameter is a clearance or a clearance over the bioavailability depending on the route (cl.obs is cl or cl_f), so the route decides the variable; without route it is recognized from the parameters PKNCA reports for it (c0 after a bolus, mrt.iv.obs after an intravenous dose, tlag and mrt.obs after an extravascular one).

Parameters:

Name	Type	Description	Default
`source`	`str \| Path \| DataFrame`	the table or the path of its csv file	required

Other Parameters:

Name	Type	Description
`route`	`Route \| str \| None`	route of the dose, recognized from the parameters by default

Returns:

Type	Description
`DataFrame`	One row per profile and interval, one column per variable.

Raises:

Type	Description
`ValueError`	if the table lacks the columns of PKNCA or the route can not be recognized from it.