Metadata-Version: 2.1
Name: PDIpy
Version: 0.0.3
Summary: Simulate Photodynamic Inactivation (PDI) of a Cocci Bacterium from a kinetics model of membrane oxidation.
Home-page: https://github.com/freiburgermsu/PDIpy
Author: Andrew Freiburger
Author-email: andrewfreiburger@gmail.com
License: MIT
Keywords: antibacterial,photodynamic,biophysics,computational,biology,medicine,PDI,antibiotics
Platform: UNKNOWN

Simulating Photodynamic Inactivation of a Cocci bacterium 
------------------------------------------------------------------------

|PyPI version| |Actions Status| |Downloads| |License|

.. |PyPI version| image:: https://img.shields.io/pypi/v/pdipy.svg?logo=PyPI&logoColor=brightgreen
   :target: https://pypi.org/project/pdipy/
   :alt: PyPI version

.. |Actions Status| image:: https://github.com/freiburgermsu/pdipy/workflows/Test%20PDIpy/badge.svg
   :target: https://github.com/freiburgermsu/pdipy/actions
   :alt: Actions Status

.. |License| image:: https://img.shields.io/badge/License-MIT-blue.svg
   :target: https://opensource.org/licenses/MIT
   :alt: License

.. |Downloads| image:: https://pepy.tech/badge/pdipy
   :target: https://pepy.tech/project/pdipy
   :alt: Downloads

Antibiotic resistance is developing medical crisis that is projected to surpass cancer in annual deaths by mid-21st century. Photodynamic Inactivation (PDI) is a promising treatment method that escapes resistance evolution and may be an essential technology to hamper the growing threat of resistant pathogens. The requisite rate of research to mitigate these somber projections requires computational tools that can improve and expedite experimental research in developing PDI treatments.

`PDIpy <https://pypi.org/project/pdipy/>`_ is offered as the first comprehensive software of PDI to fulfill this by simulating PDI biochemistry from a chemical kinetics model. PDIpy accepts user inputs of an experimental system, executes a `Tellurium <https://tellurium.readthedocs.io/en/latest/walkthrough.html>`_ kinetic system, and expresses and exports the results through CSV spreadsheets and SVG images. Post-processing of the simulation data is further supported with a function that parses the based upon user parameters. The `examples directory <https://github.com/freiburgermsu/pdipy/examples>`_ of the PDIpy GitHub exemplifies PDIpy through replicating experimental observations. Users and developers are encouraged to critique and improve PDIpy, as an open-source library, through `GitHub issues <https://github.com/freiburgermsu/pdipy/issues>`_. 

____________


PDIpy API
--------------

++++++++++++++++++++++
Installation
++++++++++++++++++++++

pdipy is installed in a command prompt, Powershell, Terminal, or Anaconda Command Prompt via ``pip``::

 pip install pdipy

++++++++++++++++++++++
__init__()
++++++++++++++++++++++

The simulation environment is defined:

.. code-block:: python

 import pdipy
 pdi = pdipy.PDI(total_time, solution_dimensions = {}, surface_system = False, 
                 well_count = 24, timestep = 3, verbose = False, jupyter = False)

- *total_time* ``float``: specifies the total simulated time in minutes.
- *simulation* ``dict``: defines the physical dimensions of the simulated solution, which are used to calculate photonic density and photosensitizer volume proportion.
- *surface_system* ``bool``: specifies whether a photodynamic system with a surface-bound, cross-linked, photosensitizer will be simulated.
- *well_count* ``int``: specifies the petri dish well count that will be simulated, which begets default dimensions of the simulated solution.
- *timestep* ``int``: specifies the timestep value in minutes of the simulation, which subtly affects the log-reduction predictions at the end of the simulated time.  
- *verbose* ``bool``: specifies whether simulation details and calculated values will be printed. This is valuable for troubleshooting.
- *jupyter* ``bool``: specifies whether the simulation is being conducted in a Jupyter Notebook, which allows ``display()`` to illustrate data tables and figures.

++++++++++++++++++++++
define_conditions()
++++++++++++++++++++++

