Merge pull request #63 from lewisamarshall/development

Documentation Update

.codeclimate.yml

@@ -0,0 +1,17 @@
+languages:
+  Python: true
+
+exclude_paths:
+- "docs/*"
+
+ratings:
+  paths:
+  - "**.py"
+
+engines:
+  fixme:
+    enabled: true
+  pep8:
+    enabled: true
+  radon:
+    enabled: true

docs/source/Aqueous.rst

@@ -0,0 +1,6 @@
+The Aqueous Class
+=============
+
+.. autoclass:: ionize.Aqueous
+   :members:
+   :inherited-members:

docs/source/Database.rst

@@ -0,0 +1,5 @@
+The **ionize** Database
+=======================
+
+.. autoclass:: ionize.Database
+   :members:

docs/source/Ion.rst

@@ -2,4 +2,5 @@ The Ion Class
 =============
 
 .. autoclass:: ionize.Ion
-   :members: robinson_stokes_mobility, ionization_fraction, effective_mobility, molar_conductivity, set_T
+   :members:
+   :inherited-members:

docs/source/Nucleic_Acid.rst

@@ -0,0 +1,6 @@
+The NucleicAcid Class
+=============
+
+.. autoclass:: ionize.NucleicAcid
+   :members:
+   :inherited-members:

docs/source/Protein.rst

@@ -0,0 +1,10 @@
+The Protein Class
+=============
+
+.. autoclass:: ionize.Protein
+   :members:
+   :inherited-members:
+
+.. autoclass:: ionize.Peptide
+   :members:
+   :inherited-members:

docs/source/conf.py

@@ -18,15 +18,17 @@
 import sys
 import os
 import mock
-
-MOCK_MODULES = ['numpy', 'scipy', 'scipy.optimize']
+MOCK_MODULES = ['numpy', 'scipy', 'scipy.optimize', 'numpy.linalg', 'Bio',
+                'Bio.SeqUtils', 'Bio.SeqUtils.IsoelectricPoint',
+                'Bio.SeqUtils.ProtParam']
 for mod_name in MOCK_MODULES:
     sys.modules[mod_name] = mock.Mock()
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../..'))
+import ionize
 
 # -- General configuration ------------------------------------------------
 
@@ -63,9 +65,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.2.0c'
+version = '.'.join(ionize.__version__.split('.')[:-1])
 # The full version, including alpha/beta/rc tags.
-release = '0.2.0c'
+release = ionize.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/constants.rst

@@ -0,0 +1,5 @@
+Constants
+=============
+
+.. automodule:: ionize.constants
+  :members:

docs/source/index.rst

@@ -27,7 +27,12 @@ Contents:
 
     Ion
     Solution
-    database
+    Nucleic_Acid
+    Protein
+    Database
+    Aqueous
+    utils
+    constants
 
 
 

docs/source/utils.rst

@@ -0,0 +1,4 @@
+Utilities
+=============
+
+.. autofunction:: ionize.deserialize

ionize/Database/__init__.py

@@ -7,6 +7,7 @@
 
 
 class Database(object):
