diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..246ea6a --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,23 @@ +# Changelog + +## Version 0.0.2 +Project Updates: + + Enable Github Actions + + Temporarily freeze Pandas v1.1.5 due to NaN errors + + Handle empty data returns + +Install Updates: + + Issue #29, #7: Fix install commands + +Documentation Updates: + + Issue #26: Fix typos and errors in README + + Issue #27, 35: Fix basin3d reference and updates authors + + Issue #28: Update git clone link in README + + Issue #38: Add BASIN-3D concepts to documentation + + Issue #41: Fix autogenerated Sphinx documentation + + Remove prerequisites section in README + + Update license to the BASIN-3D license + +## Version 0.0.1 +Project Updates: + + Prepare version for open-source release \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ecd4e80..f6d6f97 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,83 @@ ## How to contribute to basin3d -* Steps for creating good issues or pull requests. -* Links to external documentation, mailing lists, or a code of conduct. -* Community and behavioral expectations. +## Quick Links +* [Documentation]() +* [Issue Template: Bugs](.github/ISSUE_TEMPLATE/bug_report.md) +* [Issue Template: New Feature](.github/ISSUE_TEMPLATE/feature_request.md) +* [Pull Request Template](.github/pull_request_template.md) +* [Code of Conduct](CODE_OF_CONDUCT.md) + + +## Development Practices + +* basin3d uses the [GitFlow model](https://datasift.github.io/gitflow/IntroducingGitFlow.html) + of branching and code versioning in git. +* Code development will be performed in a feature/development branch of the repo. Commits will not be made directly to the master branch of basin3d repo. Developers will submit a pull request that is then merged by another team member, if another team member is available. +* Each pull request should contain only related modifications to a feature or bug fix. +* Sensitive information (secret keys, usernames etc) and configuration data (e.g database host port) should not be checked into the repo. +* A practice of rebasing with the main repo should be used rather than merge commits. + +## Develop + +Setup virtualenv for development and testing purposes. All basin3d tests +are in `tests/`. + +Create an Anaconda environment + + $ conda create -y -n basin3d python=3.7 + +Activate the new environment and prepare it for development + + $ conda activate basin3d + $ conda develop -npf -n basin3d . + +Install basin3d and its dependencies + + $ pip install $(cat requirements.txt) pytest + $ pip install pytest-flake8 pytest-mypy pytest-cov sphinx PSphinxTheme + $ python setup.py develop + +Run the tests (mypy and flake8 tests executed by default) + + $ pytest + +Run the tests with coverage + + $ pytest --cov=basin3d + +Run the tests with coverage ONLY + + $ pytest --cov=basin3d tests + + +## Documentation + +Sphinx is used to generate documentation. You first need to create a virtual environment for generating the docs. + + $ conda activate basin3d + $ pip install -r docs/requirements.txt + +Generate the documentation + + $ cd docs + $ make html + +Review the generated documentation + + $ open _build/html/index.html + + +## Versioning + +We use [SemVer](http://semver.org/) for versioning. For the versions available, +see the [tags on this repository](https://github.com/BASIN-3D/basin3d/tags). + +Workflow for tagging and building release: + +1. checkout the version to tag from `main` +1. `$ git tag -a v[version]-[release] -m "Tagging release v[version]-[release]"` +1. build distribution with `$ setup.py` +1. `$ git push origin v[version]-[release]` + +## Questions +Our preferred channels of communication are public. Please open a [new discussion topic](https://github.com/BASIN-3D/basin3d/discussions) on Github discussions diff --git a/README.md b/README.md index e47032e..fc30810 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,49 @@ # basin3d -Broker for Assimilation, Synthesis and Integration of eNvironmental Diverse, Distributed Datasets. -A data synthesis framework for earth science data. +Broker for Assimilation, Synthesis and Integration of eNvironmental Diverse, Distributed Datasets. +![basin3d](https://user-images.githubusercontent.com/20212666/112556236-ff1a9b80-8d86-11eb-9009-25b658ce41e0.png) -## Development Practices +BASIN-3D is a software ecosystem that synthesizes diverse earth science data from a variety of remote data sources on-demand, without the need for storing data in a single database. It is designed to parse, translate, and synthesize diverse observations from well-curated repositories into standardized formats for scientific uses such as analysis and visualization. -* basin3d uses the [GitFlow model](https://datasift.github.io/gitflow/IntroducingGitFlow.html) - of branching and code versioning in git. -* Code development will be performed in a feature/development branch of the repo. Commits will not be made directly to the master branch of basin3d repo. Developers will submit a pull request that is then merged by another team member, if another team member is available. -* Each pull request should contain only related modifications to a feature or bug fix. -* Sensitive information (secret keys, usernames etc) and configuration data (e.g database host port) should not be checked into the repo. -* A practice of rebasing with the main repo should be used rather than merge commits. +basin3d is the core BASIN-3D application that uses a generalized data synthesis model that applies across a variety of earth science observation types (hydrology, geochemistry, climate etc.). -## Getting Started - -### Get the code - -These instructions will get you a copy of the project up and running on your local machine for -development and testing purposes. - - $ git clone git@github.com:BASIN-3D/basin3d.git - $ cd basin3d - -## Develop -Setup virtualenv for development and testing purposes. All basin3d tests -are in `tests/`. - -Create an Anaconda environment - - $ conda create -y -n basin3d python=3.7 - -Activate the new environment and prepare it for development - - $ conda activate basin3d - $ conda develop -npf -n basin3d . - -Install basin3d and its dependencies +basin3d has available plugins that can connect to specific data sources of interest, and map the data source vocabularies to the basin3d synthesis models. - $ pip install $(cat requirements.txt) pytest - $ pip install pytest-flake8 pytest-mypy pytest-cov sphinx PSphinxTheme - $ python setup.py develop - -Run the tests (mypy and flake8 tests executed by default) - $ pytest - -Run the tests with coverage - $ pytest --cov=basin3d - -Run the tests with coverage ONLY +## Getting Started +### Install - $ pytest --cov=basin3d tests - -## Documentation -Sphinx is used to generate documentation. You first need -to create a virtual environment for generating the docs. +Install a source distribution with pip: - $ conda activate basin3d - $ pip install -r docs/requirements.txt + $ pip install git+https://github.com/BASIN-3D/basin3d.git -Generate the documentation - - $ cd docs - $ make html +Make sure your installation was successful: -Review the generated documentation + $ python + >>> import basin3d + >>> - $ open _build/html/index.html - -# Install +## Documentation - -Install a source distribution with pip: +See latest basin3d documentation [here](https://basin-3d.github.io/basin3d/html/index.html) - $ pip install basin3d-.tar.gz - -To get started read the [setup](docs/getting_started.rst) documentation -## Versioning +## Contributing -We use [SemVer](http://semver.org/) for versioning. For the versions available, -see the [tags on this repository](https://github.com/BASIN-3D/basin3d/tags). +If you’re interested in contributing to basin3d, check out out our [contributing guidelines](CONTRIBUTING.md). It will help explain why, what, and how to get started. -Workflow for tagging and building release: -1. checkout the version to tag from `main` -1. `$ git tag -a v[version]-[release] -m "Tagging release v[version]-[release]"` -1. build distribution with `$ setup.py` -1. `$ git push origin v[version]-[release]` +## Changelog +See the [changelog](CHANGES.md) for a history of updates and changes to basin3d ## Authors * **Charuleka Varadharajan** - [LBL](https://eesa.lbl.gov/profiles/charuleka-varadharajan/) * **Valerie Hendrix** - [LBL](https://crd.lbl.gov/departments/data-science-and-technology/uss/staff/valerie-hendrix) * **Danielle Svehla Christianson** - [LBL](https://crd.lbl.gov/departments/data-science-and-technology/uss/staff/danielle-christianson/) +* **Catherine Wong** - [LBL](https://crd.lbl.gov/departments/data-science-and-technology/uss) ## Copyright @@ -123,4 +71,4 @@ See [LICENSE](LICENSE) file for licensing details ## Acknowledgments -This research is supported as part of the Watershed Function Scientific Focus Area funded by the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research under Award no. DE-AC02-05CH11231. This research used resources of the National Energy Research Scientific Computing Center (NERSC), U.S. Department of Energy Office of Science User Facility operated under Contract No. DE-AC02-05CH11231. +This research is supported as part of the Watershed Function Scientific Focus Area funded by the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research under Award no. DE-AC02-05CH11231. This research used resources of the National Energy Research Scientific Computing Center (NERSC), U.S. Department of Energy Office of Science User Facility operated under Contract No. DE-AC02-05CH11231. \ No newline at end of file diff --git a/docs/_templates/indexcontent.html b/docs/_templates/indexcontent.html index f7fe093..2f8bdb8 100644 --- a/docs/_templates/indexcontent.html +++ b/docs/_templates/indexcontent.html @@ -16,7 +16,7 @@ Instructions on installing BASIN-3D

