Add license, code of conduct, style guide

CODE_OF_CONDUCT.md

@@ -0,0 +1,55 @@
+# `Mirage` Code of Conduct
+
+## Introduction
+
+This code of conduct applies to all spaces related to the `mirage` project, including all public and private mailing lists, repositories, issue trackers, wikis, and any other communication channel used by our community.
+
+This code of conduct should be honored by everyone who participates in the `mirage` project formally or informally, or claims any affiliation with the project, in any project-related activities and especially when representing the project, in any role.
+
+This code is not exhaustive or complete. It serves to distill our common understanding of a collaborative, shared environment and goals. Please try to follow this code in spirit as much as in letter, to create a friendly and productive environment that enriches the surrounding community.
+
+## Our Pledge
+
+As members of the community,
+
+- We pledge to treat all people with respect and provide a harassment- and bullying-free environment, regardless of sex, sexual orientation and/or gender identity, disability, physical appearance, body size, race, nationality, ethnicity, and religion. In particular, sexual language and imagery, sexist, racist, or otherwise exclusionary jokes are not appropriate.
+
+- We pledge to respect the work of others by recognizing acknowledgment/citation requests of original authors. As authors, we pledge to be explicit about how we want our own work to be cited or acknowledged.
+
+- We pledge to welcome those interested in joining the community, and realize that including people with a variety of opinions and backgrounds will only serve to enrich our community. In particular, discussions relating to pros/cons of various technologies, programming languages, and so on are welcome, but these should be done with respect, taking proactive measure to ensure that all participants are heard and feel confident that they can freely express their opinions.
+
+- We pledge to welcome questions and answer them respectfully, paying particular attention to those new to the community. We pledge to provide respectful criticisms and feedback in forums, especially in discussion threads resulting from code contributions.
+
+- We pledge to be conscientious of the perceptions of the wider community and to respond to criticism respectfully. We will strive to model behaviors that encourage productive debate and disagreement, both within our community and where we are criticized. We will treat those outside our community with the same respect as people within our community.
+
+- We pledge to help the entire community follow the code of conduct, and to not remain silent when we see violations of the code of conduct. We will take action when members of our community violate this code such as such as contacting conduct@stsci.edu (all emails sent to this address will be treated with the strictest confidence) or talking privately with the person.
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Scope
+
+This code of conduct applies to all community situations online and offline, including mailing lists, forums, social media, conferences, meetings, associated social events, and one-to-one interactions.
+
+## Attribution
+
+This Code of Conduct is adapted from several existing code of conducts:
+
+- The [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at [http://contributor-covenant.org/version/1/4](http://contributor-covenant.org/version/1/4/)
+- The [`stsci-package-template` code of conduct](https://github.com/spacetelescope/stsci-package-template/blob/master/CODE_OF_CONDUCT.md)
+- The [`scipy` code of conduct](https://docs.scipy.org/doc/scipy/reference/dev/conduct/code_of_conduct.html)
+- http://www.astropy.org/code_of_conduct.html
+- https://www.numfocus.org/about/code-of-conduct/

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2018, Association of Universities for Research in Astronomy.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* 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.
+
+* Neither the name of the copyright holder 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 HOLDER 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.

README.md

@@ -230,4 +230,45 @@ simulated exposure. Example use shown in the WFSS notebook.
 
 **`yaml_generator.py`** - Beginning with an Astronomer's Proposal Tool (APT) file,
 create the yaml files necessary to simulate the entire proposal. Example use
-shown in the imaging and WFSS notebooks.
+shown in the imaging and WFSS notebooks.
+
+
+### Contributing
+
+Prior to contributing to the `mirage` development, please review our [style guide](https://github.com/spacetelescope/mirage/blob/master/style_guide/style_guide.md).
+
+The following is a bare bones example of a best work flow for contributing to the project:
+
+1. Create a fork off of the `spacetelescope` `mirage` repository.
+2. Make a local clone of your fork.
+3. Ensure your personal fork is pointing `upstream` properly.
+4. Create a branch on that personal fork.
+5. Make your software changes.
+6. Push that branch to your personal GitHub repository (i.e. `origin`).
+7. On the `spacetelescope` `mirage` repository, create a pull request that merges the branch into `spacetelescope:master`.
+8. Assign a reviewer from the team for the pull request.
+9. Iterate with the reviewer over any needed changes until the reviewer accepts and merges your branch.
+10. Delete your local copy of your branch.
+
+
+## Code of Conduct
+
+Users and contributors to the `mirage` repository should adhere to the [Code of Conduct](https://github.com/spacetelescope/mirage/blob/master/CODE_OF_CONDUCT.md).  Any issues or violations pertaining to the Code of Conduct should be brought to the attention of a `mirage` team member or to `conduct@stsci.edu`.
+
+
+## Questions
+
+Any questions about the `mirage` project or its software can be directed to `hilbert@stsci.edu`.
+
+
+## Current Development Team
+- Bryan Hilbert
+- Johannes Sahlmann
+- Lauren Chambers
+- Kevin Volk
+- Shannon Osborne
+- Marshall Perrin
+
+
+## Acknowledgments:
+`Mirage` is based on a NIRISS data simulator originally written by Kevin Volk.

style_guide/example.py

@@ -0,0 +1,180 @@
+#! /usr/bin/env python
+"""This is the module docstring.
+
+The module docstring should have a one line description (as above) as
+well as a more detailed description in a paragraph below the one line
+description (i.e. this).  Module dosctring lines should be limited to
+72 characters.  Monospace font can be achived with ``two single
+forward-apostrophes``.  The description should provided a detailed
+overview of the purpose of the module (what does it do) and how it
+achieves this purpose (how does it do it).
+
+Authors
+-------
+
+    - Bryan Hilbert
+
+Use
+---
+
+    This module can be executed via the command line as such:
+
+    ::
+        python example.py [path] [-f|--filter filter]
+
+    Required arguments:
+
+    ``path`` - The path to the input file
+
+    Optional arguments:
+
+    ``-f|--filter`` - The filter to process.  if not provided, the
+        defult value is "F606W".
+
+Dependencies
+------------
+
+    Here is where any external dependencies can be listed or described.
+    For example:
+
+    The user must have a configuration file named ``config.yaml``
+    placed in the current working directory.
+
+References
+----------
+
+    Here is where any references to external sources related to the
+    code can be listed or described.  For example:
+
+    Code adopted from IDL routine written by Hilbert et al., 2009.
+
+Notes
+-----
+
+    Here is where any additional notes (that are beyond the scope of the
+    description) can be described.
+"""
+
+import argparse
+import glob
+import os
+import sys
+from typing import List, Union, Tuple, Optional, Any, Dict
+
+from astropy.io import fits
+import matplotlib.pyplot as plt
+import numpy as np
+import scipy
+from sqlalchemy import Float, Integer, String
+
+
+# Global variables should be avoided, but if used should be named with
+# all-caps
+A_GLOBAL_VARIABLE = 'foo' # type: str
+
+
+def my_main_function(path: str, filter: str) -> None:
+    """The main function of the ``example`` module.
+
+    This function performs the main tasks of the module.  See module
+    docstrings for further details.
+
+    Parameters
+    ----------
+    path : str
+        The path to the input file.
+    filter : str
+        The filter to process (e.g. "F606W").
+    """
+
+    print('Using {} as an input file'.format(path))
+    an_int = 1 # type: int
+    a_float = 3.14 # type: float
+    a_bool = True # type: bool
+    a_list = ['Dog', 'Cat', 'Turtle', False, 7] # type: List[Union[str, bool, int]]
+    a_tuple = ('Dog', 'Cat', 'Turtle', False, 7) # type: Tuple[str, str, str, bool, int]
+    a_dict = {'key1': 'value1', 'key2': 'value2'} # type: Dict[str, str]
+    an_obj = object() # type: object
+
+    result = some_other_function(an_int, a_float, a_bool, a_list, a_tuple, a_dict, an_obj) # type: Optional[int]
+
+    print(result)
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command line arguments. Returns ``args`` object.
+
+    Returns
+    -------
+    args : obj
+        An argparse object containing all of the arguments
+    """
+
+    # Create help strings
+    path_help = 'The path to the input file.' # type: str
+    filter_help = 'The filter to process (e.g. "F606W").' # type: str
+
+    # Add arguments
+    parser = argparse.ArgumentParser() # type: argparse.ArgumentParser
+    parser.add_argument('path',
+                        type=str,
+                        default=os.getcwd(),
+                        help=path_help)
+    parser.add_argument('-f --filter',
+                        dest='filter',
+                        type=str,
+                        required=False,
+                        default='F606W',
+                        help=filter_help)
+
+    # Parse args
+    args = parser.parse_args() # type: argparse.Namespace
+
+    return args
+
+
+def some_other_function(an_int: int, a_float: float, a_bool: bool, a_list: List[Any],
+                        a_tuple: Tuple[Any], a_dict: Dict[Any, Any], an_obj: object) -> int:
+    """This function just does a bunch of nonsense.
+
+    But it serves as a decent example of some things.
+
+    Parameters
+    ----------
+    an_int : int
+        Who knows what we will use this integer for.
+    a_bool : bool
+        Who knows what we will use this boolean for.
+    a_float: float
+        Who knows what we will use this float for.
+    a_list : list
+        Who knows what we will use this list for.
+    a_tuple : tuple
+        Who knows what we will use this tuple for.
+    a_dict : dict
+        Who knows what we will use this dictionary for.
+    an_obj : obj
+        Who knows what we will use this object for.
+
+    Returns
+    -------
+    results : int
+        The result of the function.
+    """
+
+    # File I/O should be handeled with 'with open' when possible
+    with open('my_file', 'w') as f:
+        f.write('My favorite integer is {}'.format(an_int))
+
+    # Operators should be separated by spaces
+    print(a_float + a_float)
+
+    return an_int
+
+
+
+if __name__ == '__main__':
+
+    args = parse_args() # type: argparse.Namespace
+
+    my_main_function(args.path, args.filter)

style_guide/style_guide.md

@@ -0,0 +1,68 @@
+Python Code Style Guide for `mirage`
+===================================
+
+This document serves as a style guide for all `mirage` software development.  Any requested contribution to the `mirage` code repository should be checked against this guide, and any violation of the guide should be fixed before the code is committed to
+the `master` branch.  Please refer to the accompanying [`example.py`](https://github.com/spacetelescope/mirage/blob/master/style_guide/example.py) script for a example code that abides by this style guide.
+
+Prerequisite Reading
+--------------------
+
+It is assumed that the reader of this style guide has read and is familiar with the following:
+
+- The [PEP8 Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/)
+- The [PEP257 Docstring Conventions Style Guide](https://www.python.org/dev/peps/pep-0257/)
+- The [`numpydoc` docstring convention](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)
+
+
+Workflow
+--------
+
+All software development for the `mirage` project should follow a continuous integration workflow.  Before committing any code changes, use `flake8` to check the code against `PEP8` standards.  Also check that your code is conforming to this style guide.
+
+
+Version Numbers and Tags
+------------------------
+
+Any changes pushed to the `master` branch should be tagged with a version number.  The version number convention is `x.y.z`, where
+
+    x = The main version number.  Increase when making incompatible API changes.
+    y = The feature number.  Increase when change contains a new feature with or without bug fixes.
+    z = The hotfix number. Increase when change only contains bug fixes.
+
+
+Security
+--------
+
+The following items should never be committed in the `mirage` source code or GitHub issues/pull requests:
+
+- Account credentials of any kind (e.g. database usernames and passwords)
+- Internal directory structures or filepaths
+- Machine names
+- Proprietary data
+
+
+`mirage`-specific Code Standards
+------------------------------
+
+`mirage` code shall adhere to the `PEP8` conventions save for the following exceptions:
+
+ - Lines of code need not to be restricted to 79 characters.  However, it is encouraged to break up obnoxiously long lines into several lines if it benefits the overall readability of the code
+
+ Additionally, the code shall adhere to the following special guidelines:
+
+ - Function and class definitions should be placed in alphabetical order in the module
+ - It is encouraged to annotate variables and functions using the [`typing`](https://docs.python.org/3/library/typing.html) module (see [PEP 483](https://www.python.org/dev/peps/pep-0483/), [PEP 484](https://www.python.org/dev/peps/pep-0484/), and [PEP 526](https://www.python.org/dev/peps/pep-0526/)).
+
+
+`mirage`-Specific Documentation Standards
+---------------------------------------
+
+`mirage` code shall adhere to the `PEP257` and `numpydoc` conventions.  The following are further recommendations:
+
+- Each module should have at minimum a description, `Authors` and `Use` section.
+- Each function/method should have at minimum a description, `Parameters` (if necessary), and `Returns` (if necessary) sections
+
+Acknowledgements
+----------------
+
+This style guide as well as [`example.py`](https://github.com/spacetelescope/mirage/blob/master/style_guide/example.py) were adapted from those used by the [`jwql` project](https://github.com/spacetelescope/jwql).