The characteristics of the simulated system are concisely defined in a single function:

.. code-block:: python

 pdi.define_conditions(bacterial_specie = None, bacterial_characteristics = {}, 
       bacterial_cfu_ml = 1e6, biofilm = False, photosensitizer = 'A3B_4Zn', 
       photosensitizer_characteristics = {}, photosensitizer_molar = None, photosensitizer_g = 90e-9, 
       cross_linked_sqr_m = 0.0191134, light_source = None, light_characteristics = {}, measurement = {})

- *bacterial_specie* ``str``: specifies one of the bacteria in the ``pdipy/parameters/bacteria`` directory, where *S. aureus* is imported by default. These imported parameters are overwritten by the ``bacterial_characteristics``, and can be used in conjunction.
- *bacterial_characteristics* ``dict``: provides custom characteristics of the simulated bacterium that supplant imported characteristics from the ``bacterial_specie`` argument. The expected dictionary keys ``shape``, ``membrane_thickness_nm``, ``cell_mass_pg``, ``"cell_volume_fL``, ``eps_oxidation_rate_constant``, and ``cellular_dry_mass_proportion_biofilm`` are all themselves dictionaries that follow a simple structure:

.. code-block:: json

 {
    	  "value": 0.268,
    	  "reference": "A. G. O’DONNELL, M. R. NAHAIE, M. GOODFELLOW, D. E. MINNIKINI, and V. HAJEK. Numerical Analysis of Fatty Acid Profiles in the Identification of Staphylococci. Journal of General Microbiology (1989). 131, 2023-2033. https://doi.org/10.1099/00221287-131-8-2023",
    	  "notes": "All saturated SCFAs were summed from Table 2 for all S. aureus entries."
 }

The ``reference`` and ``notes`` keys are optional, yet may be important for provenance and reproducibility of the simulation results. The final key of ``bacterial_characteristics`` is ``membrane_chemicals``, which characterizes the chemicals that constitutes the bacterial membrane such as ``BCFA`` for branch-chain fatty acids and ``SCFA`` for straight-chain fatty acids. The sub-structure of these values are exemplified by the following content for the ``"SCFA"`` entry for *S. aureus*:

.. code-block:: json

 {
     "density_gL": {
          "value": 0.94,
          "reference": ["https://pubchem.ncbi.nlm.nih.gov/compound/Stearic-acid#section=Density"],
          "notes": "The density for all saturated fatty acids is estimated as stearic acid."
          },
     "formula": [
          "C20_H38_O2",
          "C18_H34_O2",
          "C16_H30_O2"
          ],
	 "proportion": {
	      "value": 0.268,
	      "reference": "A. G. O’DONNELL, M. R. NAHAIE, M. GOODFELLOW, D. E. MINNIKINI, and V. HAJEK. Numerical Analysis of Fatty Acid Profiles in the Identification of Staphylococci. Journal of General Microbiology (1989). 131, 2023-2033. https://doi.org/10.1099/00221287-131-8-2023",
	      "notes": "All saturated SCFAs were summed from Table 2 for all S. aureus entries."
          }
  }


- *bacterial_cfu_ml* ``float``: specifies the bacterial concentration for simulations of solution-based photosensitizers. 
- *biofilm* ``bool``: specifies whether a biofilm will be simulated.
- *photosensitizer* ``str``: specifies which photosensitizer from the predefined options in the ``pdipy/parameters/photosensitizers.json`` parameter file will be simulated.
- *photosensitizer_characteristics* ``dict``: defines characteristics of the simulation photosensitizer, which supplant the characteristics from the ``photosensitizer`` parameter. The expected structure of the dictionary are keys with dictionary substructure according to the following example:

