From 9bee376309ee8c1dc06c9934d96e3758137ea9c1 Mon Sep 17 00:00:00 2001 From: Maximilian Roos <5635139+max-sixty@users.noreply.github.com> Date: Thu, 14 Apr 2022 18:20:15 -0700 Subject: [PATCH] Convert readme to markdown Still some improvements we can make, but it is nicer in markdown. Also we were making some mistaken; e.g. the list of external files in the license section wasn't actually formatted as a list. --- README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 148 ----------------------------------------------------- 2 files changed, 130 insertions(+), 148 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 00000000000..57a68d42192 --- /dev/null +++ b/README.md @@ -0,0 +1,130 @@ +# xarray: N-D labeled arrays and datasets + +[![image](https://github.com/pydata/xarray/workflows/CI/badge.svg?branch=main)](https://github.com/pydata/xarray/actions?query=workflow%3ACI) +[![image](https://codecov.io/gh/pydata/xarray/branch/main/graph/badge.svg)](https://codecov.io/gh/pydata/xarray) +[![image](https://readthedocs.org/projects/xray/badge/?version=latest)](https://docs.xarray.dev/) +[![image](https://img.shields.io/badge/benchmarked%20by-asv-green.svg?style=flat)](https://pandas.pydata.org/speed/xarray/) +[![image](https://img.shields.io/pypi/v/xarray.svg)](https://pypi.python.org/pypi/xarray/) +[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black) +[![image](https://zenodo.org/badge/DOI/10.5281/zenodo.598201.svg)](https://doi.org/10.5281/zenodo.598201) +[![image](https://img.shields.io/twitter/follow/xarray_dev?style=social)](https://twitter.com/xarray_dev) + +**xarray** (formerly **xray**) is an open source project and Python +package that makes working with labelled multi-dimensional arrays +simple, efficient, and fun! + +Xarray introduces labels in the form of dimensions, coordinates and +attributes on top of raw [NumPy](https://www.numpy.org)-like arrays, +which allows for a more intuitive, more concise, and less error-prone +developer experience. The package includes a large and growing library +of domain-agnostic functions for advanced analytics and visualization +with these data structures. + +Xarray was inspired by and borrows heavily from +[pandas](https://pandas.pydata.org), the popular data analysis package +focused on labelled tabular data. It is particularly tailored to working +with [netCDF](https://www.unidata.ucar.edu/software/netcdf) files, which +were the source of xarray\'s data model, and integrates tightly with +[dask](https://dask.org) for parallel computing. + +## Why xarray? + +Multi-dimensional (a.k.a. N-dimensional, ND) arrays (sometimes called +"tensors") are an essential part of computational science. They are +encountered in a wide range of fields, including physics, astronomy, +geoscience, bioinformatics, engineering, finance, and deep learning. In +Python, [NumPy](https://www.numpy.org) provides the fundamental data +structure and API for working with raw ND arrays. However, real-world +datasets are usually more than just raw numbers; they have labels which +encode information about how the array values map to locations in space, +time, etc. + +Xarray doesn\'t just keep track of labels on arrays \-- it uses them to +provide a powerful and concise interface. For example: + +- Apply operations over dimensions by name: `x.sum('time')`. +- Select values by label instead of integer location: + `x.loc['2014-01-01']` or `x.sel(time='2014-01-01')`. +- Mathematical operations (e.g., `x - y`) vectorize across multiple + dimensions (array broadcasting) based on dimension names, not shape. +- Flexible split-apply-combine operations with groupby: + `x.groupby('time.dayofyear').mean()`. +- Database like alignment based on coordinate labels that smoothly + handles missing values: `x, y = xr.align(x, y, join='outer')`. +- Keep track of arbitrary metadata in the form of a Python dictionary: + `x.attrs`. + +## Documentation + +Learn more about xarray in its official documentation at +. + +Try out an [interactive Jupyter +notebook](https://mybinder.org/v2/gh/pydata/xarray/main?urlpath=lab/tree/doc/examples/weather-data.ipynb). + +## Contributing + +You can find information about contributing to xarray at our +[Contributing +page](https://docs.xarray.dev/en/latest/contributing.html#). + +## Get in touch + +- Ask usage questions ("How do I?") on + [StackOverflow](https://stackoverflow.com/questions/tagged/python-xarray). +- Report bugs, suggest features or view the source code [on + GitHub](https://github.com/pydata/xarray). +- For less well defined questions or ideas, or to announce other + projects of interest to xarray users, use the [mailing + list](https://groups.google.com/forum/#!forum/xarray). + +## NumFOCUS + +[![image](https://numfocus.org/wp-content/uploads/2017/07/NumFocus_LRG.png)](https://numfocus.org/) + +Xarray is a fiscally sponsored project of +[NumFOCUS](https://numfocus.org), a nonprofit dedicated to supporting +the open source scientific computing community. If you like Xarray and +want to support our mission, please consider making a +[donation](https://numfocus.salsalabs.org/donate-to-xarray/) to support +our efforts. + +## History + +Xarray is an evolution of an internal tool developed at [The Climate +Corporation](http://climate.com/). It was originally written by Climate +Corp researchers Stephan Hoyer, Alex Kleeman and Eugene Brevdo and was +released as open source in May 2014. The project was renamed from +"xray" in January 2016. Xarray became a fiscally sponsored project of +[NumFOCUS](https://numfocus.org) in August 2018. + +## License + +Copyright 2014-2019, xarray Developers + +Licensed under the Apache License, Version 2.0 (the "License"); you +may not use this file except in compliance with the License. You may +obtain a copy of the License at + + + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +Xarray bundles portions of pandas, NumPy and Seaborn, all of which are +available under a "3-clause BSD" license: + +- pandas: setup.py, xarray/util/print_versions.py +- NumPy: xarray/core/npcompat.py +- Seaborn: _determine_cmap_params in xarray/core/plot/utils.py + +Xarray also bundles portions of CPython, which is available under the +"Python Software Foundation License" in xarray/core/pycompat.py. + +Xarray uses icons from the icomoon package (free version), which is +available under the "CC BY 4.0" license. + +The full text of these licenses are included in the licenses directory. diff --git a/README.rst b/README.rst deleted file mode 100644 index e07febdf747..00000000000 --- a/README.rst +++ /dev/null @@ -1,148 +0,0 @@ -xarray: N-D labeled arrays and datasets -======================================= - -.. image:: https://github.com/pydata/xarray/workflows/CI/badge.svg?branch=main - :target: https://github.com/pydata/xarray/actions?query=workflow%3ACI -.. image:: https://codecov.io/gh/pydata/xarray/branch/main/graph/badge.svg - :target: https://codecov.io/gh/pydata/xarray -.. image:: https://readthedocs.org/projects/xray/badge/?version=latest - :target: https://docs.xarray.dev/ -.. image:: https://img.shields.io/badge/benchmarked%20by-asv-green.svg?style=flat - :target: https://pandas.pydata.org/speed/xarray/ -.. image:: https://img.shields.io/pypi/v/xarray.svg - :target: https://pypi.python.org/pypi/xarray/ -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/python/black -.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.598201.svg - :target: https://doi.org/10.5281/zenodo.598201 -.. image:: https://img.shields.io/twitter/follow/xarray_dev?style=social - :target: https://twitter.com/xarray_dev - - -**xarray** (formerly **xray**) is an open source project and Python package -that makes working with labelled multi-dimensional arrays simple, -efficient, and fun! - -Xarray introduces labels in the form of dimensions, coordinates and -attributes on top of raw NumPy_-like arrays, which allows for a more -intuitive, more concise, and less error-prone developer experience. -The package includes a large and growing library of domain-agnostic functions -for advanced analytics and visualization with these data structures. - -Xarray was inspired by and borrows heavily from pandas_, the popular data -analysis package focused on labelled tabular data. -It is particularly tailored to working with netCDF_ files, which were the -source of xarray's data model, and integrates tightly with dask_ for parallel -computing. - -.. _NumPy: https://www.numpy.org -.. _pandas: https://pandas.pydata.org -.. _dask: https://dask.org -.. _netCDF: https://www.unidata.ucar.edu/software/netcdf - -Why xarray? ------------ - -Multi-dimensional (a.k.a. N-dimensional, ND) arrays (sometimes called -"tensors") are an essential part of computational science. -They are encountered in a wide range of fields, including physics, astronomy, -geoscience, bioinformatics, engineering, finance, and deep learning. -In Python, NumPy_ provides the fundamental data structure and API for -working with raw ND arrays. -However, real-world datasets are usually more than just raw numbers; -they have labels which encode information about how the array values map -to locations in space, time, etc. - -Xarray doesn't just keep track of labels on arrays -- it uses them to provide a -powerful and concise interface. For example: - -- Apply operations over dimensions by name: ``x.sum('time')``. -- Select values by label instead of integer location: - ``x.loc['2014-01-01']`` or ``x.sel(time='2014-01-01')``. -- Mathematical operations (e.g., ``x - y``) vectorize across multiple - dimensions (array broadcasting) based on dimension names, not shape. -- Flexible split-apply-combine operations with groupby: - ``x.groupby('time.dayofyear').mean()``. -- Database like alignment based on coordinate labels that smoothly - handles missing values: ``x, y = xr.align(x, y, join='outer')``. -- Keep track of arbitrary metadata in the form of a Python dictionary: - ``x.attrs``. - -Documentation -------------- - -Learn more about xarray in its official documentation at https://docs.xarray.dev/ - -Contributing ------------- - -You can find information about contributing to xarray at our `Contributing page `_. - -Get in touch ------------- - -- Ask usage questions ("How do I?") on `StackOverflow`_. -- Report bugs, suggest features or view the source code `on GitHub`_. -- For less well defined questions or ideas, or to announce other projects of - interest to xarray users, use the `mailing list`_. - -.. _StackOverFlow: https://stackoverflow.com/questions/tagged/python-xarray -.. _mailing list: https://groups.google.com/forum/#!forum/xarray -.. _on GitHub: https://github.com/pydata/xarray - -NumFOCUS --------- - -.. image:: https://numfocus.org/wp-content/uploads/2017/07/NumFocus_LRG.png - :scale: 25 % - :target: https://numfocus.org/ - -Xarray is a fiscally sponsored project of NumFOCUS_, a nonprofit dedicated -to supporting the open source scientific computing community. If you like -Xarray and want to support our mission, please consider making a donation_ -to support our efforts. - -.. _donation: https://numfocus.salsalabs.org/donate-to-xarray/ - -History -------- - -Xarray is an evolution of an internal tool developed at `The Climate -Corporation`__. It was originally written by Climate Corp researchers Stephan -Hoyer, Alex Kleeman and Eugene Brevdo and was released as open source in -May 2014. The project was renamed from "xray" in January 2016. Xarray became a -fiscally sponsored project of NumFOCUS_ in August 2018. - -__ http://climate.com/ -.. _NumFOCUS: https://numfocus.org - -License -------- - -Copyright 2014-2019, xarray Developers - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - https://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - -Xarray bundles portions of pandas, NumPy and Seaborn, all of which are available -under a "3-clause BSD" license: -- pandas: setup.py, xarray/util/print_versions.py -- NumPy: xarray/core/npcompat.py -- Seaborn: _determine_cmap_params in xarray/core/plot/utils.py - -Xarray also bundles portions of CPython, which is available under the "Python -Software Foundation License" in xarray/core/pycompat.py. - -Xarray uses icons from the icomoon package (free version), which is -available under the "CC BY 4.0" license. - -The full text of these licenses are included in the licenses directory.