Merge pull request #516 from sciris/rc3.1.0

Release 3.1.0

CHANGELOG.rst

@@ -8,6 +8,38 @@ All major updates to Sciris are documented here.
 By import convention, components of the Sciris library are listed beginning with ``sc.``, e.g. ``sc.odict()``.
 
 
+Version 3.1.0 (2022-08-13)
+--------------------------
+
+New features
+~~~~~~~~~~~~
+#. ``sc.equal()`` compares two (or more) arbitrarily complex objects. It can handle arrays, dataframes, custom objects with no ``__eq__`` method defined, etc. It can also print a detailed comparison of the objects 
+#. ``sc.nanequal()`` is an extension of ``np.array_equal()`` to handle a broader range of types (e.g., mixed-type ``object`` arrays that cannot be cast to float). Other ``NaN``-related methods have also been updated to be more robust.
+#. ``sc.manualcolorbar()`` allows highly customized colorbars to be added to plots, including to plots with no "mappable" data (e.g., scatterplots).
+#. Added ``sc.options.reset()`` as an alias to ``sc.options.set('defaults')``.
+
+
+Bugfixes
+~~~~~~~~
+#. Sciris is now compatible with a broader range of dependencies (e.g., Python, NumPy, pandas, and Matplotlib); in most cases, the latest version of Sciris is now backwards-compatible with all dependency versions since January 2021.
+#. Updated ``sc.pr()`` to include class attributes (instead of instance attributes), and added a new function ``sc.classatt()`` to list them.
+#. ``sc.readdate()`` now returns ``datetime`` objects unchanged, rather than raising an exception.
+#. Fixed ``repr`` for empty ``sc.objdict()``.
+#. Fixed transposed ordering for ``sc.bar3d()``.
+
+Other changes
+~~~~~~~~~~~~~
+#. ``sc.load()`` has been significantly refactored to be simpler and more robust. Pandas' ``pd.read_pickle()`` is now included as one of the default unpickling options. Unsuccessful unpickling now always produces a ``Failed`` object, with as much data retained as possible.
+#. ``sc.jsonpickle()`` and ``sc.jsonunpickle()`` can now save to/read from files directly.
+#. Updated ``sc.toarray()`` to use ``dtype=object`` instead of ``dtype=str`` by default; otherwise, all elements in mixed-type arrays (e.g. ``[1,'a']``) are cast to string.
+#. ``sc.dataframe`` has a new ``equal`` class method (e.g. ``sc.dataframe.equal(df1, df2)``), and revised ``equals()`` and ``==`` behavior to match pandas.
+#. Improved robustness of ``sc.parallelize()``, especially when using custom parallelizers, including more options for customizing the global dictionary.
+#. ``sc.timer()`` objects can now be added, which will concatenate all the times.
+#. Added an option to run ``sc.benchmark()`` in parallel (to test the full capacity of the machine rather than a single core).
+#. ``sc.iterobj()`` now provides more options for controlling how the object is iterated, and no longer (by default) descends into NumPy arrays, pandas DataFrames, etc. ``sc.search()`` also has additional options.
+#. Updated 3D plotting functions (``sc.plot3d()``, ``sc.surf3d``, etc.) to have more flexibility of data input, consistency, and robustness.
+
+
 Version 3.0.0 (2023-04-20)
 --------------------------
 

README.rst

@@ -27,7 +27,8 @@ If you have questions, feature suggestions, or would like some help getting star
 Installation
 ------------
 
-Using pip: ``pip install sciris``
+Using ``pip``: ``pip install sciris``
+Using ``conda``: ``conda install -c conda-forge sciris``
 
 *Requires Python >= 3.7*.
 

docs/build_docs

@@ -1,4 +1,8 @@
 #!/bin/bash
+# Build docs. Example usage:
+#  ./build_docs # default
+#  ./build_docs never # don't rebuild notebooks
+#  ./build_docs noclean # don't clean up tutorials
 
 echo 'Building docs...'
 start=$SECONDS