+    """A database containing ion information."""
 
     _default_source = os.path.join(os.getcwd(),
                                    os.path.dirname(__file__),
@@ -27,6 +28,7 @@ def _open(self):
             self._data = json.load(fp)
 
     def load(self, name):
+        """Return an ion from the database based on the name."""
         name = name.lower()
         if name in self.data:
             data = {key: value for
@@ -36,16 +38,28 @@ def load(self, name):
             raise NameError('Ion {} not found in database.'.format(name))
 
     def search(self, searchstring):
+        """Return each name in the database that matches the searchstring.
+
+        The searchstring can be a regular expression.
+        """
         return tuple(sorted([str(key) for key in self.data.keys()
                              if re.search(searchstring, key)]))
 
     def keys(self):
+        """Return the keys of the database as a list."""
         return sorted(self.data.keys())
 
+    def serialize(self):
+        """Return a JSON formatted serialization of the database."""
+        return json.dumps(self.data)
+
     def __getitem__(self, key):
+        """Return the ion that matches the key."""
         return self.load(key)
 
     def __iter__(self):
+        """Retern a generator that yields each ion in the Database."""
+
         for key in self.keys():
             yield self[key]
 
@@ -54,6 +68,3 @@ def __repr__(self):
 
     def __str__(self):
         return 'Database: {} entries'.format(len(self.keys()))
-
-    def serialize(self):
-        return json.dumps(self.data)

ionize/Ion/BaseIon.py

@@ -74,7 +74,7 @@ def serialize(self, nested=False, compact=False):
     def save(self, filename):
         """Save a serialized Ion to a file."""
         with open(filename, 'w') as file:
-            json.dump(self.serialize(), file)
+            file.write(self.serialize())
 
     def mobility(self):
         """The effective mobility of the ion.

ionize/Ion/ionization.py

@@ -35,6 +35,11 @@ def ionization_fraction(self, pH=None, ionic_strength=None, temperature=None):
 
 
 def charge(self, pH=None, ionic_strength=None, temperature=None, moment=1):
+    """Return the time-averaged charge of the charge of the ion.
+
+    Use the moment argument to control which moment of the average charge is
+    calculated.
+    """
     fraction = self.ionization_fraction(pH, ionic_strength, temperature)
     return np.sum(fraction * self.valence**moment)
 

ionize/Ion/mobility.py

@@ -37,6 +37,7 @@ def mobility(self, pH=None, ionic_strength=None, temperature=None):
 
 
 def actual_mobility(self, ionic_strength=None, temperature=None):
+    """Return the mobility for each charge state."""
     try:
         return self.onsager_fuoss_mobility()
     except AttributeError:
@@ -47,6 +48,10 @@ def actual_mobility(self, ionic_strength=None, temperature=None):
 
 
 def absolute_mobility(self, temperature=None):
+    """Return the mobility of each charge state.
+
+    Absolulte mobility does not take ionic strength into account.
+    """
     _, _, temperature = \
         self._resolve_context(None, None, temperature)
 
@@ -101,6 +106,7 @@ def robinson_stokes_mobility(self, ionic_strength=None, temperature=None):
 
 
 def onsager_fuoss_mobility(self):
+    """Return the onsager fuoss corrected mobility of each charge state."""
     _, ionic_strength, temperature = \
         self._resolve_context(None, None, None)
 

ionize/IonComplex/IonComplex.py

@@ -1,8 +1,8 @@
-from ..Ion import Ion, fixed_state
+from ..Ion import BaseIon, fixed_state
 
 
 @fixed_state
-class IonComplex(Ion):
+class IonComplex(BaseIon):
 
     _state = ('name', 'members')
 

ionize/Solution/__init__.py

@@ -55,9 +55,8 @@ class Solution(object):
     """
 
     _solvent = Aqueous
-    # TODO: move these into solvent.
-    _hydronium = Ion('H+', [1], [100], [362E-9])
-    _hydroxide = Ion('OH-', [-1], [-100], [-205E-9])
+    _hydronium = None
+    _hydroxide = None
 
     _pH = 7.                # Normal pH units.
     _ionic_strength = 0.    # Expected in molar.
@@ -76,14 +75,23 @@ def _name_lookup(self):
 
     @property
     def ions(self):
+        """Return a tuple of the ions in the solution."""
         return tuple(self._contents.keys())
 
     @property
     def concentrations(self):
+        """Return a numpy array of the ion concentrations in the solution."""
         return np.array(list(self._contents.values()))
 
-    pH = property(operator.attrgetter("_pH"))
-    ionic_strength = property(operator.attrgetter("_ionic_strength"))
+    @property
+    def pH(self):
+        """The pH of the solution."""
+        return self._pH
+
+    @property
+    def ionic_strength(self):
+        """The ionic strength of the solution."""
+        return self._ionic_strength
 
     def __init__(self, ions=[], concentrations=[], temperature=None):
         """Initialize a solution object."""
@@ -111,6 +119,9 @@ def __init__(self, ions=[], concentrations=[], temperature=None):
             assert concentration >= 0, 'Concentrations must be positive.'
             self._contents[ion] = concentration
 
+        # TODO: move these into database.
+        self._hydronium = Ion('H+', [1], [100], [362E-9])
+        self._hydroxide = Ion('OH-', [-1], [-100], [-205E-9])
         self._hydronium = copy.copy(self._hydronium)
         self._hydroxide = copy.copy(self._hydroxide)
         self._hydronium.context(self)
@@ -123,8 +134,11 @@ def __init__(self, ions=[], concentrations=[], temperature=None):
     def temperature(self, temperature=None):
         """Set or get the temperature of the solution.
 
-        If a temperature is supplied, returns a context manager that reverts
-        to the original temperature.
+        If no argument is supplied, returns the current temperature of the
+        solution.
+
+        If a numerical temperature is supplied, returns a context manager that
+        reverts to the original temperature.
         """
         if temperature is None:
             return self._temperature
@@ -156,6 +170,10 @@ def _cOH(self):
         return cOH
 
     def concentration(self, ion):
+        """Return the concentration of the input ion.
+
+        The input may be an Ion or an ion name as a string.
+        """
         if ion in ('H+', self._hydronium):
             return self._cH()
         elif ion in ('OH-', self._hydroxide):
@@ -237,14 +255,17 @@ def __getitem__(self, item):
             raise KeyError(item)
 
     def serialize(self, nested=False, compact=False):
+        """Return a JSON-formatted serialization of the object."""
         serial = {'__solution__': True}
         serial['concentrations'] = self.concentrations
         serial['ions'] = self.ions
         return _serialize(serial, nested, compact)
 
+    # TODO: Figure out why this dumps text.
     def save(self, filename):
+        """Save the solution to file."""
         with open(filename, 'w') as file:
-            json.dump(self.serialize(), file)
+            file.write(self.serialize())
 
     from .equilibrium import _equilibrate
     from .conductivity import conductivity, hydroxide_conductivity, \

ionize/Solution/conservation.py

@@ -69,6 +69,7 @@ def jovin(self):
 
 
 def gas(self):
+    """Return the Gas conservation function value of the solution."""
     alberty = self.alberty()
     jovin = self.jovin()
     gas = [alberty - jovin / self._hydronium.mobility(self.pH),

ionize/Solution/debye.py

@@ -1,7 +1,7 @@
 def debye(self, temperature=None):
     """Return the Debye length of the solution.
 
-    Uses the Debye-Huckel approximation for the calculation
+    Uses the Debye-Huckel approximation for the calculation.
     """
     if temperature is None:
         temperature = self.temperature()

ionize/Solution/equilibrium.py

@@ -39,8 +39,8 @@ def calculate_pH(self, ionic_strength):
     # Set up the matrix of Ls, the multiplication
     # of acidity coefficients for each ion.
     l_matrix = np.array([np.resize(ion.acidity_product(ionic_strength),
-                                         [max_columns])
-                         for ion in self.ions])
+                        [max_columns])
+                        for ion in self.ions])
 
     # Construct Q vector.
     Q = 1.0
