Metadata-Version: 2.1
Name: elixir-dx
Version: 1.0.0
Summary: Python wrapper for Data Explorer
Author-email: ciusji <bqjimaster@gmail.com>
Keywords: data,exploration,visualization
Description-Content-Type: text/markdown
License-File: LICENSE.md

<div align="right">
    <img src="https://raw.githubusercontent.com/ElixirNote/elixirnote/main/docs/assets/guinsoolab-badge.png" width=60 alt="badge">
</div>
<div align="center">
    <img src="https://raw.githubusercontent.com/ElixirNote/elixirnote/main/docs/assets/elixirnote2.svg" width=120 alt="logo" />
    <br />
    <small>go from data to knowledge</small>
</div>

# ElixirDx

> A collaborative notebook platform that enables teams to use and visualize data, together.


## Requirements

Python 3.8+

## Installation

```shell
pip install dx
```

Then import the package:

```python
import dx
```

## Usage

The `dx` library currently enables DEX media type visualization of pandas `DataFrame` and `Series` objects, as 
well as numpy `ndarray` objects. This can be handled in two ways:
- explicit `dx.display()` calls
- setting the `display_mode` to update the IPython display formatter for a session

### With `dx.display()`
`dx.display()` will display a single dataset using the DEX media type. It currently supports:
- pandas `DataFrame` objects
  ```python
  import pandas as pd
  import random

  df = pd.DataFrame({
      'random_ints': [random.randint(0, 100) for _ in range(500)],
      'random_floats': [random.random() for _ in range(500)],
  })
  dx.display(df)
  ```

- tabular data as `dict` or `list` types
  ```python
  dx.display([
    [1, 5, 10, 20, 500],
    [1, 2, 3, 4, 5],
    [0, 0, 0, 0, 1]
  ])
  ```

- `.csv` or `.json` filepaths 
  ```python
  df = dx.random_dataframe()
  df.to_csv("dx_docs_sample.csv", index=False)

  dx.display("dx_docs_sample.csv")
  ```

### With `dx.set_display_mode()`
Using either `"simple"` or `"enhanced"` display modes will allow `dx` will update the current `IPython` display formatters to allow DEX media type visualization of pandas `DataFrame` objects for an entire notebook / kernel session instead of the default `DataFrame` display output.

<details>
<summary>Details</summary>

This will adjust pandas options to:
- increasing the number of rows displayed to `50000` from pandas default of `60`
- increasing the number of columns displayed to `50` from pandas default of `20`
- enabling `html.table_schema` (`False` by default in pandas)

This will also handle some basic column cleaning and generate a schema for the `DataFrame` using `pandas.io.json.build_table_schema`. Depending on the display mode, the data will be transformed into either a list of dictionaries or list of lists of columnar values.
- `"simple"` - list of dictionaries
- `"enhanced"` - list of lists
</details>

> **NOTE:**
> Unlike `dx.display()`, this **only** affects pandas DataFrames (or any types set in `settings.RENDERABLE_OBJECTS`); it does not affect the display of `.csv`/`.json` file data, or `dict`/`list` outputs


- `dx.set_display_mode("simple")`
  
  ```python
  import dx
  import numpy as np
  import pandas as pd

  # enable DEX display outputs from now on
  dx.set_display_mode("simple")

  df = pd.read_csv("dx_docs_sample.csv")
  df
  ```
  ```python
  df2 = pd.DataFrame(
      [
          [1, 5, 10, 20, 500],
          [1, 2, 3, np.nan, 5],
          [0, 0, 0, np.nan, 1]
      ],
      columns=['a', 'b', 'c', 'd', 'e']
  )
  df2
  ```

If, at any point, you want to go back to the default display formatting (vanilla pandas output), use the `"plain"` display mode. This will revert the IPython display format update to its original state and put the pandas options back to their default values.

- `dx.set_display_mode("plain")`
  ```python
  # revert to original pandas display outputs from now on
  dx.set_display_mode("plain")

  df = pd.read_csv("dx_docs_sample.csv")
  df
  ```
  ```python
  df2 = pd.DataFrame(
      [
          [1, 5, 10, 20, 500],
          [1, 2, 3, np.nan, 5],
          [0, 0, 0, np.nan, 1]
      ],
      columns=['a', 'b', 'c', 'd', 'e']
  )
  df2
  ```

### Generating Sample Data
Documentation coming soon!

## Contributing

See [CONTRIBUTING.md](https://github.com/ElixirNote/elixirdx/blob/main/CONTRIBUTING.md).

## Code of Conduct

We follow the ElixirNote [code of conduct](https://github.com/ElixirNote/elixirdx/blob/main/CODE_OF_CONDUCT.md).

## LICENSE

See [LICENSE.md](https://github.com/ElixirNote/elixirdx/blob/main/LICENSE.md).
