<commit_before>.. _data-containers:

Data Containers
===============

The most useful methods for ``Datasets`` are those that create ``DataContainer`` objects:
physically meaningful spatial objects that contain cells or particles with field data. ``jt``
implements a number of the data container objects available in ``yt``,
and attempts to match the API of these objects as closely as possible. All of these objects can
be created from a ``Dataset`` object, typically with some additional information supplied.

Supplying ``Length`` and ``Center`` Type Arguments to Data Containers
---------------------------------------------------------------------

A general note will be helpful before diving into the various ``DataContainer`` objects that are
available. Special ``Union`` types, ``Length`` and ``Center``, have been defined for the various
methods below for creating different objects.

A ``Length``-type argument is for length quantities such as ``radius`` or ``height`` and can be
one of the following:

  * A ``Real`` number. If so, the assumed units are ``"code_length"``.
  * A ``(value, unit)`` tuple, e.g., ``(1.5,"Mpc")``.
  * A ``YTQuantity``.

A ``Center``-type argument is for the ``center`` of an object and can be one of the following:

  * A ``String``, e.g., ``"max"`` (or ``"m"``), ``"center"`` (or ``"c"``).
  * An ``Array`` of ``Real`` numbers. If so, the assumed units are ``"code_length"``.
  * A ``YTArray``.

.. |yt_cont_docs| replace:: ``yt`` Documentation on data container objects
.. _yt_cont_docs: http://yt-project.org/docs/3.0/analyzing/objects.html

.. |yt_fp_docs| replace:: ``yt`` Documentation on field parameters
.. _yt_fp_docs: http://yt-project.org/doc/analyzing/fields.html#field-parameters

.. note::

  All of the ``DataContainer`` objects take additional optional arguments,
  which are not documented here. Information on these can be found in the |yt_cont_docs|_.

Available Data Containers
-------------------------

.. _all_data:

All Data
++++++++

The simplest data container is one that represents all of the data in the ``Dataset``. It requires
no parameters to create, except the ``Dataset`` object:

.. code-block:: julia

  function AllData(ds::Dataset; args...)

Examples:

.. code-block:: jlcon

  julia> dd = jt.AllData(ds)

.. _sphere:

Sphere
++++++

A ``Sphere`` is an object with a ``center`` and a ``radius``.

.. code-block:: julia

  function Sphere(ds::Dataset, center::Center, radius::Length; args...)

Examples:

.. code-block:: jlcon

  julia> sp = jt.Sphere(ds, "max", (100.,"kpc"))

.. code-block:: jlcon

  julia> R = jt.YTQuantity(200.,"kpc")

  julia> sp = jt.Sphere(ds, [0.0,0.0,0.0], R)

.. _region:

Region
++++++

A ``Region`` is a rectangular prism with a ``left_edge``, a ``right_edge``, and a ``center``
(that can be anywhere in the domain). The edges can be ``YTArray``\ s,
or ``Array``\ s of ``Real``\ s, in which case they will be assumed to be in units of
``code_length``.

.. code-block:: julia

  function Region(ds::Dataset, center::Center, left_edge::Union(YTArray,Array),
                    right_edge::Union(YTArray,Array); args...)

Examples:

.. code-block:: jlcon

  julia> reg = jt.Region(ds, "c", [-3.0e23,-3.0e23,-3.0e23], [3.0e23,3.0e23, 3.0e23])

.. code-block:: jlcon

  julia> a = jt.YTArray([-0.5,-0.2,-0.3], "unitary")

  julia> b = jt.YTArray([0.4,0.1,0.4], "unitary")

  julia> reg = jt.Region(ds, [0.0,0.0,0.0], a, b)

.. _disk:

Disk
++++

A ``Disk`` is a disk or cylinder-shaped region with the z-axis of the cylinder pointing along a
``normal`` vector, with a ``radius``, a ``center``, and a ``height``:

.. code-block:: julia

  function Disk(ds::Dataset, center::Center, normal::Array, radius::Length,
                  height::Length; args...)

Examples:

.. code-block:: jlcon

  dk = jt.Disk(ds, "c", [1.0,0.2,-0.3], (100,"kpc"), (0.5,"Mpc"))

.. _ray:

Ray<commit_msg>Missed this<commit_after>.. _data-containers:

Data Containers
===============