@@ -19,8 +23,18 @@ if [[ "$*" == *"debug"* ]]; then
 else
     export BUILD_DEBUG=
 fi
-make html # Actually make
 
+# Actually make
+make html 
+
+# Clean up tutorials
+if [[ "$*" != *"noclean"* ]]; then
+    cd tutorials
+    ./clean_outputs
+    cd ..
+fi
+
+# Tidy up
 duration=$(( SECONDS - start ))
 echo "Docs built after $duration seconds."
 echo "Index:"

docs/overview.rst

@@ -110,12 +110,14 @@ Other utilities
 -  :func:`sc.heading() <sc_printing.heading>`: print text as a 'large' heading
 -  :func:`sc.colorize() <sc_printing.colorize>`: print text in a certain color
 -  :func:`sc.sigfig() <sc_printing.sigfig>`: truncate a number to a certain number of significant figures
+-  :func:`sc.search() <sc_nested.search>`: search for a key, attribute, or value in a complex object
+-  :func:`sc.equal() <sc_nested.equal>`: check whether two or more complex objects are equal
 
 
 Installation and run instructions
 ---------------------------------
 
-1. Install Sciris: ``pip install sciris``
+1. Install Sciris: ``pip install sciris`` (or ``conda install -c conda-forge sciris``)
 
 2. Use Sciris: ``import sciris as sc``
 
@@ -127,7 +129,7 @@ Citation
 
 To cite Sciris, cite the `paper <http://paper.sciris.org>`_:
 
-  Kerr CC, Sanz-Leon P, Abeysuriya RG, Chadderdon GL, Harbuz VS, Saidi P, Quiroga M, Martin-Hughes R, Kelly SL, Cohen JA, Stuart RM, Nachesa AN. **Sciris: Simplifying scientific software in Python**. *Journal of Open Source Software* 2023 (under review).
+  Kerr CC, Sanz-Leon P, Abeysuriya RG, Chadderdon GL, Harbuz VS, Saidi P, Quiroga M, Martin-Hughes R, Kelly SL, Cohen JA, Stuart RM, Nachesa AN. **Sciris: Simplifying scientific software in Python**. *Journal of Open Source Software* 2023 (in press).
 
 The citation is also available in `BibTeX format`_.
 

docs/tutorials/clean_outputs

@@ -37,4 +37,7 @@ if clean_nb:
 else:
     print('\nNot clearing notebook output\n')
 
+# Undo modifications to dancing_lines.gif
+sc.runcommand('git checkout -- dancing_lines.gif')
+
 T.toc('Done!\n\n')

docs/tutorials/tut_files.ipynb

@@ -97,7 +97,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We can create any object, save it, then reload it from disk and it works just like new – even calling methods works! What's happening here? Under the hood, `sc.save()` saves the object as a [gzipped](https://docs.python.org/3/library/gzip.html) (compressed) [pickle]](https://docs.python.org/3/library/pickle.html) (byte stream). Pickles are how Python sends objects internally, so can handle almost anything. (For the few corner cases that `pickle` can't handle, `sc.save()` falls back on [dill](https://dill.readthedocs.io/en/latest/), which really can handle everything.) \n",
+    "We can create any object, save it, then reload it from disk and it works just like new – even calling methods works! What's happening here? Under the hood, `sc.save()` saves the object as a [gzipped](https://docs.python.org/3/library/gzip.html) (compressed) [pickle](https://docs.python.org/3/library/pickle.html) (byte stream). Pickles are how Python sends objects internally, so can handle almost anything. (For the few corner cases that `pickle` can't handle, `sc.save()` falls back on [dill](https://dill.readthedocs.io/en/latest/), which really can handle everything.) \n",
     "\n",
     "There are also other compression options than gzip ([zstandard](https://python-zstandard.readthedocs.io/en/latest/) or no compression), but you probably don't need to worry about these. (If you _really_ care about performance, then `sc.zsave()`, which uses `zstandard` by default, is slightly faster than `sc.save()` – but regardless of how a file was saved you can load it with `sc.load()`."
    ]