.. code-block:: json

 {
		"e_quantum_yield": {
			"value": 0.6,
			"reference": "Singlet Oxygen Yields and Radical Contributions in the Dye-Sensitised Photo-oxidation in methanol of esters of polyunsaturated fatty acids _oleic, linoleic, linolenic, and arachidonic) Chacon et al., 1988"
		},
		"so_specificity": {
			"value": 0.8,
			"reference": null
		},
		"formula": {
			"value": "C76_H48_N16_F12_Zn",
			"reference": null
		},
		"soret_nm": {
			"value": [ 400, 430 ],
			"reference": null
		},
		"q_nm": {
			"value": [ 530, 625 ],
			"reference": null
		},
		"charge": 4,
		"photobleaching_constant (cm^2/J)": {
			"value": 1.74e-7,
			"reference": "“Photobleaching kinetics, photoproduct formation, and dose estimation during ALA induced PpIX PDT of MLL cells under well oxygenated and hypoxic conditions” by Dysart et al., 2005",
			"notes": "The 0.015 value from literature is divided by 8.64e4 -- the quantity of seconds in a day -- to yield a sensible value. A similar value is discovered from “PHOTOBLEACHING OF PORPHYRINS USED IN PHOTODYNAMIC THERAPY AND  IMPLICATIONS FOR THERAPY” by Mang et al., 1987"
			},
		"dimensions": {
			"shape": "disc",
			"length_A": 32.8,
			"width_A": 32.8,
			"depth_A": 1.5,
			"notes": "The depth is atomic thickness, as quantified by this paper https://www.nature.com/articles/ncomms1291."
		} 
 }

The ``value`` sub-key in the dictionary substructures, where it is present, is the only necessary sub-key for each parameter.

- *photosensitizer_molar* ``float``: specifies the photosensitizer molar concentration for simulations of a solution-based photosensitizer.
- *photosensitizer_g* ``float``: specifies the mass of photosensitizer that is surface-bound in cross-linked simulations.
- *cross_linked_sqr_m* ``float``: defines the square-meters area that is coated with the bound photosensitizer from the ``photosensitizer_g`` parameter, for cross-linked  simulations.
- *parameterized_ph_charge* ``bool``: specifies whether the pH will be charged balance, where ``True`` prevents the parameterization of alkalinity in the feed solution. 
- *measurement* ``dict``: provides the unit and quantity of the photonic intensity measurement of the light source in a key-value pair. The supported unit options are: ``irradiance`` in mW/cm\ :sup:`2`\, ``exposure`` in J/cm\ :sup:`2`\, ``lux`` in lumen/m\ :sup:`2`\, and ``lumens`` in lumens.
- *light_source* ``str``: specifies a light source from the predefined options in the ``pdipy/parameters/light_source.json`` parameter file will be simulated. 
- *light_characteristics* ``dict``: specifies custom characteristics of the light source, which overwrite characteristics that are specified from the ``light_source`` option. The expected structure of the dictionary are keys with dictionary substructure according to the following example:

.. code-block:: json

 {
    "visible_proportion": {
      "value": 0.1,
      "reference": "Macisaac et al., 1999"
    },
    "lumens_per_watt": {
      "value": 3,
      "reference": "Michael F. Hordeski. Dictionary Of Energy Efficiency Technologies. Fairmont Press. ISBN: 9780824748104"
    }
  }

where the ``value`` sub-key in the dictionary substructures is the only necessary sub-key for each parameter.


++++++++++++++++++++++
simulate()
++++++++++++++++++++++

The aforementioned system specifications are refined into chemical parameters and are executed in a ``Tellurium`` kinetic model:

.. code-block:: python

 pdi.simulate(export_name = None, export_directory = None, figure_title = None, 
            y_label = 'log10', exposure_axis = False, display_fa_oxidation = False, 
            display_ps_excitation = False, export_content = True)

- *export_name* & *export_directory* ``str``: specify the name and directory, respectively, to which the simulation contents will be saved, where ``None`` defaults to a folder name with simulation parameters **PDIpy-<photosensitizer_selection>-<bacterial_specie>-<count>** within the current workign directory.
- *figure_title* & *y_label* ``str``: specify the title and y-axis label of the simulation figure, respectively. The y-axis label is vague to support generalization to plots where the fatty acid oxidation and photosensitizer excitation content is overlaid, and thus would be not appropriately described by more descriptive labels. The value of ``None`` defaults to **Cytoplasmic oxidation and inactivation of < bacterial genera_specie > via PDI**. 
- *exposure_axis* ``bool``: specifies whether the x-axis of the simulation figure will be defined with cumulative exposure J/cm\ :sup:`2`\ over the simulation or in minutes of simulation time, where the latter is default.
- *display_fa_oxidation* & *display_ps_excitation* ``bool``: determine whether the fatty acid oxidation or the photosensitizer excitation proportions, respectively, will be plotted with the reduction data.
- *export_content* ``bool``: specifies whether the simulation content will be exported.