The most useful methods for ``Datasets`` are those that create ``DataContainer`` objects:
physically meaningful spatial objects that contain cells or particles with field data. ``jt``
implements a number of the data container objects available in ``yt``,
and attempts to match the API of these objects as closely as possible. All of these objects can
be created from a ``Dataset`` object, typically with some additional information supplied.

Supplying ``Length`` and ``Center`` Type Arguments to Data Containers
---------------------------------------------------------------------

A general note will be helpful before diving into the various ``DataContainer`` objects that are
available. Special ``Union`` types, ``Length`` and ``Center``, have been defined for the various
methods below for creating different objects.

A ``Length``-type argument is for length quantities such as ``radius`` or ``height`` and can be
one of the following:

  * A ``Real`` number. If so, the assumed units are ``"code_length"``.
  * A ``(value, unit)`` tuple, e.g., ``(1.5,"Mpc")``.
  * A ``YTQuantity``.

A ``Center``-type argument is for the ``center`` of an object and can be one of the following:

  * A ``String``, e.g., ``"max"`` (or ``"m"``), ``"center"`` (or ``"c"``).
  * An ``Array`` of ``Real`` numbers. If so, the assumed units are ``"code_length"``.
  * A ``YTArray``.

.. |yt_cont_docs| replace:: ``yt`` Documentation on data container objects
.. _yt_cont_docs: http://yt-project.org/docs/3.0/analyzing/objects.html

.. |yt_fp_docs| replace:: ``yt`` Documentation on field parameters
.. _yt_fp_docs: http://yt-project.org/doc/analyzing/fields.html#field-parameters

.. note::

  All of the ``DataContainer`` objects take additional optional arguments,
  which are not documented here. Information on these can be found in the |yt_cont_docs|_.

Available Data Containers
-------------------------

.. _all_data:

All Data
++++++++

The simplest data container is one that represents all of the data in the ``Dataset``. It requires
no parameters to create, except the ``Dataset`` object:

.. code-block:: julia

  function AllData(ds::Dataset; args...)

Examples:

.. code-block:: jlcon

  julia> dd = jt.AllData(ds)

.. _sphere:

Sphere
++++++

A ``Sphere`` is an object with a ``center`` and a ``radius``.

.. code-block:: julia

  function Sphere(ds::Dataset, center::Center, radius::Length; args...)

Examples:

.. code-block:: jlcon

  julia> sp = jt.Sphere(ds, "max", (100.,"kpc"))

.. code-block:: jlcon

  julia> R = jt.YTQuantity(200.,"kpc")

  julia> sp = jt.Sphere(ds, [0.0,0.0,0.0], R)

.. _region:

Region
++++++

A ``Region`` is a rectangular prism with a ``left_edge``, a ``right_edge``, and a ``center``
(that can be anywhere in the domain). The edges can be ``YTArray``\ s,
or ``Array``\ s of ``Real``\ s, in which case they will be assumed to be in units of
``code_length``.

.. code-block:: julia

  function Region(ds::Dataset, center::Center, left_edge::Union(YTArray,Array),
                    right_edge::Union(YTArray,Array); args...)

Examples:

.. code-block:: jlcon

  julia> reg = jt.Region(ds, "c", [-3.0e23,-3.0e23,-3.0e23], [3.0e23,3.0e23, 3.0e23])

.. code-block:: jlcon

  julia> a = jt.YTArray([-0.5,-0.2,-0.3], "unitary")

  julia> b = jt.YTArray([0.4,0.1,0.4], "unitary")

  julia> reg = jt.Region(ds, [0.0,0.0,0.0], a, b)

.. _disk:

Disk
++++

A ``Disk`` is a disk or cylinder-shaped region with the z-axis of the cylinder pointing along a
``normal`` vector, with a ``radius``, a ``center``, and a ``height``:

.. code-block:: julia

  function Disk(ds::Dataset, center::Center, normal::Array, radius::Length,
                  height::Length; args...)

Examples:

.. code-block:: jlcon

  julia> dk = jt.Disk(ds, "c", [1.0,0.2,-0.3], (100,"kpc"), (0.5,"Mpc"))

.. _ray:

Ray
{'fraction_non_alphanumeric': 0.19526931482195656, 'fraction_numerical': 0.01774006941766294, 'mean_word_length': 3.473835537665325, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 20, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3094831', 'n_tokens_mistral': 2644, 'n_tokens_neox': 2581, 'n_words': 889}