Merge pull request #20 from LinkedEarth/Development

Development

Documentation/source/Introduction.rst

@@ -0,0 +1,107 @@
+Pyleoclim
+=========
+
+What is it?
+```````````
+
+Pyleoclim is a Python package primarily geared towards the analysis and visualization of paleoclimate data.
+Such data often come in the form of timeseries with missing values and age uncertainties, and the package
+includes several low-level methods to deal with these issues, as well as high-level methods that re-use those
+to perform scientific workflows.
+
+The package assumes that the data are stored in the Linked Paleo Data (`LiPD <http://www.clim-past.net/12/1093/2016/>`_)
+format and makes extensive use of the `LiPD utilities <http://nickmckay.github.io/LiPD-utilities/>`_. The package
+is aware of age ensembles stored via LiPD and uses them for time-uncertain analyses very much like `GeoChronR <http://nickmckay.github.io/GeoChronR/>`_.
+
+**Current Capabilities:**
+
+* binning
+* interpolation
+* plotting maps, timeseries, and basic age model information
+* paleo-aware correlation analysis (isopersistent, isospectral, and classical t-test)
+* weighted wavelet Z transform (WWZ)
+
+**Future capabilities:**
+
+* paleo-aware singular spectrum analysis (AR(1) null eigenvalue identification, missing data)
+* spectral analysis (Multi-Taper Method, Lomb-Scargle)
+* cross-wavelet analysis
+* index reconstruction
+* climate reconstruction
+
+* ensemble methods for most of the above
+
+Version Information
+```````````````````
+| 0.3.0: Compatibility with LiPD 1.3 and Spectral module added
+| 0.2.5: Fix error on loading (Looking for Spectral Module)
+| 0.2.4: Fix load error from init
+| 0.2.3: Freeze LiPD version to 1.2 to avoid conflicts with 1.3
+| 0.2.2: Change progressbar to tqdm and add standardization function
+| 0.2.1: Update package requirements
+| 0.2.0: Restructure the package so that the main functions can be called without the use of a LiPD files and associated timeseries objects.
+| 0.1.4: Rename functions using camel case convention and consistency with LiPD utilities version 0.1.8.5
+| 0.1.3: Compatible with LiPD utilities version 0.1.8.5
+|        Function openLiPD() renamed openLiPDs()
+| 0.1.2: Compatible with LiPD utilities version 0.1.8.3
+|        Uses Basemap instead of cartopy
+| 0.1.1: Freezes the package prior to version 0.1.8.2 of LiPD utilities
+| 0.1.0: First release
+
+Installation
+````````````
+Python v3.4+ is required. Tested with Python v3.5
+Pyleoclim is published through Pypi and easily installed via pip::
+
+  pip install pyleoclim
+
+Quickstart guide
+````````````````
+
+1. Open your command line application (Terminal or Command Prompt)
+2. Install with command::
+
+  pip install pyleoclim
+
+3. Wait for installation to complete, then:
+
+  a. Import the package into your favorite Python environment (we recommend the use of Spyder, which comes standard with the Anaconda build)
+  b. Use Jupyter Notebook to go through the tutorial contained in the `PyleolimQuickstart.ipynb <https://github.com/LinkedEarth/Pyleoclim_util/tree/master/Example>`_
+
+Requirements
+````````````
+
+* LiPD v0.2.2+
+* pandas v0.19+
+* numpy v1.12+
+* matplotlib v2.0+
+* Basemap v1.0.7+
+* scipy v0.19.0+
+* statsmodel v0.8.0+
+* seaborn v0.7.0+
+* scikit-learn v0.17.1+
+* tqdm v4.14.0+
+* pathos v0.2.0+
+
+The installer will automatically check for the needed updates.
+
+Further information
+```````````````````
+| GitHub: `https://github.com/LinkedEarth/Pyleoclim_util <https://github.com/LinkedEarth/Pyleoclim_util>`_
+| LinkedEarth: `http://linked.earth <http://linked.earth>`_
+| Python and Anaconda: `http://conda.pydata.org/docs/test-drive.html <http://conda.pydata.org/docs/test-drive.html>`_
+| Jupyter Notebook: `http://jupyter.org/ <http://jupyter.org/>`_
+
+Contact
+```````
+Please report issues to `[email protected] <[email protected]>`_
+
+License
+```````
+The project is licensed under the `GNU Public License <https://github.com/LinkedEarth/Pyleoclim_util/blob/master/license>`_ .
+
+Disclaimer
+``````````
+This material is based upon work supported by the U.S. National Science Foundation under Grant Number
+ICER-1541029. Any opinions, findings, and conclusions or recommendations expressed in this material are those
+of the investigators and do not necessarily reflect the views of the National Science Foundation.

Documentation/source/LIPDutils.rst

