schrodinger.application.jaguar.macro_pka_utils module

class schrodinger.application.jaguar.macro_pka_utils.TableData(name, mol, pop, pH_pop)

Bases: tuple

mol: Mol

Alias for field number 1

name: str

Alias for field number 0

pH_pop: float

Alias for field number 3

pop: float

Alias for field number 2

class schrodinger.application.jaguar.macro_pka_utils.GraphData(x, y, labels)

Bases: NamedTuple

x: dict[tuple[int, int], list[float]]

Alias for field number 0

y: dict[tuple[int, int], list[float]]

Alias for field number 1

labels: dict[tuple[int, int], str]

Alias for field number 2

schrodinger.application.jaguar.macro_pka_utils.array_abs_diff(a: ndarray, b: ndarray) → ndarray

Find the elementwise difference between two arrays. Used in PhPopulations.replace_calcd_pKas_with_expts()

Parameters:

  • a – first array

  • b – second array

Returns:

elementwise absolute difference between a and b

schrodinger.application.jaguar.macro_pka_utils.get_aligned_mols(mols: list[rdkit.Chem.rdchem.Mol]) → list[rdkit.Chem.rdchem.Mol]

Align molecules by the common core of all compounds using RDKit MCS and return new RDKit mol instances.

Parameters:

mols – list of molecules

Returns:

list of of newly-oriented RDKit mol objects

schrodinger.application.jaguar.macro_pka_utils.get_2Dimage(mol: Mol, scaling: int = 30) → str | None

Return image bytes of SVG file depicting a 2D structure. It doesn’t store SVG file in disk.

The optional argument <scaling> allows the image size to be adjusted dynamically according to the span of the 2D coordinates. Else a default size is used for all molecules.

Parameters:

  • mol – RDKit mol structure to generate the image file

  • scaling – scale factor to multiply original image size by, where ‘original’ is derived from the span of the X or Y cartesian coordinates.

Returns:

image bytes of 2D structure

schrodinger.application.jaguar.macro_pka_utils.is_pka_ordering_physical(macro_pka: dict[tuple[int, int], float]) → bool

Physically, macro-pKa values should increase monotonically with decreasing charge. However, mispredictions can break this expectation in actual calculations. Check the macro-pKa’s and return False if any of the values are reversed.

Parameters:

macro_pka – macro-pKa values and (prot_charge, deprot_charge) keys

Returns:

True if pKa order is physical, otherwise False

class schrodinger.application.jaguar.macro_pka_utils.PhPopulations(pops: dict[int, dict[int, float]], macro_pkas: dict[tuple[int, int], float])

Bases: object

Container for pH-dependent and pH-independent tautomer populations from a Macro-pKa calculation.

__init__(pops: dict[int, dict[int, float]], macro_pkas: dict[tuple[int, int], float])
Parameters:

  • pops – dict of pH-independent tautomer populations of form {charge: {tautomer_index: population}}

  • macro_pkas – dict of Macro-pKa equilibrium constants of form {(prot_charge, deprot_charge): pKa}

property isoelectric_pH: float | None

Return isoelectric pH for this collection of tautomers and pKa’s. The isoelectric point is the pH at which the population distribution of the tautomers is such that the total net charge is exactly zero.

get_populations_at_pH(pH: float) → dict[int, dict[int, float]]

Get populations of each tautomer at a given pH value.

Parameters:

pH – pH at which to compute pH-dependent populations

Returns:

pH-dependent populations in form {charge: {tautomer_index: population}}

get_pH_population_factors(pH: float, use_linalg: bool = False) → dict[int, float]

Get population factors for a given pH value, which may be used to scale the pH-independent tautomer populations to obtain the pH-dependent populations. Note that the factor is the same for all tautomers of a given molecular charge.

Use recursive method by default because we believe it is slightly more stable numerically than solving a set of linear equations.

Parameters:

  • pH – pH at which to compute population factors.

  • use_linalg – get factors by solving linear equations instead of recursively.

Returns:

dict of population scaling factors keyed by charge.

get_net_charge_at_pH(pH: float) → float

Return the net charge for the population of tautomers equilibrated at the input pH value. Note we normalize the charge such that if 100% of the tautomers have charge +1, then the “net charge” will be +1, regardless of absolute concentrations. We also omit the proton charge from this expression.