@@ -50,8 +50,7 @@ def calculate_pH(self, ionic_strength):
     # Convolve with water dissociation.
     Q = np.convolve(Q, [-self._solvent.dissociation(ionic_strength,
                                                     self.temperature()),
-                           0.0, 1.0])
-
+                        0.0, 1.0])
 
     # Construct P matrix
     PMat = []
@@ -70,7 +69,7 @@ def calculate_pH(self, ionic_strength):
 
     # Multiply P matrix by concentrations, and sum.
     P = np.sum(np.array(PMat, ndmin=2) *
-                  np.array(self.concentrations)[:, np.newaxis], 0)
+               np.array(self.concentrations)[:, np.newaxis], 0)
     # Construct polynomial. Change the shapes as needed, then reverse the order
     if len(P) < len(Q):
         P.resize(Q.shape)

ionize/Solution/titrate.py

@@ -48,11 +48,11 @@ def titrate(self, titrant, target, titration_property='pH', return_c=False):
 
     att = getattr(self, titration_property)
     if isinstance(att, numbers.Number):
-        min_func = lambda c:\
-            getattr(self + (titrant, c), titration_property)-target
+        def min_func(c):
+            return getattr(self + (titrant, c), titration_property)-target
     else:
-        min_func = lambda c: \
-            getattr(self + (titrant, c), titration_property)()-target
+        def min_func(c):
+            return getattr(self + (titrant, c), titration_property)()-target
 
     with warnings.catch_warnings():
         warnings.simplefilter("ignore")
@@ -68,8 +68,10 @@ def titrate(self, titrant, target, titration_property='pH', return_c=False):
 
 
 def equilibrate_CO2(self):
+    """Titrates the CO2 in solution to equilibrium with earth's atmosphere."""
     CO2 = database['carbonic acid']
     CO2.context(self)
+    # TODO: move to constants
     atmospheric_CO2 = 0.0004
     eq = atmospheric_CO2 * self._solvent.henry_CO2(self.temperature())