@@ -0,0 +1,39 @@
+LiPD Utilities
+==============
+
+This modules allow basic manipulation of LiPD files
+
+Creating Directories and saving
+```````````````````````````````
+
+.. autofunction:: pyleoclim.LipdUtils.createDir
+
+.. autofunction:: pyleoclim.LipdUtils.saveFigure
+
+LiPD files
+``````````
+
+.. autofunction:: pyleoclim.LipdUtils.enumerateLipds
+
+.. autofunction:: pyleoclim.LipdUtils.promptForLipd
+
+Handling Variables
+``````````````````
+
+.. autofunction:: pyleoclim.LipdUtils.promptForVariable
+
+.. autofunction:: pyleoclim.LipdUtils.xAxisTs
+
+.. autofunction:: pyleoclim.LipdUtils.checkXaxis
+
+Handling timeseries objects
+```````````````````````````
+
+.. autofunction:: pyleoclim.LipdUtils.enumerateTs
+
+.. autofunction:: pyleoclim.LipdUtils.getTs
+
+Linking LiPDs to the LinkedEarth Ontology
+`````````````````````````````````````````
+
+.. autofunction:: pyleoclim.LipdUtils.LipdToOntology

Documentation/source/Main.rst

@@ -0,0 +1,84 @@
+Main Functions
+==============
+
+
+Using Pyleoclim with a LiPD file
+""""""""""""""""""""""""""""""""
+
+Getting started
+```````````````
+
+Pyleoclim relies heavily on the concept of timeseries objects introduced in
+`LiPD <http://www.clim-past.net/12/1093/2016/>`_ and implemented in the
+`LiPD utilities <http://nickmckay.github.io/LiPD-utilities/>`_.
+
+Briefly, timeseries objects are dictionaries containing the ChronData values and
+PaleoData values as well as the metadata associated with the record. If one record
+has three ProxyObservations (e.g., Mg/Ca, d18O, d13C) then it will have three timeseries
+objects, one for each of the observations.
+
+The LiPD utilities function lipd.extractTs() returns a list of dictionaries for
+the selected LiPD files, which need to be passed to Pyleoclim along with the path
+to the directory containing the LiPD files.
+
+This is done through the functions pyleoclim.readLiPD() and pyleoclim.extracTs(),
+ which are lightweight versions of their counterparts in the LiPD utilities:
+
+.. autofunction:: pyleoclim.readLipd
+.. autofunction:: pyleoclim.extractTs
+
+Mapping
+```````
+.. autofunction:: pyleoclim.mapAllArchive
+
+.. autofunction:: pyleoclim.mapLipd
+
+Plotting
+````````
+.. autofunction:: pyleoclim.plotTs
+
+.. autofunction:: pyleoclim.histTs
+
+Summary Plots
+'''''''''''''
+
+Summary plots are a special categories of plots enabled by Pyleoclim.
+They allow to plot specific information about a timeseries but are not customizable.
+
+.. autofunction:: pyleoclim.summaryTs
+
+Statistics
+``````````
+
+.. autofunction:: pyleoclim.statsTs
+
+.. autofunction:: pyleoclim.corrSigTs
+
+Timeseries
+``````````
+Basic manipulations of the timeseries objects.
+
+.. autofunction:: pyleoclim.binTs
+
+.. autofunction:: pyleoclim.interpTs
+
+.. autofunction:: pyleoclim.standardizeTs
+
+Analysis in the frequency domain
+````````````````````````````````
+.. autofunction:: pyleoclim.wwzTs
+
+Using Pyleoclim without a LiPD file
+"""""""""""""""""""""""""""""""""""
+
+The Pyleoclim modules can be called separately so the main functions can be used without a timeseries objects.
+The following modules are available:
+
+* pyleoclim.Map: mapping functions
+* pyleoclim.Plot: plotting functions
+* pyleoclim.Stats: statistics (including correlation)
+* pyleoclim.Timeseries: binning, interpolating
+* pyleoclim.Spectral: analysis in the frequency domain
+
+In addition, the pyleoclim.LipdUtils module allows the basic manipulation of LiPD files and the pyleoclim.SummaryPlots module
+contains some functions to extract information about a timeseries object.

Documentation/source/Spectral.rst

@@ -0,0 +1,18 @@
+Spectral Functions
+==================
+
+This module allows analysis in the frequency domain
+
+.. autofunction:: pyleoclim.Spectral.ar1_fit
+
+.. autofunction:: pyleoclim.Spectral.ar1_sim
+
+.. autofunction:: pyleoclim.Spectral.wwz
+
+.. autofunction:: pyleoclim.Spectral.wwz_psd
+
+.. autofunction:: pyleoclim.Spectral.plot_wwa
+
+.. autofunction:: pyleoclim.Spectral.plot_wwadist
+
+.. autofunction:: pyleoclim.Spectral.plot_psd

Documentation/source/Stats.rst

@@ -0,0 +1,6 @@
+Statistics Functions
+====================
+
+.. autofunction:: pyleoclim.Stats.simpleStats
+
+.. autofunction:: pyleoclim.Stats.corrsig

Documentation/source/SummaryPlots.rst

@@ -0,0 +1,12 @@
+Summary Plots
+==============
+
+This module handles some basic return for the summary plots.
+
+**Requires** a LiPD file
+
+.. autofunction:: pyleoclim.SummaryPlots.getMetadata
+
+.. autofunction:: pyleoclim.SummaryPlots.TsData
+
+.. autofunction:: pyleoclim.SummaryPlots.agemodelData

Documentation/source/Timeseries.rst

@@ -0,0 +1,12 @@
+Timeseries Functions
+====================
+
+This module allows the manipulation of timeseries.
+
+.. autofunction:: pyleoclim.Timeseries.bin
+
+.. autofunction:: pyleoclim.Timeseries.interp
+
+.. autofunction:: pyleoclim.Timeseries.onCommonAxis
+
+.. autofunction:: pyleoclim.Timeseries.standardize