++++++++++++++++++++++
parse_data()
++++++++++++++++++++++

The processed data can be automatically processed through this function, as a convenient form of post-processing within the ``PDI`` object environment:

.. code-block:: python

 value, unit = pdi.data_parsing(log_reduction = None, target_hours = None)

- *log_reduction* ``float``: inquires at what time the specified log-reduction is achieved 
- *target_hours* ``float``: inquires what log-reduction is achieved that the specified time

**Returns** *value* ``float``: The value of the search inquiry, reported in the respective units.

**Returns** *unit* ``str``: The units of the search inquiry result, being either log-reduction or hours.
 
____________


Accessible content
----------------------

Numerous entities are stored within the ``PDI`` object, and can be subsequently used in a workflow. The complete list of content within the ``PDI`` object can be identified and printed through the built-in ``dir()`` function in the following example sequence:

.. code-block:: python

 from pdipy import PDI

 # define the simulation conditions
 pdi = PDI(total_time = 360)
 pdi.define_conditions(bacterial_specie = 'S_aureus', bacterial_cfu_ml = 1e7, 
 photosensitizer = 'A3B_4Zn', photosensitizer_molar = 18e-9, measurement = {'irradiance': 8}, light_source = 'LED')
 
 # execute and export the simulation
 pdi.simulate()

 # parse the data and evaluate the PDI object contents
 value, unit = pdi.parse_data(log_reduction = 5)
 print(dir(pdi))

The following list highlights stored content in the ``PDI`` object after a simulation:

- *raw_data* & *processed_data* ``Pandas.DataFrame``: `Pandas DataFrames <https://pandas.pydata.org/pandas-docs/stable/reference/frame.html>`_ that contain the raw and processed simulation data, respectively. This files are also exported through the export function.
- *model* & *phrasedml_str* ``str``: The kinetic model and its corresponding `SED-ML <https://sed-ml.org/>`_ plot, respectively, composed in a string that can be read by Tellurium and converted into the standard XML formats of these languages.
- *bacterium*, *photosensitizer*, & *light* ``dict``: Dictionaries of the simulation parameters for the bacterium, photosensitizer, and light, respectively.
- *parameters*, *variables*, & *results* ``dict``: Dictionaries that possess the input parameters, calculation variables, and simulation results, respectively.
- *figure* & *ax* ``MatplotLib.Pyplot.subplots``: The `MatPlotLib objects <https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.subplot.html#matplotlib.pyplot.subplot>`_ of the simulation figure, which allows the user to externally manipulate the figure without recreating a new figure from the raw or processed data.
- *chem_mw* ``chemw.ChemMW``: The ``ChemMW`` object from the `ChemW module <https://pypi.org/project/ChemW/>`_, which allows users to calculate the molecular weight from a string of any chemical formula. The formatting specifications are detailed in the README of the ChemW module. 
- *hf* ``hillfit.HillFit``: The ``HillFit`` object from the `Hillfit module <https://pypi.org/project/hillfit/>`_ is stored, from which the Hill-equation regrssion parameters, equation string, and R\ :sup:`2`\ of the fitted equation can be programmatically accessed, in addition to being exported with the ``PDIpy`` content through the ``export()`` function.
- *bacteria* ``list``: A list of all the predefined bacteria parameter files, from which a user can easily simulate via the ``PDI`` object.
- *light_parameters*, *photosensitizers*, & *solution* ``dict``: Dictionaries of the predefined options and parameters for the light sources, photosensitizers, and solution dimensions, respectively.