-

Quick Guide
+

Quick Guide
Quick guide to basic functions

Examples
Examples for using BASIN-3D

diff --git a/docs/changelog.rst b/docs/changelog.rst index 4b3f466..50930dc 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,2 +1,26 @@ Change Log -********** \ No newline at end of file +********** + +Version 0.0.2 +############## +Project Updates: + + Enable Github Actions + + Temporarily freeze Pandas v1.1.5 due to NaN errors + + Handle empty data returns + +Install Updates: + + Issue #29, #7: Fix install commands + +Documentation Updates: + + Issue #26: Fix typos and errors in README + + Issue #27, 35: Fix basin3d reference and updates authors + + Issue #28: Update git clone link in README + + Issue #38: Add BASIN-3D concepts to documentation + + Issue #41: Fix autogenerated Sphinx documentation + + Remove prerequisites section in README + + Update license to the BASIN-3D license + +Version 0.0.1 +############### +Project Updates: + + Prepare version for open-source release \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index a9f1b23..0938852 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,7 +19,7 @@ # -- Project information ----------------------------------------------------- # General information about the project. -project = 'basin3d-core' +project = 'basin3d' copyright = '2020, The Regents of the University of California, through Lawrence Berkeley National Laboratory \n(subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.' author = 'Charuleka Varadharajan, Valerie Hendrix, Danielle Christianson' @@ -33,7 +33,7 @@ # # import os # import sys -version = "0.0.1" +version = "0.0.2" # -- General configuration --------------------------------------------------- @@ -102,7 +102,7 @@ # A shorter title for the navigation bar. Default is the same as html_title. # # html_short_title = None -html_short_title = 'basin3d-core {}'.format(version) +html_short_title = 'basin3d {}'.format(version) # The name of an image file (relative to this directory) to place at the top # of the sidebar. @@ -201,7 +201,7 @@ # html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'basin3d-coredoc' +htmlhelp_basename = 'basin3d-doc' # -- Options for LaTeX output --------------------------------------------- @@ -231,7 +231,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'basin3d-core-{}.tex'.format(version), 'basin3d-core Documentation', + (master_doc, 'basin3d-{}.tex'.format(version), 'basin3d Documentation', 'Charuleka Varadharajan, Valerie Hendrix', 'manual'), ] @@ -272,7 +272,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'basin-3d', 'basin3d-core Documentation', + (master_doc, 'basin-3d', 'basin3d Documentation', [author], 1) ] @@ -287,8 +287,8 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'basin3d-core', 'basin3d-core Documentation', - author, 'basin3d-core', 'One line description of project.', + (master_doc, 'basin3d', 'basin3d Documentation', + author, 'basin3d', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/copyright_notice.rst b/docs/copyright_notice.rst index adc8f64..180ab5c 100644 --- a/docs/copyright_notice.rst +++ b/docs/copyright_notice.rst @@ -1,2 +1,9 @@ Copyright Notice -**************** \ No newline at end of file +**************** + + +Broker for Assimilation, Synthesis and Integration of eNvironmental Diverse, Distributed Datasets (BASIN-3D) Copyright (c) 2019, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved. + +If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov. + +NOTICE. This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit other to do so. \ No newline at end of file diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 38a56cd..5e051bb 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -1,38 +1,28 @@ ============================ -BASIN-3D Getting Started +Install basin3d ============================ BASIN-3D (Broker for Assimilation, Synthesis and Integration of eNvironmental Diverse, Distributed Datasets) - -Get Code ---------- -These instructions will get you a copy of the basin3d-core code base. :: - - $ git clone git@github.com:Watershed-Function-SFA/basin3d-core.git - $ cd basin3d-core - - Install ------- .. warning:: - It is advised that you install basin3d-core into a virtual environment. (e.g. `Anaconda `_, + It is advised that you install basin3d into a virtual environment. (e.g. `Anaconda `_, `Virtualenv `_). For more information about virtual environments see `Python documentation `_. -Install basin3d-core using the following command.:: +Install basin3d using the following command:: + + $ pip install git+https://github.com/BASIN-3D/basin3d.git - $ python setup.py install -Use ---- -Make sure your installation was successful.:: +Make sure your installation was successful:: $ python >>> import basin3d - >>> \ No newline at end of file + >>> diff --git a/docs/index.rst b/docs/index.rst index 018cbab..b9e1a7a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,10 +5,10 @@ Welcome to basin3d-core |release| documentation! intro concepts - examples getting_started - api - models + quick_guide + examples + key_functions contact license_agreement copyright_notice diff --git a/docs/api.rst b/docs/key_functions.rst similarity index 87% rename from docs/api.rst rename to docs/key_functions.rst index 309aabc..925cd7a 100644 --- a/docs/api.rst +++ b/docs/key_functions.rst @@ -1,4 +1,4 @@ -.. _apireference: +.. _keyfunctionsreference: Key Functions ************* diff --git a/docs/license_agreement.rst b/docs/license_agreement.rst index 6703498..4cc1b3e 100644 --- a/docs/license_agreement.rst +++ b/docs/license_agreement.rst @@ -1,2 +1,46 @@ License Agreement -***************** \ No newline at end of file +***************** + +Broker for Assimilation, Synthesis and Integration of eNvironmental Diverse, Distributed Datasets (BASIN-3D) Copyright (c) 2019, The +Regents of the University of California, through Lawrence Berkeley National +Laboratory (subject to receipt of any required approvals from the U.S. +Dept. of Energy). All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +(1) Redistributions of source code must retain the above copyright notice, +this list of conditions and the following disclaimer. + +(2) Redistributions in binary form must reproduce the above copyright +notice, this list of conditions and the following disclaimer in the +documentation and/or other materials provided with the distribution. + +(3) Neither the name of the University of California, Lawrence Berkeley +National Laboratory, U.S. Dept. of Energy nor the names of its contributors +may be used to endorse or promote products derived from this software +without specific prior written permission. + + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + +You are under no obligation whatsoever to provide any bug fixes, patches, +or upgrades to the features, functionality or performance of the source +code ("Enhancements") to anyone; however, if you choose to make your +Enhancements available either publicly, or directly to Lawrence Berkeley +National Laboratory, without imposing a separate written license agreement +for such Enhancements, then you hereby grant the following license: a +non-exclusive, royalty-free perpetual license to install, use, modify, +prepare derivative works, incorporate into other computer software, +distribute, and sublicense such enhancements or derivative works thereof, +in binary and source code form. \ No newline at end of file diff --git a/docs/models.rst b/docs/quick_guide.rst similarity index 97% rename from docs/models.rst rename to docs/quick_guide.rst index 455c835..fffb9a7 100644 --- a/docs/models.rst +++ b/docs/quick_guide.rst @@ -1,4 +1,4 @@ -.. _modelsreference: +.. _quickguidereference: Quick Guide ****************** @@ -34,10 +34,3 @@ Get a List of Variables Supported by a Data Source Get Time Series Data ---------------------- .. autofunction:: basin3d.synthesis.get_timeseries_data - - - - - - - diff --git a/setup.py b/setup.py index dc83e09..6ceec55 100644 --- a/setup.py +++ b/setup.py @@ -43,17 +43,21 @@ with open('requirements.txt') as f: required = f.read().splitlines() -setup(name='basin3d-core', +setup(name='basin3d', version=__release__, description='BASIN-3D Core Framework', long_description=README, - author='Val Hendrix', - author_email='vchendrix@lbl.gov', - url='https://github.com/Watershed-Function-SFA/basin3d-core', + author='Val Hendrix, ', + author_email='vchendrix@lbl.gov, ', + url='https://github.com/BASIN-3D/basin3d', packages=packages, data_files=['basin3d/data/basin3d_variables_hydrology.csv', 'basin3d/plugins/mapping_usgs.csv'], include_package_data=True, - python_requires=">=3.7", - install_requires=required + install_requires=[ + "pandas", + "pyyaml", + "requests", + "tinydb" + ] )