Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README for Julia 1.0 #98

Closed
wants to merge 1 commit into from
Closed

Update README for Julia 1.0 #98

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 10 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,9 @@

# Missings

*A missing value representation for Julia for databases and statistics*
*Convenience functions to work with missing values in Julia*

| **PackageEvaluator** | **Build Status** |
|:---------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------:|
|[![][pkg-0.6-img]][pkg-0.6-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] |
[![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url]


## Installation
Expand All @@ -18,10 +16,15 @@ julia> Pkg.add("Missings")

## Project Status

The package is tested against the current Julia `0.6` release and nightly on Linux, OS X, and Windows.

Starting from Julia `0.7` the `Missing` type and basic functionalities related to it have been merged to core Julia.
This package still provides additional features to handle `missing` values.
See [the Julia manual](https://docs.julialang.org/en/v1/manual/missing/index.html) for general documentation on missing values in Julia.
This package still provides additional features to handle `missing` values:
- `Missings.T` to extract `T` from a `Union{T, Missing}` type
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth mentioning this at all given that Base.nonmissingtype exists?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Until it's exported I'd rather not recommend it. Also it's broken in complex cases in older Julia versions.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's fair I suppose.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#102

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `Missings.T` to extract `T` from a `Union{T, Missing}` type
- `Missings.nonmissingtype` to extract `T` from a `Union{T, Missing}` type

- `allowmissing` and `disallowmissing` to convert between `Vector{T}` and `Vector{Union{T, Missing}}`
- `passmissing` to wrap a function so that it returns `missing` if any of its positional arguments is `missing`
- `levels` to get the unique values in a vector excluding `missing` and in their preferred order

Other functions should not be used in newly-written code as they have equivalents in Julia Base.

## Contributing and Questions

Expand All @@ -45,14 +48,3 @@ Contributions are very welcome, as are feature requests and suggestions. Please
[codecov-url]: https://codecov.io/gh/JuliaData/Missings.jl

[issues-url]: https://github.com/JuliaData/Missings.jl/issues

[pkg-0.6-img]: http://pkg.julialang.org/badges/Missings_0.6.svg
[pkg-0.6-url]: http://pkg.julialang.org/?pkg=Missings

## Documentation

Missings.jl provides a single type `Missing` with a single instance `missing` which represents a missing value in data. `missing` values behave essentially like [`NULL` in SQL](https://en.wikipedia.org/wiki/NULL_(SQL)) or [`NA` in R](https://cran.r-project.org/doc/manuals/r-release/R-lang.html#NA-handling). `missing` differs from `nothing` (the object returned by Julia functions and blocks which do not return any value) in that it can be passed to many operators and functions, prompting them to return `missing`. Where appropriate, packages should provide methods propagating `missing` for the functions they define.

The package defines standard operators and functions which propagate `missing` values: for example `1 + missing` and `cos(missing)` both return `missing`. In particular, note that comparison operators `==`, `<`, `>`, `<=` and `=>` (but not `isequal` nor `isless`) also propagate `missing`, so that `1 == missing` and `missing == missing` both return `missing`. Use `ismissing` to test whether a value is `missing`. Logical operators `&`, `|`, `⊻`/`xor` implement [three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic): they return `missing` only when the result cannot be determined. For example, `true & missing` returns `missing` but `true | missing` returns `true`.

In many cases, `missing` values will have to be skipped or replaced with a valid value. For example, `sum([1, missing])` returns `missing` due to the behavior of `+`. Use `sum(Missings.skip([1, missing])` to ignore `missing` values. `sum(Missings.replace([1, missing], 0))` would have the same effect. `Missings.fail` throws an error if any value is found while iterating over the data. These three functions return an iterator and therefore do not need to allocate a copy of the data. Finally, the `Missings.coalesce` function is a more complex and powerful version of `Missings.replace`.