Parameters:

pH – pH value

Returns:

net charge

get_isoelectric_pH() → float | None

Return the isoelectric pH (IEP) for this set of tautomers and pKa’s. The isoelectric point is the pH at which the population distribution of the tautomers is such that the total net charge is zero. i.e., the total population of the positively-charged tautomers exactly balances the negatively-charged tautomers.

We only attempt to find the IEP if there are both positive and negative tautomers present in the system, and if the ordering of the pKa’s is physical. Otherwise we return None.

Returns:

isoelectric pH value

replace_calcd_pKas_with_expts(ref_pkas: list[float])

Match up the experimental pKas with the calculated macro-pKas such that the differences are minimized. This is done by expanding the exptl pKa list and calculating the differences between the experimental and calculated pKas. The expanded experimental pKa list with the smallest average difference is then used to map the experimental pKas to the calculated macro-pKas. There is a key assumption that all experimental macro-pKas are sequential and contiguous.

Parameters:

ref_pkas – list of reference/experimental pKas

Returns:

mapped experimental pKas

graph_net_charge_curve(jobname: str, pH_min: float = -5, pH_max: float = 25, pH_step: float = 0.1) → str

Plot net-charge curve on pH half-open interval [pH_min, pH_max) for total population of tautomers of all charges.

Parameters:

  • jobname – file name prefix

  • pH_min – minimum pH

  • pH_max – maximum pH

  • pH_step – pH step size

Returns:

file name of output .png file

schrodinger.application.jaguar.macro_pka_utils.sort_and_screen_populations(populations: dict[int, dict[int, float]], cutoff: float) → list[tuple[int, int, float]]

Sort tautomers by charge, pH-independent populations, and index. Screen away tautomers that are insignificant according to their pH-independent population.

Specifically, loop over charges, taking the most populated tautomer per charge in turn. Use the tautomer index to tie-break when populations are equal. Return a flat list instead of a dictionary.

Parameters:

  • populations – pH-independent tautomer populations, indexed by molecular charge and tautomer index.

  • cutoff – cutoff for tautomer populations to include.

Returns:

list of sorted population data list[(charge, index, population)]

schrodinger.application.jaguar.macro_pka_utils.write_populations_report(jobname: str, tautomers: dict[int, dict[int, rdkit.Chem.rdchem.Mol]], macro_pkas: dict[tuple[int, int], float], populations: PhPopulations, user_pH: float, page_title: str | None = None, cmdline: str | None = None, names: dict[int, dict[int, str]] | None = None, scaling: int = 30, cutoff: float = 0.0001, print_warning: bool = False, extra_html: str = '') → str

Create a final HTML page summarizing all the dominant tautomers found, the macro-pKa transitions, and pH-dependent and independent populations.

Parameters:

  • jobname – name of job to prefix file names.

  • tautomers – tautomers of all charges, indexed by molecular charge and a unique tautomer index.

  • macro_pkas – macro-pKa’s for all charge transitions computed, indexed by prot/deprot charges.

  • populations – pH-dependent and independent tautomer populations, indexed by molecular charge and tautomer index.

  • user_pH – user-requested pH to show populations in table.

  • page_title – title to print at top of report.

  • cmdline – command line string for printing.

  • names – optional unique names for each tautomer, indexed by molecular charge and tautomer index (same as tautomers indices).

  • scaling – scale factor to multiply original image size by, where ‘original’ is derived from the span of the X or Y cartesian coordinates.

  • cutoff – optional cutoff for tautomer populations to include (0 to 1)

  • print_warning – if True, print a warning about the order of the pKa values when they are unphysical.

  • extra_html – optional HTML to dump verbatim into the report; useful for propagating input options or other extra data.

Returns:

absolute path to HTML file on launch machine

schrodinger.application.jaguar.macro_pka_utils.dump_output_csv_file(jobname: str, pkas: dict[tuple[int, int], float])

Write Macro-pKa output to a simple .csv file

Parameters:

  • jobname – name of job to prefix file names

  • pkas – dict of Macro-pKa’s like {(prot_charge, deprot_charge): pKa}